@pithy-sh/payments 0.2.0 → 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.
Files changed (53) hide show
  1. package/dist/capability.d.ts.map +1 -1
  2. package/dist/capability.js +3 -0
  3. package/dist/config/config.d.ts.map +1 -1
  4. package/dist/config/config.js +2 -1
  5. package/dist/http/routes.d.ts.map +1 -1
  6. package/dist/http/routes.js +32 -1
  7. package/dist/http/webhookGuard.d.ts +9 -6
  8. package/dist/http/webhookGuard.d.ts.map +1 -1
  9. package/dist/http/webhookGuard.js +44 -8
  10. package/dist/rails/apple/x509.d.ts.map +1 -1
  11. package/dist/rails/apple/x509.js +6 -0
  12. package/dist/rails/google/oidc.d.ts +91 -31
  13. package/dist/rails/google/oidc.d.ts.map +1 -1
  14. package/dist/rails/google/oidc.js +144 -127
  15. package/dist/rails/google/playApi.js +1 -1
  16. package/dist/rails/google/rail.d.ts +25 -0
  17. package/dist/rails/google/rail.d.ts.map +1 -1
  18. package/dist/rails/google/rail.js +2 -1
  19. package/dist/rails/paddle/rail.d.ts +10 -1
  20. package/dist/rails/paddle/rail.d.ts.map +1 -1
  21. package/dist/rails/paddle/signature.d.ts +8 -2
  22. package/dist/rails/paddle/signature.d.ts.map +1 -1
  23. package/dist/rails/paddle/signature.js +17 -2
  24. package/dist/rails/providers.d.ts +15 -0
  25. package/dist/rails/providers.d.ts.map +1 -1
  26. package/dist/rails/providers.js +2 -1
  27. package/dist/rails/stripe/rail.d.ts +11 -1
  28. package/dist/rails/stripe/rail.d.ts.map +1 -1
  29. package/dist/rails/stripe/signature.d.ts +8 -1
  30. package/dist/rails/stripe/signature.d.ts.map +1 -1
  31. package/dist/secret/branches.d.ts +39 -0
  32. package/dist/secret/branches.d.ts.map +1 -0
  33. package/dist/secret/branches.js +46 -0
  34. package/dist/secret/registry.d.ts.map +1 -1
  35. package/dist/secret/registry.js +15 -15
  36. package/dist/version.generated.d.ts +1 -1
  37. package/dist/version.generated.js +1 -1
  38. package/package.json +11 -9
  39. package/src/capability.ts +7 -0
  40. package/src/config/config.ts +10 -1
  41. package/src/http/routes.ts +32 -1
  42. package/src/http/webhookGuard.ts +40 -7
  43. package/src/rails/apple/x509.ts +18 -0
  44. package/src/rails/google/oidc.ts +194 -218
  45. package/src/rails/google/rail.ts +28 -0
  46. package/src/rails/paddle/rail.ts +10 -1
  47. package/src/rails/paddle/signature.ts +39 -3
  48. package/src/rails/providers.ts +16 -0
  49. package/src/rails/stripe/rail.ts +11 -1
  50. package/src/rails/stripe/signature.ts +8 -1
  51. package/src/secret/branches.ts +48 -0
  52. package/src/secret/registry.ts +24 -2
  53. package/src/version.generated.ts +1 -1
@@ -0,0 +1,39 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { SecretBranchSeam } from "@pithy-sh/core/src/capability/capability";
4
+ import type { PaymentsRailToggles } from "../config/config";
5
+ /**
6
+ * **Which rails' credentials this project will actually be asked for.**
7
+ *
8
+ * `PaymentsProviderCredentials` is five optional blocks, because five rails are possible. Only the
9
+ * catalog says which are on, and a rail that is off "refuses its routes and its webhook" — so its
10
+ * credentials are a value nothing will ever read, and `pithy secrets create
11
+ * payments-provider-credentials` must neither offer them nor write them (#516).
12
+ *
13
+ * **The mapping is stated here rather than matched by name in the CLI.** `rails.paddle` and
14
+ * `PaymentsProviderCredentials.paddle` are spelled the same today, and that is a coincidence of two
15
+ * declarations in this package rather than a rule anything holds. A CLI keying off the spelling would
16
+ * be guessing, in the way #513 records: two things one line apart that convention cannot tell apart.
17
+ * This capability has the toggles and the schema in one hand at construction, so it answers.
18
+ *
19
+ * `PAYMENTS_RAILS` rather than `Object.keys(rails)` — one stable order for the prompts, and the same
20
+ * order every other per-rail sweep in this package uses.
21
+ */
22
+ export declare function paymentsSecretBranches(rails: PaymentsRailToggles): SecretBranchSeam;
23
+ /**
24
+ * **The same question one level up: is the secret reachable at all (#541).**
25
+ *
26
+ * {@link paymentsSecretBranches} says which *blocks* of the bundle a project will be asked for. With
27
+ * every rail off there are none — and the bundle itself is then a value nothing will ever read, because
28
+ * every read of it is behind a rail: the checkout routes, the webhook guard, and the reconciliation
29
+ * Workflow each refuse before they reach the store. Every toggle defaults `false`, so this is the state
30
+ * `pithy add payments` leaves a project in until a rail is named, and `pithy doctor` listed the
31
+ * credential as outstanding work under *"fine to leave until you need it"* for the whole of it.
32
+ *
33
+ * Declared here rather than derived by the CLI from an empty branch list, for
34
+ * {@link paymentsSecretBranches}' own reason: an empty list is *no blocks to ask for*, which is not the
35
+ * same claim as *nothing reads this*, and a reporting command that conflated the two would be right by
36
+ * luck. The capability holds the toggles, so the capability answers.
37
+ */
38
+ export declare function paymentsInapplicableSecrets(rails: PaymentsRailToggles): Record<string, string>;
39
+ //# sourceMappingURL=branches.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"branches.d.ts","sourceRoot":"","sources":["../../src/secret/branches.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAI5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB,CAEnF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG9F"}
@@ -0,0 +1,46 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { PAYMENTS_RAILS } from "../data/rail.js";
4
+ import { PAYMENTS_PROVIDER_SECRET } from "./registry.js";
5
+ //#region src/secret/branches.ts
6
+ /**
7
+ * **Which rails' credentials this project will actually be asked for.**
8
+ *
9
+ * `PaymentsProviderCredentials` is five optional blocks, because five rails are possible. Only the
10
+ * catalog says which are on, and a rail that is off "refuses its routes and its webhook" — so its
11
+ * credentials are a value nothing will ever read, and `pithy secrets create
12
+ * payments-provider-credentials` must neither offer them nor write them (#516).
13
+ *
14
+ * **The mapping is stated here rather than matched by name in the CLI.** `rails.paddle` and
15
+ * `PaymentsProviderCredentials.paddle` are spelled the same today, and that is a coincidence of two
16
+ * declarations in this package rather than a rule anything holds. A CLI keying off the spelling would
17
+ * be guessing, in the way #513 records: two things one line apart that convention cannot tell apart.
18
+ * This capability has the toggles and the schema in one hand at construction, so it answers.
19
+ *
20
+ * `PAYMENTS_RAILS` rather than `Object.keys(rails)` — one stable order for the prompts, and the same
21
+ * order every other per-rail sweep in this package uses.
22
+ */
23
+ function paymentsSecretBranches(rails) {
24
+ return { [PAYMENTS_PROVIDER_SECRET]: PAYMENTS_RAILS.filter((rail) => rails[rail]) };
25
+ }
26
+ /**
27
+ * **The same question one level up: is the secret reachable at all (#541).**
28
+ *
29
+ * {@link paymentsSecretBranches} says which *blocks* of the bundle a project will be asked for. With
30
+ * every rail off there are none — and the bundle itself is then a value nothing will ever read, because
31
+ * every read of it is behind a rail: the checkout routes, the webhook guard, and the reconciliation
32
+ * Workflow each refuse before they reach the store. Every toggle defaults `false`, so this is the state
33
+ * `pithy add payments` leaves a project in until a rail is named, and `pithy doctor` listed the
34
+ * credential as outstanding work under *"fine to leave until you need it"* for the whole of it.
35
+ *
36
+ * Declared here rather than derived by the CLI from an empty branch list, for
37
+ * {@link paymentsSecretBranches}' own reason: an empty list is *no blocks to ask for*, which is not the
38
+ * same claim as *nothing reads this*, and a reporting command that conflated the two would be right by
39
+ * luck. The capability holds the toggles, so the capability answers.
40
+ */
41
+ function paymentsInapplicableSecrets(rails) {
42
+ if (PAYMENTS_RAILS.some((rail) => rails[rail])) return {};
43
+ return { [PAYMENTS_PROVIDER_SECRET]: "payments() enables no rail, so no code path reads a credential" };
44
+ }
45
+ //#endregion
46
+ export { paymentsInapplicableSecrets, paymentsSecretBranches };
@@ -1 +1 @@
1
- {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,kCAAkC,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAUzE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,iHAC0E,CAAC;AAEjH,eAAO,MAAM,wBAAwB;;;;;kBAuB6E,CAAC;AACnH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;;;;kBA2BiF,CAAC;AACxH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,yBAAyB;;;kBAe2E,CAAC;AAClH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,+BAA+B;;;;kBAqBkE,CAAC;AAC/G,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE9F,eAAO,MAAM,yBAAyB;;;kBAiBnC,CAAC;AACJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYrC,CAAC;AACJ,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBlC,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,WAAW,EAAE,2BAA2B,EACxC,IAAI,EAAE,CAAC,GACN,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAS7C"}
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,kCAAkC,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAUzE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,iHAC0E,CAAC;AAEjH,eAAO,MAAM,wBAAwB;;;;;kBAiC6E,CAAC;AACnH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;;;;kBAgCiF,CAAC;AACxH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,yBAAyB;;;kBAiB2E,CAAC;AAClH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,+BAA+B;;;;kBAwBkE,CAAC;AAC/G,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE9F,eAAO,MAAM,yBAAyB;;;kBAmBnC,CAAC;AACJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYrC,CAAC;AACJ,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBlC,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,WAAW,EAAE,2BAA2B,EACxC,IAAI,EAAE,CAAC,GACN,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAS7C"}
@@ -85,29 +85,29 @@ const PAYMENTS_RAIL_CONSOLES = {
85
85
  */
86
86
  const PAYMENTS_CREDENTIALS_PAGE = "https://github.com/pithy-sh/pithy/blob/main/docs/commands/payments.md#where-each-rails-credentials-come-from";
87
87
  const PaymentsAppleCredentials = z.strictObject({
88
- bundleId: z.string().min(1).describe("The app's bundle id. Not a secret, but part of the app's identity at Apple: every notification and receipt is checked against it, because an Apple signature proves Apple signed the payload and never that it is about this app."),
89
- keyId: z.string().min(1).describe("The App Store Connect API key id — the `kid` of the token that calls the App Store Server API."),
90
- issuerId: z.string().min(1).describe("The App Store Connect issuer id, from the Keys page. The `iss` of that same token."),
91
- privateKey: z.string().min(1).describe("The App Store Connect private key, the `.p8` file's contents including its PEM header and footer. Downloadable exactly once from App Store Connect, so it is supplied rather than minted.")
88
+ bundleId: z.string().min(1).meta({ multiline: false }).describe("The app's bundle id. Not a secret, but part of the app's identity at Apple: every notification and receipt is checked against it, because an Apple signature proves Apple signed the payload and never that it is about this app."),
89
+ keyId: z.string().min(1).meta({ multiline: false }).describe("The App Store Connect API key id — the `kid` of the token that calls the App Store Server API."),
90
+ issuerId: z.string().min(1).meta({ multiline: false }).describe("The App Store Connect issuer id, from the Keys page. The `iss` of that same token."),
91
+ privateKey: z.string().min(1).describe("The App Store Connect private key, the `.p8` file's contents including its PEM header and footer. Downloadable exactly once from App Store Connect, so it is supplied rather than minted.").meta({ multiline: true })
92
92
  }).describe("Apple's credentials: the app's identity, and the App Store Connect key that signs server-API calls.");
93
93
  const PaymentsGoogleCredentials = z.strictObject({
94
- packageName: z.string().min(1).describe("The Android application id. What a Play purchase token is looked up against, and the equivalent of Apple's bundle id."),
95
- serviceAccountEmail: z.string().min(1).describe("The Google Cloud service account that reads the Play Developer API and is the audience of the Pub/Sub push token."),
96
- privateKey: z.string().min(1).describe("The service account's private key, as the downloaded JSON's `private_key` field. Supplied, never minted."),
97
- pubsubAudience: z.string().min(1).describe("The audience the Pub/Sub push OIDC token must claim. Checked on every notification: a token with the right signature and the wrong audience is one issued for somebody else's endpoint.")
94
+ packageName: z.string().min(1).meta({ multiline: false }).describe("The Android application id. What a Play purchase token is looked up against, and the equivalent of Apple's bundle id."),
95
+ serviceAccountEmail: z.string().min(1).meta({ multiline: false }).describe("The Google Cloud service account that reads the Play Developer API and is the audience of the Pub/Sub push token."),
96
+ privateKey: z.string().min(1).describe("The service account's private key, as the downloaded JSON's `private_key` field. Supplied, never minted.").meta({ multiline: true }),
97
+ pubsubAudience: z.string().min(1).meta({ multiline: false }).describe("The audience the Pub/Sub push OIDC token must claim. Checked on every notification: a token with the right signature and the wrong audience is one issued for somebody else's endpoint.")
98
98
  }).describe("Google's credentials: the app's identity, the Play Developer API service account, and the push audience.");
99
99
  const PaymentsStripeCredentials = z.strictObject({
100
- secretKey: z.string().min(1).describe("The Stripe secret API key — `sk_live_…` or `sk_test_…`. Creates Checkout and Billing Portal sessions."),
101
- webhookSecret: z.string().min(1).describe("The webhook endpoint's signing secret — `whsec_…`. What the `Stripe-Signature` HMAC is checked against, and the one Stripe rotates.")
100
+ secretKey: z.string().min(1).meta({ multiline: false }).describe("The Stripe secret API key — `sk_live_…` or `sk_test_…`. Creates Checkout and Billing Portal sessions."),
101
+ webhookSecret: z.string().min(1).meta({ multiline: false }).describe("The webhook endpoint's signing secret — `whsec_…`. What the `Stripe-Signature` HMAC is checked against, and the one Stripe rotates.")
102
102
  }).describe("Stripe's credentials: the secret key that creates hosted sessions, and the webhook signing secret.");
103
103
  const PaymentsLemonSqueezyCredentials = z.strictObject({
104
- apiKey: z.string().min(1).describe("The Lemon Squeezy API key. Creates hosted checkouts, reads orders and subscriptions, and mints customer-portal links. Account-wide: it returns test-mode objects to a production deployment too, which is why `test_mode` on the object — never the key — decides a purchase's environment."),
105
- webhookSecret: z.string().min(1).describe("The webhook's signing secret, set when the webhook is created. What the `X-Signature` HMAC-SHA256 over the exact received body is checked against."),
106
- storeId: z.string().min(1).describe("The Lemon Squeezy store id this deployment sells through. Account-level identity, the way Apple's `bundleId` is, which is why it sits with the credentials rather than in config.")
104
+ apiKey: z.string().min(1).meta({ multiline: false }).describe("The Lemon Squeezy API key. Creates hosted checkouts, reads orders and subscriptions, and mints customer-portal links. Account-wide: it returns test-mode objects to a production deployment too, which is why `test_mode` on the object — never the key — decides a purchase's environment."),
105
+ webhookSecret: z.string().min(1).meta({ multiline: false }).describe("The webhook's signing secret, set when the webhook is created. What the `X-Signature` HMAC-SHA256 over the exact received body is checked against."),
106
+ storeId: z.string().min(1).meta({ multiline: false }).describe("The Lemon Squeezy store id this deployment sells through. Account-level identity, the way Apple's `bundleId` is, which is why it sits with the credentials rather than in config.")
107
107
  }).describe("Lemon Squeezy's credentials: the API key, the webhook signing secret, and the store's identity.");
108
108
  const PaymentsPaddleCredentials = z.strictObject({
109
- apiKey: z.string().min(1).describe("The Paddle API key — `pdl_live_apikey_…` or `pdl_sdbx_apikey_…`. Creates transactions and discounts, reads subscriptions and the event stream, and mints customer-portal sessions. It needs `customer_portal_session.write`, or Paddle returns a portal session with no authenticated URLs and the buyer lands on a sign-in page."),
110
- webhookSecret: z.string().min(1).describe("The notification destination's signing secret — `pdl_ntfset_…`. What the `Paddle-Signature` HMAC-SHA256 over `ts:body` is checked against, and the key the checkout's ownership proof is domain-separated under.")
109
+ apiKey: z.string().min(1).meta({ multiline: false }).describe("The Paddle API key — `pdl_live_apikey_…` or `pdl_sdbx_apikey_…`. Creates transactions and discounts, reads subscriptions and the event stream, and mints customer-portal sessions. It needs `customer_portal_session.write`, or Paddle returns a portal session with no authenticated URLs and the buyer lands on a sign-in page."),
110
+ webhookSecret: z.string().min(1).meta({ multiline: false }).describe("The notification destination's signing secret — `pdl_ntfset_…`. What the `Paddle-Signature` HMAC-SHA256 over `ts:body` is checked against, and the key the checkout's ownership proof is domain-separated under.")
111
111
  }).describe("Paddle's credentials: the API key, and the notification destination's signing secret. The client token is not here — it is publishable by design and lives in config, because putting it behind the secrets store would suggest verification depended on its secrecy.");
112
112
  const PaymentsProviderCredentials = z.strictObject({
113
113
  apple: PaymentsAppleCredentials.optional().describe("Apple's credentials, when the Apple rail is enabled."),
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/payments";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.2.0";
6
+ export declare const PACKAGE_VERSION = "0.3.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/payments";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.2.0";
7
+ const PACKAGE_VERSION = "0.3.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/payments",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -36,8 +36,15 @@
36
36
  "clean": "rm -rf dist .turbo",
37
37
  "reset": "bun run clean && rm -rf node_modules"
38
38
  },
39
+ "dependencies": {
40
+ "@cloudflare/workers-types": "^5.20260729.1",
41
+ "@hono/zod-validator": "^0.9.0",
42
+ "@paddle/paddle-js": "^1.6.4"
43
+ },
39
44
  "peerDependencies": {
40
- "@pithy-sh/ledger": "^0.1.5",
45
+ "@pithy-sh/core": "^0.4.0",
46
+ "@pithy-sh/ledger": "^0.2.0",
47
+ "@pithy-sh/secrets": "^0.2.0",
41
48
  "hono": "^4.13.2",
42
49
  "kysely": "^0.29.0",
43
50
  "react": "^19.0.0",
@@ -51,16 +58,11 @@
51
58
  "optional": true
52
59
  }
53
60
  },
54
- "dependencies": {
55
- "@cloudflare/workers-types": "^5.20260729.1",
56
- "@hono/zod-validator": "^0.9.0",
57
- "@paddle/paddle-js": "^1.6.4",
58
- "@pithy-sh/core": "^0.2.0",
59
- "@pithy-sh/secrets": "^0.1.5"
60
- },
61
61
  "devDependencies": {
62
62
  "@cloudflare/vitest-plugin": "^1.0.0",
63
+ "@pithy-sh/core": "workspace:*",
63
64
  "@pithy-sh/ledger": "workspace:*",
65
+ "@pithy-sh/secrets": "workspace:*",
64
66
  "@pithy-sh/tsconfig": "workspace:*",
65
67
  "@types/node": "^22.15.0",
66
68
  "@types/react": "^19.2.17",
package/src/capability.ts CHANGED
@@ -22,6 +22,7 @@ import { paymentsManifestConfig } from "./http/manifestConfig";
22
22
  import { registerPaymentsRoutes } from "./http/routes";
23
23
  import { paymentsAdminRoutes } from "./http/scopes";
24
24
  import { payments_0001_purchases } from "./migrations/0001_purchases";
25
+ import { paymentsInapplicableSecrets, paymentsSecretBranches } from "./secret/branches";
25
26
  import { paymentsSecretsRegistry } from "./secret/registry";
26
27
  import { paymentsExampleSeed } from "./seeds/example";
27
28
  import { PACKAGE_VERSION } from "./version.generated";
@@ -343,6 +344,12 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
343
344
  // One secret holds every rail's credentials. Declaring the slice here is what lets `sharedSecretsStore`
344
345
  // resolve it — a read of a name no composed capability declared throws.
345
346
  secretRegistry: paymentsSecretsRegistry,
347
+ // Which rails' credentials `pithy secrets create payments-provider-credentials` asks for. The
348
+ // schema knows five are possible; only this catalog knows which are on. See `secret/branches.ts`.
349
+ secretBranches: paymentsSecretBranches(resolved.rails),
350
+ // And whether the bundle is reachable at all. With every rail off, every read of it is behind a
351
+ // refusal — so it is not outstanding work, and `pithy doctor` asked for it anyway (#541).
352
+ inapplicableSecrets: paymentsInapplicableSecrets(resolved.rails),
346
353
  // The one durable job: the nightly reconciliation pass. Declared here so `createBackend` derives its
347
354
  // binding and types `c.var.workflows.trigger("payments/reconcile", …)` precisely.
348
355
  workflows: paymentsWorkflows,
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import { EntitlementKey } from "@pithy-sh/core/src/entitlement/entitlement";
5
+ import { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS } from "@pithy-sh/core/src/http/webhookWindow";
5
6
  import { z } from "zod";
6
7
  import { PAYMENTS_RAILS, type PaymentsRail } from "../data/rail";
7
8
  import { PaymentsSubjectType } from "../data/subject";
@@ -182,13 +183,21 @@ export const PaymentsPaddleSettings = z
182
183
  cancelUrl: ReturnUrl.optional().describe(
183
184
  "Where a buyer who backs out lands, in `hosted` mode. Optional, because an overlay a buyer closes leaves them exactly where they were.",
184
185
  ),
186
+ // The ceiling is deliberately **not** a `.max()` here, and the reason is blast radius rather than
187
+ // taste. This schema is parsed at module scope — `payments()` calls `PaymentsConfig.parse` — so a
188
+ // refusal on this one field takes the whole Worker down: every route, including the ones that have
189
+ // never heard of Paddle. A project that had legitimately set a wider window would have discovered
190
+ // that on a patch upgrade, as a dead deployment rather than a dead endpoint. The window is enforced
191
+ // where it is used instead, in `verifyPaddleSignature`, which is on the only path that compares it
192
+ // and cannot be reached around; a bad number there costs the Paddle webhook route and nothing else,
193
+ // and Paddle keeps redelivering while it is fixed. Fail closed, for one route.
185
194
  webhookFreshnessSeconds: z
186
195
  .number()
187
196
  .int()
188
197
  .positive()
189
198
  .optional()
190
199
  .describe(
191
- "How many seconds either side of now a delivery's `ts` may be dated. Omitted uses 300, deliberately not the 5 Paddle's own SDKs use: replay protection here is the webhook table's `UNIQUE (rail, providerEventId)`, which is absolute, and a five-second window adds nothing to that while turning ordinary clock skew into a dropped renewal.",
200
+ `How many seconds either side of now a delivery's \`ts\` may be dated. Omitted uses 300, deliberately not the 5 Paddle's own SDKs use: replay protection here is the webhook table's \`UNIQUE (rail, providerEventId)\`, which is absolute, and a five-second window adds nothing to that while turning ordinary clock skew into a dropped renewal. Bounded at ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} because a freshness window is a replay window: every second of it is a second longer a captured delivery keeps working. That bound is enforced by the verifier rather than by this schema, so a number past it refuses the Paddle webhook route with \`core/internal\` naming this key, instead of refusing to boot the Worker.`,
192
201
  ),
193
202
  storeCurrency: z
194
203
  .string()
@@ -8,6 +8,7 @@ import { safeEmit } from "@pithy-sh/core/src/controlPlane/audit/actions";
8
8
  import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
9
9
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
10
10
  import { InternalError, NotFoundError, PithyError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
11
+ import { memoryJwksCache } from "@pithy-sh/core/src/http/oidcWebhook";
11
12
  import { validationHook } from "@pithy-sh/core/src/http/validation";
12
13
  import { resolveWorkflowBinding } from "@pithy-sh/core/src/workflow/dispatch";
13
14
  import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
@@ -909,7 +910,37 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
909
910
  const { config } = options;
910
911
  const base = options.basePath ?? config.basePath;
911
912
  const clock = options.now ?? (() => new Date());
912
- const trust = options.trust ?? {};
913
+ /**
914
+ * The caller's seams, plus the one thing a per-request rail cannot own: Google's key store.
915
+ *
916
+ * **Built here because this is the first thing in the chain that outlives a request.** `payments()` calls
917
+ * `registerPaymentsRoutes` once, at composition, so this object is constructed once per isolate and every
918
+ * delivery the Google webhook sees shares it. The rail below it is rebuilt per request by
919
+ * `resolveRailProvider` — a cache hung on that would be one that has never held anything — and the module
920
+ * variable that used to hold it is exactly what #520 deleted, because state no caller owns needs an
921
+ * exported `reset` for every suite that inherits it.
922
+ *
923
+ * **Owning the store is not the same as having none.** That is core's sentence, on `JwksCache`, about the
924
+ * surface anonymous traffic arrives on, and the Google webhook is one: the OIDC guard resolves a key by
925
+ * `kid` *before* it can check a signature, so with no store a forged token buys a round trip to Google,
926
+ * 1:1. Google rate-limits us, `fetchJwks` maps that to `core/upstream_failed`, and that code is in the
927
+ * webhook guard's pass-through set — so Pub/Sub redelivers the genuine notifications into the same
928
+ * uncached path. One anonymous caller, the whole rail down.
929
+ *
930
+ * **The store answers both floods, and only one of them is about a published `kid`.** What it holds
931
+ * collapses a forgery naming a key Google really publishes; `JwksCache.claimRefresh` — the window, one ask
932
+ * per `OIDC_JWKS_MIN_REFRESH_SECONDS` — collapses the cheaper one, the token naming a `kid` nobody has
933
+ * ever published, which is a miss and was therefore a fetch apiece however much was cached. Both live in
934
+ * this object, so a route passing its own store passes both bounds together.
935
+ *
936
+ * On `clock`, not wall time, so a suite injecting a clock governs the expiry too. A route wanting a bound
937
+ * harder than one isolate's memory — shared across isolates, or rate-limiting — passes its own
938
+ * `trust.googleJwksCache` and this one is never built.
939
+ */
940
+ const trust: RailTrustOptions = {
941
+ ...(options.trust ?? {}),
942
+ googleJwksCache: options.trust?.googleJwksCache ?? memoryJwksCache({ now: clock }),
943
+ };
913
944
  /** The seam `payments()` built, or the resolver-less one this config implies. See {@link PaymentsRoutesOptions.subject}. */
914
945
  const seam: PaymentsSubjectSeam = options.subject ?? { billingSubject: config.billingSubject };
915
946
 
@@ -78,10 +78,40 @@ function failingStep(cause: unknown): string {
78
78
  return cause instanceof PithyError ? cause.payload.code : "unknown";
79
79
  }
80
80
 
81
- /** The codes a rail may raise that describe our side rather than the sender's, and so keep their own status. */
81
+ /**
82
+ * The codes a rail may raise that describe our side rather than the sender's, and so keep their own status.
83
+ *
84
+ * **Membership is decided by whose fault the code names, not by its status.** `payments/rail_not_configured`
85
+ * is a 404 and `core/internal` is a 500; what they share is that neither is a statement about the caller, so
86
+ * re-coding either as `payments/webhook_unverified` would be a lie in the one direction that costs the most —
87
+ * it names a culprit, and the culprit is us.
88
+ *
89
+ * The three `core/*` members are what #521 added, and they are the reason this set exists as a set. The
90
+ * signed-webhook verifiers now refuse a freshness window that is not a window — a `NaN` from
91
+ * `Number(env.STRIPE_WEBHOOK_TOLERANCE)` on a variable nobody set — as `core/internal`, because a comparison
92
+ * against `NaN` deletes the replay window rather than widening it. Caught here and re-rendered as a 401, that
93
+ * refusal arrived at the operator as *"check the webhook signing secret"*: it blamed the sender for our
94
+ * configuration, sent whoever was debugging to the one place the answer is not, and wrote an audit row saying
95
+ * a forgery had arrived when none had. CLAUDE.md §Errors gives a 500-class code exactly one job — *read **our**
96
+ * logs* — and laundering it into a 401 destroys that job entirely.
97
+ *
98
+ * `core/upstream_failed` and `core/upstream_timeout` ride along for the same reason `payments/provider_unavailable`
99
+ * already does: they are the shared-client spelling of a hop into something we do not control, and
100
+ * `workflows/retryPolicy.ts` already classifies the three together. Nothing on the verification path raises
101
+ * them today; the set is the place that would have to be edited if one ever did, and forgetting is what this
102
+ * comment exists to prevent.
103
+ *
104
+ * **The client boundary is untouched by any of this.** Every one of these still leaves through `clientError`,
105
+ * which strips `action` and `detail` — so the sender learns a status and a bland `message`, and the knob's
106
+ * name reaches the terminal, the `--json` line and the log alone. What changed is that the operator's surface
107
+ * and the status code stop saying *bad signature* when the truth is *this endpoint is misconfigured*.
108
+ */
82
109
  const PASS_THROUGH_CODES: ReadonlySet<string> = new Set([
83
110
  "payments/provider_unavailable",
84
111
  "payments/rail_not_configured",
112
+ "core/internal",
113
+ "core/upstream_failed",
114
+ "core/upstream_timeout",
85
115
  ]);
86
116
 
87
117
  /** A verified delivery, as the handler receives it: the notification, and the row recording it. */
@@ -145,12 +175,15 @@ function database(c: Context<PithyHonoEnv>): D1Database {
145
175
  * distinction helps a developer; on a webhook it would only tell a forger how close it got. The original code
146
176
  * rides in `detail`, which the HTTP codec strips.
147
177
  *
148
- * **Two codes pass through unchanged, because they are not the caller's failure.** A rail that cannot reach its
149
- * store (`payments/provider_unavailable`) or cannot use its own credentials (`payments/rail_not_configured`) has
150
- * not judged the delivery at all — Google's rail must call the Play Developer API to resolve a notification, and
151
- * an outage there is ours, not the sender's. Reporting either as a failed signature would send an operator
152
- * hunting for a rotated key while the real answer is in a status page, and would tell the audit trail a forgery
153
- * arrived when none did. Both remain non-2xx, so the provider still redelivers.
178
+ * **{@link PASS_THROUGH_CODES} pass through unchanged, because they are not the caller's failure.** A rail that
179
+ * cannot reach its store (`payments/provider_unavailable`) or cannot use its own credentials
180
+ * (`payments/rail_not_configured`) has not judged the delivery at all — Google's rail must call the Play
181
+ * Developer API to resolve a notification, and an outage there is ours, not the sender's. A rail handed a
182
+ * freshness window that is not a number (`core/internal`) has not judged it either, and that one is our
183
+ * configuration rather than our dependency's weather. Reporting any of them as a failed signature would send an
184
+ * operator hunting for a rotated key while the real answer is in a status page or in one line of
185
+ * `wrangler.jsonc`, and would tell the audit trail a forgery arrived when none did. All remain non-2xx, so the
186
+ * provider still redelivers.
154
187
  */
155
188
  export function requireSignedWebhook(
156
189
  rail: PaymentsRail,
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
4
5
  import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors";
5
6
  import {
6
7
  ASN1_BOOLEAN,
@@ -354,7 +355,24 @@ export async function verifyCertificateChain(
354
355
  }
355
356
 
356
357
  const certificates = chain.map((der) => parseCertificate(der));
358
+ // The fourth instance of #521's shape, in the package the sweep was written from. `at` is one operand of
359
+ // both comparisons below, and `NaN < x` and `NaN > x` are false alike — so an invalid `now` does not widen
360
+ // the validity window, it deletes it, and every certificate in the chain passes the one check that says a
361
+ // certificate is still in date. That is the whole of expiry: a leaf Apple retired years ago, or one whose
362
+ // `notBefore` has not arrived, would verify against a chain that still roots in the pinned certificate.
363
+ //
364
+ // `InternalError`, not `rejected()`. Only a caller-supplied clock reaches here — the certificate's own
365
+ // dates are parsed from ASN.1 and are `Date`s or a `malformed` throw — so this is our configuration, and
366
+ // the 400 `rejected()` raises would tell a buyer their purchase is invalid over our broken clock.
357
367
  const at = options.now.getTime();
368
+ if (!Number.isFinite(at)) {
369
+ throw new InternalError({
370
+ message: "That purchase could not be verified.",
371
+ action: "Give the Apple rail a valid clock.",
372
+ detail:
373
+ "X.509: chain verification was handed a clock that is not a valid Date, so no certificate's validity window can be judged.",
374
+ });
375
+ }
358
376
  for (const [index, certificate] of certificates.entries()) {
359
377
  if (at < certificate.notBefore.getTime() || at > certificate.notAfter.getTime()) {
360
378
  throw rejected(