@pithy-sh/payments 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,2BAA2B,CAAC;AAU9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC;AAsMF,6FAA6F;AAC7F,MAAM,WAAW,kBACf,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,OAAO,iBAAiB,CAAC;IAC7F,4BAA4B;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAgGrE;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,kBAAkB,CAE7F"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,2BAA2B,CAAC;AAU9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC;AAsMF,6FAA6F;AAC7F,MAAM,WAAW,kBACf,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,OAAO,iBAAiB,CAAC;IAC7F,4BAA4B;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAmGrE;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,kBAAkB,CAE7F"}
@@ -10,7 +10,7 @@ import { paymentsWorkflows } from "./workflows/specs.js";
10
10
  import { paymentsAdminRoutes } from "./http/scopes.js";
11
11
  import { registerPaymentsRoutes } from "./http/routes.js";
12
12
  import { payments_0001_purchases } from "./migrations/0001_purchases.js";
13
- import { paymentsSecretBranches } from "./secret/branches.js";
13
+ import { paymentsInapplicableSecrets, paymentsSecretBranches } from "./secret/branches.js";
14
14
  import { paymentsExampleSeed } from "./seeds/example.js";
15
15
  import { PACKAGE_VERSION } from "./version.generated.js";
16
16
  import { defineCapability } from "@pithy-sh/core/src/capability/capability";
@@ -213,6 +213,7 @@ function payments(options) {
213
213
  providesEntitlements: true,
214
214
  secretRegistry: paymentsSecretsRegistry,
215
215
  secretBranches: paymentsSecretBranches(resolved.rails),
216
+ inapplicableSecrets: paymentsInapplicableSecrets(resolved.rails),
216
217
  workflows: paymentsWorkflows,
217
218
  compose: (context) => checkLedgerGrants(context, resolved),
218
219
  boot: () => requireImplementedSubject(resolveSubject),
@@ -1 +1 @@
1
- {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAEL,KAAK,cAAc,EAKpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAUzB,OAAO,EAAE,KAAK,mBAAmB,EAAkD,MAAM,4BAA4B,CAAC;AA0BtH,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AA2EhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsJG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AA2JD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,qCAAqC;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,4GAA4G;IAC5G,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,GACD;IACE,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,gBAAgB,GAC7B,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAmBtC;AAkPD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAm9DxG"}
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAU7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAEL,KAAK,cAAc,EAKpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAUzB,OAAO,EAAE,KAAK,mBAAmB,EAAkD,MAAM,4BAA4B,CAAC;AA0BtH,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AA2EhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsJG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AA2JD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,qCAAqC;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,4GAA4G;IAC5G,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,GACD;IACE,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,gBAAgB,GAC7B,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAmBtC;AAkPD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAi/DxG"}
@@ -30,6 +30,7 @@ import { InternalError, NotFoundError, PithyError, ValidationError } from "@pith
30
30
  import { zValidator } from "@hono/zod-validator";
31
31
  import { safeEmit } from "@pithy-sh/core/src/controlPlane/audit/actions";
32
32
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
33
+ import { memoryJwksCache } from "@pithy-sh/core/src/http/oidcWebhook";
33
34
  import { validationHook } from "@pithy-sh/core/src/http/validation";
34
35
  import { resolveWorkflowBinding } from "@pithy-sh/core/src/workflow/dispatch";
35
36
  import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
@@ -501,7 +502,37 @@ function registerPaymentsRoutes(options) {
501
502
  const { config } = options;
502
503
  const base = options.basePath ?? config.basePath;
503
504
  const clock = options.now ?? (() => /* @__PURE__ */ new Date());
504
- const trust = options.trust ?? {};
505
+ /**
506
+ * The caller's seams, plus the one thing a per-request rail cannot own: Google's key store.
507
+ *
508
+ * **Built here because this is the first thing in the chain that outlives a request.** `payments()` calls
509
+ * `registerPaymentsRoutes` once, at composition, so this object is constructed once per isolate and every
510
+ * delivery the Google webhook sees shares it. The rail below it is rebuilt per request by
511
+ * `resolveRailProvider` — a cache hung on that would be one that has never held anything — and the module
512
+ * variable that used to hold it is exactly what #520 deleted, because state no caller owns needs an
513
+ * exported `reset` for every suite that inherits it.
514
+ *
515
+ * **Owning the store is not the same as having none.** That is core's sentence, on `JwksCache`, about the
516
+ * surface anonymous traffic arrives on, and the Google webhook is one: the OIDC guard resolves a key by
517
+ * `kid` *before* it can check a signature, so with no store a forged token buys a round trip to Google,
518
+ * 1:1. Google rate-limits us, `fetchJwks` maps that to `core/upstream_failed`, and that code is in the
519
+ * webhook guard's pass-through set — so Pub/Sub redelivers the genuine notifications into the same
520
+ * uncached path. One anonymous caller, the whole rail down.
521
+ *
522
+ * **The store answers both floods, and only one of them is about a published `kid`.** What it holds
523
+ * collapses a forgery naming a key Google really publishes; `JwksCache.claimRefresh` — the window, one ask
524
+ * per `OIDC_JWKS_MIN_REFRESH_SECONDS` — collapses the cheaper one, the token naming a `kid` nobody has
525
+ * ever published, which is a miss and was therefore a fetch apiece however much was cached. Both live in
526
+ * this object, so a route passing its own store passes both bounds together.
527
+ *
528
+ * On `clock`, not wall time, so a suite injecting a clock governs the expiry too. A route wanting a bound
529
+ * harder than one isolate's memory — shared across isolates, or rate-limiting — passes its own
530
+ * `trust.googleJwksCache` and this one is never built.
531
+ */
532
+ const trust = {
533
+ ...options.trust ?? {},
534
+ googleJwksCache: options.trust?.googleJwksCache ?? memoryJwksCache({ now: clock })
535
+ };
505
536
  /** The seam `payments()` built, or the resolver-less one this config implies. See {@link PaymentsRoutesOptions.subject}. */
506
537
  const seam = options.subject ?? { billingSubject: config.billingSubject };
507
538
  /**
@@ -1,7 +1,8 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
+ import { type JwksCache, OidcJwk, OidcJwks } from "@pithy-sh/core/src/http/oidcWebhook";
3
4
  import { z } from "zod";
4
- import { type GoogleHttpFetch } from "./http";
5
+ import type { GoogleHttpFetch } from "./http";
5
6
  /**
6
7
  * The authenticity boundary on Google's webhook: the OIDC token a Pub/Sub push carries.
7
8
  *
@@ -17,21 +18,47 @@ import { type GoogleHttpFetch } from "./http";
17
18
  * for. Verify the signature and skip the audience and you have built an endpoint that accepts notifications
18
19
  * from any Google customer who points a subscription at it.
19
20
  *
20
- * Four checks, in this order, and the order is deliberate:
21
+ * ## Everything above is `@pithy-sh/core/src/http/oidcWebhook`, and none of it is here
21
22
  *
22
- * 1. **Pin the algorithm before touching a key.** `alg` arrives in a header nobody has verified, so it is
23
- * parsed against a literal `RS256` rather than looked up. That is what makes the two published confusions
24
- * unreachable — `none`, which asks for the signature to be skipped, and `HS256`, which asks the verifier to
25
- * HMAC with the public key as if it were a shared secret. Neither survives a literal.
26
- * 2. **Resolve the key by `kid` from Google's published set.** Never from the token, which is why there is no
27
- * `jwk`/`x5u` handling here: a token that carries its own key is a token that verifies itself.
28
- * 3. **Verify the signature over the exact received segments** — `header.claims` as encoded.
29
- * 4. **Then read the claims,** and only then, because a claim from an unverified token means nothing.
23
+ * Algorithm pinning, key resolution by `kid`, signature verification, issuer, audience, `exp`, `nbf`, `iat`,
24
+ * the JWKS fetch and its cache: one implementation, in core, shared with every other OIDC sender the kit
25
+ * verifies. This module is the **Google specialization** — two issuer spellings, a key endpoint, an audience,
26
+ * and the one claim pair Google's own guidance adds — and nothing else. A second copy of a verifier is a
27
+ * second thing to keep current, and the thing that would drift here is an authentication boundary (#520).
30
28
  *
31
- * A failure to *read* the token is `payments/invalid_receipt`; a token that is well-formed and does not check
32
- * out is `payments/verification_failed`. On the webhook path the guard maps either to
33
- * `payments/webhook_unverified` (401), so the distinction serves the operator reading `detail` rather than the
34
- * caller — and a forger is told nothing about how close it got.
29
+ * Core is stricter than the copy it replaced, deliberately: `nbf` is honored, a non-finite skew or key-set
30
+ * lifetime is refused rather than silently disabling the freshness checks, and a claim outside `Date`'s range
31
+ * is quoted as a number rather than throwing a `RangeError` while composing the refusal it had already
32
+ * decided on.
33
+ *
34
+ * ## What a refusal is called
35
+ *
36
+ * Core answers `core/webhook_unverified` for every failing step. The rail re-codes that to
37
+ * **`payments/verification_failed`**, so the audit trail's `metadata.step` stays a `payments/*` value and the
38
+ * webhook guard's pass-through set governs the rest. Core's `detail` rides along under a `Google:` prefix.
39
+ *
40
+ * `payments/invalid_receipt` no longer appears on this path, and that is a deliberate contract change rather
41
+ * than something the refactor dropped. It meant *the token could not be read*, which is a **receipt**
42
+ * distinction: `PaymentsRailProvider.verify` uses it for a client submission, where telling a developer that
43
+ * their payload is malformed is useful. A Pub/Sub push token is not a receipt, it is a webhook credential, and
44
+ * on the webhook path the guard already collapsed both codes to `payments/webhook_unverified` (401) before
45
+ * anything reached the sender — so no caller ever saw the difference, and core's own argument for one code
46
+ * applies with full force: a forger must not learn which check it tripped. Both codes were 400 and
47
+ * `verifyGoogleOidcToken` is not exported from the package, so the change is visible in exactly one place,
48
+ * the audit row's `metadata.step`.
49
+ *
50
+ * Two codes come from core untouched, because neither is a statement about the sender and both are already in
51
+ * the webhook guard's pass-through set: `core/internal` (500) for an endpoint of ours that is not configured
52
+ * to verify anything, and `core/upstream_failed` (502) for Google's key endpoint failing to answer. The
53
+ * second replaces `payments/provider_unavailable` (503) on the JWKS hop alone — CLAUDE.md §Errors gives the
54
+ * upstream pair exactly this job, and the Play Developer API hop is untouched and still 503.
55
+ *
56
+ * **A pass-through code is a code an anonymous caller must not be able to choose**, and that is what decided
57
+ * where the line sits. A published key that is not RSA, or will not import, used to be core's 502 and is
58
+ * core's 401 now: the key was reached because a `kid` in an unverified header selected it, so a 502 there
59
+ * let a forger pick a code this rail passes through — out of the audit trail, and into Pub/Sub's indefinite
60
+ * retry — by naming one `kid` instead of another. Nothing a `kid` can steer stays in the pass-through set.
61
+ * What is left in it is failure nobody chose: the endpoint being unreachable, and our own configuration.
35
62
  */
36
63
  /** Where Google publishes the keys that sign an OIDC token. Public, so it is pinned here rather than stored. */
37
64
  export declare const GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs";
@@ -41,8 +68,13 @@ export declare const GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/cer
41
68
  */
42
69
  export declare const GOOGLE_OIDC_ISSUERS: readonly string[];
43
70
  /**
44
- * One published RSA verification key, in the shape Google's key endpoint returns. `.loose()` because Google
45
- * adds fields and a key set must not be rejected for carrying something new.
71
+ * One published RSA verification key, and the key set Google's endpoint returns.
72
+ *
73
+ * Core's schemas under the rail's published names, not copies of them. The shape is the JWKS shape — it
74
+ * belongs to RFC 7517 rather than to Google — and two declarations of one wire format is the same drift this
75
+ * module exists to remove, one layer down. The names stay because they are `@pithy-sh/payments`' public
76
+ * surface and an adopter typing a Pub/Sub emulator's key against `GoogleJwk` should not have to learn a
77
+ * second one.
46
78
  */
47
79
  export declare const GoogleJwk: z.ZodObject<{
48
80
  kid: z.ZodString;
@@ -52,8 +84,7 @@ export declare const GoogleJwk: z.ZodObject<{
52
84
  alg: z.ZodOptional<z.ZodString>;
53
85
  use: z.ZodOptional<z.ZodString>;
54
86
  }, z.core.$loose>;
55
- export type GoogleJwk = z.infer<typeof GoogleJwk>;
56
- /** Google's published key set. At least one key: an empty set is an endpoint that is not answering properly. */
87
+ export type GoogleJwk = OidcJwk;
57
88
  export declare const GoogleJwks: z.ZodObject<{
58
89
  keys: z.ZodArray<z.ZodObject<{
59
90
  kid: z.ZodString;
@@ -64,19 +95,24 @@ export declare const GoogleJwks: z.ZodObject<{
64
95
  use: z.ZodOptional<z.ZodString>;
65
96
  }, z.core.$loose>>;
66
97
  }, z.core.$loose>;
67
- export type GoogleJwks = z.infer<typeof GoogleJwks>;
98
+ export type GoogleJwks = OidcJwks;
68
99
  /**
69
- * The claims a Pub/Sub push token carries, narrowed to the ones that decide anything. `.loose()` keeps the
70
- * rest — the whole token is never stored, but a claim set must not be refused for being richer than expected.
100
+ * The claims a Pub/Sub push token carries: core's, plus the two Google adds.
101
+ *
102
+ * `email` and `email_verified` are the extension, and they are the reason this schema exists at all — core
103
+ * reads what every OIDC token has and hands the rest to a predicate. Extended rather than redeclared, so
104
+ * `iss`/`aud`/`exp`/`nbf`/`iat` have one definition in the kit. Still `.loose()`: the whole token is never
105
+ * stored, and a claim set must not be refused for being richer than expected.
71
106
  */
72
107
  export declare const GoogleOidcClaims: z.ZodObject<{
73
108
  iss: z.ZodString;
74
109
  aud: z.ZodString;
110
+ sub: z.ZodOptional<z.ZodString>;
75
111
  exp: z.ZodNumber;
112
+ nbf: z.ZodOptional<z.ZodNumber>;
76
113
  iat: z.ZodOptional<z.ZodNumber>;
77
114
  email: z.ZodOptional<z.ZodString>;
78
115
  email_verified: z.ZodOptional<z.ZodBoolean>;
79
- sub: z.ZodOptional<z.ZodString>;
80
116
  }, z.core.$loose>;
81
117
  export type GoogleOidcClaims = z.infer<typeof GoogleOidcClaims>;
82
118
  /** What verifying a push token needs. Everything is explicit, so verification is deterministic in a test. */
@@ -93,26 +129,46 @@ export interface VerifyGoogleOidcOptions {
93
129
  * Keys accepted **in addition to** Google's published set, matched by `kid`.
94
130
  *
95
131
  * Additive, so nothing can narrow production's trust: a token whose `kid` these do not cover still resolves
96
- * against Google. Two callers have a real reason — the tests, which mint their own key so the signature check
97
- * is exercised for real, and a local Pub/Sub emulator, whose tokens are signed by a key Google never saw.
132
+ * against Google. Two callers have a real reason — the tests, which mint their own key so the signature
133
+ * check is exercised for real, and a local Pub/Sub emulator, whose tokens are signed by a key Google never
134
+ * saw.
98
135
  */
99
136
  trustedKeys?: readonly GoogleJwk[];
100
137
  /**
101
- * Tolerance on `exp` and `iat`, in seconds. Defaults to a minute, and must be a finite number from 0 to
102
- * {@link OIDC_MAX_CLOCK_SKEW_SECONDS}; anything else is `core/internal`, because this is the second operand
103
- * of both freshness comparisons and one `NaN` turns the pair into no-ops together.
138
+ * Tolerance on `exp`, `nbf` and `iat`, in seconds. Defaults to a minute, and must be a finite number from 0
139
+ * to core's maximum; anything else is `core/internal`, because this is the second operand of all three
140
+ * freshness comparisons and one `NaN` turns them into no-ops together.
104
141
  */
105
142
  clockSkewSeconds?: number;
143
+ /**
144
+ * How long a fetched key set is held. Defaults to core's hour, and must be a finite number of seconds — a
145
+ * `NaN` is an entry that never expires, which pins a key Google has rotated out.
146
+ */
147
+ jwksTtlSeconds?: number;
148
+ /**
149
+ * Where Google's fetched keys are held between deliveries.
150
+ *
151
+ * **Injected, and there is no default**, which is the point: this used to be a module variable no caller
152
+ * owned, and the only way a test suite could stop inheriting the previous one's keys was an exported
153
+ * `resetGoogleJwksCache` whose sole purpose was to undo it. With no cache the verifier fetches per call,
154
+ * which is correct and slow; a Worker that verifies more than one notification per hour passes a
155
+ * `memoryJwksCache` built once at module scope, or one over KV to share it across isolates.
156
+ *
157
+ * It is two bounds in one object: what Google published, and when Google was last asked. The second is
158
+ * what a token naming a `kid` nobody published runs into, and with no store there is no second bound
159
+ * either — which is why the webhook path is given one and the `verify` path is not.
160
+ */
161
+ jwksCache?: JwksCache;
106
162
  }
107
- /** Drop the cached key set. For tests, which must not inherit another suite's keys. */
108
- export declare function resetGoogleJwksCache(): void;
109
163
  /**
110
164
  * Verify one Pub/Sub push OIDC token and return its claims.
111
165
  *
112
- * @throws {@link PaymentsInvalidReceiptError} when the token cannot be read — wrong segment count, a header
113
- * Google would never send, a non-JSON segment.
114
- * @throws {@link PaymentsVerificationFailedError} when it is well-formed and does not check out — an unknown
115
- * key, a bad signature, the wrong audience, the wrong issuer, an expiry, the wrong service account.
166
+ * @throws {@link PaymentsVerificationFailedError} when the sender did not prove itself — an unreadable token,
167
+ * an unknown key, a key that cannot verify an `RS256` signature, a bad signature, the wrong audience, the
168
+ * wrong issuer, an expiry, the wrong service account.
169
+ * @throws `core/internal` (500) when this endpoint is not configured to verify anything — an audience that is
170
+ * empty, a clock that is not a clock, a skew or key-set lifetime that is not a number.
171
+ * @throws `core/upstream_failed` (502) when Google's key endpoint could not be read.
116
172
  */
117
173
  export declare function verifyGoogleOidcToken(token: string, options: VerifyGoogleOidcOptions): Promise<GoogleOidcClaims>;
118
174
  //# sourceMappingURL=oidc.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../../src/rails/google/oidc.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,eAAe,EAA+B,MAAM,QAAQ,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,gHAAgH;AAChH,eAAO,MAAM,eAAe,+CAA+C,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAA2D,CAAC;AA+B7G;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;iBAU0C,CAAC;AACjE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,gHAAgH;AAChH,eAAO,MAAM,UAAU;;;;;;;;;iBAKmC,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;iBAuBwE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,6GAA6G;AAC7G,MAAM,WAAW,uBAAuB;IACtC,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,GAAG,EAAE,IAAI,CAAC;IACV,iGAAiG;IACjG,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAWD,uFAAuF;AACvF,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AA6DD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CA8E3B"}
1
+ {"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../../src/rails/google/oidc.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,SAAS,EAAc,OAAO,EAAE,QAAQ,EAAmB,MAAM,qCAAqC,CAAC;AACrH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,gHAAgH;AAChH,eAAO,MAAM,eAAe,+CAA+C,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAA2D,CAAC;AAE7G;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS;;;;;;;iBAAU,CAAC;AACjC,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC;AAChC,eAAO,MAAM,UAAU;;;;;;;;;iBAAW,CAAC;AACnC,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;iBAUwE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,6GAA6G;AAC7G,MAAM,WAAW,uBAAuB;IACtC,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,GAAG,EAAE,IAAI,CAAC;IACV,iGAAiG;IACjG,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAwB3B"}