@capxul/sdk 0.1.0-alpha.0

package/dist/types-Cokyqgwm.d.cts

@@ -0,0 +1,202 @@
+import * as types from '@repo/api-contract/gen/types';
+import { PublicId, AccountId, SafeId, OrganizationId, KycProfileId, ExternalAccountId, SubAccountId, BalanceLedgerEntryId, ApiKeyId, TreasuryId, MemberId, KybProfileId, NextAction, PaymentId, TransferId, WithdrawalId, DocumentId, WebhookEndpointId, WebhookEventId, VirtualAccountId, VirtualCardId, OperationId, CorrelationId } from '@repo/platform-kernel';
+
+/**
+ * SDK surface types.
+ *
+ * Derivation policy (post-codegen-relitigation, 2026-04-20):
+ * - Import wire types directly from `@repo/api-contract/gen/types` — the
+ *   new generator (@hey-api/openapi-ts) emits faithful discriminated
+ *   unions from OpenAPI `const:` and narrow string-literal enums, so
+ *   the old `z.infer<typeof schemas.X>` round-trip through Zod (which
+ *   stripped discriminants via `passthrough()`) is gone.
+ * - Rebrand the top-level `id` field on every resource to the kernel's
+ *   branded ID type per `.claude/rules/typescript-style.md`.
+ * - Keep `WithStatus<>` so per-method narrowings are discriminated unions
+ *   (one variant per status literal), which `Extract<T, { status: K }>`
+ *   can narrow inside `matchStatus`.
+ * - Use `Override<>` ONLY where the OpenAPI source emits `additionalProperties`
+ *   open shapes (`Safe.owner`, `Operation.actor`, `Operation.subject`) that
+ *   need the SDK's canonical tagged-ref shape. Every other former
+ *   `Override<>` site was redundant and has been deleted.
+ */
+
+type Rebrand<Wire, Id extends PublicId> = Wire & {
+    readonly id: Id;
+};
+/**
+ * Override-via-intersection helper. Kept for the few wire fields that
+ * OpenAPI emits as open-shape (`additionalProperties` → `{ [key:
+ * string]: unknown }`) where the SDK surface needs the canonical
+ * tagged-ref shape. `Safe.owner`, `Operation.actor`, `Operation.subject`
+ * are the current consumers.
+ */
+type Override<Wire, Fields> = Wire & Fields;
+/**
+ * Distributes over the literal union `S` so the result is a discrim-
+ * inated union (one member per status value). `Extract<T, { status:
+ * "x" }>` narrows correctly against the output — without the
+ * distribution, a plain object with a union-typed `status` field is
+ * not a discriminated union and Extract returns `never`.
+ *
+ * When `S === "action_required"` the variant additionally requires
+ * `nextAction: NextAction` (not optional) per Rule D (CANON.md §4.40 +
+ * sdk-surface.md §3a): `action_required` is inline on mutation /
+ * snapshot responses and callers can safely route via `matchAction`.
+ */
+type WithStatus<T, S extends string> = S extends unknown ? T & {
+    readonly status: S;
+} & (S extends "action_required" ? {
+    readonly nextAction: NextAction;
+} : unknown) : never;
+type Money = types.Money;
+type Settlement = types.Settlement;
+type TimestampIso = types.TimestampIso;
+type UserIdentifier = types.UserIdentifier;
+/**
+ * Tagged reference to the public resource a succeeded operation
+ * produced (per sdk-surface.md §1b `operation`).
+ */
+type OperationResult = {
+    readonly object: "account" | "organization" | "safe" | "treasury" | "kyc_profile" | "kyb_profile" | "external_account" | "payment" | "member" | "withdrawal" | "operation" | "webhook_endpoint" | "webhook_event" | "sub_account" | "virtual_account" | "virtual_card" | "transfer" | "document" | "balance_ledger_entry" | "api_key";
+    readonly id: string;
+};
+/**
+ * Terminal-state error sidecar on resources that can fail (Operation,
+ * Payment, Withdrawal, Transfer).
+ */
+type ResourceError = {
+    readonly code: string;
+    readonly message: string;
+};
+
+type OperationStatus = types.OperationStatus;
+type OperationSummary = Rebrand<types.OperationSummary, OperationId> & {
+    readonly correlationId: CorrelationId;
+};
+/**
+ * Full operation envelope.
+ *
+ * `actor` and `subject` are hand-overridden because OpenAPI emits
+ * them as `additionalProperties` open-shape; SDK surface carries the
+ * canonical tagged-ref shape.
+ *
+ * `nextAction` is re-asserted against the kernel's `NextAction` union
+ * (9 kinds including `confirm_fx_quote` per §4.58) so callers get the
+ * kernel-branded field types (e.g. `Email`, `PhoneNumber`, `Username`
+ * on `fix_destination.recipient`). The wire carries the same 9 kinds
+ * structurally; the kernel re-assertion preserves the SDK surface's
+ * exhaustiveness contract against drift.
+ *
+ * `result` and `error` come through the generator faithfully, but
+ * we re-type them to narrow the tagged-ref `object` field to the
+ * closed `OperationResult["object"]` catalog.
+ */
+type Operation = Override<Rebrand<types.Operation, OperationId>, {
+    readonly correlationId: CorrelationId;
+    readonly actor: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly subject?: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly nextAction?: NextAction;
+    readonly result?: OperationResult | null;
+    readonly error?: ResourceError | null;
+}>;
+type Account = Omit<Rebrand<types.Account, AccountId>, "kycTier" | "primarySafeId"> & {
+    readonly kycTier?: types.Account["kycTier"] | null;
+    readonly primarySafeId?: SafeId | null;
+};
+type AccountLookupResult = types.AccountLookupResult;
+/**
+ * `owner` is hand-overridden: the OpenAPI source emits it as an
+ * `additionalProperties` open object; SDK surface carries the canonical
+ * tagged-ref shape.
+ */
+type Safe = Override<Rebrand<types.Safe, SafeId>, {
+    readonly owner: {
+        readonly type: "account";
+        readonly id: AccountId;
+    } | {
+        readonly type: "organization";
+        readonly id: OrganizationId;
+    };
+}>;
+type Organization = Rebrand<types.Organization, OrganizationId>;
+type Treasury = Rebrand<types.Treasury, TreasuryId> & {
+    readonly organizationId: OrganizationId;
+};
+type KycProfile = Rebrand<types.KycProfile, KycProfileId>;
+type KybProfile = Rebrand<types.KybProfile, KybProfileId>;
+type ExternalAccount = Rebrand<types.ExternalAccount, ExternalAccountId>;
+type ExternalAccountKind = types.ExternalAccountKind;
+type PageInfo = types.PageInfo;
+type List<T> = {
+    readonly object: "list";
+    readonly data: readonly T[];
+    readonly page: PageInfo;
+};
+type WirePaymentWithBrand = Rebrand<types.Payment, PaymentId>;
+type PaymentStatus = "processing" | "action_required" | "succeeded" | "failed" | "canceled";
+/**
+ * Full `Payment` — discriminated union on status so `matchStatus`
+ * narrows correctly.
+ */
+type Payment = WithStatus<WirePaymentWithBrand, PaymentStatus>;
+/**
+ * Per-method narrowing for `payments.create`. Terminal states
+ * (`succeeded`, `canceled`) arrive out-of-band per Rule D (CANON.md
+ * §4.40 + sdk-surface.md §3a), so the synchronous return carries
+ * only `processing | action_required | failed`.
+ */
+type CreatePaymentResult = WithStatus<WirePaymentWithBrand, "processing" | "action_required" | "failed">;
+type PaymentParty = types.PaymentParty;
+type WireWithdrawalWithBrand = Rebrand<types.Withdrawal, WithdrawalId>;
+/**
+ * Canon-aligned superset (resources.mdx §withdrawal lifecycle note).
+ * Wider than `OperationStatus` because `submitted → completed` is a
+ * withdrawal-specific transition driven by external reconciliation
+ * the operation envelope cannot witness directly. Slice 1 of
+ * Withdrawals v1 (#440) widened this from `PaymentStatus` to match
+ * canon.
+ */
+type WithdrawalStatus = "draft" | "action_required" | "processing" | "submitted" | "completed" | "failed" | "canceled";
+type Withdrawal = WithStatus<WireWithdrawalWithBrand, WithdrawalStatus>;
+type CreateWithdrawalResult = WithStatus<WireWithdrawalWithBrand, "processing" | "action_required" | "failed">;
+type WireTransferWithBrand = Rebrand<types.Transfer, TransferId>;
+type TransferStatus = PaymentStatus;
+type Transfer = WithStatus<WireTransferWithBrand, TransferStatus>;
+type CreateTransferResult = WithStatus<WireTransferWithBrand, "processing" | "action_required" | "failed">;
+type TransferEndpoint = types.TransferEndpoint;
+type TransferCustody = types.TransferCustody;
+type TransferFx = types.TransferFx;
+type Document = types.Document & {
+    readonly id: DocumentId;
+};
+type InvoiceDocument = types.InvoiceDocument;
+type PayrollRunDocument = types.PayrollRunDocument;
+type PayrollScheduleDocument = types.PayrollScheduleDocument;
+type ReceiptDocument = types.ReceiptDocument;
+type KycUploadDocument = types.KycUploadDocument;
+type BankStatementDocument = types.BankStatementDocument;
+type TaxFormDocument = types.TaxFormDocument;
+type SubAccount = Rebrand<types.SubAccount, SubAccountId>;
+type SubAccountOwnerKind = types.SubAccountOwnerKind;
+type VirtualAccount = Rebrand<types.VirtualAccount, VirtualAccountId>;
+type VirtualAccountOwnerKind = types.VirtualAccountOwnerKind;
+type VirtualCard = Rebrand<types.VirtualCard, VirtualCardId>;
+type VirtualCardOwnerKind = types.VirtualCardOwnerKind;
+type VirtualCardLimits = types.VirtualCardLimits;
+type WebhookEndpoint = Rebrand<types.WebhookEndpoint, WebhookEndpointId>;
+type WebhookEvent = Rebrand<types.WebhookEvent, WebhookEventId>;
+type ApiKey = Rebrand<types.ApiKey, ApiKeyId>;
+type ApiKeyEnvironment = types.ApiKeyEnvironment;
+type ApiKeyType = types.ApiKeyType;
+type Scope = types.Scope;
+type Member = Rebrand<types.Member, MemberId>;
+type BalanceLedgerEntry = Rebrand<types.BalanceLedgerEntry, BalanceLedgerEntryId>;
+
+export type { WithdrawalStatus as $, Account as A, BalanceLedgerEntry as B, CreatePaymentResult as C, Document as D, ExternalAccount as E, TransferEndpoint as F, TransferFx as G, TransferStatus as H, InvoiceDocument as I, Treasury as J, KybProfile as K, List as L, Member as M, VirtualAccountOwnerKind as N, Operation as O, PageInfo as P, VirtualCard as Q, ReceiptDocument as R, Safe as S, TaxFormDocument as T, UserIdentifier as U, VirtualAccount as V, VirtualCardLimits as W, VirtualCardOwnerKind as X, WebhookEndpoint as Y, WebhookEvent as Z, Withdrawal as _, AccountLookupResult as a, ApiKey as b, ApiKeyEnvironment as c, ApiKeyType as d, BankStatementDocument as e, CreateTransferResult as f, CreateWithdrawalResult as g, ExternalAccountKind as h, KycProfile as i, KycUploadDocument as j, Money as k, OperationStatus as l, OperationSummary as m, Organization as n, Payment as o, PaymentParty as p, PaymentStatus as q, PayrollRunDocument as r, PayrollScheduleDocument as s, Scope as t, Settlement as u, SubAccount as v, SubAccountOwnerKind as w, TimestampIso as x, Transfer as y, TransferCustody as z };

package/dist/types-Cokyqgwm.d.ts

@@ -0,0 +1,202 @@
+import * as types from '@repo/api-contract/gen/types';
+import { PublicId, AccountId, SafeId, OrganizationId, KycProfileId, ExternalAccountId, SubAccountId, BalanceLedgerEntryId, ApiKeyId, TreasuryId, MemberId, KybProfileId, NextAction, PaymentId, TransferId, WithdrawalId, DocumentId, WebhookEndpointId, WebhookEventId, VirtualAccountId, VirtualCardId, OperationId, CorrelationId } from '@repo/platform-kernel';
+
+/**
+ * SDK surface types.
+ *
+ * Derivation policy (post-codegen-relitigation, 2026-04-20):
+ * - Import wire types directly from `@repo/api-contract/gen/types` — the
+ *   new generator (@hey-api/openapi-ts) emits faithful discriminated
+ *   unions from OpenAPI `const:` and narrow string-literal enums, so
+ *   the old `z.infer<typeof schemas.X>` round-trip through Zod (which
+ *   stripped discriminants via `passthrough()`) is gone.
+ * - Rebrand the top-level `id` field on every resource to the kernel's
+ *   branded ID type per `.claude/rules/typescript-style.md`.
+ * - Keep `WithStatus<>` so per-method narrowings are discriminated unions
+ *   (one variant per status literal), which `Extract<T, { status: K }>`
+ *   can narrow inside `matchStatus`.
+ * - Use `Override<>` ONLY where the OpenAPI source emits `additionalProperties`
+ *   open shapes (`Safe.owner`, `Operation.actor`, `Operation.subject`) that
+ *   need the SDK's canonical tagged-ref shape. Every other former
+ *   `Override<>` site was redundant and has been deleted.
+ */
+
+type Rebrand<Wire, Id extends PublicId> = Wire & {
+    readonly id: Id;
+};
+/**
+ * Override-via-intersection helper. Kept for the few wire fields that
+ * OpenAPI emits as open-shape (`additionalProperties` → `{ [key:
+ * string]: unknown }`) where the SDK surface needs the canonical
+ * tagged-ref shape. `Safe.owner`, `Operation.actor`, `Operation.subject`
+ * are the current consumers.
+ */
+type Override<Wire, Fields> = Wire & Fields;
+/**
+ * Distributes over the literal union `S` so the result is a discrim-
+ * inated union (one member per status value). `Extract<T, { status:
+ * "x" }>` narrows correctly against the output — without the
+ * distribution, a plain object with a union-typed `status` field is
+ * not a discriminated union and Extract returns `never`.
+ *
+ * When `S === "action_required"` the variant additionally requires
+ * `nextAction: NextAction` (not optional) per Rule D (CANON.md §4.40 +
+ * sdk-surface.md §3a): `action_required` is inline on mutation /
+ * snapshot responses and callers can safely route via `matchAction`.
+ */
+type WithStatus<T, S extends string> = S extends unknown ? T & {
+    readonly status: S;
+} & (S extends "action_required" ? {
+    readonly nextAction: NextAction;
+} : unknown) : never;
+type Money = types.Money;
+type Settlement = types.Settlement;
+type TimestampIso = types.TimestampIso;
+type UserIdentifier = types.UserIdentifier;
+/**
+ * Tagged reference to the public resource a succeeded operation
+ * produced (per sdk-surface.md §1b `operation`).
+ */
+type OperationResult = {
+    readonly object: "account" | "organization" | "safe" | "treasury" | "kyc_profile" | "kyb_profile" | "external_account" | "payment" | "member" | "withdrawal" | "operation" | "webhook_endpoint" | "webhook_event" | "sub_account" | "virtual_account" | "virtual_card" | "transfer" | "document" | "balance_ledger_entry" | "api_key";
+    readonly id: string;
+};
+/**
+ * Terminal-state error sidecar on resources that can fail (Operation,
+ * Payment, Withdrawal, Transfer).
+ */
+type ResourceError = {
+    readonly code: string;
+    readonly message: string;
+};
+
+type OperationStatus = types.OperationStatus;
+type OperationSummary = Rebrand<types.OperationSummary, OperationId> & {
+    readonly correlationId: CorrelationId;
+};
+/**
+ * Full operation envelope.
+ *
+ * `actor` and `subject` are hand-overridden because OpenAPI emits
+ * them as `additionalProperties` open-shape; SDK surface carries the
+ * canonical tagged-ref shape.
+ *
+ * `nextAction` is re-asserted against the kernel's `NextAction` union
+ * (9 kinds including `confirm_fx_quote` per §4.58) so callers get the
+ * kernel-branded field types (e.g. `Email`, `PhoneNumber`, `Username`
+ * on `fix_destination.recipient`). The wire carries the same 9 kinds
+ * structurally; the kernel re-assertion preserves the SDK surface's
+ * exhaustiveness contract against drift.
+ *
+ * `result` and `error` come through the generator faithfully, but
+ * we re-type them to narrow the tagged-ref `object` field to the
+ * closed `OperationResult["object"]` catalog.
+ */
+type Operation = Override<Rebrand<types.Operation, OperationId>, {
+    readonly correlationId: CorrelationId;
+    readonly actor: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly subject?: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly nextAction?: NextAction;
+    readonly result?: OperationResult | null;
+    readonly error?: ResourceError | null;
+}>;
+type Account = Omit<Rebrand<types.Account, AccountId>, "kycTier" | "primarySafeId"> & {
+    readonly kycTier?: types.Account["kycTier"] | null;
+    readonly primarySafeId?: SafeId | null;
+};
+type AccountLookupResult = types.AccountLookupResult;
+/**
+ * `owner` is hand-overridden: the OpenAPI source emits it as an
+ * `additionalProperties` open object; SDK surface carries the canonical
+ * tagged-ref shape.
+ */
+type Safe = Override<Rebrand<types.Safe, SafeId>, {
+    readonly owner: {
+        readonly type: "account";
+        readonly id: AccountId;
+    } | {
+        readonly type: "organization";
+        readonly id: OrganizationId;
+    };
+}>;
+type Organization = Rebrand<types.Organization, OrganizationId>;
+type Treasury = Rebrand<types.Treasury, TreasuryId> & {
+    readonly organizationId: OrganizationId;
+};
+type KycProfile = Rebrand<types.KycProfile, KycProfileId>;
+type KybProfile = Rebrand<types.KybProfile, KybProfileId>;
+type ExternalAccount = Rebrand<types.ExternalAccount, ExternalAccountId>;
+type ExternalAccountKind = types.ExternalAccountKind;
+type PageInfo = types.PageInfo;
+type List<T> = {
+    readonly object: "list";
+    readonly data: readonly T[];
+    readonly page: PageInfo;
+};
+type WirePaymentWithBrand = Rebrand<types.Payment, PaymentId>;
+type PaymentStatus = "processing" | "action_required" | "succeeded" | "failed" | "canceled";
+/**
+ * Full `Payment` — discriminated union on status so `matchStatus`
+ * narrows correctly.
+ */
+type Payment = WithStatus<WirePaymentWithBrand, PaymentStatus>;
+/**
+ * Per-method narrowing for `payments.create`. Terminal states
+ * (`succeeded`, `canceled`) arrive out-of-band per Rule D (CANON.md
+ * §4.40 + sdk-surface.md §3a), so the synchronous return carries
+ * only `processing | action_required | failed`.
+ */
+type CreatePaymentResult = WithStatus<WirePaymentWithBrand, "processing" | "action_required" | "failed">;
+type PaymentParty = types.PaymentParty;
+type WireWithdrawalWithBrand = Rebrand<types.Withdrawal, WithdrawalId>;
+/**
+ * Canon-aligned superset (resources.mdx §withdrawal lifecycle note).
+ * Wider than `OperationStatus` because `submitted → completed` is a
+ * withdrawal-specific transition driven by external reconciliation
+ * the operation envelope cannot witness directly. Slice 1 of
+ * Withdrawals v1 (#440) widened this from `PaymentStatus` to match
+ * canon.
+ */
+type WithdrawalStatus = "draft" | "action_required" | "processing" | "submitted" | "completed" | "failed" | "canceled";
+type Withdrawal = WithStatus<WireWithdrawalWithBrand, WithdrawalStatus>;
+type CreateWithdrawalResult = WithStatus<WireWithdrawalWithBrand, "processing" | "action_required" | "failed">;
+type WireTransferWithBrand = Rebrand<types.Transfer, TransferId>;
+type TransferStatus = PaymentStatus;
+type Transfer = WithStatus<WireTransferWithBrand, TransferStatus>;
+type CreateTransferResult = WithStatus<WireTransferWithBrand, "processing" | "action_required" | "failed">;
+type TransferEndpoint = types.TransferEndpoint;
+type TransferCustody = types.TransferCustody;
+type TransferFx = types.TransferFx;
+type Document = types.Document & {
+    readonly id: DocumentId;
+};
+type InvoiceDocument = types.InvoiceDocument;
+type PayrollRunDocument = types.PayrollRunDocument;
+type PayrollScheduleDocument = types.PayrollScheduleDocument;
+type ReceiptDocument = types.ReceiptDocument;
+type KycUploadDocument = types.KycUploadDocument;
+type BankStatementDocument = types.BankStatementDocument;
+type TaxFormDocument = types.TaxFormDocument;
+type SubAccount = Rebrand<types.SubAccount, SubAccountId>;
+type SubAccountOwnerKind = types.SubAccountOwnerKind;
+type VirtualAccount = Rebrand<types.VirtualAccount, VirtualAccountId>;
+type VirtualAccountOwnerKind = types.VirtualAccountOwnerKind;
+type VirtualCard = Rebrand<types.VirtualCard, VirtualCardId>;
+type VirtualCardOwnerKind = types.VirtualCardOwnerKind;
+type VirtualCardLimits = types.VirtualCardLimits;
+type WebhookEndpoint = Rebrand<types.WebhookEndpoint, WebhookEndpointId>;
+type WebhookEvent = Rebrand<types.WebhookEvent, WebhookEventId>;
+type ApiKey = Rebrand<types.ApiKey, ApiKeyId>;
+type ApiKeyEnvironment = types.ApiKeyEnvironment;
+type ApiKeyType = types.ApiKeyType;
+type Scope = types.Scope;
+type Member = Rebrand<types.Member, MemberId>;
+type BalanceLedgerEntry = Rebrand<types.BalanceLedgerEntry, BalanceLedgerEntryId>;
+
+export type { WithdrawalStatus as $, Account as A, BalanceLedgerEntry as B, CreatePaymentResult as C, Document as D, ExternalAccount as E, TransferEndpoint as F, TransferFx as G, TransferStatus as H, InvoiceDocument as I, Treasury as J, KybProfile as K, List as L, Member as M, VirtualAccountOwnerKind as N, Operation as O, PageInfo as P, VirtualCard as Q, ReceiptDocument as R, Safe as S, TaxFormDocument as T, UserIdentifier as U, VirtualAccount as V, VirtualCardLimits as W, VirtualCardOwnerKind as X, WebhookEndpoint as Y, WebhookEvent as Z, Withdrawal as _, AccountLookupResult as a, ApiKey as b, ApiKeyEnvironment as c, ApiKeyType as d, BankStatementDocument as e, CreateTransferResult as f, CreateWithdrawalResult as g, ExternalAccountKind as h, KycProfile as i, KycUploadDocument as j, Money as k, OperationStatus as l, OperationSummary as m, Organization as n, Payment as o, PaymentParty as p, PaymentStatus as q, PayrollRunDocument as r, PayrollScheduleDocument as s, Scope as t, Settlement as u, SubAccount as v, SubAccountOwnerKind as w, TimestampIso as x, Transfer as y, TransferCustody as z };

package/dist/webhooks.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+// src/errors.ts
+var CapxulError = class extends Error {
+  code;
+  details;
+  operationId;
+  correlationId;
+  retryable;
+  constructor(init) {
+    super(
+      init.message,
+      init.cause !== void 0 ? { cause: init.cause } : void 0
+    );
+    this.name = "CapxulError";
+    this.code = init.code;
+    this.details = init.details;
+    this.operationId = init.operationId;
+    this.correlationId = init.correlationId;
+    this.retryable = init.retryable;
+  }
+};
+
+// ../config/src/timing.ts
+var WEBHOOK_FRESHNESS_WINDOW_MS = 5 * 60 * 1e3;
+
+// ../config/src/org-roles.ts
+function roleKeyFromLabel(label) {
+  const bytes = new TextEncoder().encode(label);
+  const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return "0x" + hex.padEnd(64, "0");
+}
+roleKeyFromLabel("OWNER");
+roleKeyFromLabel("FINANCE_MANAGER");
+roleKeyFromLabel("TEAM_LEAD");
+
+// src/webhooks.ts
+async function verifyWebhook(request, secret, options) {
+  if (!secret) {
+    throw new CapxulError({
+      code: "INVALID_INPUT",
+      message: "A webhook signing secret is required."
+    });
+  }
+  const timestamp = request.headers.get("x-capxul-timestamp");
+  const signature = request.headers.get("x-capxul-signature");
+  if (!timestamp || !signature) {
+    return { valid: false, reason: "invalid_signature" };
+  }
+  const timestampMs = Number(timestamp);
+  if (!Number.isFinite(timestampMs)) {
+    return { valid: false, reason: "malformed" };
+  }
+  const freshnessWindowMs = options?.freshnessWindowMs ?? WEBHOOK_FRESHNESS_WINDOW_MS;
+  if (Math.abs(Date.now() - timestampMs) > freshnessWindowMs) {
+    return { valid: false, reason: "replay" };
+  }
+  const body = await request.text();
+  const signatureHex = signature.startsWith("sha256=") ? signature.slice("sha256=".length) : signature;
+  if (!/^[a-f0-9]{64}$/i.test(signatureHex)) {
+    return { valid: false, reason: "invalid_signature" };
+  }
+  const validSignature = await verifyHmacSha256(
+    secret,
+    `${timestamp}.${body}`,
+    signatureHex
+  );
+  if (!validSignature) {
+    return { valid: false, reason: "invalid_signature" };
+  }
+  const parsed = parseWebhookEvent(body);
+  if (!parsed) {
+    return { valid: false, reason: "malformed" };
+  }
+  return { valid: true, event: parsed };
+}
+async function verifyHmacSha256(secret, message, signatureHex) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  return await crypto.subtle.verify(
+    "HMAC",
+    key,
+    hexToArrayBuffer(signatureHex),
+    encoder.encode(message)
+  );
+}
+function hexToArrayBuffer(hex) {
+  const buffer = new ArrayBuffer(hex.length / 2);
+  const bytes = new Uint8Array(buffer);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return buffer;
+}
+function parseWebhookEvent(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (!isWebhookEvent(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function isWebhookEvent(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.id === "string" && typeof candidate.type === "string" && typeof candidate.createdAt === "string" && (candidate.operationId === void 0 || typeof candidate.operationId === "string") && (candidate.correlationId === void 0 || typeof candidate.correlationId === "string") && !!candidate.data && typeof candidate.data === "object" && !Array.isArray(candidate.data);
+}
+
+exports.verifyWebhook = verifyWebhook;

package/dist/webhooks.d.cts

@@ -0,0 +1,34 @@
+import { Z as WebhookEvent } from './types-Cokyqgwm.cjs';
+import '@repo/api-contract/gen/types';
+import '@repo/platform-kernel';
+
+/**
+ * Webhook verification primitive per CANON.md §4.41 +
+ * `.claude/rules/webhook-security.md`.
+ *
+ * Verifies HMAC-SHA256 over the raw request body using
+ * `crypto.subtle.verify` (timing-safe by default), checks freshness
+ * against a configurable window, and returns a tagged-union result.
+ *
+ * Framework adapters (`@capxul/sdk-next`, future `@capxul/sdk-hono`)
+ * wrap this primitive with HTTP handler glue. This file is the one
+ * canonical crypto entry point.
+ */
+type WebhookVerificationResult = {
+    readonly valid: true;
+    readonly event: WebhookEvent;
+} | {
+    readonly valid: false;
+    readonly reason: "invalid_signature" | "replay" | "malformed";
+};
+type WebhookVerificationOptions = {
+    /**
+     * Maximum age of a payload (based on `createdAt`) before it is
+     * rejected as a replay. Defaults to 5 minutes
+     * (`WEBHOOK_FRESHNESS_WINDOW_MS` in `@repo/config`).
+     */
+    readonly freshnessWindowMs?: number;
+};
+declare function verifyWebhook(request: Request, secret: string, options?: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+
+export { type WebhookVerificationOptions, type WebhookVerificationResult, verifyWebhook };

package/dist/webhooks.d.ts

@@ -0,0 +1,34 @@
+import { Z as WebhookEvent } from './types-Cokyqgwm.js';
+import '@repo/api-contract/gen/types';
+import '@repo/platform-kernel';
+
+/**
+ * Webhook verification primitive per CANON.md §4.41 +
+ * `.claude/rules/webhook-security.md`.
+ *
+ * Verifies HMAC-SHA256 over the raw request body using
+ * `crypto.subtle.verify` (timing-safe by default), checks freshness
+ * against a configurable window, and returns a tagged-union result.
+ *
+ * Framework adapters (`@capxul/sdk-next`, future `@capxul/sdk-hono`)
+ * wrap this primitive with HTTP handler glue. This file is the one
+ * canonical crypto entry point.
+ */
+type WebhookVerificationResult = {
+    readonly valid: true;
+    readonly event: WebhookEvent;
+} | {
+    readonly valid: false;
+    readonly reason: "invalid_signature" | "replay" | "malformed";
+};
+type WebhookVerificationOptions = {
+    /**
+     * Maximum age of a payload (based on `createdAt`) before it is
+     * rejected as a replay. Defaults to 5 minutes
+     * (`WEBHOOK_FRESHNESS_WINDOW_MS` in `@repo/config`).
+     */
+    readonly freshnessWindowMs?: number;
+};
+declare function verifyWebhook(request: Request, secret: string, options?: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+
+export { type WebhookVerificationOptions, type WebhookVerificationResult, verifyWebhook };