@aquarian-metals/coin-moebius-coinbase-business 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aquarian-metals
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @aquarian-metals/coin-moebius-coinbase-business
+
+Coinbase Business provider for **[Coin Moebius](https://github.com/aquarian-metals/coin-moebius)**.
+
+Three entries in one package:
+
+- `@aquarian-metals/coin-moebius-coinbase-business` — browser entry, redirects to Coinbase's hosted checkout.
+- `@aquarian-metals/coin-moebius-coinbase-business/server` — Node-only webhook verifier (Hook0 v1 signatures). **Never import this from browser code.**
+- `@aquarian-metals/coin-moebius-coinbase-business/subscription` — optional, server-only helper that creates a webhook subscription via the CDP API. Import this if you want to provision the subscription from your own code; ignore it if you manage the subscription out-of-band.
+
+## Replaces Coinbase Commerce
+
+🚨 Coinbase Commerce was sunset for new merchants and the migration cutover ran on March 31, 2026. The legacy `coinbase-commerce-node` SDK targets the deprecated Commerce surface. This package targets the current Coinbase Business Checkout API instead.
+
+## Geography
+
+Coinbase Business currently supports merchants registered in the United States or Singapore only. Merchants in other jurisdictions cannot use this provider until Coinbase expands eligibility.
+
+## Install
+
+For the browser:
+
+```bash
+npm install @aquarian-metals/coin-moebius-coinbase-business
+```
+
+No additional dependencies required for the server verifier — it uses Web Crypto exclusively.
+
+## Use — browser
+
+```ts
+import { createCoinbaseBusinessProvider } from '@aquarian-metals/coin-moebius-coinbase-business';
+import { createPaymentManager } from '@aquarian-metals/coin-moebius';
+
+const payments = createPaymentManager({
+  providers: [
+    createCoinbaseBusinessProvider({
+      sessionEndpoint: '/api/checkout/coinbase-business',
+    }),
+  ],
+});
+```
+
+The session endpoint on your server is expected to call Coinbase's Checkout API and return `{ url: hosted_url }`. The provider redirects the buyer to `hosted_url` and fires `onPending` synchronously.
+
+## Use — server (webhook verification)
+
+```ts
+import { createCoinbaseBusinessVerifier } from '@aquarian-metals/coin-moebius-coinbase-business/server';
+
+const verify = createCoinbaseBusinessVerifier({
+  webhookSecret: process.env.COINBASE_BUSINESS_WEBHOOK_SECRET,
+});
+
+// inside your webhook route:
+const result = await verify.verify(rawBody, request.headers);
+if (result) {
+  // result.status is one of: 'success' | 'failed'
+  // result.paymentId is the Coinbase checkout id
+}
+```
+
+### Status mapping
+
+| Coinbase event             | `PaymentResult.status`                               |
+| -------------------------- | ---------------------------------------------------- |
+| `checkout.payment.success` | `success`                                            |
+| `checkout.payment.failed`  | `failed`                                             |
+| `checkout.payment.expired` | `failed`                                             |
+| anything else              | (verifier returns `null`, signature still validated) |
+
+Coinbase Business does not emit an in-flight `pending` event. The buyer experience between session creation and the first webhook is "awaiting payment" by absence-of-event, not a positive signal. If your UX needs an interim state, render it from the moment your session endpoint responds and clear it on the webhook.
+
+### Webhook signature format
+
+Coinbase routes Business webhooks through [Hook0](https://documentation.hook0.com/). The signature header is structured, not a bare digest:
+
+```
+X-Hook0-Signature: t=<unix-seconds>,h=<space-separated-header-names>,v1=<hex-sha256>
+```
+
+The signed content is `${t}.${h}.${headerValues.join('.')}.${rawBody}`, HMAC-SHA256 with the webhook secret. The verifier handles the parsing for you, but if you ever need to verify by hand the format is the same as Hook0's published Node.js reference.
+
+The verifier also enforces a 5-minute replay window by default. Override with `maxAgeSeconds` if you have a legitimate reason (e.g., replaying captured fixtures).
+
+## Use — server (programmatic webhook subscription)
+
+Coinbase Business does not expose a dashboard form to add a webhook URL. The subscription must be created via API, and the signing secret is **only returned on the create response** — you cannot retrieve it later.
+
+```ts
+import { createCoinbaseBusinessSubscription } from '@aquarian-metals/coin-moebius-coinbase-business/subscription';
+
+const sub = createCoinbaseBusinessSubscription({
+  cdpKeyId: process.env.CDP_KEY_ID,
+  cdpPrivateKeyPem: process.env.CDP_PRIVATE_KEY_PEM,
+  mode: 'live',
+});
+
+const { subscriptionId, signingSecret } = await sub.subscribe({
+  callbackUrl: 'https://app.example.com/webhook/coinbase-business',
+});
+
+// Persist signingSecret now. It is not retrievable later.
+```
+
+### CDP key setup
+
+1. Create a CDP account at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com).
+2. Under API Keys, create a new key. Coinbase issues an EC P-256 keypair; download the private key (PEM, PKCS8) when prompted.
+3. Pass the key id to `cdpKeyId` and the PEM contents to `cdpPrivateKeyPem`.
+
+The helper signs requests with ES256 (ECDSA P-256 + SHA-256). Coinbase also supports Ed25519, but ES256 has broader Web Crypto support across older runtimes and Coinbase accepts both.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Coinbase Business client-side provider for Coin Moebius.
+ *
+ * Hosted-checkout flow only. The provider POSTs the buyer's selection to the
+ * caller's `sessionEndpoint`, receives `{ url }` pointing at Coinbase
+ * Business's `hosted_url`, fires `onPending`, and redirects the buyer there.
+ * Coinbase handles the asset picker, on-chain monitoring, and forwarding.
+ *
+ * The server-side webhook verifier lives at `./server` and the optional
+ * programmatic subscription helper at `./subscription`, so this browser
+ * entry stays free of Node-only crypto and HTTP code.
+ *
+ *     import { createCoinbaseBusinessProvider } from '@aquarian-metals/coin-moebius-coinbase-business';
+ *     const coinbase = createCoinbaseBusinessProvider({
+ *       sessionEndpoint: '/api/checkout/coinbase-business',
+ *     });
+ *
+ *     const manager = createPaymentManager({ providers: [coinbase] });
+ *     await manager.initiate({ productId: 'pro', amount: 9.99, currency: 'USD' });
+ */
+import type { PaymentProvider } from '@aquarian-metals/coin-moebius-core';
+export interface CoinbaseBusinessProviderConfig {
+    /** Full URL of the session endpoint that returns `{ url: hosted_url }`. */
+    sessionEndpoint: string;
+    /** Optional fetch override — used by tests. Defaults to global `fetch`. */
+    fetcher?: typeof fetch;
+    /** Optional navigation override — used by tests. Defaults to `location.assign`. */
+    navigate?: (url: string) => void;
+}
+/**
+ * Build a `PaymentProvider` registered as `id: 'coinbase-business'`. Returns a
+ * `PaymentResult` with status `'pending'` immediately after redirect; the
+ * actual settlement lands on the server via the Hook0-signed webhook.
+ * Coinbase Business does not fire any in-flight event before `success` /
+ * `failed` / `expired`, so consumers wanting buyer-side completion should
+ * also call `manager.subscribeToStatus(paymentId, …)` after `initiate`.
+ */
+export declare function createCoinbaseBusinessProvider(config: CoinbaseBusinessProviderConfig): PaymentProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EACX,eAAe,EAGf,MAAM,oCAAoC,CAAC;AAE5C,MAAM,WAAW,8BAA8B;IAC9C,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAQD;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC7C,MAAM,EAAE,8BAA8B,GACpC,eAAe,CAmDjB"}

package/dist/index.js

@@ -0,0 +1,57 @@
+/**
+ * Build a `PaymentProvider` registered as `id: 'coinbase-business'`. Returns a
+ * `PaymentResult` with status `'pending'` immediately after redirect; the
+ * actual settlement lands on the server via the Hook0-signed webhook.
+ * Coinbase Business does not fire any in-flight event before `success` /
+ * `failed` / `expired`, so consumers wanting buyer-side completion should
+ * also call `manager.subscribeToStatus(paymentId, …)` after `initiate`.
+ */
+export function createCoinbaseBusinessProvider(config) {
+    const fetcher = config.fetcher ?? globalThis.fetch.bind(globalThis);
+    const navigate = config.navigate ??
+        ((url) => {
+            window.location.assign(url);
+        });
+    return {
+        id: 'coinbase-business',
+        name: 'Coinbase Business',
+        async initiate(options, callbacks) {
+            try {
+                const body = {
+                    productId: options.productId,
+                    amount: options.amount,
+                    currency: options.currency,
+                };
+                if (options.metadata)
+                    body.metadata = options.metadata;
+                const response = await fetcher(config.sessionEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(body),
+                });
+                if (!response.ok) {
+                    throw new Error(`coin-moebius/coinbase-business: session endpoint responded ${response.status}`);
+                }
+                const payload = (await response.json());
+                if (!payload.url) {
+                    throw new Error('coin-moebius/coinbase-business: session response missing `url`');
+                }
+                const result = {
+                    status: 'pending',
+                    paymentId: payload.paymentId ?? '',
+                    provider: 'coinbase-business',
+                    amount: options.amount,
+                    currency: options.currency,
+                    metadata: options.metadata ?? {},
+                    timestamp: Date.now(),
+                };
+                callbacks.onPending?.(result);
+                navigate(payload.url);
+            }
+            catch (err) {
+                callbacks.onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyCA;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B,CAC7C,MAAsC;IAEtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpE,MAAM,QAAQ,GACb,MAAM,CAAC,QAAQ;QACf,CAAC,CAAC,GAAW,EAAE,EAAE;YAChB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IAEJ,OAAO;QACN,EAAE,EAAE,mBAAmB;QACvB,IAAI,EAAE,mBAAmB;QACzB,KAAK,CAAC,QAAQ,CAAC,OAAwB,EAAE,SAAS;YACjD,IAAI,CAAC;gBACJ,MAAM,IAAI,GAA4B;oBACrC,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;iBAC1B,CAAC;gBACF,IAAI,OAAO,CAAC,QAAQ;oBAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;gBAEvD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE;oBACtD,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;oBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;iBAC1B,CAAC,CAAC;gBACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CACd,8DAA8D,QAAQ,CAAC,MAAM,EAAE,CAC/E,CAAC;gBACH,CAAC;gBACD,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAoB,CAAC;gBAC3D,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;gBACnF,CAAC;gBAED,MAAM,MAAM,GAAkB;oBAC7B,MAAM,EAAE,SAAS;oBACjB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;oBAClC,QAAQ,EAAE,mBAAmB;oBAC7B,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;oBAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;oBAChC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;iBACrB,CAAC;gBACF,SAAS,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC;gBAC9B,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,SAAS,CAAC,OAAO,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACxE,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Coinbase Business server-side webhook verifier. Implements the Hook0 v1
+ * signature scheme (Coinbase routes Business Checkout webhooks through Hook0;
+ * see <https://documentation.hook0.com/tutorials/webhook-authentication>):
+ *
+ *   X-Hook0-Signature: t=<unix-seconds>,h=<space-separated-header-names>,v1=<hex-sha256>
+ *
+ *   signed = `${t}.${h}.${headerValues.join('.')}.${rawBody}`
+ *   v1     = HMAC-SHA256(signed, webhookSecret)   // hex-encoded
+ *
+ * Where `headerValues` are the inbound request's values for the headers
+ * listed (in order) in the `h=` field. The `h=` field is space-separated and
+ * header names are matched case-insensitively. If `h=` is absent (Hook0 v0
+ * legacy mode), the signed content is `${t}.${rawBody}`.
+ *
+ * A replay-window guard (default 300 seconds) rejects messages where
+ * `now - t > maxAgeSeconds`. Tests pass `Number.POSITIVE_INFINITY` to bypass
+ * wall-clock drift on captured fixtures.
+ *
+ * The verifier returns a `PaymentResult` for the three Checkout API event
+ * types and resolves to `null` for any other signed event so consumers can
+ * skip non-payment deliveries without polluting their transaction store:
+ *
+ *   checkout.payment.success → success
+ *   checkout.payment.failed  → failed
+ *   checkout.payment.expired → failed   (treated as terminal negative)
+ *
+ * Coinbase Business does not emit an in-flight `pending` event; absence-of-
+ * event is the "awaiting payment" signal between checkout creation and the
+ * first webhook landing.
+ */
+import type { WebhookEvent } from '@aquarian-metals/coin-moebius-core';
+export interface CoinbaseBusinessVerifierConfig {
+    /**
+     * Webhook signing secret returned by Coinbase at subscription creation
+     * time. Coinbase does not expose this secret in a dashboard after
+     * creation — capture it on the subscription response and persist it.
+     */
+    webhookSecret: string;
+    /**
+     * Maximum age, in seconds, that a webhook's `t=` timestamp can be before
+     * the verifier rejects it. Defaults to 300 (matches Hook0's default
+     * replay window). Set to `Number.POSITIVE_INFINITY` in tests against
+     * fixed-time fixtures.
+     */
+    maxAgeSeconds?: number;
+    /**
+     * Clock override. Returns the current time in seconds. Defaults to
+     * `Math.floor(Date.now() / 1000)`. Useful for deterministic tests.
+     */
+    now?: () => number;
+}
+export interface WebhookVerifier {
+    verify(rawBody: unknown, headers: Record<string, string | undefined>): Promise<WebhookEvent | null>;
+}
+/**
+ * Parsed components of the `X-Hook0-Signature` header. Exposed for callers
+ * that want to validate the header shape without running the full HMAC step.
+ */
+export interface ParsedHook0Signature {
+    timestamp: number;
+    headerNames: string[];
+    signature: string;
+}
+export declare function createCoinbaseBusinessVerifier(config: CoinbaseBusinessVerifierConfig): WebhookVerifier;
+/**
+ * Parse a raw `X-Hook0-Signature` header value into its `t`, `h`, `v1`
+ * components. Throws if any required field is missing or malformed.
+ *
+ * Exported so callers with non-standard rawBody pipelines can validate the
+ * header shape without going through the full verifier.
+ */
+export declare function parseHook0Signature(header: string): ParsedHook0Signature;
+/**
+ * Compute the canonical Hook0 v1 signature. Hex-encoded HMAC-SHA256 over
+ * `${t}.${h}.${headerValues.join('.')}.${rawBody}`, or `${t}.${rawBody}` when
+ * `headerNames` is empty (v0 legacy form).
+ *
+ * Exported so callers can verify with the same routine without re-importing
+ * internals.
+ */
+export declare function computeCoinbaseBusinessSignature(timestamp: number, headerNames: readonly string[], headerValues: readonly string[], rawBody: string, webhookSecret: string): Promise<string>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEtF,MAAM,WAAW,8BAA8B;IAC9C;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,MAAM,CACL,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACzC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,8BAA8B,CAC7C,MAAM,EAAE,8BAA8B,GACpC,eAAe,CA0CjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAuBxE;AAED;;;;;;;GAOG;AACH,wBAAsB,gCAAgC,CACrD,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/server.js

@@ -0,0 +1,203 @@
+/**
+ * Coinbase Business server-side webhook verifier. Implements the Hook0 v1
+ * signature scheme (Coinbase routes Business Checkout webhooks through Hook0;
+ * see <https://documentation.hook0.com/tutorials/webhook-authentication>):
+ *
+ *   X-Hook0-Signature: t=<unix-seconds>,h=<space-separated-header-names>,v1=<hex-sha256>
+ *
+ *   signed = `${t}.${h}.${headerValues.join('.')}.${rawBody}`
+ *   v1     = HMAC-SHA256(signed, webhookSecret)   // hex-encoded
+ *
+ * Where `headerValues` are the inbound request's values for the headers
+ * listed (in order) in the `h=` field. The `h=` field is space-separated and
+ * header names are matched case-insensitively. If `h=` is absent (Hook0 v0
+ * legacy mode), the signed content is `${t}.${rawBody}`.
+ *
+ * A replay-window guard (default 300 seconds) rejects messages where
+ * `now - t > maxAgeSeconds`. Tests pass `Number.POSITIVE_INFINITY` to bypass
+ * wall-clock drift on captured fixtures.
+ *
+ * The verifier returns a `PaymentResult` for the three Checkout API event
+ * types and resolves to `null` for any other signed event so consumers can
+ * skip non-payment deliveries without polluting their transaction store:
+ *
+ *   checkout.payment.success → success
+ *   checkout.payment.failed  → failed
+ *   checkout.payment.expired → failed   (treated as terminal negative)
+ *
+ * Coinbase Business does not emit an in-flight `pending` event; absence-of-
+ * event is the "awaiting payment" signal between checkout creation and the
+ * first webhook landing.
+ */
+const DEFAULT_MAX_AGE_SECONDS = 300;
+export function createCoinbaseBusinessVerifier(config) {
+    const maxAge = config.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+    const now = config.now ?? (() => Math.floor(Date.now() / 1000));
+    return {
+        async verify(rawBody, headers) {
+            if (!config.webhookSecret) {
+                throw new Error('coin-moebius/coinbase-business: webhookSecret missing on verifier config');
+            }
+            const signatureHeader = headerValue(headers, 'x-hook0-signature');
+            if (!signatureHeader) {
+                throw new Error('coin-moebius/coinbase-business: missing x-hook0-signature header');
+            }
+            const parsed = parseHook0Signature(signatureHeader);
+            // Replay-window guard. Distinct from signature failure so callers
+            // can log the two cases separately if they want.
+            const age = Math.abs(now() - parsed.timestamp);
+            if (age > maxAge) {
+                throw new Error(`coin-moebius/coinbase-business: webhook timestamp outside replay window (age ${age}s, max ${maxAge}s)`);
+            }
+            const bodyString = normalizeBody(rawBody);
+            const expected = await computeCoinbaseBusinessSignature(parsed.timestamp, parsed.headerNames, parsed.headerNames.map((name) => headerValue(headers, name) ?? ''), bodyString, config.webhookSecret);
+            if (!timingSafeStringEqual(expected, parsed.signature)) {
+                throw new Error('coin-moebius/coinbase-business: invalid signature');
+            }
+            return toPaymentResult(bodyString);
+        },
+    };
+}
+/**
+ * Parse a raw `X-Hook0-Signature` header value into its `t`, `h`, `v1`
+ * components. Throws if any required field is missing or malformed.
+ *
+ * Exported so callers with non-standard rawBody pipelines can validate the
+ * header shape without going through the full verifier.
+ */
+export function parseHook0Signature(header) {
+    const parts = {};
+    for (const piece of header.split(',')) {
+        const eq = piece.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = piece.slice(0, eq).trim();
+        const value = piece.slice(eq + 1).trim();
+        if (key)
+            parts[key] = value;
+    }
+    const t = Number.parseInt(parts.t ?? '', 10);
+    if (!Number.isFinite(t) || t <= 0) {
+        throw new Error('coin-moebius/coinbase-business: signature header missing or invalid `t`');
+    }
+    const signature = parts.v1;
+    if (!signature) {
+        throw new Error('coin-moebius/coinbase-business: signature header missing `v1`');
+    }
+    // `h` is optional. Hook0 v0 deliveries omit it; the signed payload then
+    // is just `${t}.${rawBody}`. We handle both shapes via an empty list.
+    const headerNames = parts.h ? parts.h.split(/\s+/).filter(Boolean) : [];
+    return { timestamp: t, headerNames, signature };
+}
+/**
+ * Compute the canonical Hook0 v1 signature. Hex-encoded HMAC-SHA256 over
+ * `${t}.${h}.${headerValues.join('.')}.${rawBody}`, or `${t}.${rawBody}` when
+ * `headerNames` is empty (v0 legacy form).
+ *
+ * Exported so callers can verify with the same routine without re-importing
+ * internals.
+ */
+export async function computeCoinbaseBusinessSignature(timestamp, headerNames, headerValues, rawBody, webhookSecret) {
+    if (headerNames.length !== headerValues.length) {
+        throw new Error('coin-moebius/coinbase-business: headerNames / headerValues length mismatch');
+    }
+    const signed = headerNames.length === 0
+        ? `${timestamp}.${rawBody}`
+        : `${timestamp}.${headerNames.join(' ')}.${headerValues.join('.')}.${rawBody}`;
+    const message = new TextEncoder().encode(signed);
+    const keyBytes = new TextEncoder().encode(webhookSecret);
+    const key = await crypto.subtle.importKey('raw', keyBytes, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sigBuf = await crypto.subtle.sign('HMAC', key, message);
+    return toHex(new Uint8Array(sigBuf));
+}
+function toPaymentResult(bodyString) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyString);
+    }
+    catch {
+        throw new Error('coin-moebius/coinbase-business: body is not valid JSON');
+    }
+    const eventType = parsed.event?.type ?? parsed.type ?? '';
+    const data = parsed.event?.data ?? parsed.data ?? {};
+    const status = mapEventType(eventType);
+    if (status === null)
+        return null;
+    const { amount, currency } = readAmountAndCurrency(data);
+    return {
+        kind: 'payment',
+        status,
+        paymentId: String(data.checkout_id ?? data.id ?? ''),
+        provider: 'coinbase-business',
+        amount,
+        currency,
+        metadata: {
+            ...(data.metadata ?? {}),
+            coinbaseEventType: eventType,
+        },
+        timestamp: Date.now(),
+        raw: parsed,
+    };
+}
+/**
+ * Map Coinbase Business event types to the SDK's `PaymentStatus` union.
+ * Unknown events return `null` so consumers can skip non-payment deliveries.
+ *
+ *   checkout.payment.success → success
+ *   checkout.payment.failed  → failed
+ *   checkout.payment.expired → failed (terminal negative, treated like fail)
+ */
+function mapEventType(eventType) {
+    switch (eventType) {
+        case 'checkout.payment.success':
+            return 'success';
+        case 'checkout.payment.failed':
+        case 'checkout.payment.expired':
+            return 'failed';
+        default:
+            return null;
+    }
+}
+function readAmountAndCurrency(data) {
+    // Coinbase Business returns the local-currency price under a few shapes
+    // depending on the API revision. Probe each and fall back to zero/USD
+    // so the verifier never throws on an otherwise-valid signed event.
+    const local = data.pricing?.local ?? data.local_price;
+    const rawAmount = local?.amount ?? data.amount;
+    const amount = typeof rawAmount === 'string' ? Number.parseFloat(rawAmount) : (rawAmount ?? 0);
+    const currency = (local?.currency ?? data.currency ?? 'USD').toUpperCase();
+    return { amount: Number.isFinite(amount) ? amount : 0, currency };
+}
+function normalizeBody(rawBody) {
+    if (typeof rawBody === 'string')
+        return rawBody;
+    if (rawBody instanceof Uint8Array)
+        return new TextDecoder().decode(rawBody);
+    if (rawBody && typeof rawBody === 'object')
+        return JSON.stringify(rawBody);
+    throw new Error('coin-moebius/coinbase-business: unsupported body type');
+}
+function headerValue(headers, name) {
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower)
+            return value;
+    }
+    return undefined;
+}
+function timingSafeStringEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i++) {
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return mismatch === 0;
+}
+function toHex(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/subscription.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Programmatic webhook-subscription helper for Coinbase Business. Calls the
+ * CDP webhook subscriptions endpoint to register a callback URL, signing it
+ * with a CDP-issued JWT. The response contains the webhook signing secret;
+ * **this is the only time Coinbase exposes that secret**, so the caller must
+ * persist it before returning to the user.
+ *
+ * Coinbase Business does not expose a dashboard form to paste a webhook URL.
+ * Subscription creation is programmatic-only — callers who want to manage
+ * webhook subscriptions in their own provisioning flow import this module.
+ * Callers who only need to verify incoming webhooks can ignore it entirely.
+ *
+ * The JWT is signed with ES256 (ECDSA P-256 + SHA-256) via Web Crypto, which
+ * is universally available on Workers, Bun, Node 18+, and modern browsers.
+ * Coinbase's docs also list Ed25519/EdDSA as "recommended" but Web Crypto
+ * support for Ed25519 is uneven across older runtimes; ES256 is the safe
+ * cross-runtime choice and Coinbase accepts both.
+ */
+export type CoinbaseBusinessMode = 'live' | 'sandbox';
+export interface CoinbaseBusinessSubscriptionConfig {
+    /** CDP API key id (the `kid` field on the JWT). */
+    cdpKeyId: string;
+    /**
+     * CDP-issued EC P-256 private key in PEM form (PKCS8). Coinbase shows
+     * this once at key creation; persist it on the caller side.
+     */
+    cdpPrivateKeyPem: string;
+    /** Selects sandbox vs production CDP endpoints. */
+    mode?: CoinbaseBusinessMode;
+    /** Optional fetch override — used by tests. Defaults to global `fetch`. */
+    fetcher?: typeof fetch;
+}
+export interface SubscribeOptions {
+    /** Public HTTPS URL where Coinbase will deliver webhook events. */
+    callbackUrl: string;
+    /**
+     * Event types to subscribe to. Defaults to the three Checkout payment
+     * events the verifier maps. Pass an empty array to receive every
+     * event Coinbase emits (not recommended; the verifier returns `null`
+     * for non-payment events anyway, but bandwidth is bandwidth).
+     */
+    eventTypes?: readonly string[];
+}
+export interface SubscribeResult {
+    /** Coinbase subscription id; persist for future deletes/updates. */
+    subscriptionId: string;
+    /**
+     * The webhook signing secret. **Not retrievable later** — persist this
+     * now or you'll need to delete and recreate the subscription.
+     */
+    signingSecret: string;
+    /** Raw response payload for callers that need additional fields. */
+    raw: unknown;
+}
+export declare function createCoinbaseBusinessSubscription(config: CoinbaseBusinessSubscriptionConfig): {
+    subscribe(options: SubscribeOptions): Promise<SubscribeResult>;
+};
+/**
+ * Build and sign a CDP-flavored JWT. Exposed so callers integrating other
+ * CDP endpoints (Advanced Trade, Onchain) can reuse the same routine.
+ *
+ * The JWT pattern is documented at
+ * <https://docs.cdp.coinbase.com/get-started/authentication/jwt-authentication>:
+ *
+ *   header  = { alg: 'ES256', typ: 'JWT', kid: <keyId>, nonce: <random> }
+ *   payload = { sub: <keyId>, iss: 'cdp', aud: ['cdp_service'],
+ *               nbf: <now>, exp: <now + 120>, uri: '<METHOD> <host+path>' }
+ */
+export declare function signCdpJwt(options: {
+    keyId: string;
+    privateKeyPem: string;
+    method: string;
+    url: string;
+}): Promise<string>;
+//# sourceMappingURL=subscription.d.ts.map

package/dist/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../src/subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,kCAAkC;IAClD,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAChC,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,GAAG,EAAE,OAAO,CAAC;CACb;AAUD,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,kCAAkC;uBAIlE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;EAwCrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,MAAM,CAAC,CAkClB"}

package/dist/subscription.js

@@ -0,0 +1,140 @@
+/**
+ * Programmatic webhook-subscription helper for Coinbase Business. Calls the
+ * CDP webhook subscriptions endpoint to register a callback URL, signing it
+ * with a CDP-issued JWT. The response contains the webhook signing secret;
+ * **this is the only time Coinbase exposes that secret**, so the caller must
+ * persist it before returning to the user.
+ *
+ * Coinbase Business does not expose a dashboard form to paste a webhook URL.
+ * Subscription creation is programmatic-only — callers who want to manage
+ * webhook subscriptions in their own provisioning flow import this module.
+ * Callers who only need to verify incoming webhooks can ignore it entirely.
+ *
+ * The JWT is signed with ES256 (ECDSA P-256 + SHA-256) via Web Crypto, which
+ * is universally available on Workers, Bun, Node 18+, and modern browsers.
+ * Coinbase's docs also list Ed25519/EdDSA as "recommended" but Web Crypto
+ * support for Ed25519 is uneven across older runtimes; ES256 is the safe
+ * cross-runtime choice and Coinbase accepts both.
+ */
+const SUBSCRIPTION_URL = 'https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions';
+const JWT_LIFETIME_SECONDS = 120;
+const DEFAULT_EVENT_TYPES = [
+    'checkout.payment.success',
+    'checkout.payment.failed',
+    'checkout.payment.expired',
+];
+export function createCoinbaseBusinessSubscription(config) {
+    const fetcher = config.fetcher ?? globalThis.fetch.bind(globalThis);
+    return {
+        async subscribe(options) {
+            const eventTypes = options.eventTypes ?? DEFAULT_EVENT_TYPES;
+            const jwt = await signCdpJwt({
+                keyId: config.cdpKeyId,
+                privateKeyPem: config.cdpPrivateKeyPem,
+                method: 'POST',
+                url: SUBSCRIPTION_URL,
+            });
+            const response = await fetcher(SUBSCRIPTION_URL, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${jwt}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    callback_url: options.callbackUrl,
+                    event_types: eventTypes,
+                    environment: config.mode ?? 'live',
+                }),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                throw new Error(`coin-moebius/coinbase-business: subscription create failed (${response.status}): ${body}`);
+            }
+            const payload = (await response.json());
+            const subscriptionId = readString(payload, 'id', 'subscription_id');
+            const signingSecret = readString(payload, 'signing_secret', 'secret');
+            if (!subscriptionId || !signingSecret) {
+                throw new Error('coin-moebius/coinbase-business: subscription response missing id or signing_secret');
+            }
+            return { subscriptionId, signingSecret, raw: payload };
+        },
+    };
+}
+/**
+ * Build and sign a CDP-flavored JWT. Exposed so callers integrating other
+ * CDP endpoints (Advanced Trade, Onchain) can reuse the same routine.
+ *
+ * The JWT pattern is documented at
+ * <https://docs.cdp.coinbase.com/get-started/authentication/jwt-authentication>:
+ *
+ *   header  = { alg: 'ES256', typ: 'JWT', kid: <keyId>, nonce: <random> }
+ *   payload = { sub: <keyId>, iss: 'cdp', aud: ['cdp_service'],
+ *               nbf: <now>, exp: <now + 120>, uri: '<METHOD> <host+path>' }
+ */
+export async function signCdpJwt(options) {
+    const now = Math.floor(Date.now() / 1000);
+    const parsedUrl = new URL(options.url);
+    const uriClaim = `${options.method.toUpperCase()} ${parsedUrl.host}${parsedUrl.pathname}`;
+    const header = {
+        alg: 'ES256',
+        typ: 'JWT',
+        kid: options.keyId,
+        nonce: randomNonce(),
+    };
+    const payload = {
+        sub: options.keyId,
+        iss: 'cdp',
+        aud: ['cdp_service'],
+        nbf: now,
+        exp: now + JWT_LIFETIME_SECONDS,
+        uri: uriClaim,
+    };
+    const signingInput = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(payload))}`;
+    const privateKey = await importEcPrivateKey(options.privateKeyPem);
+    const signatureBuf = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, privateKey, new TextEncoder().encode(signingInput));
+    // Web Crypto returns the IEEE P1363 raw r||s format, which is exactly
+    // what JOSE wants for ES256 (no DER decoding needed).
+    const signature = base64UrlEncodeBytes(new Uint8Array(signatureBuf));
+    return `${signingInput}.${signature}`;
+}
+async function importEcPrivateKey(pem) {
+    const pkcs8 = pemToBytes(pem);
+    return crypto.subtle.importKey('pkcs8', pkcs8, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign']);
+}
+function pemToBytes(pem) {
+    const stripped = pem
+        .replace(/-----BEGIN [^-]+-----/, '')
+        .replace(/-----END [^-]+-----/, '')
+        .replace(/\s+/g, '');
+    if (!stripped) {
+        throw new Error('coin-moebius/coinbase-business: empty PEM payload');
+    }
+    const binary = atob(stripped);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function base64UrlEncode(input) {
+    return base64UrlEncodeBytes(new TextEncoder().encode(input));
+}
+function base64UrlEncodeBytes(bytes) {
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function randomNonce() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return base64UrlEncodeBytes(bytes);
+}
+function readString(obj, ...keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=subscription.js.map

package/dist/subscription.js.map

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

package/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "@aquarian-metals/coin-moebius-coinbase-business",
+	"version": "1.0.0",
+	"description": "Coinbase Business provider for Coin Moebius — hosted Checkout API redirect, plus a server-only Hook0 v1 webhook verifier and an optional programmatic webhook-subscription helper. Replaces the deprecated Coinbase Commerce surface.",
+	"keywords": [
+		"payments",
+		"coinbase",
+		"coinbase-business",
+		"crypto",
+		"checkout",
+		"webhook",
+		"hook0",
+		"coin-moebius"
+	],
+	"author": "aquarian-metals",
+	"license": "MIT",
+	"homepage": "https://github.com/aquarian-metals/coin-moebius#readme",
+	"bugs": {
+		"url": "https://github.com/aquarian-metals/coin-moebius/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/aquarian-metals/coin-moebius.git",
+		"directory": "packages/providers/coinbase-business"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./server": {
+			"types": "./dist/server.d.ts",
+			"import": "./dist/server.js"
+		},
+		"./subscription": {
+			"types": "./dist/subscription.d.ts",
+			"import": "./dist/subscription.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+		"build": "npm run clean && tsc",
+		"prepublishOnly": "npm run build"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"@aquarian-metals/coin-moebius-core": "^1.0.0"
+	},
+	"devDependencies": {
+		"typescript": "~5.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}