@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
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import type { JwksCache } from "@pithy-sh/core/src/http/oidcWebhook";
4
5
  import type { PaymentsConfig } from "../config/config";
5
6
  import { productForProviderSku, railEnabled } from "../config/config";
6
7
  import type { PaymentsRail } from "../data/rail";
@@ -66,6 +67,20 @@ export interface RailTrustOptions {
66
67
  googleTransport?: GoogleHttpFetch;
67
68
  /** A Play access token already minted, so a batch of Google refreshes pays for one. */
68
69
  googleAccessToken?: string;
70
+ /**
71
+ * Where the Google rail holds Google's published verification keys between deliveries.
72
+ *
73
+ * **The third kind of seam, and the only one that is about availability rather than trust or cost.** A rail
74
+ * is built per request, so it cannot own a store that outlives one; the webhook path resolves a key before
75
+ * it can check a signature; and therefore with no store an anonymous POST buys a round trip to Google,
76
+ * 1:1 — whether it names a `kid` Google publishes, which the held keys answer, or one nobody ever
77
+ * published, which only the store's refresh window does. `registerPaymentsRoutes` supplies one per
78
+ * registered route tree when a caller gives none; this parameter is for the caller that wants a harder
79
+ * bound than an isolate's memory, a store over KV or the Cache API that every isolate shares — and sharing
80
+ * it shares the window with it. Additive to nothing and narrowing nothing: core still fetches for a `kid`
81
+ * the store does not hold once the window is over, which is how key rotation stays invisible.
82
+ */
83
+ googleJwksCache?: JwksCache;
69
84
  /** The HTTP transport the Stripe rail reaches Stripe's API through. Defaults to `fetch`. */
70
85
  stripeTransport?: StripeHttpFetch;
71
86
  /** The HTTP transport the Lemon Squeezy rail reaches its API through. Defaults to `fetch`. */
@@ -98,6 +113,7 @@ const RAIL_FACTORIES: Partial<Record<PaymentsRail, RailFactory>> = {
98
113
  trustedKeys: trust.googleTrustedKeys,
99
114
  transport: trust.googleTransport,
100
115
  accessToken: trust.googleAccessToken,
116
+ jwksCache: trust.googleJwksCache,
101
117
  }),
102
118
  stripe: (credentials, trust) =>
103
119
  stripeRail(railCredentials(credentials, "stripe"), { transport: trust.stripeTransport }),
@@ -50,7 +50,17 @@ import { parseStripeNotification } from "./webhook";
50
50
  export interface StripeRailOptions {
51
51
  /** The HTTP seam Stripe's API is reached through. Defaults to the runtime's `fetch`. */
52
52
  transport?: StripeHttpFetch;
53
- /** The signature freshness window, in seconds. Defaults to Stripe's own five minutes. */
53
+ /**
54
+ * The signature freshness window, in seconds. Defaults to Stripe's own five minutes.
55
+ *
56
+ * Threaded down unchanged and validated in exactly one place: `@pithy-sh/core`'s `checkSignedWebhook`, which
57
+ * refuses a non-finite, negative, or over-wide window as `core/internal` before it compares anything. This
58
+ * layer, `webhook.ts` and `signature.ts` each re-apply a default with `??` — which catches `undefined` and
59
+ * never `NaN` — and none of them re-checks the number. That is deliberate: one place that refuses is better
60
+ * than three that each half-check, and nothing on this path can reach the comparison without going through
61
+ * the primitive, so there is no bypass for a second check to cover. Three copies of the bound would only be
62
+ * three chances for one of them to drift.
63
+ */
54
64
  toleranceSeconds?: number;
55
65
  }
56
66
 
@@ -68,7 +68,14 @@ export type StripeSignatureHeader = SignedWebhookHeader;
68
68
  export interface VerifyStripeSignatureOptions {
69
69
  /** The clock. Injected so the replay window is deterministic in tests rather than wall-clock dependent. */
70
70
  now: Date;
71
- /** The freshness window, in seconds. Defaults to {@link STRIPE_SIGNATURE_TOLERANCE_SECONDS}. */
71
+ /**
72
+ * The freshness window, in seconds. Defaults to {@link STRIPE_SIGNATURE_TOLERANCE_SECONDS}.
73
+ *
74
+ * The `??` below applies that default and nothing more — a `NaN` passes it untouched, on purpose. The
75
+ * primitive owns the bound (`core/internal` for anything non-finite, negative, or over-wide) because it owns
76
+ * the comparison, and every caller on this path reaches it. See {@link ./rail.StripeRailOptions} for why the
77
+ * check is not repeated at each layer.
78
+ */
72
79
  toleranceSeconds?: number;
73
80
  }
74
81
 
@@ -0,0 +1,48 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ import type { SecretBranchSeam } from "@pithy-sh/core/src/capability/capability";
5
+ import type { PaymentsRailToggles } from "../config/config";
6
+ import { PAYMENTS_RAILS } from "../data/rail";
7
+ import { PAYMENTS_PROVIDER_SECRET } from "./registry";
8
+
9
+ /**
10
+ * **Which rails' credentials this project will actually be asked for.**
11
+ *
12
+ * `PaymentsProviderCredentials` is five optional blocks, because five rails are possible. Only the
13
+ * catalog says which are on, and a rail that is off "refuses its routes and its webhook" — so its
14
+ * credentials are a value nothing will ever read, and `pithy secrets create
15
+ * payments-provider-credentials` must neither offer them nor write them (#516).
16
+ *
17
+ * **The mapping is stated here rather than matched by name in the CLI.** `rails.paddle` and
18
+ * `PaymentsProviderCredentials.paddle` are spelled the same today, and that is a coincidence of two
19
+ * declarations in this package rather than a rule anything holds. A CLI keying off the spelling would
20
+ * be guessing, in the way #513 records: two things one line apart that convention cannot tell apart.
21
+ * This capability has the toggles and the schema in one hand at construction, so it answers.
22
+ *
23
+ * `PAYMENTS_RAILS` rather than `Object.keys(rails)` — one stable order for the prompts, and the same
24
+ * order every other per-rail sweep in this package uses.
25
+ */
26
+ export function paymentsSecretBranches(rails: PaymentsRailToggles): SecretBranchSeam {
27
+ return { [PAYMENTS_PROVIDER_SECRET]: PAYMENTS_RAILS.filter((rail) => rails[rail]) };
28
+ }
29
+
30
+ /**
31
+ * **The same question one level up: is the secret reachable at all (#541).**
32
+ *
33
+ * {@link paymentsSecretBranches} says which *blocks* of the bundle a project will be asked for. With
34
+ * every rail off there are none — and the bundle itself is then a value nothing will ever read, because
35
+ * every read of it is behind a rail: the checkout routes, the webhook guard, and the reconciliation
36
+ * Workflow each refuse before they reach the store. Every toggle defaults `false`, so this is the state
37
+ * `pithy add payments` leaves a project in until a rail is named, and `pithy doctor` listed the
38
+ * credential as outstanding work under *"fine to leave until you need it"* for the whole of it.
39
+ *
40
+ * Declared here rather than derived by the CLI from an empty branch list, for
41
+ * {@link paymentsSecretBranches}' own reason: an empty list is *no blocks to ask for*, which is not the
42
+ * same claim as *nothing reads this*, and a reporting command that conflated the two would be right by
43
+ * luck. The capability holds the toggles, so the capability answers.
44
+ */
45
+ export function paymentsInapplicableSecrets(rails: PaymentsRailToggles): Record<string, string> {
46
+ if (PAYMENTS_RAILS.some((rail) => rails[rail])) return {};
47
+ return { [PAYMENTS_PROVIDER_SECRET]: "payments() enables no rail, so no code path reads a credential" };
48
+ }
@@ -100,23 +100,33 @@ export const PaymentsAppleCredentials = z
100
100
  bundleId: z
101
101
  .string()
102
102
  .min(1)
103
+ .meta({ multiline: false })
103
104
  .describe(
104
105
  "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.",
105
106
  ),
106
107
  keyId: z
107
108
  .string()
108
109
  .min(1)
110
+ .meta({ multiline: false })
109
111
  .describe("The App Store Connect API key id — the `kid` of the token that calls the App Store Server API."),
110
112
  issuerId: z
111
113
  .string()
112
114
  .min(1)
115
+ .meta({ multiline: false })
113
116
  .describe("The App Store Connect issuer id, from the Keys page. The `iss` of that same token."),
114
117
  privateKey: z
115
118
  .string()
116
119
  .min(1)
117
120
  .describe(
118
121
  "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.",
119
- ),
122
+ )
123
+ // **A PEM spans lines, and that is a fact about how it can be asked for.** `pithy secrets create`
124
+ // prompts a `json` secret one field at a time (#516) through a masked, single-line prompt, which
125
+ // submits at the first newline and feeds the rest of the paste to the questions after it — every
126
+ // fragment satisfying `min(1)`, so the corrupt bundle *validates* and surfaces as a failed
127
+ // signature months later. The marker is what makes this whole secret fall back to one prompt for
128
+ // one JSON document, where the newline is escaped and nothing splits.
129
+ .meta({ multiline: true }),
120
130
  })
121
131
  .describe("Apple's credentials: the app's identity, and the App Store Connect key that signs server-API calls.");
122
132
  export type PaymentsAppleCredentials = z.infer<typeof PaymentsAppleCredentials>;
@@ -126,12 +136,14 @@ export const PaymentsGoogleCredentials = z
126
136
  packageName: z
127
137
  .string()
128
138
  .min(1)
139
+ .meta({ multiline: false })
129
140
  .describe(
130
141
  "The Android application id. What a Play purchase token is looked up against, and the equivalent of Apple's bundle id.",
131
142
  ),
132
143
  serviceAccountEmail: z
133
144
  .string()
134
145
  .min(1)
146
+ .meta({ multiline: false })
135
147
  .describe(
136
148
  "The Google Cloud service account that reads the Play Developer API and is the audience of the Pub/Sub push token.",
137
149
  ),
@@ -140,10 +152,13 @@ export const PaymentsGoogleCredentials = z
140
152
  .min(1)
141
153
  .describe(
142
154
  "The service account's private key, as the downloaded JSON's `private_key` field. Supplied, never minted.",
143
- ),
155
+ )
156
+ // A PEM again, and marked for the reason Apple's `privateKey` is: see the comment there.
157
+ .meta({ multiline: true }),
144
158
  pubsubAudience: z
145
159
  .string()
146
160
  .min(1)
161
+ .meta({ multiline: false })
147
162
  .describe(
148
163
  "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.",
149
164
  ),
@@ -156,12 +171,14 @@ export const PaymentsStripeCredentials = z
156
171
  secretKey: z
157
172
  .string()
158
173
  .min(1)
174
+ .meta({ multiline: false })
159
175
  .describe(
160
176
  "The Stripe secret API key — `sk_live_…` or `sk_test_…`. Creates Checkout and Billing Portal sessions.",
161
177
  ),
162
178
  webhookSecret: z
163
179
  .string()
164
180
  .min(1)
181
+ .meta({ multiline: false })
165
182
  .describe(
166
183
  "The webhook endpoint's signing secret — `whsec_…`. What the `Stripe-Signature` HMAC is checked against, and the one Stripe rotates.",
167
184
  ),
@@ -174,18 +191,21 @@ export const PaymentsLemonSqueezyCredentials = z
174
191
  apiKey: z
175
192
  .string()
176
193
  .min(1)
194
+ .meta({ multiline: false })
177
195
  .describe(
178
196
  "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.",
179
197
  ),
180
198
  webhookSecret: z
181
199
  .string()
182
200
  .min(1)
201
+ .meta({ multiline: false })
183
202
  .describe(
184
203
  "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.",
185
204
  ),
186
205
  storeId: z
187
206
  .string()
188
207
  .min(1)
208
+ .meta({ multiline: false })
189
209
  .describe(
190
210
  "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.",
191
211
  ),
@@ -198,12 +218,14 @@ export const PaymentsPaddleCredentials = z
198
218
  apiKey: z
199
219
  .string()
200
220
  .min(1)
221
+ .meta({ multiline: false })
201
222
  .describe(
202
223
  "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.",
203
224
  ),
204
225
  webhookSecret: z
205
226
  .string()
206
227
  .min(1)
228
+ .meta({ multiline: false })
207
229
  .describe(
208
230
  "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.",
209
231
  ),
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/payments";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.2.0";
16
+ export const PACKAGE_VERSION = "0.3.0";