Report malformed percent-escapes in Google resource URLs instead of throwing URIError

[sarbojitrana]

Fixes #55.

Root cause

getGatekeeperClassFor() in packages/gatekeeper-google/src/google.ts hands user-supplied URL text straight to decodeURIComponent(), with no try. decodeURIComponent() throws URIError: URI malformed on any % that isn't followed by two hex digits, so a bare % in the URL escapes the function's own error handling entirely:

https://mail.google.com/mail/u/0/#search/50%off     ->  URIError: URI malformed
https://mail.google.com/mail/u/0/#label/Q1 100%     ->  URIError: URI malformed

That is out of step with the rest of the same function, which explains itself whenever input is wrong — "Invalid Google Sheets URL: no spreadsheet ID found", "Gmail label name must be between 1 and 320 bytes." A user who pastes a search containing a percent sign gets none of that, just the raw decode failure. A % in a Gmail search or label is not exotic: "50% off", "Q1 100%", any label with a percentage in it.

There were four such bare decodes in the function, not two. The issue names the two Gmail branches and the calendar one; grepping the function turns up a fourth in the BigQuery branch:

line	branch	reachable via
869	Calendar	% in the calendar-ID path segment
902	BigQuery	% in any project/dataset/table segment
941	Gmail #search/	% anywhere in the query
945	Gmail #label/	% anywhere in the label

The Gmail two are the easy ones to hit, since the whole hash is user text; the other two need a % in one specific segment.

The fix

One local helper, routed through at all four sites:

// decodeURIComponent(), but a malformed escape (e.g. the bare `%` in a search for "50% off")
// reports which URL was bad instead of throwing a raw `URIError: URI malformed`. Such input is
// rejected rather than read literally: these values scope the binding, and guessing at what the
// user meant could scope it to something other than what they think they connected.
function decodePercentEncoded(what: string, encoded: string): string {
  try {
    return decodeURIComponent(encoded);
  } catch {
    throw new Error(
        `Invalid ${what}: not valid percent-encoded text. Write a literal "%" as "%25".`);
  }
}

Now:

Error: Invalid Gmail search URL: not valid percent-encoded text. Write a literal "%" as "%25".

Three notes on the choices, since they were the judgement calls:

Reject rather than repair. The tempting alternative is to treat an undecodable % as a literal % and carry on. I deliberately didn't. These strings scope the binding — which search, which label, which calendar, which BigQuery table the agent may read. Silently reinterpreting one risks scoping a capability to something other than what the user believes they connected, and a wrong guess here fails open. An error the user can act on is the safer failure. The message names %25 so the fix is obvious.

Scope: this function, not all seven packages. #55 notes the same pattern lives in seven gatekeepers and asks whether the fix should be a shared helper. Going by CONTRIBUTING.md's "no more than a dozen or so lines", I kept this to the one function the issue reports, as a local helper. A shared safe-decode utility across confluence/email/homeassistant/linear/notion/slack/google is a much bigger and more opinionated change — happy to open a discussion for it if you want that instead, and this patch is a clean no-op to revert if so.

Included BigQuery, though #55 doesn't mention it. It's the same bug on the same user input in the same function, and leaving it would mean fixing three of four identical call sites. Say the word and I'll drop that one line.

google.ts:3001 also decodes, but its input is KV keys this file wrote with encodeURIComponent() — never malformed, never user input. Left alone.

Proof

Before/after, driving the same branch dispatch with decodePercentEncoded lifted verbatim out of the patched source (testing the shipped helper, not a paraphrase):

=== Regressions: malformed percent-escape ===

  PASS  https://mail.google.com/mail/u/0/#search/50%off
        before: URIError: URI malformed
        after:  Error: Invalid Gmail search URL: not valid percent-encoded text. Write a literal "%" as "%25".

  PASS  https://mail.google.com/mail/u/0/#label/Q1 100%
        before: URIError: URI malformed
        after:  Error: Invalid Gmail label URL: not valid percent-encoded text. Write a literal "%" as "%25".

  PASS  https://calendar.google.com/calendar/u%/r
        before: URIError: URI malformed
        after:  Error: Invalid Google Calendar URL: not valid percent-encoded text. Write a literal "%" as "%25".

  PASS  https://bigquery.googleapis.com/my-project%/dataset
        before: URIError: URI malformed
        after:  Error: Invalid BigQuery resource URL: not valid percent-encoded text. Write a literal "%" as "%25".

Well-formed input decodes byte-identically to before — this is a pure error-path change:

=== Behavior preserved for well-formed input ===

  PASS  #inbox                                 -> gmail: inbox
  PASS  #search/50%25+off                      -> gmail search: 50% off
  PASS  #search/from%3Aalice+is%3Aunread       -> gmail search: from:alice is:unread
  PASS  #label/Q1%20100%25                     -> gmail label: Q1 100%
  PASS  #label/Work%2FUrgent                   -> gmail label: Work/Urgent
  PASS  calendar/c_abc123%40group...           -> calendar: c_abc123@group.calendar.google.com
  PASS  bigquery/my-project/my_dataset/my_table -> bigquery: my-project / my_dataset / my_table

Note #search/50%25+off — the properly-escaped form of the same "50% off" search Gmail's own UI produces — still decodes correctly, and the +-to-space normalization above line 941 is untouched.

Pre-existing validation still fires (the fix doesn't swallow anything):

  PASS  #chats        -> Error: Unsupported Gmail view. ...
  PASS  #label/       -> Error: Gmail label name must be between 1 and 320 bytes.

Checks:

• pnpm lint:check — exit 0 (no new warnings; the one pre-existing google.ts warning is at line 2246, unrelated)
• pnpm --filter @gadgets/google-gatekeeper types:check — exit 0
• pnpm test — all suites pass except @gadgets/integration-tests, which fails identically on a clean tree at 0eaec6c (Could not resolve "./generated/format-blueprints.js"). Verified by stashing the patch and re-running: same failure, so it's pre-existing and unrelated.

Diff is 18 insertions / 4 deletions in one file.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[sarbojitrana]

I have read the CLA Document and I hereby sign the CLA

[sarbojitrana]

recheck

[kentonv]

Hi @sarbojitrana,

Apologies but, per our contributing guide, we prefer not to receive external pull requests. We prefer instead to receive issue reports, which we can then direct our own agents to solve. Could you please file an issue instead?