@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.
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +3 -0
- package/dist/config/config.d.ts.map +1 -1
- package/dist/config/config.js +2 -1
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +32 -1
- package/dist/http/webhookGuard.d.ts +9 -6
- package/dist/http/webhookGuard.d.ts.map +1 -1
- package/dist/http/webhookGuard.js +44 -8
- package/dist/rails/apple/x509.d.ts.map +1 -1
- package/dist/rails/apple/x509.js +6 -0
- package/dist/rails/google/oidc.d.ts +91 -31
- package/dist/rails/google/oidc.d.ts.map +1 -1
- package/dist/rails/google/oidc.js +144 -127
- package/dist/rails/google/playApi.js +1 -1
- package/dist/rails/google/rail.d.ts +25 -0
- package/dist/rails/google/rail.d.ts.map +1 -1
- package/dist/rails/google/rail.js +2 -1
- package/dist/rails/paddle/rail.d.ts +10 -1
- package/dist/rails/paddle/rail.d.ts.map +1 -1
- package/dist/rails/paddle/signature.d.ts +8 -2
- package/dist/rails/paddle/signature.d.ts.map +1 -1
- package/dist/rails/paddle/signature.js +17 -2
- package/dist/rails/providers.d.ts +15 -0
- package/dist/rails/providers.d.ts.map +1 -1
- package/dist/rails/providers.js +2 -1
- package/dist/rails/stripe/rail.d.ts +11 -1
- package/dist/rails/stripe/rail.d.ts.map +1 -1
- package/dist/rails/stripe/signature.d.ts +8 -1
- package/dist/rails/stripe/signature.d.ts.map +1 -1
- package/dist/secret/branches.d.ts +39 -0
- package/dist/secret/branches.d.ts.map +1 -0
- package/dist/secret/branches.js +46 -0
- package/dist/secret/registry.d.ts.map +1 -1
- package/dist/secret/registry.js +15 -15
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +11 -9
- package/src/capability.ts +7 -0
- package/src/config/config.ts +10 -1
- package/src/http/routes.ts +32 -1
- package/src/http/webhookGuard.ts +40 -7
- package/src/rails/apple/x509.ts +18 -0
- package/src/rails/google/oidc.ts +194 -218
- package/src/rails/google/rail.ts +28 -0
- package/src/rails/paddle/rail.ts +10 -1
- package/src/rails/paddle/signature.ts +39 -3
- package/src/rails/providers.ts +16 -0
- package/src/rails/stripe/rail.ts +11 -1
- package/src/rails/stripe/signature.ts +8 -1
- package/src/secret/branches.ts +48 -0
- package/src/secret/registry.ts +24 -2
- package/src/version.generated.ts +1 -1
package/src/rails/providers.ts
CHANGED
|
@@ -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 }),
|
package/src/rails/stripe/rail.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
+
}
|
package/src/secret/registry.ts
CHANGED
|
@@ -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
|
),
|
package/src/version.generated.ts
CHANGED