repoaccess-core 0.2.0

package/src/kv-keys.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+// Centralized ENTITLEMENTS key builders + TTL. Shared by the grant/revoke workflow and
+// the claim flow so the wire formats can never drift apart.
+
+export const CLAIM_TTL_SEC = 30 * 24 * 60 * 60 // 30 days
+
+// 180 days - covers the refund window + the ~120d card-chargeback window, and bounds KV accumulation
+// so records don't grow unbounded.
+export const GRANT_TTL_SEC = 180 * 24 * 60 * 60
+
+/** Grant correlation record - 180d TTL, also deleted on revoke. */
+export const grantKey = (adapter: string, txn: string) =>
+  `grant:${adapter}:${txn}`
+
+/** Pending claim by single-use token. */
+export const claimKey = (token: string) => `claim:${token}`
+
+/** Reverse index so revoke can find a still-pending claim by transaction (KV can't query by value). */
+export const claimIndexKey = (adapter: string, txn: string) =>
+  `claim_txn:${adapter}:${txn}`

package/src/raw-request.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import type { RawRequest } from './types'
+
+const FORM_CONTENT_TYPE = 'application/x-www-form-urlencoded'
+
+/**
+ * Capture the request body byte-exact BEFORE any JSON parse. HMAC verification breaks if the body
+ * is parsed and re-serialized (Paddle, Coinbase Commerce), so adapters must receive the raw text.
+ * The body is read exactly once.
+ *
+ * For form-urlencoded providers (Gumroad/Mollie), a parsed `URLSearchParams` view is attached
+ * alongside the raw text - the raw text remains the source of truth for signatures.
+ */
+export async function captureRawRequest(request: Request): Promise<RawRequest> {
+  const bodyText = await request.text()
+  const { headers } = request
+  const contentType = headers.get('content-type') ?? ''
+  const bodyForm = contentType.includes(FORM_CONTENT_TYPE)
+    ? new URLSearchParams(bodyText)
+    : undefined
+  return { bodyText, bodyForm, headers }
+}

package/src/repoaccess.config.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import type { RepoAccessConfig } from './types'
+
+/**
+ * Deployment config as code - the typed, user-owned replacement for the old non-secret
+ * `wrangler vars`. SECRETS are NOT here: `GITHUB_TOKEN`, the adapters' `*_WEBHOOK_SECRET`, and the
+ * optional `EVENT_WEBHOOK_SECRET` stay in the runtime env.
+ *
+ * Core ships a NEUTRAL template - never hard-code a real org/product map here. A deployer
+ * copies this file and fills in their values. Two shapes are supported:
+ *
+ *   • single-env  - export one config and point both `createWorker`/`createAccessWorkflow` at it;
+ *   • sandbox/prod split - export two profiles (below) and select per-environment via wrangler's
+ *     per-env `main` (`src/index.ts` → sandbox, `src/index.production.ts` → production).
+ *
+ * `env` is unavailable at module top-level in Workers, so the profile is chosen at build/deploy time
+ * by which entry wrangler loads - not from a runtime var.
+ */
+
+/** Shared base - neutral defaults. `defaults` is log_only/empty so an unmapped product grants nothing. */
+const base: RepoAccessConfig = {
+  githubOrg: '',
+  productTeamMap: {
+    defaults: {
+      teams: [],
+      grant_mode: 'claim',
+      revoke_policy: { mode: 'log_only' },
+    },
+  },
+  // branding omitted → the claim controller fills neutral defaults (name "RepoAccess").
+}
+
+/** Default/sandbox profile (loaded by `src/index.ts`). */
+export const sandbox: RepoAccessConfig = base
+
+/** Production profile (loaded by `src/index.production.ts`). Neutral in core - a deployer overrides. */
+export const production: RepoAccessConfig = base

package/src/ssrf.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+/**
+ * SSRF guard for outbound event delivery. **Always on** - there is no flag to
+ * disable it. `validateWebhookUrl` runs before every outbound fetch and enforces:
+ *   - https only (http only when explicitly opted in);
+ *   - reject IP-literal hosts in private / reserved / loopback / link-local ranges, including the
+ *     `169.254.169.254` cloud-metadata address;
+ *   - an optional exact-or-suffix domain allowlist.
+ *
+ * ⚠️ workerd LIMITATION: a Worker cannot resolve a hostname to its IP address in-process, so a
+ * hostname that *resolves* to a private IP (DNS rebinding) is NOT caught by the IP-literal checks
+ * below. The domain **allowlist** is the strong control against that - recommend sellers set it.
+ * `redirect: 'manual'` at the fetch call site blocks redirect-to-internal. (Residual documented in
+ * the security audit.)
+ *
+ * Pure + dependency-free so it can be unit-tested directly and read in one sitting (security
+ * code readability is a feature).
+ */
+
+export interface SsrfOptions {
+  /** Host allowlist; when non-empty the host must match one entry (exact or suffix). */
+  allowlist?: string[]
+  /** Permit `http:` (default false → https only). */
+  allowHttp?: boolean
+}
+
+export type SsrfResult = { ok: true; url: URL } | { ok: false; reason: string }
+
+export function validateWebhookUrl(
+  raw: string,
+  opts: SsrfOptions = {},
+): SsrfResult {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    return { ok: false, reason: 'invalid url' }
+  }
+
+  if (
+    url.protocol !== 'https:' &&
+    !(opts.allowHttp && url.protocol === 'http:')
+  ) {
+    return { ok: false, reason: `scheme ${url.protocol} not allowed` }
+  }
+
+  // URL.hostname keeps brackets for IPv6 literals on some runtimes - strip them defensively.
+  const host = url.hostname.replace(/^\[/, '').replace(/\]$/, '').toLowerCase()
+
+  const v4 = parseIPv4(host)
+  if (v4) {
+    if (isPrivateIPv4(v4)) return { ok: false, reason: 'private/reserved IPv4' }
+  } else if (host.includes(':')) {
+    const v6 = parseIPv6(host)
+    if (!v6) return { ok: false, reason: 'unparseable IPv6 literal' }
+    if (isBlockedIPv6(v6)) return { ok: false, reason: 'private/reserved IPv6' }
+  }
+  // else: a DNS hostname - cannot resolve in-worker (see header note); the allowlist is the control.
+
+  const allow = parseAllowlist(opts.allowlist)
+  if (allow.length > 0 && !hostMatchesAllowlist(host, allow)) {
+    return { ok: false, reason: 'host not in allowlist' }
+  }
+
+  return { ok: true, url }
+}
+
+// --- IPv4 -------------------------------------------------------------------
+
+function parseIPv4(host: string): number[] | null {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+  if (!m) return null
+  const octets = m.slice(1, 5).map((s) => Number(s))
+  return octets.some((o) => o > 255) ? null : octets
+}
+
+function isPrivateIPv4([a, b]: number[]): boolean {
+  if (a === 10) return true // 10/8 private
+  if (a === 172 && b >= 16 && b <= 31) return true // 172.16/12 private
+  if (a === 192 && b === 168) return true // 192.168/16 private
+  if (a === 127) return true // 127/8 loopback
+  if (a === 0) return true // 0.0.0.0/8 "this network"
+  if (a === 169 && b === 254) return true // 169.254/16 link-local (incl. 169.254.169.254 metadata)
+  if (a === 100 && b >= 64 && b <= 127) return true // 100.64/10 CGNAT (defense-in-depth)
+  if (a >= 224) return true // 224/4 multicast + 240/4 reserved + 255.255.255.255 (defense-in-depth)
+  return false
+}
+
+// --- IPv6 -------------------------------------------------------------------
+
+function parseIPv6(input: string): Uint8Array | null {
+  let s = input
+  const pct = s.indexOf('%')
+  if (pct !== -1) s = s.slice(0, pct) // strip zone id
+
+  // Embedded IPv4 tail (e.g. ::ffff:1.2.3.4) → fold into two hextets.
+  if (s.includes('.')) {
+    const i = s.lastIndexOf(':')
+    if (i === -1) return null
+    const v4 = parseIPv4(s.slice(i + 1))
+    if (!v4) return null
+    const hi = ((v4[0] << 8) | v4[1]).toString(16)
+    const lo = ((v4[2] << 8) | v4[3]).toString(16)
+    s = `${s.slice(0, i + 1)}${hi}:${lo}`
+  }
+
+  const halves = s.split('::')
+  if (halves.length > 2) return null
+  const head = halves[0] ? halves[0].split(':') : []
+  const tail =
+    halves.length === 2 ? (halves[1] ? halves[1].split(':') : []) : null
+
+  let groups: string[]
+  if (tail === null) {
+    groups = head
+  } else {
+    const missing = 8 - head.length - tail.length
+    if (missing < 1) return null // '::' must stand in for ≥1 group
+    groups = [...head, ...Array(missing).fill('0'), ...tail]
+  }
+  if (groups.length !== 8) return null
+
+  const bytes = new Uint8Array(16)
+  for (let i = 0; i < 8; i++) {
+    if (!/^[0-9a-f]{1,4}$/.test(groups[i])) return null
+    const v = parseInt(groups[i], 16)
+    bytes[i * 2] = v >> 8
+    bytes[i * 2 + 1] = v & 0xff
+  }
+  return bytes
+}
+
+function isBlockedIPv6(b: Uint8Array): boolean {
+  if (b.every((x) => x === 0)) return true // :: unspecified
+  if (b.slice(0, 15).every((x) => x === 0) && b[15] === 1) return true // ::1 loopback
+  if ((b[0] & 0xfe) === 0xfc) return true // fc00::/7 unique-local
+  if (b[0] === 0xfe && (b[1] & 0xc0) === 0x80) return true // fe80::/10 link-local
+  // IPv4-mapped ::ffff:a.b.c.d → apply the v4 rules to the embedded address.
+  const mapped =
+    b.slice(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff
+  if (mapped && isPrivateIPv4([b[12], b[13], b[14], b[15]])) return true
+  return false
+}
+
+// --- allowlist --------------------------------------------------------------
+
+function parseAllowlist(raw?: string[]): string[] {
+  if (!raw) return []
+  return raw.map((s) => s.trim().toLowerCase()).filter(Boolean)
+}
+
+function hostMatchesAllowlist(host: string, allow: string[]): boolean {
+  return allow.some((entry) => host === entry || host.endsWith(`.${entry}`))
+}

package/src/types.ts

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+/**
+ * Pinned core contract.
+ *
+ * This is the public surface every adapter implements. Keep it minimal and provider-agnostic:
+ * provider specifics live in adapters, never here.
+ */
+
+/**
+ * A JSON value - the serializable shape that survives a `step.do` boundary. Cloudflare Workflows
+ * persists every step result, so `step.do<T>()` constrains `T` to `Serializable`; bare `unknown`
+ * fails that constraint. Used for GitHub response bodies (`GithubResult.json`), which ARE JSON at
+ * runtime.
+ *
+ * Both composite arms are named interfaces (not inline `Json[]` / `{ [k]: Json }`): routing the
+ * recursion through `ReadonlyArray` and an interface lets the workers-types `Serializable<T>` mapped
+ * type resolve each arm via its dedicated `ReadonlyArray` / object branch and reuse the memoized
+ * `Serializable<Json>`, instead of re-expanding to infinite instantiation depth (TS2589).
+ */
+export type Json = null | boolean | number | string | JsonArray | JsonObject
+export interface JsonArray extends ReadonlyArray<Json> {}
+export interface JsonObject {
+  readonly [key: string]: Json
+}
+
+export type GrantMode = 'username' | 'email' | 'claim' // `email` is for a later release
+
+export interface RevokePolicy {
+  mode: 'auto_revoke' | 'log_only'
+  /** Gates `refund` events only; chargebacks always revoke under auto_revoke. */
+  full_refund_only?: boolean
+}
+
+export interface ProductConfig {
+  /** Team slugs → resolved to numeric ids at runtime (KV `team:{slug}`). */
+  teams: string[]
+  grant_mode?: GrantMode
+  revoke_policy?: RevokePolicy
+}
+
+/**
+ * Product→team map - flat shape: adapter keys + a sibling `defaults`. `defaults` is a
+ * RESERVED key: `resolveProductConfig` guards it so an adapter literally named "defaults" cannot
+ * shadow the fallback. Authored as a typed object in `RepoAccessConfig.productTeamMap`,
+ * no longer a JSON-string var.
+ */
+export interface ProductTeamMap {
+  defaults: ProductConfig
+  [adapter: string]: ProductConfig | { [product_id: string]: ProductConfig }
+}
+
+/**
+ * Seller-configurable claim-page branding. The contract type for both
+ * `RepoAccessConfig.branding` (as a `Partial`, defaulted by the controller) and the claim template's
+ * view (re-exported from `claim-template.tsx`).
+ */
+export interface Branding {
+  name: string
+  logoUrl: string
+  faviconUrl: string
+}
+
+/**
+ * Outbound event delivery. Optional/opt-in - omit (or leave `url` empty) for the log-only
+ * sink. The signing secret is NOT here: it stays in the env as `EVENT_WEBHOOK_SECRET`.
+ */
+export interface EventWebhookConfig {
+  /** Destination URL; unset/empty → delivery is a no-op (log-only). */
+  url?: string
+  /** SSRF host allowlist (exact-or-suffix match). Empty/unset → any public host. */
+  allowlist?: string[]
+}
+
+/**
+ * Deployment config supplied as a typed, user-owned object - `repoaccess.config.ts` handed to
+ * `createWorker({ config })` (request path) and `createAccessWorkflow(config, adapters)` (Workflow path).
+ * SECRETS are NOT here - they
+ * stay in the runtime env: `GITHUB_TOKEN`, the adapters' `*_WEBHOOK_SECRET`, and the optional
+ * `EVENT_WEBHOOK_SECRET`.
+ */
+export interface RepoAccessConfig {
+  /** GitHub org that grants/revokes target. (was the `GITHUB_ORG` var) */
+  githubOrg: string
+  /** Product→team map as a typed object. (was the `PRODUCT_TEAM_MAP` JSON-string var) */
+  productTeamMap: ProductTeamMap
+  /** Claim-page branding; optional - the controller fills neutral defaults. (was `CLAIM_BRAND_*`) */
+  branding?: Partial<Branding>
+  /** Outbound event delivery; optional/opt-in. (was `EVENT_WEBHOOK_URL` / `EVENT_WEBHOOK_ALLOWLIST`) */
+  eventWebhook?: EventWebhookConfig
+}
+
+export interface NormalizedEvent {
+  event_type: 'payment_success' | 'refund' | 'chargeback'
+  product_id: string
+  /** Stable correlation key - identical across an order and its later refund/chargeback. */
+  transaction_id: string
+  buyer_email: string | null
+  github_username: string | null
+  /** Refund events only: true=full, false=partial, null=n/a. */
+  is_full_refund: boolean | null
+}
+
+export interface RawRequest {
+  /** Byte-exact body - HMAC verification breaks on re-serialization. */
+  bodyText: string
+  /** Parsed form body for form-urlencoded adapters (Gumroad/Mollie). */
+  bodyForm?: URLSearchParams
+  headers: Headers
+}
+
+/**
+ * The adapter's API-fetched entity under `api_callback` - opaque to core; shape is adapter-defined
+ * (first real use is Gumroad, a later release). Under api_callback the inbound payload is never trusted; grant
+ * decisions read ONLY this verified entity.
+ */
+export type VerifiedEntity = Record<string, unknown>
+
+export type VerificationStrategy =
+  | {
+      kind: 'hmac'
+      algo: 'SHA-256' | 'SHA-512'
+      /**
+       * The signing secret, read from the runtime env. The adapter is self-describing about which
+       * var holds it - e.g. `(env) => env.STRIPE_WEBHOOK_SECRET`. Returns `undefined`
+       * when unset → the engine rejects. (Contract extension over the original base contract - the pinned shape had
+       * no way for the generic engine to obtain the per-adapter key.)
+       */
+      secret(env: CloudflareBindings): string | undefined
+      /** Canonical string to sign: raw body | `ts:body` | manifest template. */
+      canonical(raw: RawRequest): string
+      /**
+       * Pull the signature(s) + optional timestamp from the headers. `signature` may be an array
+       * when a provider sends multiple candidates (e.g. Stripe `v1` during secret rotation) - the
+       * engine accepts a match against ANY.
+       */
+      extract(headers: Headers): { signature: string | string[]; ts?: string }
+      /** Replay tolerance in seconds, where the provider supplies a timestamp (e.g. Paddle ≈ 5). */
+      toleranceSec?: number
+    }
+  | {
+      kind: 'api_callback'
+      /**
+       * The validated path credential, read from the runtime env - the adapter self-describes its
+       * var, e.g. `(env) => env.GUMROAD_WEBHOOK_PATH` (mirrors hmac's `secret()`). There is no
+       * signature on the ack path for api_callback adapters, so the route timing-safe-compares the
+       * `:secret_path` URL segment against this value BEFORE enqueueing - it is the first-line
+       * credential that replaces HMAC. Returns `undefined` when unset → the route rejects
+       * (fail-closed). (ADR extending 0007.)
+       */
+      secretPath(env: CloudflareBindings): string | undefined
+      /**
+       * Fetch the authoritative entity from the provider's API. Runs as a durable, retriable Workflow
+       * step (NOT on the ack path - it is outbound I/O that would break the <100ms ack). The inbound
+       * ping body is NEVER trusted; the grant is mapped from this returned entity. `null` → terminal
+       * reject (a forged/unknown id 404s here).
+       */
+      fetchEntity(
+        raw: RawRequest,
+        env: CloudflareBindings,
+      ): Promise<VerifiedEntity | null>
+    }
+  | {
+      kind: 'shared_secret_header'
+      /**
+       * Name of the request header carrying the shared secret the provider echoes on every webhook
+       * (e.g. Telegram's `X-Telegram-Bot-Api-Secret-Token`, set once via `setWebhook`'s
+       * `secret_token`). The engine reads THIS header and timing-safe compares it against `secret`.
+       */
+      header: string
+      /**
+       * The expected secret, read from the runtime env - self-describing about which var holds it,
+       * exactly like hmac's `secret()` (e.g. `(env) => env.TELEGRAM_WEBHOOK_SECRET`). Returns
+       * `undefined` when unset → the engine rejects (fail-closed). The secret authenticates the
+       * TRANSPORT: once the header matches, the inbound body is authentic and the grant reads it
+       * directly - there is no signature to check (nothing is signed) and no entity to re-fetch (the
+       * update IS the authoritative record). The third taxonomy kind, additive over `hmac` /
+       * `api_callback`. (ADR extending 0007/0033.)
+       */
+      secret(env: CloudflareBindings): string | undefined
+    }
+
+export interface PaymentAdapter {
+  /** Adapter id used in the route `/wh/:adapter/...` and the Workflow instance id. */
+  name: string
+  verification: VerificationStrategy
+  /**
+   * Normalize the raw request into an event, or `null` (hmac/shared_secret_header → route 400;
+   * api_callback → terminal access.failed "unhandled"). The optional `entity` is the API-fetched,
+   * trusted entity, supplied ONLY on the api_callback path (fetched inside the Workflow). hmac and
+   * shared_secret_header adapters ignore it and keep working unchanged. Under api_callback, map the
+   * grant from `entity` - never from `raw` (the ping is untrusted).
+   */
+  parse(raw: RawRequest, entity?: VerifiedEntity): NormalizedEvent | null
+  /**
+   * OPTIONAL interactive-handshake hook. When present, the router delegates a verified request to it
+   * BEFORE `parse` (only ever AFTER verification has passed - it can never bypass auth): a returned
+   * `Response` IS the ack (the router returns it, no enqueue), `null` falls through to the normal
+   * `parse → enqueue` path. It exists for providers whose webhook carries handshake steps as well as
+   * terminal events - e.g. Telegram's `pre_checkout_query`, which the bot must answer (its own bounded
+   * outbound call) before the terminal `successful_payment` arrives and flows through `parse`. Every
+   * existing adapter omits it and is unaffected. (ADR extending 0033.)
+   */
+  handle?(raw: RawRequest, env: CloudflareBindings): Promise<Response | null>
+}
+
+/**
+ * The raw, UNVERIFIED ping enqueued for an `api_callback` adapter. The Workflow fetches the
+ * authoritative entity (never trusting this body) and parses the event from it. Carried instead of
+ * a `NormalizedEvent` because, for api_callback, there is nothing to parse on the ack path - the
+ * event isn't known until the entity is fetched in a durable step.
+ */
+export interface ApiCallbackPing {
+  /** The ping body byte-exact (the adapter derives its lookup id from this / `form`). */
+  bodyText: string
+  /** Parsed form fields (form-urlencoded ping); rebuilt into `URLSearchParams` in the Workflow. */
+  form: Record<string, string>
+}
+
+/**
+ * Params handed to `AccessWorkflow` on enqueue (internal - not part of the adapter contract).
+ * Exactly one of `event` / `ping` is set:
+ *   - `event` - the hmac path: `parse()` already ran on the (fast, local) ack path.
+ *   - `ping`  - the api_callback path: the Workflow fetches the entity + parses (outbound I/O kept
+ *     off the ack path). Grant vs revoke is then derived from the resolved `event.event_type`.
+ */
+export interface AccessWorkflowParams {
+  adapter: string
+  event?: NormalizedEvent
+  ping?: ApiCallbackPing
+  /**
+   * Set by claim completion. Forces `username` grant mode - the product's configured mode is
+   * `claim`, which would otherwise loop back into another claim - and makes the grant emit
+   * `claim.completed` on success. The handle is validated at the claim POST before enqueue.
+   */
+  from_claim?: boolean
+}

package/src/username.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+// GitHub username grammar: ≤39 chars, alphanumeric + single internal hyphens,
+// no leading/trailing/consecutive hyphens. A malformed handle is treated as "no username" → claim
+// fallback (so it never burns the org's 50/24h invitation quota). Same regex runs inline on the
+// claim POST. Format validation is necessary-but-not-sufficient: a well-formed handle for a
+// non-existent account still surfaces as a 404 from the membership call → access.failed.
+const GITHUB_USERNAME = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/
+
+export function isValidGithubUsername(
+  value: string | null | undefined,
+): value is string {
+  return typeof value === 'string' && GITHUB_USERNAME.test(value)
+}

package/src/verify.ts

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import type {
+  PaymentAdapter,
+  RawRequest,
+  VerificationStrategy,
+  VerifiedEntity,
+} from './types'
+
+/**
+ * Verification engine. Core declares the strategy on each adapter and
+ * executes it here - adapters never do their own crypto. Runs on the fast-ack request path, so it
+ * does no work beyond the signature check (hmac) or the single entity fetch (api_callback, which is
+ * itself the verification). On failure the route rejects BEFORE enqueueing.
+ */
+export type VerifyResult =
+  | { ok: true; entity?: VerifiedEntity }
+  | { ok: false; reason: string }
+
+type HmacStrategy = Extract<VerificationStrategy, { kind: 'hmac' }>
+type ApiCallbackStrategy = Extract<
+  VerificationStrategy,
+  { kind: 'api_callback' }
+>
+type SharedSecretHeaderStrategy = Extract<
+  VerificationStrategy,
+  { kind: 'shared_secret_header' }
+>
+
+const encoder = new TextEncoder()
+
+async function hmacHex(
+  algo: 'SHA-256' | 'SHA-512',
+  secret: string,
+  message: string,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: algo },
+    false,
+    ['sign'],
+  )
+  const mac = await crypto.subtle.sign('HMAC', key, encoder.encode(message))
+  const bytes = new Uint8Array(mac)
+  let hex = ''
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0')
+  return hex
+}
+
+/**
+ * Constant-time hex compare. The length check is acceptable: a digest's length is fixed by its
+ * algorithm, so a length mismatch only ever means an invalid signature, not a secret-dependent
+ * branch. The XOR loop over equal-length strings does not short-circuit. (invariant: timing-safe)
+ */
+export function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}
+
+/**
+ * Constant-time UTF-8 string compare with NO early length-leak. Used for the api_callback
+ * `:secret_path` credential check - unlike `timingSafeEqualHex` (which returns early on a length
+ * mismatch, acceptable for fixed-length digests but a length oracle for a variable-length secret),
+ * this folds the length difference into the accumulator and always iterates over the EXPECTED
+ * secret's byte length. So neither the candidate's content nor its length short-circuits: a wrong
+ * length still fails (via the length XOR) without a distinguishable early return, and the loop count
+ * depends only on the deployment-fixed `expected`, never on attacker input.
+ */
+export function timingSafeEqualString(
+  candidate: string,
+  expected: string,
+): boolean {
+  const a = encoder.encode(candidate)
+  const b = encoder.encode(expected)
+  let diff = a.length ^ b.length
+  for (let i = 0; i < b.length; i++) {
+    diff |= b[i] ^ (i < a.length ? a[i] : 0)
+  }
+  return diff === 0
+}
+
+export async function verifyHmac(
+  strategy: HmacStrategy,
+  raw: RawRequest,
+  env: CloudflareBindings,
+  nowMs: number = Date.now(),
+): Promise<VerifyResult> {
+  const secret = strategy.secret(env)
+  if (!secret) return { ok: false, reason: 'missing signing secret' }
+
+  const { signature, ts } = strategy.extract(raw.headers)
+  const candidates = (
+    Array.isArray(signature) ? signature : [signature]
+  ).filter(Boolean)
+  if (candidates.length === 0) return { ok: false, reason: 'missing signature' }
+
+  // Replay window, only where the provider supplies a timestamp (e.g. Paddle ≈ 5s).
+  if (strategy.toleranceSec !== undefined) {
+    if (!ts) return { ok: false, reason: 'missing timestamp' }
+    const tsSec = Number(ts)
+    if (!Number.isFinite(tsSec))
+      return { ok: false, reason: 'invalid timestamp' }
+    if (Math.abs(nowMs / 1000 - tsSec) > strategy.toleranceSec) {
+      return { ok: false, reason: 'timestamp outside tolerance' }
+    }
+  }
+
+  const expected = await hmacHex(strategy.algo, secret, strategy.canonical(raw))
+  // Match against ANY candidate (e.g. Stripe sends one v1 per active secret during rotation).
+  const matched = candidates.some((candidate) =>
+    timingSafeEqualHex(expected, candidate.toLowerCase()),
+  )
+  if (!matched) return { ok: false, reason: 'signature mismatch' }
+  return { ok: true }
+}
+
+export async function verifyApiCallback(
+  strategy: ApiCallbackStrategy,
+  raw: RawRequest,
+  env: CloudflareBindings,
+): Promise<VerifyResult> {
+  // The inbound payload is never trusted: the grant decision reads only this fetched entity.
+  // (The route's :secret_path segment is the first-line filter; enforced per-adapter in a later release.)
+  const entity = await strategy.fetchEntity(raw, env)
+  if (!entity) return { ok: false, reason: 'entity fetch returned null' }
+  return { ok: true, entity }
+}
+
+/**
+ * Verify a `shared_secret_header` request: the provider echoes a shared secret in a fixed header
+ * (e.g. Telegram's `X-Telegram-Bot-Api-Secret-Token`). Constant-time compare that header against the
+ * configured secret - fail-closed when the secret is unset OR the header is missing/mismatched (401),
+ * the same posture as the other two kinds. The secret authenticates the TRANSPORT: no body is signed
+ * and no entity is re-fetched, so this does NO body parse and NO outbound I/O - once the header
+ * matches, the inbound body is authentic and the grant reads it directly (like hmac, unlike
+ * api_callback). Synchronous, but returns a `VerifyResult` for a uniform `verifyRequest` surface.
+ */
+export function verifySharedSecretHeader(
+  strategy: SharedSecretHeaderStrategy,
+  raw: RawRequest,
+  env: CloudflareBindings,
+): VerifyResult {
+  const expected = strategy.secret(env)
+  if (!expected) return { ok: false, reason: 'missing shared secret' }
+  const provided = raw.headers.get(strategy.header)
+  // No header → fail-closed. (Compare anyway would also fail, but skip the work and be explicit.)
+  if (provided === null) return { ok: false, reason: 'missing secret header' }
+  // Constant-time, no early length-leak - same compare used for the api_callback secret path.
+  if (!timingSafeEqualString(provided, expected))
+    return { ok: false, reason: 'secret header mismatch' }
+  return { ok: true }
+}
+
+/** Execute an adapter's declared verification strategy. */
+export function verifyRequest(
+  adapter: PaymentAdapter,
+  raw: RawRequest,
+  env: CloudflareBindings,
+): Promise<VerifyResult> {
+  const strategy = adapter.verification
+  switch (strategy.kind) {
+    case 'hmac':
+      return verifyHmac(strategy, raw, env)
+    case 'api_callback':
+      return verifyApiCallback(strategy, raw, env)
+    case 'shared_secret_header':
+      return Promise.resolve(verifySharedSecretHeader(strategy, raw, env))
+  }
+}