@adonis-agora/payments 0.2.0 → 0.3.0

package/dist/src/webhook_security.d.ts

@@ -1,8 +1,8 @@
 /**
  * Shared webhook-auth primitives for the drivers. Every gateway signs webhooks
  * differently (Stripe: SDK HMAC; AbacatePay: HMAC-SHA256; Woovi: HMAC-SHA1 or
- * RSA-SHA256; Asaas: shared token), but the comparison and digest mechanics are the
- * same — they live here so every driver verifies with the same, timing-safe code.
+ * RSA-SHA256; Asaas: shared token; PagBank: a bare SHA-256 over token+body), but the
+ * comparison and digest mechanics are the same — they live here so every driver verifies with the same, timing-safe code.
  */
 /** Length-independent, timing-safe string comparison. */
 export declare function safeCompare(received: string, expected: string): boolean;
@@ -11,7 +11,24 @@ export declare function safeCompare(received: string, expected: string): boolean
  * timing-safe. `digest` matches the gateway's encoding (`base64` for AbacatePay and
  * Woovi's HMAC mode).
  */
-export declare function verifyHmacSignature(rawBody: string, signature: string | undefined, secret: string, algorithm: 'sha256' | 'sha1'): boolean;
+export declare function verifyHmacSignature(rawBody: string, signature: string | undefined, secret: string, algorithm: 'sha256' | 'sha1', 
+/**
+ * How the gateway encodes the digest. Base64 is the default because the first gateways
+ * here used it; hex is at least as common (Paddle, Lemon Squeezy, Razorpay, Mercado Pago,
+ * Mollie all send hex), and getting it wrong fails CLOSED — every signature mismatches —
+ * so it is safe to leave to the caller.
+ */
+encoding?: 'base64' | 'hex'): boolean;
+/**
+ * The same check over a payload the gateway builds rather than the raw body.
+ *
+ * Several schemes sign a CONSTRUCTED string — Paddle's `ts:body`, Standard Webhooks'
+ * `id.timestamp.body`, Square's `notificationUrl + body`, Mercado Pago's id/request/ts
+ * manifest. The signed bytes are the whole security property, so building them is the one
+ * step a driver must own; this only removes the reason to hand-roll the comparison, which
+ * is where a `===` creeps back in and reintroduces a timing side channel.
+ */
+export declare function verifyHmacOverPayload(payload: string, signature: string | undefined, secret: string, algorithm: 'sha256' | 'sha1', encoding?: 'base64' | 'hex'): boolean;
 /**
  * Verify Woovi's recommended `x-webhook-signature`: an RSA-SHA256 signature made with
  * Woovi's private key, verified here against the public key published at
@@ -26,4 +43,78 @@ export declare function verifyRsaSha256Signature(rawBody: string, signature: str
  * set. Drivers only reach this when their credential is configured.
  */
 export declare function requireMatchingCredential(received: string | undefined, expected: string, provider: string, what: string): void;
+/**
+ * Verify PagBank's `x-authenticity-token`: the hex SHA-256 of `<token>-<rawBody>`, where
+ * `<token>` is the very same Bearer token that authenticates API calls.
+ *
+ * Read that construction again, because it is not an HMAC. It is a secret **prefix**
+ * hashed with a Merkle–Damgård function, which is the textbook setup for a
+ * length-extension forgery: anyone who has seen one valid (body, token) pair can compute
+ * a valid token for that body plus a suffix, without ever learning the secret. What saves
+ * it in practice is that the forged body is the original body followed by binary padding,
+ * and `JSON.parse` rejects that — so a forgery has to survive the parser, not just the
+ * hash. It is still weaker than the HMAC every other gateway here uses, and the secret is
+ * shared with the API credential, so rotating one rotates the other.
+ *
+ * The comparison is timing-safe and case-insensitive (PagBank sends lowercase hex).
+ */
+export declare function verifyPagBankAuthenticityToken(rawBody: string, received: string | undefined, token: string): boolean;
+/**
+ * Verify a [Standard Webhooks](https://www.standardwebhooks.com/) signature.
+ *
+ * The scheme: sign `` `${webhook-id}.${webhook-timestamp}.${rawBody}` `` with HMAC-SHA256,
+ * base64. The `webhook-signature` header carries a SPACE-SEPARATED list of `v1,<sig>` — a
+ * list, because a secret being rotated is signed with both keys at once, so checking only
+ * the first entry breaks every rotation.
+ *
+ * `keyEncoding` is the part that bites, and neither vendor documents it — both derivations
+ * below were read out of their own SDK source:
+ *
+ * - `'base64'` (the spec default) — strip the `whsec_` prefix and base64-DECODE the rest.
+ *   Dodo Payments does this.
+ * - `'raw'` — use the secret's UTF-8 bytes as-is, `whsec_` prefix included. Polar does this
+ *   (its SDK base64-encodes the secret before handing it to the reference library, which
+ *   decodes it straight back).
+ *
+ * Getting it wrong fails closed — every signature mismatches — so the cost is a rejected
+ * webhook, not an accepted forgery. Which is why each driver pins its own derivation with a
+ * test that signs using the OTHER one and asserts rejection.
+ *
+ * `toleranceSeconds` bounds replay. It defaults to 5 minutes, the spec's own recommendation;
+ * pass `0` to skip the check. Note the idempotency ledger already makes a replayed event a
+ * no-op — this is the outer guard, not the only one.
+ */
+export declare function verifyStandardWebhookSignature(options: {
+    rawBody: string;
+    headers: Record<string, string | string[] | undefined>;
+    secret: string;
+    keyEncoding: 'base64' | 'raw';
+    toleranceSeconds?: number;
+    /** Overridable clock, so the tolerance is testable. */
+    now?: Date;
+}): boolean;
+/**
+ * Refuse to boot when a configured driver CAN authenticate webhook deliveries but was given
+ * nothing to authenticate them with.
+ *
+ * The hole: the library mounts `POST /payments/webhook/:provider` for every configured
+ * provider, and a driver whose credential slot is empty verifies nothing — so anyone who
+ * knows the URL can post `{"event":"PAYMENT_RECEIVED", ...}` and the built-in sync marks a
+ * payment paid. Nothing logged it, nothing warned, and the app's own webhook-security tests
+ * passed *because* they only asserted that a good signature is accepted.
+ *
+ * This package already fails closed in the two comparable places — the dashboard throws at
+ * boot on a missing session secret, the dispatcher throws on a mode it cannot serve — and
+ * this is the same decision for the one endpoint the public internet can reach.
+ *
+ * The opt-out is explicit and per-provider, because terminating verification upstream is a
+ * real deployment (mutual TLS at the edge, an API gateway that checks the signature) and it
+ * is exactly what Efí's driver does by design. What it must not be is the default.
+ */
+export declare function assertWebhookVerification(drivers: Iterable<[string, {
+    provider?: string;
+    webhookVerification?: string;
+}]>, options?: {
+    allowUnverifiedWebhooks?: boolean | readonly string[];
+}): void;
 //# sourceMappingURL=webhook_security.d.ts.map

package/dist/src/webhook_security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook_security.d.ts","sourceRoot":"","sources":["../../src/webhook_security.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,GAAG,MAAM,GAC3B,OAAO,CAIT;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,GAChB,OAAO,CAWT;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,IAAI,CAON"}
+{"version":3,"file":"webhook_security.d.ts","sourceRoot":"","sources":["../../src/webhook_security.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,GAAG,MAAM;AAC5B;;;;;GAKG;AACH,QAAQ,GAAE,QAAQ,GAAG,KAAgB,GACpC,OAAO,CAST;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,GAAG,MAAM,EAC5B,QAAQ,GAAE,QAAQ,GAAG,KAAgB,GACpC,OAAO,CAST;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,GAChB,OAAO,CAgBT;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,IAAI,CAUN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,GACZ,OAAO,CAST;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GAAG,OAAO,CAuCV;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,EAChF,OAAO,GAAE;IAAE,uBAAuB,CAAC,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAAA;CAAO,GACtE,IAAI,CAoBN"}

package/dist/src/webhook_security.js

@@ -1,9 +1,11 @@
-import { createHmac, verify as cryptoVerify, timingSafeEqual } from 'node:crypto';
+import { createHash, createHmac, verify as cryptoVerify, timingSafeEqual } from 'node:crypto';
+import { reportWebhookVerification } from './diagnostics.js';
+import { headerValue } from './http.js';
 /**
  * Shared webhook-auth primitives for the drivers. Every gateway signs webhooks
  * differently (Stripe: SDK HMAC; AbacatePay: HMAC-SHA256; Woovi: HMAC-SHA1 or
- * RSA-SHA256; Asaas: shared token), but the comparison and digest mechanics are the
- * same — they live here so every driver verifies with the same, timing-safe code.
+ * RSA-SHA256; Asaas: shared token; PagBank: a bare SHA-256 over token+body), but the
+ * comparison and digest mechanics are the same — they live here so every driver verifies with the same, timing-safe code.
  */
 /** Length-independent, timing-safe string comparison. */
 export function safeCompare(received, expected) {
@@ -16,11 +18,41 @@ export function safeCompare(received, expected) {
  * timing-safe. `digest` matches the gateway's encoding (`base64` for AbacatePay and
  * Woovi's HMAC mode).
  */
-export function verifyHmacSignature(rawBody, signature, secret, algorithm) {
-    if (signature === undefined || signature === '')
+export function verifyHmacSignature(rawBody, signature, secret, algorithm, 
+/**
+ * How the gateway encodes the digest. Base64 is the default because the first gateways
+ * here used it; hex is at least as common (Paddle, Lemon Squeezy, Razorpay, Mercado Pago,
+ * Mollie all send hex), and getting it wrong fails CLOSED — every signature mismatches —
+ * so it is safe to leave to the caller.
+ */
+encoding = 'base64') {
+    if (signature === undefined || signature === '') {
+        reportWebhookVerification(`hmac-${algorithm}`, false);
         return false;
-    const expected = createHmac(algorithm, secret).update(rawBody, 'utf8').digest('base64');
-    return safeCompare(signature, expected);
+    }
+    const expected = createHmac(algorithm, secret).update(rawBody, 'utf8').digest(encoding);
+    const ok = safeCompare(signature, expected);
+    reportWebhookVerification(`hmac-${algorithm}`, ok);
+    return ok;
+}
+/**
+ * The same check over a payload the gateway builds rather than the raw body.
+ *
+ * Several schemes sign a CONSTRUCTED string — Paddle's `ts:body`, Standard Webhooks'
+ * `id.timestamp.body`, Square's `notificationUrl + body`, Mercado Pago's id/request/ts
+ * manifest. The signed bytes are the whole security property, so building them is the one
+ * step a driver must own; this only removes the reason to hand-roll the comparison, which
+ * is where a `===` creeps back in and reintroduces a timing side channel.
+ */
+export function verifyHmacOverPayload(payload, signature, secret, algorithm, encoding = 'base64') {
+    if (signature === undefined || signature === '') {
+        reportWebhookVerification(`hmac-${algorithm}-over-payload`, false);
+        return false;
+    }
+    const expected = createHmac(algorithm, secret).update(payload, 'utf8').digest(encoding);
+    const ok = safeCompare(signature, expected);
+    reportWebhookVerification(`hmac-${algorithm}-over-payload`, ok);
+    return ok;
 }
 /**
  * Verify Woovi's recommended `x-webhook-signature`: an RSA-SHA256 signature made with
@@ -29,12 +61,16 @@ export function verifyHmacSignature(rawBody, signature, secret, algorithm) {
  * PEM document (the dashboard shows it base64-encoded).
  */
 export function verifyRsaSha256Signature(rawBody, signature, publicKey) {
-    if (signature === undefined || signature === '')
+    if (signature === undefined || signature === '') {
+        reportWebhookVerification('rsa-sha256', false);
         return false;
+    }
     const pem = publicKey.includes('-----BEGIN')
         ? publicKey
         : Buffer.from(publicKey, 'base64').toString('utf8');
-    return cryptoVerify('RSA-SHA256', Buffer.from(rawBody, 'utf8'), pem, Buffer.from(signature, 'base64'));
+    const ok = cryptoVerify('RSA-SHA256', Buffer.from(rawBody, 'utf8'), pem, Buffer.from(signature, 'base64'));
+    reportWebhookVerification('rsa-sha256', ok);
+    return ok;
 }
 /**
  * Enforce a configured webhook credential against the request headers. Returns the
@@ -44,10 +80,138 @@ export function verifyRsaSha256Signature(rawBody, signature, publicKey) {
  */
 export function requireMatchingCredential(received, expected, provider, what) {
     if (received === undefined || received === '') {
+        reportWebhookVerification('shared-token', false);
         throw new Error(`[payments] Missing webhook ${what} on ${provider} request.`);
     }
     if (!safeCompare(received, expected)) {
+        reportWebhookVerification('shared-token', false);
         throw new Error(`[payments] Invalid ${provider} webhook ${what}.`);
     }
+    reportWebhookVerification('shared-token', true);
+}
+/**
+ * Verify PagBank's `x-authenticity-token`: the hex SHA-256 of `<token>-<rawBody>`, where
+ * `<token>` is the very same Bearer token that authenticates API calls.
+ *
+ * Read that construction again, because it is not an HMAC. It is a secret **prefix**
+ * hashed with a Merkle–Damgård function, which is the textbook setup for a
+ * length-extension forgery: anyone who has seen one valid (body, token) pair can compute
+ * a valid token for that body plus a suffix, without ever learning the secret. What saves
+ * it in practice is that the forged body is the original body followed by binary padding,
+ * and `JSON.parse` rejects that — so a forgery has to survive the parser, not just the
+ * hash. It is still weaker than the HMAC every other gateway here uses, and the secret is
+ * shared with the API credential, so rotating one rotates the other.
+ *
+ * The comparison is timing-safe and case-insensitive (PagBank sends lowercase hex).
+ */
+export function verifyPagBankAuthenticityToken(rawBody, received, token) {
+    if (received === undefined || received === '') {
+        reportWebhookVerification('sha256-token-prefix', false);
+        return false;
+    }
+    const expected = createHash('sha256').update(`${token}-${rawBody}`, 'utf8').digest('hex');
+    const ok = safeCompare(received.toLowerCase(), expected);
+    reportWebhookVerification('sha256-token-prefix', ok);
+    return ok;
+}
+/**
+ * Verify a [Standard Webhooks](https://www.standardwebhooks.com/) signature.
+ *
+ * The scheme: sign `` `${webhook-id}.${webhook-timestamp}.${rawBody}` `` with HMAC-SHA256,
+ * base64. The `webhook-signature` header carries a SPACE-SEPARATED list of `v1,<sig>` — a
+ * list, because a secret being rotated is signed with both keys at once, so checking only
+ * the first entry breaks every rotation.
+ *
+ * `keyEncoding` is the part that bites, and neither vendor documents it — both derivations
+ * below were read out of their own SDK source:
+ *
+ * - `'base64'` (the spec default) — strip the `whsec_` prefix and base64-DECODE the rest.
+ *   Dodo Payments does this.
+ * - `'raw'` — use the secret's UTF-8 bytes as-is, `whsec_` prefix included. Polar does this
+ *   (its SDK base64-encodes the secret before handing it to the reference library, which
+ *   decodes it straight back).
+ *
+ * Getting it wrong fails closed — every signature mismatches — so the cost is a rejected
+ * webhook, not an accepted forgery. Which is why each driver pins its own derivation with a
+ * test that signs using the OTHER one and asserts rejection.
+ *
+ * `toleranceSeconds` bounds replay. It defaults to 5 minutes, the spec's own recommendation;
+ * pass `0` to skip the check. Note the idempotency ledger already makes a replayed event a
+ * no-op — this is the outer guard, not the only one.
+ */
+export function verifyStandardWebhookSignature(options) {
+    const id = headerValue(options.headers, 'webhook-id');
+    const timestamp = headerValue(options.headers, 'webhook-timestamp');
+    const signature = headerValue(options.headers, 'webhook-signature');
+    if (!id || !timestamp || !signature) {
+        reportWebhookVerification('standard-webhooks', false);
+        return false;
+    }
+    const tolerance = options.toleranceSeconds ?? 300;
+    if (tolerance > 0) {
+        const sent = Number(timestamp);
+        if (!Number.isFinite(sent)) {
+            reportWebhookVerification('standard-webhooks', false);
+            return false;
+        }
+        const nowSeconds = Math.floor((options.now ?? new Date()).getTime() / 1000);
+        if (Math.abs(nowSeconds - sent) > tolerance) {
+            reportWebhookVerification('standard-webhooks', false);
+            return false;
+        }
+    }
+    const key = options.keyEncoding === 'raw'
+        ? Buffer.from(options.secret, 'utf8')
+        : Buffer.from(options.secret.replace(/^whsec_/, ''), 'base64');
+    const expected = createHmac('sha256', key)
+        .update(`${id}.${timestamp}.${options.rawBody}`, 'utf8')
+        .digest('base64');
+    // Every `v1,<sig>` entry is checked: during a secret rotation the gateway signs with both
+    // the old and the new key, and only one of them can match.
+    const ok = signature
+        .split(' ')
+        .filter((part) => part.startsWith('v1,'))
+        .some((part) => safeCompare(part.slice(3), expected));
+    reportWebhookVerification('standard-webhooks', ok);
+    return ok;
+}
+/**
+ * Refuse to boot when a configured driver CAN authenticate webhook deliveries but was given
+ * nothing to authenticate them with.
+ *
+ * The hole: the library mounts `POST /payments/webhook/:provider` for every configured
+ * provider, and a driver whose credential slot is empty verifies nothing — so anyone who
+ * knows the URL can post `{"event":"PAYMENT_RECEIVED", ...}` and the built-in sync marks a
+ * payment paid. Nothing logged it, nothing warned, and the app's own webhook-security tests
+ * passed *because* they only asserted that a good signature is accepted.
+ *
+ * This package already fails closed in the two comparable places — the dashboard throws at
+ * boot on a missing session secret, the dispatcher throws on a mode it cannot serve — and
+ * this is the same decision for the one endpoint the public internet can reach.
+ *
+ * The opt-out is explicit and per-provider, because terminating verification upstream is a
+ * real deployment (mutual TLS at the edge, an API gateway that checks the signature) and it
+ * is exactly what Efí's driver does by design. What it must not be is the default.
+ */
+export function assertWebhookVerification(drivers, options = {}) {
+    const allow = options.allowUnverifiedWebhooks;
+    if (allow === true)
+        return;
+    const allowed = new Set(Array.isArray(allow) ? allow : []);
+    for (const [name, driver] of drivers) {
+        if (driver.webhookVerification !== 'unconfigured')
+            continue;
+        if (allowed.has(name) || (driver.provider !== undefined && allowed.has(driver.provider))) {
+            continue;
+        }
+        throw new Error([
+            `[payments] The "${name}" driver can verify webhook deliveries but has no credential`,
+            `configured, so \`POST /payments/webhook/${driver.provider ?? name}\` would accept any`,
+            'request that reaches it — including one that marks a payment paid.',
+            "Set the gateway's webhook secret/token (see the provider docs page for the env var),",
+            'or, if verification is genuinely terminated upstream, say so explicitly with',
+            `\`allowUnverifiedWebhooks: ['${name}']\` in config/payments.ts.`,
+        ].join(' '));
+    }
 }
 //# sourceMappingURL=webhook_security.js.map

package/dist/src/webhook_security.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook_security.js","sourceRoot":"","sources":["../../src/webhook_security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElF;;;;;GAKG;AAEH,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,QAAgB;IAC5D,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,SAA6B,EAC7B,MAAc,EACd,SAA4B;IAE5B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxF,OAAO,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAe,EACf,SAA6B,EAC7B,SAAiB;IAEjB,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC1C,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtD,OAAO,YAAY,CACjB,YAAY,EACZ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EAC5B,GAAG,EACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CACjC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAA4B,EAC5B,QAAgB,EAChB,QAAgB,EAChB,IAAY;IAEZ,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,OAAO,QAAQ,WAAW,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sBAAsB,QAAQ,YAAY,IAAI,GAAG,CAAC,CAAC;IACrE,CAAC;AACH,CAAC"}
+{"version":3,"file":"webhook_security.js","sourceRoot":"","sources":["../../src/webhook_security.ts"],"names":[],"mappings":"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"}

package/dist/stubs/config/payments.stub

@@ -37,6 +37,19 @@ export default defineConfig({
     //   // Recommended RSA signature (x-webhook-signature):
     //   webhookPublicKey: env.get('WOOVI_PUBLIC_KEY'),
     // }),
+    // pagbank: payments.pagbank({
+    //   token: env.get('PAGBANK_TOKEN'),
+    //   // Webhooks are verified with the SAME token (x-authenticity-token); there is no
+    //   // separate secret. Only turn verification off for the sandbox, never in production.
+    //   notificationUrls: [`${env.get('APP_URL')}/payments/webhook/pagbank`],
+    // }),
+    // efi: payments.efi({
+    //   clientId: env.get('EFI_CLIENT_ID'),
+    //   clientSecret: env.get('EFI_CLIENT_SECRET'),
+    //   pixKey: env.get('EFI_PIX_KEY'),
+    //   // Efí's Pix API needs mutual TLS: the .p12 from the dashboard, as a path or Buffer.
+    //   certificate: env.get('EFI_CERTIFICATE'),
+    // }),
   },
 
   /**

package/dist/stubs/config/payments_client.stub

@@ -0,0 +1,42 @@
+{{{
+  exports({ to: app.configPath('payments_client.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/payments/client'
+
+/**
+ * Configuration for the browser-facing payment status endpoint — the one
+ * \`usePaymentStatus()\` from \`@adonis-agora/payments-react\` polls while a Pix
+ * QR code or a boleto is on screen.
+ *
+ * DISABLED BY DEFAULT. Unlike the dashboard, this endpoint is reachable by every
+ * logged-in browser, so you turn it on deliberately.
+ *
+ * The three hooks below are the whole authorization story:
+ *
+ * - \`authorize\`          — is this request allowed at all (default: there is a
+ *                          resolved user on \`ctx.auth\`; no user is a 401).
+ * - \`owner\`              — who is asking (default: \`{ type: 'User', id: user.id }\`).
+ * - \`authorizeReference\` — may this caller see THIS payment. The default checks
+ *                          the payment's gateway customer against the one the owner
+ *                          holds in \`billing_customers\`. If you never recorded that
+ *                          mapping with \`ensureCustomer(..., { store, owner })\`, the
+ *                          default DENIES — write your own hook against your own
+ *                          tables instead.
+ */
+export default defineConfig({
+  // Turn it on. Nothing is mounted while this is false.
+  // enabled: true,
+  // path: '/payments/client',
+  // authorize: async (ctx) => {
+  //   await ctx.auth.check()
+  //   return ctx.auth.user !== undefined
+  // },
+  // owner: async (ctx) => {
+  //   const user = ctx.auth.user
+  //   return user ? { type: 'User', id: String(user.id) } : null
+  // },
+  // authorizeReference: async (ctx, reference) => {
+  //   const order = await Order.findBy('gatewayPaymentId', reference)
+  //   return order?.userId === ctx.auth.user?.id
+  // },
+})

package/dist/stubs/config/payments_dashboard.stub

@@ -0,0 +1,38 @@
+{{{
+  exports({ to: app.configPath('payments_dashboard.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/payments/dashboard'
+
+/**
+ * Configuration for the @adonis-agora/payments dashboard.
+ *
+ * By default the dashboard is open OUTSIDE production, and in production it
+ * requires a bearer token equal to \`PAYMENTS_DASHBOARD_TOKEN\` (deny if unset).
+ * Replace \`authorize\` with your own guard (session, role, IP allow-list, …).
+ *
+ * Set \`enabled: false\` to remove it entirely — no routes are registered at all.
+ *
+ * \`dashboardAuth\` is an ADDITIVE, optional session gate on top of \`authorize\` —
+ * a signed cookie minted via a built-in login page (Mode B: \`login\`) and/or a
+ * "open the console from your app" endpoint (Mode A: \`session\`). At least one
+ * of the two is required when \`dashboardAuth\` is set.
+ */
+export default defineConfig({
+  // enabled: true,
+  // path: '/payments-dashboard',
+  // currency: 'BRL',
+  // authorize: (ctx) => ctx.auth.user?.isAdmin === true,
+  // dashboardAuth: {
+  //   secret: env.get('PAYMENTS_DASHBOARD_SECRET'),
+  //   ttl: '8h',
+  //   // Mode B — standalone login page.
+  //   login: async (username, password) => {
+  //     if (username === 'admin' && password === env.get('PAYMENTS_DASHBOARD_PASSWORD')) {
+  //       return { id: 'admin', name: 'Admin' }
+  //     }
+  //     return null
+  //   },
+  //   // Mode A — mint a session for an already-authenticated host request.
+  //   // session: async (request) => (request.user?.isAdmin ? { id: request.user.id } : null),
+  // },
+})

package/dist/stubs/database/migrations/create_billing_tables.stub

@@ -2,89 +2,47 @@
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_billing_tables.ts`) })
 }}}
 import { BaseSchema } from '@adonisjs/lucid/schema'
+import { createBillingTables, dropBillingTables } from '@adonis-agora/payments'
 
+/**
+ * The billing tables, for an app that would rather run DDL explicitly than have the library
+ * do it.
+ *
+ * **You may not need this file.** `@adonis-agora/payments` creates its own tables on first
+ * use, the same way `@adonis-agora/durable` and `@adonis-agora/authz` do — that is the
+ * ecosystem convention, and it is on by default. This migration exists for the case where
+ * that is not wanted: a shared database you do not own, a team that reviews every DDL, a
+ * deploy that runs migrations as a separate step.
+ *
+ * If you keep it, turn the automatic path off so there is one owner:
+ *
+ *     // config/payments.ts
+ *     billing: { autoCreateSchema: false }
+ *
+ * Leaving both on is harmless — the DDL is idempotent, so whichever runs second does
+ * nothing — but "who creates this table" should have one answer.
+ *
+ * Both paths call the SAME `createBillingTables`, which is the point: a schema defined twice
+ * is a schema that drifts, and this package spent a release finding the consequences of two
+ * things that were supposed to agree and did not.
+ *
+ * `this.defer` is how a Lucid migration hands over the query client.
+ *
+ * `createBillingTables` is idempotent in both directions: it creates what is missing AND
+ * applies the guarded `ALTER`s for columns the library added after a table shipped. So
+ * re-running this migration after upgrading the package carries those columns — which is
+ * why running it twice is safe and why there is no second file.
+ */
 export default class extends BaseSchema {
-  protected tableName = 'billing_customers'
-
   async up() {
-    this.schema.createTable('billing_customers', (table) => {
-      table.uuid('id').primary()
-      table.string('owner_type')
-      table.string('owner_id')
-      table.string('gateway_id').unique()
-      table.string('provider')
-      table.string('email').nullable()
-      table.string('name').nullable()
-      table.string('tax_id').nullable()
-      table.jsonb('metadata').nullable()
-      table.timestamp('created_at', { useTz: true }).notNullable()
-      table.timestamp('updated_at', { useTz: true }).notNullable()
-      table.index(['owner_type', 'owner_id'], 'billing_customers_owner_idx')
-    })
-
-    this.schema.createTable('billing_subscriptions', (table) => {
-      table.uuid('id').primary()
-      table.string('gateway_id').unique()
-      table.string('provider')
-      table.string('status')
-      table.string('plan_id')
-      table.string('customer_id').nullable()
-      table.timestamp('trial_ends_at', { useTz: true }).nullable()
-      table.timestamp('ends_at', { useTz: true }).nullable()
-      table.jsonb('payload').nullable()
-      table.timestamp('created_at', { useTz: true }).notNullable()
-      table.timestamp('updated_at', { useTz: true }).notNullable()
-      table.index(['customer_id'], 'billing_subscriptions_customer_idx')
-    })
-
-    this.schema.createTable('billing_payments', (table) => {
-      table.uuid('id').primary()
-      table.string('gateway_id').unique()
-      table.string('provider')
-      table.string('status')
-      table.bigInteger('amount')
-      table.string('currency', 3)
-      table.string('customer_id').nullable()
-      table.string('subscription_id').nullable()
-      table.jsonb('payload').nullable()
-      table.timestamp('paid_at', { useTz: true }).nullable()
-      table.timestamp('created_at', { useTz: true }).notNullable()
-      table.timestamp('updated_at', { useTz: true }).notNullable()
-      table.index(['customer_id'], 'billing_payments_customer_idx')
-      table.index(['subscription_id'], 'billing_payments_subscription_idx')
-    })
-
-    this.schema.createTable('billing_webhook_events', (table) => {
-      table.uuid('id').primary()
-      table.string('gateway_event_id').unique()
-      table.string('provider')
-      table.string('type')
-      table.string('status')
-      table.jsonb('payload').nullable()
-      table.text('error').nullable()
-      table.timestamp('created_at', { useTz: true }).notNullable()
-      table.timestamp('updated_at', { useTz: true }).notNullable()
-    })
-
-    this.schema.createTable('billing_usage_events', (table) => {
-      table.uuid('id').primary()
-      table.string('subscription_id').nullable()
-      table.string('customer_id').nullable()
-      table.string('meter')
-      table.integer('quantity').defaultTo(1)
-      table.jsonb('metadata').nullable()
-      table.timestamp('recorded_at', { useTz: true }).notNullable()
-      table.timestamp('updated_at', { useTz: true }).notNullable()
-      table.index(['subscription_id', 'meter'], 'billing_usage_subscription_meter_idx')
-      table.index(['customer_id', 'meter'], 'billing_usage_customer_meter_idx')
+    this.defer(async (db) => {
+      await createBillingTables(db)
     })
   }
 
   async down() {
-    this.schema.dropTable('billing_customers')
-    this.schema.dropTable('billing_subscriptions')
-    this.schema.dropTable('billing_payments')
-    this.schema.dropTable('billing_webhook_events')
-    this.schema.dropTable('billing_usage_events')
+    this.defer(async (db) => {
+      await dropBillingTables(db)
+    })
   }
 }

package/dist/stubs/make/webhook_handler/main.stub

@@ -6,24 +6,42 @@
   })
 }}}
 import { inject } from '@adonisjs/core'
-import type { WebhookEvent } from '@adonis-agora/payments'
+import type { WebhookEventFor } from '@adonis-agora/payments'
 
 /**
- * Webhook handler para `{{ entity.name }}` — rodado pela rota da própria lib
- * (`/payments/webhook/:provider`) dentro do WebhookProcessor. Um throw marca o evento
- * como failed no ledger e o dispatcher re-tenta (durable/in-process).
+ * Webhook handler for `{{ entity.name }}`, run by the library's own route
+ * (`POST /payments/webhook/:provider`) inside the WebhookProcessor. Throwing marks the
+ * event `failed` in the ledger, the dispatcher retries, and the route answers 500 so the
+ * gateway redelivers — a 2xx over a failed event is the payment lost.
  *
- * Faça a lógica pesada rodar numa fila/workflow durable e dispatch aqui:
+ * The class is resolved from the container, so constructor injection works: add a
+ * dependency and `@inject()` supplies it.
  *
- *   const engine = await app.container.make(WorkflowEngine)
- *   await engine.start(MyWorkflow, { ... }, randomUUID())
+ * `eventType` is checked at BOOT: a type in the `payment.*`/`subscription.*` namespace that
+ * is not one of the normalized `WEBHOOK_EVENT_TYPES` throws, because a handler nothing ever
+ * calls is a grant that silently never happens while the delivery is recorded as processed.
+ *
+ * Webhooks must answer fast. Do the heavy work — the grant, the activation — in a durable
+ * workflow and only dispatch from here:
+ *
+ *   await this.engine.start(MyWorkflow, { externalReference }, randomUUID())
  */
 @inject()
 export default class {{ handlerName }}Handler {
   static readonly eventType = '{{ entity.name }}'
 
-  async handle(event: WebhookEvent): Promise<void> {
-    // Sua lógica de negócio (ou dispatch pra um workflow durable / job da fila)...
-    void event
+  /**
+   * `WebhookEventFor<'{{ entity.name }}'>` types `event.data` from the event type — a payment
+   * payload for the payment events, a dispute payload for the dispute ones — so nothing here
+   * needs the `event.data as PaymentWebhookData` cast that used to open every handler, and
+   * reading a payment field off a dispute is a compile error rather than `undefined`.
+   */
+  async handle(event: WebhookEventFor<'{{ entity.name }}'>): Promise<void> {
+    // `externalReference` is the id YOUR app set on the charge, echoed back by the
+    // gateway — the routing key from this event to your own row.
+    const { externalReference } = event.data
+    if (!externalReference) return
+
+    void externalReference
   }
-}
+}