@pithy-sh/payments 0.2.0 → 0.2.1
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 +2 -0
- package/dist/config/config.d.ts.map +1 -1
- package/dist/config/config.js +2 -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 +5 -1
- package/dist/rails/google/oidc.d.ts.map +1 -1
- package/dist/rails/google/oidc.js +12 -0
- 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/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 +23 -0
- package/dist/secret/branches.d.ts.map +1 -0
- package/dist/secret/branches.js +27 -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 +4 -4
- package/src/capability.ts +4 -0
- package/src/config/config.ts +10 -1
- package/src/http/webhookGuard.ts +40 -7
- package/src/rails/apple/x509.ts +18 -0
- package/src/rails/google/oidc.ts +28 -1
- package/src/rails/paddle/rail.ts +10 -1
- package/src/rails/paddle/signature.ts +39 -3
- package/src/rails/stripe/rail.ts +11 -1
- package/src/rails/stripe/signature.ts +8 -1
- package/src/secret/branches.ts +28 -0
- package/src/secret/registry.ts +24 -2
- package/src/version.generated.ts +1 -1
package/dist/capability.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,2BAA2B,CAAC;AAU9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC;AAsMF,6FAA6F;AAC7F,MAAM,WAAW,kBACf,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,OAAO,iBAAiB,CAAC;IAC7F,4BAA4B;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAgGrE;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,kBAAkB,CAE7F"}
|
package/dist/capability.js
CHANGED
|
@@ -10,6 +10,7 @@ import { paymentsWorkflows } from "./workflows/specs.js";
|
|
|
10
10
|
import { paymentsAdminRoutes } from "./http/scopes.js";
|
|
11
11
|
import { registerPaymentsRoutes } from "./http/routes.js";
|
|
12
12
|
import { payments_0001_purchases } from "./migrations/0001_purchases.js";
|
|
13
|
+
import { paymentsSecretBranches } from "./secret/branches.js";
|
|
13
14
|
import { paymentsExampleSeed } from "./seeds/example.js";
|
|
14
15
|
import { PACKAGE_VERSION } from "./version.generated.js";
|
|
15
16
|
import { defineCapability } from "@pithy-sh/core/src/capability/capability";
|
|
@@ -211,6 +212,7 @@ function payments(options) {
|
|
|
211
212
|
dependsOn: ["secrets"],
|
|
212
213
|
providesEntitlements: true,
|
|
213
214
|
secretRegistry: paymentsSecretsRegistry,
|
|
215
|
+
secretBranches: paymentsSecretBranches(resolved.rails),
|
|
214
216
|
workflows: paymentsWorkflows,
|
|
215
217
|
compose: (context) => checkLedgerGrants(context, resolved),
|
|
216
218
|
boot: () => requireImplementedSubject(resolveSubject),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAoCjE,eAAO,MAAM,mBAAmB;;;;;;iBA6B+E,CAAC;AAChH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,mBAAmB;;;;EAI7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,oBAAoB;;iBAQyE,CAAC;AAC3G,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,eAAO,MAAM,qBAAqB;;iBAQuE,CAAC;AAC1G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,qBAAqB;;iBAUkE,CAAC;AACrG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,2BAA2B;;iBAUgE,CAAC;AACzG,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,eAAO,MAAM,4BAA4B;;;iBAetC,CAAC;AACJ,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF,eAAO,MAAM,qBAAqB;;iBAUkE,CAAC;AACrG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;kBAmDhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC5E,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEjF,eAAO,MAAM,sBAAsB;;;;iBAUhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,mBAAmB;;;iBAYwD,CAAC;AACzF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,cAAc;;;;;iBAMyF,CAAC;AACrH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCyE,CAAC;AACtG,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0LvB,CAAC;AACL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAC7D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACnE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAC3E,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEjF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,yGAAyG;AACzG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAalG;AAED,wGAAwG;AACxG,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAGnG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,MAAM,GACV,oBAAoB,GAAG,SAAS,CAKlC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,WAAW,CAAC,MAAM,CAAC,CAIjF;AAED,8GAA8G;AAC9G,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE5F;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAE/E"}
|
package/dist/config/config.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
import { PAYMENTS_RAILS } from "../data/rail.js";
|
|
4
4
|
import { PaymentsSubjectType } from "../data/subject.js";
|
|
5
5
|
import { EntitlementKey } from "@pithy-sh/core/src/entitlement/entitlement";
|
|
6
|
+
import { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS } from "@pithy-sh/core/src/http/webhookWindow";
|
|
6
7
|
import { z } from "zod";
|
|
7
8
|
//#region src/config/config.ts
|
|
8
9
|
/**
|
|
@@ -61,7 +62,7 @@ const PaymentsPaddleSettings = z.strictObject({
|
|
|
61
62
|
environment: z.enum(["sandbox", "production"]).describe("Which Paddle account this project sells through. Paddle Billing partitions sandbox from live by account — separate host, separate key, separate notification destinations — so this decides both the API host and every purchase's recorded environment. There is no `mode` field on a Paddle payload that could contradict it."),
|
|
62
63
|
successUrl: ReturnUrl.describe("Where a buyer lands after paying. Used as `settings.successUrl` for Paddle.js and as the redirect target in `hosted` mode. Build it on `PUBLIC_ORIGIN`, never on a literal."),
|
|
63
64
|
cancelUrl: ReturnUrl.optional().describe("Where a buyer who backs out lands, in `hosted` mode. Optional, because an overlay a buyer closes leaves them exactly where they were."),
|
|
64
|
-
webhookFreshnessSeconds: z.number().int().positive().optional().describe(
|
|
65
|
+
webhookFreshnessSeconds: z.number().int().positive().optional().describe(`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.`),
|
|
65
66
|
storeCurrency: z.string().regex(CURRENCY_CODE_PATTERN, "A currency code is lowercase, digits, and dashes.").optional().describe("The currency this Paddle catalog prices in, lowercase ISO 4217 — `usd`. Optional, and the only thing it does is let a fixed-amount discount in another currency be refused when it is created rather than when a customer redeems it. Paddle accepts the mismatched object and fails at redemption, so without this the error arrives at the buyer instead of at you.")
|
|
66
67
|
}).describe("How this project sells through Paddle. `strictObject`, and that is what refuses `portalReturnUrl`: Paddle's customer portal takes no return parameter, so accepting one and dropping it would leave a URL an adopter wrote and believed in that nothing ever reads — a lie in a file they trust.");
|
|
67
68
|
const PaymentsStripeSettings = z.object({
|
|
@@ -38,12 +38,15 @@ export interface WebhookGuardOptions {
|
|
|
38
38
|
* distinction helps a developer; on a webhook it would only tell a forger how close it got. The original code
|
|
39
39
|
* rides in `detail`, which the HTTP codec strips.
|
|
40
40
|
*
|
|
41
|
-
* **
|
|
42
|
-
* store (`payments/provider_unavailable`) or cannot use its own credentials
|
|
43
|
-
* not judged the delivery at all — Google's rail must call the Play
|
|
44
|
-
* an outage there is ours, not the sender's.
|
|
45
|
-
*
|
|
46
|
-
*
|
|
41
|
+
* **{@link PASS_THROUGH_CODES} pass through unchanged, because they are not the caller's failure.** A rail that
|
|
42
|
+
* cannot reach its store (`payments/provider_unavailable`) or cannot use its own credentials
|
|
43
|
+
* (`payments/rail_not_configured`) has not judged the delivery at all — Google's rail must call the Play
|
|
44
|
+
* Developer API to resolve a notification, and an outage there is ours, not the sender's. A rail handed a
|
|
45
|
+
* freshness window that is not a number (`core/internal`) has not judged it either, and that one is our
|
|
46
|
+
* configuration rather than our dependency's weather. Reporting any of them as a failed signature would send an
|
|
47
|
+
* operator hunting for a rotated key while the real answer is in a status page or in one line of
|
|
48
|
+
* `wrangler.jsonc`, and would tell the audit trail a forgery arrived when none did. All remain non-2xx, so the
|
|
49
|
+
* provider still redelivers.
|
|
47
50
|
*/
|
|
48
51
|
export declare function requireSignedWebhook(rail: PaymentsRail, options: WebhookGuardOptions): MiddlewareHandler<PithyHonoEnv>;
|
|
49
52
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"webhookGuard.d.ts","sourceRoot":"","sources":["../../src/http/webhookGuard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAM7E,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;
|
|
1
|
+
{"version":3,"file":"webhookGuard.d.ts","sourceRoot":"","sources":["../../src/http/webhookGuard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAM7E,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AAkGhF,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,+FAA+F;IAC/F,YAAY,EAAE,oBAAoB,CAAC;IACnC,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,eAAe,CAQzE;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,mBAAmB,GAC3B,iBAAiB,CAAC,YAAY,CAAC,CA6GjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAenH"}
|
|
@@ -68,8 +68,41 @@ import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
|
68
68
|
function failingStep(cause) {
|
|
69
69
|
return cause instanceof PithyError ? cause.payload.code : "unknown";
|
|
70
70
|
}
|
|
71
|
-
/**
|
|
72
|
-
|
|
71
|
+
/**
|
|
72
|
+
* The codes a rail may raise that describe our side rather than the sender's, and so keep their own status.
|
|
73
|
+
*
|
|
74
|
+
* **Membership is decided by whose fault the code names, not by its status.** `payments/rail_not_configured`
|
|
75
|
+
* is a 404 and `core/internal` is a 500; what they share is that neither is a statement about the caller, so
|
|
76
|
+
* re-coding either as `payments/webhook_unverified` would be a lie in the one direction that costs the most —
|
|
77
|
+
* it names a culprit, and the culprit is us.
|
|
78
|
+
*
|
|
79
|
+
* The three `core/*` members are what #521 added, and they are the reason this set exists as a set. The
|
|
80
|
+
* signed-webhook verifiers now refuse a freshness window that is not a window — a `NaN` from
|
|
81
|
+
* `Number(env.STRIPE_WEBHOOK_TOLERANCE)` on a variable nobody set — as `core/internal`, because a comparison
|
|
82
|
+
* against `NaN` deletes the replay window rather than widening it. Caught here and re-rendered as a 401, that
|
|
83
|
+
* refusal arrived at the operator as *"check the webhook signing secret"*: it blamed the sender for our
|
|
84
|
+
* configuration, sent whoever was debugging to the one place the answer is not, and wrote an audit row saying
|
|
85
|
+
* a forgery had arrived when none had. CLAUDE.md §Errors gives a 500-class code exactly one job — *read **our**
|
|
86
|
+
* logs* — and laundering it into a 401 destroys that job entirely.
|
|
87
|
+
*
|
|
88
|
+
* `core/upstream_failed` and `core/upstream_timeout` ride along for the same reason `payments/provider_unavailable`
|
|
89
|
+
* already does: they are the shared-client spelling of a hop into something we do not control, and
|
|
90
|
+
* `workflows/retryPolicy.ts` already classifies the three together. Nothing on the verification path raises
|
|
91
|
+
* them today; the set is the place that would have to be edited if one ever did, and forgetting is what this
|
|
92
|
+
* comment exists to prevent.
|
|
93
|
+
*
|
|
94
|
+
* **The client boundary is untouched by any of this.** Every one of these still leaves through `clientError`,
|
|
95
|
+
* which strips `action` and `detail` — so the sender learns a status and a bland `message`, and the knob's
|
|
96
|
+
* name reaches the terminal, the `--json` line and the log alone. What changed is that the operator's surface
|
|
97
|
+
* and the status code stop saying *bad signature* when the truth is *this endpoint is misconfigured*.
|
|
98
|
+
*/
|
|
99
|
+
const PASS_THROUGH_CODES = /* @__PURE__ */ new Set([
|
|
100
|
+
"payments/provider_unavailable",
|
|
101
|
+
"payments/rail_not_configured",
|
|
102
|
+
"core/internal",
|
|
103
|
+
"core/upstream_failed",
|
|
104
|
+
"core/upstream_timeout"
|
|
105
|
+
]);
|
|
73
106
|
/**
|
|
74
107
|
* Request-scoped, keyed on the `Request` object so an entry cannot outlive its request and cannot be reached
|
|
75
108
|
* from another one. Weak, so a dropped request drops its entry with no bookkeeping.
|
|
@@ -102,12 +135,15 @@ function database(c) {
|
|
|
102
135
|
* distinction helps a developer; on a webhook it would only tell a forger how close it got. The original code
|
|
103
136
|
* rides in `detail`, which the HTTP codec strips.
|
|
104
137
|
*
|
|
105
|
-
* **
|
|
106
|
-
* store (`payments/provider_unavailable`) or cannot use its own credentials
|
|
107
|
-
* not judged the delivery at all — Google's rail must call the Play
|
|
108
|
-
* an outage there is ours, not the sender's.
|
|
109
|
-
*
|
|
110
|
-
*
|
|
138
|
+
* **{@link PASS_THROUGH_CODES} pass through unchanged, because they are not the caller's failure.** A rail that
|
|
139
|
+
* cannot reach its store (`payments/provider_unavailable`) or cannot use its own credentials
|
|
140
|
+
* (`payments/rail_not_configured`) has not judged the delivery at all — Google's rail must call the Play
|
|
141
|
+
* Developer API to resolve a notification, and an outage there is ours, not the sender's. A rail handed a
|
|
142
|
+
* freshness window that is not a number (`core/internal`) has not judged it either, and that one is our
|
|
143
|
+
* configuration rather than our dependency's weather. Reporting any of them as a failed signature would send an
|
|
144
|
+
* operator hunting for a rotated key while the real answer is in a status page or in one line of
|
|
145
|
+
* `wrangler.jsonc`, and would tell the audit trail a forgery arrived when none did. All remain non-2xx, so the
|
|
146
|
+
* provider still redelivers.
|
|
111
147
|
*/
|
|
112
148
|
function requireSignedWebhook(rail, options) {
|
|
113
149
|
return async (c, next) => {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"x509.d.ts","sourceRoot":"","sources":["../../../src/rails/apple/x509.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"x509.d.ts","sourceRoot":"","sources":["../../../src/rails/apple/x509.ts"],"names":[],"mappings":"AAsFA;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,8BAA8B,CAAC;AACpE,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAStE,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,4GAA4G;AAC5G,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,GAAG,EAAE,UAAU,CAAC;IAChB,sGAAsG;IACtG,GAAG,EAAE,UAAU,CAAC;IAChB,gGAAgG;IAChG,MAAM,EAAE,UAAU,CAAC;IACnB,8BAA8B;IAC9B,OAAO,EAAE,UAAU,CAAC;IACpB,0CAA0C;IAC1C,SAAS,EAAE,IAAI,CAAC;IAChB,iCAAiC;IACjC,QAAQ,EAAE,IAAI,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAC;IACjB,yCAAyC;IACzC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,wEAAwE;IACxE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,SAAS,EAAE,UAAU,CAAC;IACtB,6GAA6G;IAC7G,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC9C,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,sGAAsG;IACtG,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,yGAAyG;AACzG,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1B;AAED,iGAAiG;AACjG,MAAM,WAAW,kBAAkB;IACjC,gGAAgG;IAChG,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,mEAAmE;IACnE,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,sGAAsG;IACtG,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AA6FD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,iBAAiB,CAuCnE;AAiCD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA8FvB"}
|
package/dist/rails/apple/x509.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors.js";
|
|
4
4
|
import { asn1Children, bytesEqual, decodeBase64, derSignatureToRaw, readAsn1, readBits, readBoolean, readInteger, readOid } from "./der.js";
|
|
5
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
6
|
//#region src/rails/apple/x509.ts
|
|
6
7
|
/**
|
|
7
8
|
* X.509 certificates, and the chain check that makes an Apple signature mean something.
|
|
@@ -234,6 +235,11 @@ async function verifyCertificateChain(chain, options) {
|
|
|
234
235
|
if (chain.length > MAX_CHAIN_LENGTH) throw rejected(`X.509: a chain of ${chain.length} is longer than the ${MAX_CHAIN_LENGTH} accepted.`);
|
|
235
236
|
const certificates = chain.map((der) => parseCertificate(der));
|
|
236
237
|
const at = options.now.getTime();
|
|
238
|
+
if (!Number.isFinite(at)) throw new InternalError({
|
|
239
|
+
message: "That purchase could not be verified.",
|
|
240
|
+
action: "Give the Apple rail a valid clock.",
|
|
241
|
+
detail: "X.509: chain verification was handed a clock that is not a valid Date, so no certificate's validity window can be judged."
|
|
242
|
+
});
|
|
237
243
|
for (const [index, certificate] of certificates.entries()) if (at < certificate.notBefore.getTime() || at > certificate.notAfter.getTime()) throw rejected(`X.509: certificate ${index} is valid ${certificate.notBefore.toISOString()}–${certificate.notAfter.toISOString()}.`);
|
|
238
244
|
const root = certificates[certificates.length - 1];
|
|
239
245
|
if (!options.roots.some((encoded) => bytesEqual(decodeBase64(encoded), root.der))) throw rejected("X.509: the chain's root is not one of the pinned roots.");
|
|
@@ -97,7 +97,11 @@ export interface VerifyGoogleOidcOptions {
|
|
|
97
97
|
* is exercised for real, and a local Pub/Sub emulator, whose tokens are signed by a key Google never saw.
|
|
98
98
|
*/
|
|
99
99
|
trustedKeys?: readonly GoogleJwk[];
|
|
100
|
-
/**
|
|
100
|
+
/**
|
|
101
|
+
* Tolerance on `exp` and `iat`, in seconds. Defaults to a minute, and must be a finite number from 0 to
|
|
102
|
+
* {@link OIDC_MAX_CLOCK_SKEW_SECONDS}; anything else is `core/internal`, because this is the second operand
|
|
103
|
+
* of both freshness comparisons and one `NaN` turns the pair into no-ops together.
|
|
104
|
+
*/
|
|
101
105
|
clockSkewSeconds?: number;
|
|
102
106
|
}
|
|
103
107
|
/** Drop the cached key set. For tests, which must not inherit another suite's keys. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../../src/rails/google/oidc.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../../src/rails/google/oidc.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,eAAe,EAA+B,MAAM,QAAQ,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,gHAAgH;AAChH,eAAO,MAAM,eAAe,+CAA+C,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAA2D,CAAC;AA+B7G;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;iBAU0C,CAAC;AACjE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,gHAAgH;AAChH,eAAO,MAAM,UAAU;;;;;;;;;iBAKmC,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;iBAuBwE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,6GAA6G;AAC7G,MAAM,WAAW,uBAAuB;IACtC,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,GAAG,EAAE,IAAI,CAAC;IACV,iGAAiG;IACjG,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAWD,uFAAuF;AACvF,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AA6DD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CA8E3B"}
|
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors.js";
|
|
4
4
|
import { googleHttpFetch, googleJson } from "./http.js";
|
|
5
5
|
import { base64UrlDecode, decodeJwtJson, splitJwt } from "./jwt.js";
|
|
6
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
6
7
|
import { z } from "zod";
|
|
8
|
+
import { OIDC_MAX_CLOCK_SKEW_SECONDS } from "@pithy-sh/core/src/http/oidcWebhook";
|
|
7
9
|
//#region src/rails/google/oidc.ts
|
|
8
10
|
/**
|
|
9
11
|
* The authenticity boundary on Google's webhook: the OIDC token a Pub/Sub push carries.
|
|
@@ -160,7 +162,17 @@ async function verifyGoogleOidcToken(token, options) {
|
|
|
160
162
|
if (!parsed.success) throw new PaymentsVerificationFailedError({ detail: `Google: the token claims are not those of a Pub/Sub push token — ${issues(parsed.error)}.` });
|
|
161
163
|
const claims = parsed.data;
|
|
162
164
|
const skew = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
|
|
165
|
+
if (!Number.isFinite(skew) || skew < 0 || skew > OIDC_MAX_CLOCK_SKEW_SECONDS) throw new InternalError({
|
|
166
|
+
message: "This webhook endpoint is not configured.",
|
|
167
|
+
action: `Give the Google Pub/Sub webhook a clock skew between 0 and ${OIDC_MAX_CLOCK_SKEW_SECONDS} seconds.`,
|
|
168
|
+
detail: `Google: the push-token check was given a clock skew of ${String(skew)} seconds, and a tolerance must be a number from 0 to ${OIDC_MAX_CLOCK_SKEW_SECONDS}.`
|
|
169
|
+
});
|
|
163
170
|
const seconds = Math.floor(options.now.getTime() / 1e3);
|
|
171
|
+
if (!Number.isFinite(seconds)) throw new InternalError({
|
|
172
|
+
message: "This webhook endpoint is not configured.",
|
|
173
|
+
action: "Give the Google Pub/Sub webhook a valid clock.",
|
|
174
|
+
detail: "Google: the push-token check was handed a clock that is not a valid Date, so no token's freshness can be judged."
|
|
175
|
+
});
|
|
164
176
|
if (!GOOGLE_OIDC_ISSUERS.includes(claims.iss)) throw failed(`the token issuer is "${claims.iss}", not one of Google's.`);
|
|
165
177
|
if (claims.aud !== options.audience) throw failed(`the token audience is "${claims.aud}", and this endpoint expects "${options.audience}".`);
|
|
166
178
|
if (claims.exp + skew < seconds) throw failed(`the token expired at ${(/* @__PURE__ */ new Date(claims.exp * 1e3)).toISOString()}.`);
|
|
@@ -40,7 +40,16 @@ export interface PaddleRailOptions {
|
|
|
40
40
|
clientToken: string;
|
|
41
41
|
/** Whether checkout opens as an overlay, inline, or on Paddle's own hosted page. */
|
|
42
42
|
checkout: "overlay" | "inline" | "hosted";
|
|
43
|
-
/**
|
|
43
|
+
/**
|
|
44
|
+
* How many seconds either side of now a delivery may be dated. Undefined uses the rail's 300.
|
|
45
|
+
*
|
|
46
|
+
* Threaded down unchanged through `webhook.ts` and validated in one place, `signature.ts`, where the
|
|
47
|
+
* comparison is — a non-finite, negative, or over-wide window is `core/internal` there, refused before any
|
|
48
|
+
* delivery is judged. The layers between only apply defaults with `??`, which catches `undefined` and never
|
|
49
|
+
* `NaN`; one place that refuses beats three that each half-check. `paddle.webhookFreshnessSeconds` reaches
|
|
50
|
+
* this field and is deliberately **not** bounded again in `PaymentsPaddleSettings`: that schema parses at
|
|
51
|
+
* module scope, so a bound there refuses the whole Worker for one webhook route's knob.
|
|
52
|
+
*/
|
|
44
53
|
freshnessSeconds?: number;
|
|
45
54
|
/**
|
|
46
55
|
* The currency this project's Paddle catalog prices in, when the project declared one.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rail.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/rail.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAEV,YAAY,EAEZ,YAAY,EAEZ,oBAAoB,EAGpB,WAAW,EAEX,UAAU,EAIV,gBAAgB,EAKjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAmB,MAAM,OAAO,CAAC;AAkBtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C
|
|
1
|
+
{"version":3,"file":"rail.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/rail.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAEV,YAAY,EAEZ,YAAY,EAEZ,oBAAoB,EAGpB,WAAW,EAEX,UAAU,EAIV,gBAAgB,EAKjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAmB,MAAM,OAAO,CAAC;AAkBtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,uBAAuB;AACvB,wBAAgB,UAAU,CACxB,WAAW,EAAE,yBAAyB,EACtC,OAAO,EAAE,iBAAiB,GACzB,oBAAoB,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,gBAAgB,GAAG,UAAU,CAqHlG"}
|
|
@@ -38,7 +38,9 @@
|
|
|
38
38
|
* The window still earns its place, in both directions. It bounds how long a captured-but-never-delivered
|
|
39
39
|
* signature stays usable, and it refuses a far-future timestamp — either a broken clock or somebody trying
|
|
40
40
|
* to mint a delivery that never goes stale. Configurable, so an adopter who wants Paddle's number can set
|
|
41
|
-
* it.
|
|
41
|
+
* it — bounded, and checked before it is used, because a window is only a boundary while it is a number. A
|
|
42
|
+
* non-finite tolerance makes `drift > tolerance` false for every delivery ever signed, which is not a wider
|
|
43
|
+
* window but no window at all.
|
|
42
44
|
*
|
|
43
45
|
* Paddle re-signs each retry attempt with a fresh `ts`, which is the only way a three-day retry window and
|
|
44
46
|
* a five-second SDK tolerance could both be coherent — so the window does not silently reject retries.
|
|
@@ -60,7 +62,11 @@ export interface VerifyPaddleSignatureOptions {
|
|
|
60
62
|
secret: string;
|
|
61
63
|
/** The clock, for the freshness window. Injected so verification is deterministic. */
|
|
62
64
|
now: Date;
|
|
63
|
-
/**
|
|
65
|
+
/**
|
|
66
|
+
* How many seconds either side of `now` a delivery may be dated. Undefined uses the default, and anything
|
|
67
|
+
* present must be a finite number from 0 to {@link SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} — anything else is
|
|
68
|
+
* `core/internal`, because a `NaN` here does not widen the window, it removes it.
|
|
69
|
+
*/
|
|
64
70
|
toleranceSeconds?: number;
|
|
65
71
|
}
|
|
66
72
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/signature.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/signature.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,wGAAwG;AACxG,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,2GAA2G;AAC3G,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAkBpD,uFAAuF;AACvF,MAAM,WAAW,4BAA4B;IAC3C,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA+BD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASrG;AA2CD;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CA4Cf"}
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { PaymentsVerificationFailedError } from "../../error/errors.js";
|
|
4
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
|
+
import { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS } from "@pithy-sh/core/src/http/webhookWindow";
|
|
4
6
|
//#region src/rails/paddle/signature.ts
|
|
5
7
|
/**
|
|
6
8
|
* Paddle's authenticity proof: a timestamp and one or more HMACs, in one header.
|
|
@@ -40,7 +42,9 @@ import { PaymentsVerificationFailedError } from "../../error/errors.js";
|
|
|
40
42
|
* The window still earns its place, in both directions. It bounds how long a captured-but-never-delivered
|
|
41
43
|
* signature stays usable, and it refuses a far-future timestamp — either a broken clock or somebody trying
|
|
42
44
|
* to mint a delivery that never goes stale. Configurable, so an adopter who wants Paddle's number can set
|
|
43
|
-
* it.
|
|
45
|
+
* it — bounded, and checked before it is used, because a window is only a boundary while it is a number. A
|
|
46
|
+
* non-finite tolerance makes `drift > tolerance` false for every delivery ever signed, which is not a wider
|
|
47
|
+
* window but no window at all.
|
|
44
48
|
*
|
|
45
49
|
* Paddle re-signs each retry attempt with a fresh `ts`, which is the only way a three-day retry window and
|
|
46
50
|
* a five-second SDK tolerance could both be coherent — so the window does not silently reject retries.
|
|
@@ -141,7 +145,18 @@ async function verifyPaddleSignature(body, header, options) {
|
|
|
141
145
|
const parsed = header === null ? void 0 : parse(header.trim());
|
|
142
146
|
if (parsed === void 0) throw new PaymentsVerificationFailedError({ detail: refusal("unreadable") });
|
|
143
147
|
const tolerance = options.toleranceSeconds ?? 300;
|
|
144
|
-
if (
|
|
148
|
+
if (!Number.isFinite(tolerance) || tolerance < 0 || tolerance > SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS) throw new InternalError({
|
|
149
|
+
message: "This webhook endpoint is not configured.",
|
|
150
|
+
action: `Give the Paddle webhook a freshness window between 0 and ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} seconds.`,
|
|
151
|
+
detail: `Paddle: the signature check was given a freshness window of ${String(tolerance)} seconds, and a window must be a number from 0 to ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}.`
|
|
152
|
+
});
|
|
153
|
+
const nowSeconds = Math.floor(options.now.getTime() / 1e3);
|
|
154
|
+
if (!Number.isFinite(nowSeconds)) throw new InternalError({
|
|
155
|
+
message: "This webhook endpoint is not configured.",
|
|
156
|
+
action: "Give the Paddle webhook a valid clock.",
|
|
157
|
+
detail: "Paddle: the signature check was handed a clock that is not a valid Date, so no delivery's freshness can be judged."
|
|
158
|
+
});
|
|
159
|
+
if (Math.abs(nowSeconds - parsed.timestamp) > tolerance) throw new PaymentsVerificationFailedError({ detail: refusal("stale") });
|
|
145
160
|
const key = await signingKey(options.secret, "verify");
|
|
146
161
|
const message = new TextEncoder().encode(`${parsed.timestamp}:${body}`);
|
|
147
162
|
for (const candidate of parsed.candidates) if (await crypto.subtle.verify("HMAC", key, candidate, message)) return;
|
|
@@ -22,7 +22,17 @@ import type { StripeHttpFetch } from "./api";
|
|
|
22
22
|
export interface StripeRailOptions {
|
|
23
23
|
/** The HTTP seam Stripe's API is reached through. Defaults to the runtime's `fetch`. */
|
|
24
24
|
transport?: StripeHttpFetch;
|
|
25
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* The signature freshness window, in seconds. Defaults to Stripe's own five minutes.
|
|
27
|
+
*
|
|
28
|
+
* Threaded down unchanged and validated in exactly one place: `@pithy-sh/core`'s `checkSignedWebhook`, which
|
|
29
|
+
* refuses a non-finite, negative, or over-wide window as `core/internal` before it compares anything. This
|
|
30
|
+
* layer, `webhook.ts` and `signature.ts` each re-apply a default with `??` — which catches `undefined` and
|
|
31
|
+
* never `NaN` — and none of them re-checks the number. That is deliberate: one place that refuses is better
|
|
32
|
+
* than three that each half-check, and nothing on this path can reach the comparison without going through
|
|
33
|
+
* the primitive, so there is no bypass for a second check to cover. Three copies of the bound would only be
|
|
34
|
+
* three chances for one of them to drift.
|
|
35
|
+
*/
|
|
26
36
|
toleranceSeconds?: number;
|
|
27
37
|
}
|
|
28
38
|
/** The Stripe rail. Verifies a returning Checkout Session, verifies webhooks, and creates hosted sessions. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rail.d.ts","sourceRoot":"","sources":["../../../src/rails/stripe/rail.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAEV,YAAY,EAEZ,YAAY,EAEZ,oBAAoB,EAGpB,WAAW,EAMZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAU7C;;;;;;;;;;;;;;GAcG;AAEH,iGAAiG;AACjG,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B
|
|
1
|
+
{"version":3,"file":"rail.d.ts","sourceRoot":"","sources":["../../../src/rails/stripe/rail.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAEV,YAAY,EAEZ,YAAY,EAEZ,oBAAoB,EAGpB,WAAW,EAMZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAU7C;;;;;;;;;;;;;;GAcG;AAEH,iGAAiG;AACjG,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8GAA8G;AAC9G,wBAAgB,UAAU,CACxB,WAAW,EAAE,yBAAyB,EACtC,OAAO,GAAE,iBAAsB,GAC9B,oBAAoB,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,CA8ElE"}
|
|
@@ -50,7 +50,14 @@ export type StripeSignatureHeader = SignedWebhookHeader;
|
|
|
50
50
|
export interface VerifyStripeSignatureOptions {
|
|
51
51
|
/** The clock. Injected so the replay window is deterministic in tests rather than wall-clock dependent. */
|
|
52
52
|
now: Date;
|
|
53
|
-
/**
|
|
53
|
+
/**
|
|
54
|
+
* The freshness window, in seconds. Defaults to {@link STRIPE_SIGNATURE_TOLERANCE_SECONDS}.
|
|
55
|
+
*
|
|
56
|
+
* The `??` below applies that default and nothing more — a `NaN` passes it untouched, on purpose. The
|
|
57
|
+
* primitive owns the bound (`core/internal` for anything non-finite, negative, or over-wide) because it owns
|
|
58
|
+
* the comparison, and every caller on this path reaches it. See {@link ./rail.StripeRailOptions} for why the
|
|
59
|
+
* check is not repeated at each layer.
|
|
60
|
+
*/
|
|
54
61
|
toleranceSeconds?: number;
|
|
55
62
|
}
|
|
56
63
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/rails/stripe/signature.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,mBAAmB,EAEzB,MAAM,uCAAuC,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,wGAAwG;AACxG,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,6GAA6G;AAC7G,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAQtD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAExD,iGAAiG;AACjG,MAAM,WAAW,4BAA4B;IAC3C,2GAA2G;IAC3G,GAAG,EAAE,IAAI,CAAC;IACV
|
|
1
|
+
{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/rails/stripe/signature.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,mBAAmB,EAEzB,MAAM,uCAAuC,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,wGAAwG;AACxG,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,6GAA6G;AAC7G,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAQtD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAExD,iGAAiG;AACjG,MAAM,WAAW,4BAA4B;IAC3C,2GAA2G;IAC3G,GAAG,EAAE,IAAI,CAAC;IACV;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAE5F;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAWf"}
|
|
@@ -0,0 +1,23 @@
|
|
|
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
|
+
//# 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"}
|
|
@@ -0,0 +1,27 @@
|
|
|
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
|
+
//#endregion
|
|
27
|
+
export { 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.2.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.2.1";
|
|
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.
|
|
7
|
+
const PACKAGE_VERSION = "0.2.1";
|
|
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.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"reset": "bun run clean && rm -rf node_modules"
|
|
38
38
|
},
|
|
39
39
|
"peerDependencies": {
|
|
40
|
-
"@pithy-sh/ledger": "^0.1.
|
|
40
|
+
"@pithy-sh/ledger": "^0.1.6",
|
|
41
41
|
"hono": "^4.13.2",
|
|
42
42
|
"kysely": "^0.29.0",
|
|
43
43
|
"react": "^19.0.0",
|
|
@@ -55,8 +55,8 @@
|
|
|
55
55
|
"@cloudflare/workers-types": "^5.20260729.1",
|
|
56
56
|
"@hono/zod-validator": "^0.9.0",
|
|
57
57
|
"@paddle/paddle-js": "^1.6.4",
|
|
58
|
-
"@pithy-sh/core": "^0.
|
|
59
|
-
"@pithy-sh/secrets": "^0.1.
|
|
58
|
+
"@pithy-sh/core": "^0.3.0",
|
|
59
|
+
"@pithy-sh/secrets": "^0.1.6"
|
|
60
60
|
},
|
|
61
61
|
"devDependencies": {
|
|
62
62
|
"@cloudflare/vitest-plugin": "^1.0.0",
|
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 { 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,9 @@ 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),
|
|
346
350
|
// The one durable job: the nightly reconciliation pass. Declared here so `createBackend` derives its
|
|
347
351
|
// binding and types `c.var.workflows.trigger("payments/reconcile", …)` precisely.
|
|
348
352
|
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/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(
|
package/src/rails/google/oidc.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
|
+
import { OIDC_MAX_CLOCK_SKEW_SECONDS } from "@pithy-sh/core/src/http/oidcWebhook";
|
|
4
6
|
import { z } from "zod";
|
|
5
7
|
import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors";
|
|
6
8
|
import { type GoogleHttpFetch, googleHttpFetch, googleJson } from "./http";
|
|
@@ -150,7 +152,11 @@ export interface VerifyGoogleOidcOptions {
|
|
|
150
152
|
* is exercised for real, and a local Pub/Sub emulator, whose tokens are signed by a key Google never saw.
|
|
151
153
|
*/
|
|
152
154
|
trustedKeys?: readonly GoogleJwk[];
|
|
153
|
-
/**
|
|
155
|
+
/**
|
|
156
|
+
* Tolerance on `exp` and `iat`, in seconds. Defaults to a minute, and must be a finite number from 0 to
|
|
157
|
+
* {@link OIDC_MAX_CLOCK_SKEW_SECONDS}; anything else is `core/internal`, because this is the second operand
|
|
158
|
+
* of both freshness comparisons and one `NaN` turns the pair into no-ops together.
|
|
159
|
+
*/
|
|
154
160
|
clockSkewSeconds?: number;
|
|
155
161
|
}
|
|
156
162
|
|
|
@@ -269,8 +275,29 @@ export async function verifyGoogleOidcToken(
|
|
|
269
275
|
});
|
|
270
276
|
}
|
|
271
277
|
const claims = parsed.data;
|
|
278
|
+
// Both operands of both time checks, and both fail open unguarded: `exp + NaN < seconds` and
|
|
279
|
+
// `iat - NaN > seconds` are false alike, so one unchecked number does not widen the window — it deletes it,
|
|
280
|
+
// and a captured Play RTDN push replays forever under a signature that is genuinely Google's. Everything
|
|
281
|
+
// above still holds; freshness is precisely what is lost, which is the half nothing else here recovers.
|
|
282
|
+
// Our fault, our code: a 401 would send an operator hunting a forger who is not there. The ceiling is the
|
|
283
|
+
// kit's, imported rather than restated, because a skew is a replay window in the plainest possible units.
|
|
272
284
|
const skew = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
|
|
285
|
+
if (!Number.isFinite(skew) || skew < 0 || skew > OIDC_MAX_CLOCK_SKEW_SECONDS) {
|
|
286
|
+
throw new InternalError({
|
|
287
|
+
message: "This webhook endpoint is not configured.",
|
|
288
|
+
action: `Give the Google Pub/Sub webhook a clock skew between 0 and ${OIDC_MAX_CLOCK_SKEW_SECONDS} seconds.`,
|
|
289
|
+
detail: `Google: the push-token check was given a clock skew of ${String(skew)} seconds, and a tolerance must be a number from 0 to ${OIDC_MAX_CLOCK_SKEW_SECONDS}.`,
|
|
290
|
+
});
|
|
291
|
+
}
|
|
273
292
|
const seconds = Math.floor(options.now.getTime() / 1000);
|
|
293
|
+
if (!Number.isFinite(seconds)) {
|
|
294
|
+
throw new InternalError({
|
|
295
|
+
message: "This webhook endpoint is not configured.",
|
|
296
|
+
action: "Give the Google Pub/Sub webhook a valid clock.",
|
|
297
|
+
detail:
|
|
298
|
+
"Google: the push-token check was handed a clock that is not a valid Date, so no token's freshness can be judged.",
|
|
299
|
+
});
|
|
300
|
+
}
|
|
274
301
|
|
|
275
302
|
if (!GOOGLE_OIDC_ISSUERS.includes(claims.iss)) {
|
|
276
303
|
throw failed(`the token issuer is "${claims.iss}", not one of Google's.`);
|
package/src/rails/paddle/rail.ts
CHANGED
|
@@ -82,7 +82,16 @@ export interface PaddleRailOptions {
|
|
|
82
82
|
clientToken: string;
|
|
83
83
|
/** Whether checkout opens as an overlay, inline, or on Paddle's own hosted page. */
|
|
84
84
|
checkout: "overlay" | "inline" | "hosted";
|
|
85
|
-
/**
|
|
85
|
+
/**
|
|
86
|
+
* How many seconds either side of now a delivery may be dated. Undefined uses the rail's 300.
|
|
87
|
+
*
|
|
88
|
+
* Threaded down unchanged through `webhook.ts` and validated in one place, `signature.ts`, where the
|
|
89
|
+
* comparison is — a non-finite, negative, or over-wide window is `core/internal` there, refused before any
|
|
90
|
+
* delivery is judged. The layers between only apply defaults with `??`, which catches `undefined` and never
|
|
91
|
+
* `NaN`; one place that refuses beats three that each half-check. `paddle.webhookFreshnessSeconds` reaches
|
|
92
|
+
* this field and is deliberately **not** bounded again in `PaymentsPaddleSettings`: that schema parses at
|
|
93
|
+
* module scope, so a bound there refuses the whole Worker for one webhook route's knob.
|
|
94
|
+
*/
|
|
86
95
|
freshnessSeconds?: number;
|
|
87
96
|
/**
|
|
88
97
|
* The currency this project's Paddle catalog prices in, when the project declared one.
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
|
+
import { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS } from "@pithy-sh/core/src/http/webhookWindow";
|
|
4
6
|
import { PaymentsVerificationFailedError } from "../../error/errors";
|
|
5
7
|
|
|
6
8
|
/**
|
|
@@ -41,7 +43,9 @@ import { PaymentsVerificationFailedError } from "../../error/errors";
|
|
|
41
43
|
* The window still earns its place, in both directions. It bounds how long a captured-but-never-delivered
|
|
42
44
|
* signature stays usable, and it refuses a far-future timestamp — either a broken clock or somebody trying
|
|
43
45
|
* to mint a delivery that never goes stale. Configurable, so an adopter who wants Paddle's number can set
|
|
44
|
-
* it.
|
|
46
|
+
* it — bounded, and checked before it is used, because a window is only a boundary while it is a number. A
|
|
47
|
+
* non-finite tolerance makes `drift > tolerance` false for every delivery ever signed, which is not a wider
|
|
48
|
+
* window but no window at all.
|
|
45
49
|
*
|
|
46
50
|
* Paddle re-signs each retry attempt with a fresh `ts`, which is the only way a three-day retry window and
|
|
47
51
|
* a five-second SDK tolerance could both be coherent — so the window does not silently reject retries.
|
|
@@ -82,7 +86,11 @@ export interface VerifyPaddleSignatureOptions {
|
|
|
82
86
|
secret: string;
|
|
83
87
|
/** The clock, for the freshness window. Injected so verification is deterministic. */
|
|
84
88
|
now: Date;
|
|
85
|
-
/**
|
|
89
|
+
/**
|
|
90
|
+
* How many seconds either side of `now` a delivery may be dated. Undefined uses the default, and anything
|
|
91
|
+
* present must be a finite number from 0 to {@link SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} — anything else is
|
|
92
|
+
* `core/internal`, because a `NaN` here does not widen the window, it removes it.
|
|
93
|
+
*/
|
|
86
94
|
toleranceSeconds?: number;
|
|
87
95
|
}
|
|
88
96
|
|
|
@@ -192,8 +200,36 @@ export async function verifyPaddleSignature(
|
|
|
192
200
|
const parsed = header === null ? undefined : parse(header.trim());
|
|
193
201
|
if (parsed === undefined) throw new PaymentsVerificationFailedError({ detail: refusal("unreadable") });
|
|
194
202
|
|
|
203
|
+
// Both operands of the window comparison, checked before it runs. This is the one thing this module does
|
|
204
|
+
// import from the core primitive, and it imports the *policy* rather than the format: `drift > tolerance` is
|
|
205
|
+
// false when either side is `NaN`, so a non-finite number here does not widen the window — it deletes it, and
|
|
206
|
+
// a captured `subscription.canceled` verifies forever. The realistic source is `Number(env.PADDLE_FRESHNESS)`
|
|
207
|
+
// on a variable nobody set, threaded down through two layers of `??` that each catch `undefined` and never
|
|
208
|
+
// `NaN`. Refused as our fault with our code, because the sender did nothing wrong.
|
|
209
|
+
//
|
|
210
|
+
// **This is the only place the bound is applied, including for the config path.** `PaymentsPaddleSettings`
|
|
211
|
+
// could carry a `.max()` and deliberately does not: it parses at module scope, so refusing there refuses the
|
|
212
|
+
// Worker — every route, over one webhook knob. Here the blast radius is the Paddle webhook endpoint, which is
|
|
213
|
+
// the endpoint the number is about, and Paddle redelivers for three days while it is fixed. The refusal is no
|
|
214
|
+
// weaker for moving: there is no way to reach the comparison below without coming through this function.
|
|
195
215
|
const tolerance = options.toleranceSeconds ?? PADDLE_DEFAULT_FRESHNESS_SECONDS;
|
|
196
|
-
|
|
216
|
+
if (!Number.isFinite(tolerance) || tolerance < 0 || tolerance > SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS) {
|
|
217
|
+
throw new InternalError({
|
|
218
|
+
message: "This webhook endpoint is not configured.",
|
|
219
|
+
action: `Give the Paddle webhook a freshness window between 0 and ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} seconds.`,
|
|
220
|
+
detail: `Paddle: the signature check was given a freshness window of ${String(tolerance)} seconds, and a window must be a number from 0 to ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}.`,
|
|
221
|
+
});
|
|
222
|
+
}
|
|
223
|
+
const nowSeconds = Math.floor(options.now.getTime() / 1000);
|
|
224
|
+
if (!Number.isFinite(nowSeconds)) {
|
|
225
|
+
throw new InternalError({
|
|
226
|
+
message: "This webhook endpoint is not configured.",
|
|
227
|
+
action: "Give the Paddle webhook a valid clock.",
|
|
228
|
+
detail:
|
|
229
|
+
"Paddle: the signature check was handed a clock that is not a valid Date, so no delivery's freshness can be judged.",
|
|
230
|
+
});
|
|
231
|
+
}
|
|
232
|
+
const drift = Math.abs(nowSeconds - parsed.timestamp);
|
|
197
233
|
if (drift > tolerance) throw new PaymentsVerificationFailedError({ detail: refusal("stale") });
|
|
198
234
|
|
|
199
235
|
// The timestamp is inside the signed message, so a captured signature cannot be re-dated to slip
|
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,28 @@
|
|
|
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
|
+
}
|
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