@genesis-tech/genesispay-seller 0.12.0 → 0.13.1

package/dist/webhooks.js

@@ -1,224 +0,0 @@
-// Webhook signature verification for GenesisPay deliveries.
-//
-// The server signs every delivery in `src/features/sellers/webhooks.ts`:
-//
-//   GENESISPAY-SIGNATURE: t=<unix-seconds>,v1=<hex>
-//   v1 = HMAC_SHA256(secret, `${t}.${rawBody}`)
-//
-// Deliberately implemented on WebCrypto (`globalThis.crypto.subtle`) rather
-// than `node:crypto` so the SDK also runs on Edge runtimes, Cloudflare Workers
-// and Bun. That is why `constructEvent` is async — a conscious deviation from
-// Stripe's synchronous `constructEvent`.
-/**
- * Every event type this SDK version knows. Mirrors the server's
- * `WebhookEventType` (`src/features/sellers/webhooks.ts`) — the drift alarm is
- * `src/features/sellers/webhook-signature-contract.test.ts`, which fails when
- * the server grows a type this list does not have.
- *
- * Exported as a runtime array (not only as a type) so a handler can ask
- * `isKnownGenesisPayEventType(event.type)` before it decides what to do.
- */
-export const GENESISPAY_EVENT_TYPES = [
-    "payment.confirmed",
-    "link.paid",
-    "product.purchased",
-    "agent_payment.pending_approval",
-    "agent_payment.settled",
-    "mandate.active",
-    "mandate.charged",
-    "mandate.charge_failed",
-    "mandate.revoked",
-    "subscription.renewed",
-    "subscription.past_due",
-];
-/** True when `type` is an event type this SDK version knows about. */
-export function isKnownGenesisPayEventType(type) {
-    return GENESISPAY_EVENT_TYPES.includes(type);
-}
-/**
- * Thrown for every rejection path: malformed/missing header, missing `t`/`v1`,
- * timestamp outside the tolerance window, signature mismatch, non-JSON body.
- * Messages never contain the secret or the expected signature.
- */
-export class GenesisPaySignatureVerificationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "GenesisPaySignatureVerificationError";
-    }
-}
-const DEFAULT_TOLERANCE_SECONDS = 300;
-const SIGNATURE_HEADER_NAME = "GENESISPAY-SIGNATURE";
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder("utf-8", { fatal: false });
-/**
- * Parses `t=…,v1=…` tolerantly: any order, surrounding whitespace, and
- * repeated `v1=` values (secret rotation — one match is enough).
- */
-function parseSignatureHeader(header) {
-    let timestampRaw;
-    const signatures = [];
-    for (const rawPart of header.split(",")) {
-        const part = rawPart.trim();
-        if (part.length === 0)
-            continue;
-        const separator = part.indexOf("=");
-        if (separator <= 0) {
-            throw new GenesisPaySignatureVerificationError(`Malformed ${SIGNATURE_HEADER_NAME} header: expected comma-separated key=value pairs.`);
-        }
-        const key = part.slice(0, separator).trim();
-        const value = part.slice(separator + 1).trim();
-        if (key === "t") {
-            // A second `t=` would make the signed payload ambiguous.
-            if (timestampRaw !== undefined) {
-                throw new GenesisPaySignatureVerificationError(`Malformed ${SIGNATURE_HEADER_NAME} header: duplicate "t" value.`);
-            }
-            timestampRaw = value;
-        }
-        else if (key === "v1") {
-            if (value.length > 0)
-                signatures.push(value);
-        }
-        // Unknown keys (future scheme versions) are ignored on purpose.
-    }
-    if (timestampRaw === undefined || timestampRaw.length === 0) {
-        throw new GenesisPaySignatureVerificationError(`Missing "t" in ${SIGNATURE_HEADER_NAME} header.`);
-    }
-    if (!/^\d+$/.test(timestampRaw)) {
-        throw new GenesisPaySignatureVerificationError(`Invalid "t" in ${SIGNATURE_HEADER_NAME} header: expected unix seconds.`);
-    }
-    const timestampSeconds = Number(timestampRaw);
-    if (!Number.isSafeInteger(timestampSeconds)) {
-        throw new GenesisPaySignatureVerificationError(`Invalid "t" in ${SIGNATURE_HEADER_NAME} header: expected unix seconds.`);
-    }
-    if (signatures.length === 0) {
-        throw new GenesisPaySignatureVerificationError(`Missing "v1" in ${SIGNATURE_HEADER_NAME} header.`);
-    }
-    return { timestampSeconds, signatures };
-}
-function getSubtleCrypto() {
-    const subtle = globalThis.crypto?.subtle;
-    if (!subtle) {
-        throw new GenesisPaySignatureVerificationError("WebCrypto (globalThis.crypto.subtle) is unavailable in this runtime; webhook verification requires it.");
-    }
-    return subtle;
-}
-async function computeExpectedSignature(secret, signedPayload) {
-    const subtle = getSubtleCrypto();
-    const key = await subtle.importKey("raw", textEncoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-    const signature = await subtle.sign("HMAC", key, textEncoder.encode(signedPayload));
-    return toHex(new Uint8Array(signature));
-}
-function toHex(bytes) {
-    let hex = "";
-    for (const byte of bytes) {
-        hex += byte.toString(16).padStart(2, "0");
-    }
-    return hex;
-}
-/**
- * Constant-time string comparison. Length is checked first (lengths are not
- * secret), then every byte is folded into an XOR accumulator — no early return
- * and no `===` on the hex strings, so timing does not leak the position of the
- * first differing byte.
- */
-function timingSafeEqualStrings(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let diff = 0;
-    for (let i = 0; i < a.length; i += 1) {
-        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return diff === 0;
-}
-function decodeRawBody(rawBody) {
-    if (typeof rawBody === "string")
-        return rawBody;
-    return textDecoder.decode(rawBody);
-}
-/**
- * Verifies a GenesisPay webhook delivery and returns the parsed event.
- *
- * Pass the **raw** request body exactly as received — never a re-serialized
- * `JSON.parse` + `JSON.stringify` round trip, which changes the bytes and
- * invalidates the signature. Parsing happens only after verification succeeds.
- *
- * An event type this SDK version does not know is **not** a failure: the
- * delivery is verified and returned unchanged, so a server that adds a new
- * event type can never turn a customer's webhook route into a 400. Only the
- * signature and the envelope (`id`, `type`, `createdAt`, object `data`) can
- * reject a delivery. Widen to `GenesisPayAnyEvent` and use
- * `isKnownGenesisPayEventType()` if you want to handle that case explicitly.
- *
- * @throws {GenesisPaySignatureVerificationError} on any verification failure.
- *
- * @example
- * ```ts
- * const event = await constructEvent(
- *   await request.text(),
- *   request.headers.get("genesispay-signature") ?? "",
- *   process.env.GENESISPAY_WEBHOOK_SECRET!,
- * );
- * if (event.type === "payment.confirmed") {
- *   fulfil(event.data.link.clientReferenceId, event.data.attempt.txHash);
- * }
- * ```
- */
-export async function constructEvent(rawBody, signatureHeader, secret, opts = {}) {
-    if (typeof signatureHeader !== "string" || signatureHeader.trim().length === 0) {
-        throw new GenesisPaySignatureVerificationError(`Missing ${SIGNATURE_HEADER_NAME} header.`);
-    }
-    if (typeof secret !== "string" || secret.length === 0) {
-        throw new GenesisPaySignatureVerificationError("Missing webhook signing secret.");
-    }
-    const toleranceSeconds = opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
-    if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
-        throw new GenesisPaySignatureVerificationError("Invalid toleranceSeconds: expected a non-negative number.");
-    }
-    const { timestampSeconds, signatures } = parseSignatureHeader(signatureHeader);
-    const nowMs = opts.nowMs ?? Date.now();
-    const nowSeconds = Math.floor(nowMs / 1_000);
-    const skewSeconds = Math.abs(nowSeconds - timestampSeconds);
-    if (skewSeconds > toleranceSeconds) {
-        // Rejects future timestamps too — a clock-skewed or replayed delivery.
-        throw new GenesisPaySignatureVerificationError(`Webhook timestamp is outside the tolerance window of ${toleranceSeconds}s (off by ${skewSeconds}s).`);
-    }
-    const body = decodeRawBody(rawBody);
-    const expected = await computeExpectedSignature(secret, `${timestampSeconds}.${body}`);
-    let matched = false;
-    for (const candidate of signatures) {
-        // No early break: every candidate is compared so the work does not depend
-        // on which one matches.
-        matched = timingSafeEqualStrings(expected, candidate.toLowerCase()) || matched;
-    }
-    if (!matched) {
-        throw new GenesisPaySignatureVerificationError("Webhook signature mismatch: the payload does not match the signing secret.");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(body);
-    }
-    catch {
-        throw new GenesisPaySignatureVerificationError("Webhook body is not valid JSON.");
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new GenesisPaySignatureVerificationError("Webhook body is not a JSON object.");
-    }
-    // The envelope is asserted rather than cast. `id` in particular is the
-    // documented idempotency key — it is stable across delivery retries, so an
-    // integrator deduping on it would silently process a payment twice if it
-    // arrived as undefined. A signed body that does not carry the envelope means
-    // the sender is not the GenesisPay we know, so failing here is correct.
-    const envelope = parsed;
-    for (const field of ["id", "type", "createdAt"]) {
-        if (typeof envelope[field] !== "string" || envelope[field] === "") {
-            throw new GenesisPaySignatureVerificationError(`Webhook body is missing a string "${field}" field.`);
-        }
-    }
-    if (typeof envelope.data !== "object" ||
-        envelope.data === null ||
-        Array.isArray(envelope.data)) {
-        throw new GenesisPaySignatureVerificationError('Webhook body is missing an object "data" field.');
-    }
-    return parsed;
-}
-//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}