@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
|
@@ -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;;;;;
|
|
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"}
|
package/dist/secret/registry.js
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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/
|
|
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,
|
package/src/config/config.ts
CHANGED
|
@@ -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
|
-
|
|
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()
|
package/src/http/routes.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
package/src/http/webhookGuard.ts
CHANGED
|
@@ -78,10 +78,40 @@ function failingStep(cause: unknown): string {
|
|
|
78
78
|
return cause instanceof PithyError ? cause.payload.code : "unknown";
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
-
/**
|
|
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
|
-
* **
|
|
149
|
-
* store (`payments/provider_unavailable`) or cannot use its own credentials
|
|
150
|
-
* not judged the delivery at all — Google's rail must call the Play
|
|
151
|
-
* an outage there is ours, not the sender's.
|
|
152
|
-
*
|
|
153
|
-
*
|
|
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,
|
package/src/rails/apple/x509.ts
CHANGED
|
@@ -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(
|