repoaccess-core 0.2.0

package/src/adapters/stripe.ts

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import type { NormalizedEvent, PaymentAdapter, RawRequest } from '../types'
+
+/**
+ * Stripe reference adapter - the canonical `hmac_sha256` example, verified against the provider's
+ * webhook signature reference (docs.stripe.com/webhooks). Ships in the free core.
+ *
+ * Verification: `Stripe-Signature: t=<unix>,v1=<hex>[,v1=…][,v0=…]`. signed_payload = `${t}.${body}`,
+ * HMAC-SHA256 keyed by the endpoint signing secret (`whsec_…`). Ignore every scheme except `v1`
+ * (the `v0` test scheme is a downgrade-attack vector). Multiple `v1` appear during secret rotation -
+ * the engine matches any. Reject outside the timestamp tolerance.
+ */
+
+const SIGNATURE_HEADER = 'stripe-signature'
+const TOLERANCE_SEC = 300 // Stripe libraries' default replay window.
+
+interface StripeSignature {
+  t: string | undefined
+  v1: string[]
+}
+
+/** Parse `t=…,v1=…,v0=…` → timestamp + the v1 signatures (v0/other schemes ignored). */
+function parseStripeSignature(header: string): StripeSignature {
+  let t: string | undefined
+  const v1: string[] = []
+  for (const part of header.split(',')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    const key = part.slice(0, eq).trim()
+    const value = part.slice(eq + 1).trim()
+    if (key === 't') t = value
+    else if (key === 'v1') v1.push(value)
+  }
+  return { t, v1 }
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+/** github_username from a Checkout Session: `metadata.github_username`, else a github custom field. */
+function githubUsername(session: Record<string, unknown>): string | null {
+  const metadata = session.metadata as Record<string, unknown> | undefined
+  const fromMetadata = asString(metadata?.github_username)
+  if (fromMetadata) return fromMetadata
+
+  const fields = session.custom_fields
+  if (Array.isArray(fields)) {
+    for (const field of fields) {
+      const key = asString((field as Record<string, unknown>)?.key)
+      if (!key || !key.toLowerCase().includes('github')) continue
+      const text = (field as Record<string, unknown>).text as
+        | Record<string, unknown>
+        | undefined
+      const dropdown = (field as Record<string, unknown>).dropdown as
+        | Record<string, unknown>
+        | undefined
+      const value = asString(text?.value) ?? asString(dropdown?.value)
+      if (value) return value
+    }
+  }
+  return null
+}
+
+/** Product id for the team lookup - sellers set it in `metadata.product_id`, which the product→team map keys by. */
+function productId(object: Record<string, unknown>): string {
+  const metadata = object.metadata as Record<string, unknown> | undefined
+  return asString(metadata?.product_id) ?? ''
+}
+
+interface StripeEvent {
+  type?: unknown
+  data?: { object?: Record<string, unknown> }
+}
+
+export const stripe: PaymentAdapter = {
+  name: 'stripe',
+
+  verification: {
+    kind: 'hmac',
+    algo: 'SHA-256',
+    secret: (env) => env.STRIPE_WEBHOOK_SECRET, // undefined → engine rejects (fail-closed)
+    canonical: (raw: RawRequest) => {
+      const { t } = parseStripeSignature(
+        raw.headers.get(SIGNATURE_HEADER) ?? '',
+      )
+      return `${t ?? ''}.${raw.bodyText}`
+    },
+    extract: (headers) => {
+      const { t, v1 } = parseStripeSignature(
+        headers.get(SIGNATURE_HEADER) ?? '',
+      )
+      return { signature: v1, ts: t }
+    },
+    toleranceSec: TOLERANCE_SEC,
+  },
+
+  parse: (raw: RawRequest): NormalizedEvent | null => {
+    let event: StripeEvent
+    try {
+      event = JSON.parse(raw.bodyText) as StripeEvent
+    } catch {
+      return null
+    }
+    const object = event.data?.object
+    if (typeof event.type !== 'string' || !object) return null
+
+    switch (event.type) {
+      case 'checkout.session.completed': {
+        // Gate: a session can fire before the async payment settles for some methods.
+        if (object.payment_status !== 'paid') return null
+        // transaction_id = payment_intent (stable across the order + its refund/dispute), NOT
+        // checkout.session.id (absent from charge events).
+        const transactionId = asString(object.payment_intent)
+        if (!transactionId) return null
+        const customer = object.customer_details as
+          | Record<string, unknown>
+          | undefined
+        return {
+          event_type: 'payment_success',
+          product_id: productId(object),
+          transaction_id: transactionId,
+          buyer_email:
+            asString(customer?.email) ?? asString(object.customer_email),
+          github_username: githubUsername(object),
+          is_full_refund: null,
+        }
+      }
+
+      case 'charge.refunded': {
+        const transactionId = asString(object.payment_intent)
+        if (!transactionId) return null
+        const amount = object.amount
+        const refunded = object.amount_refunded
+        const isFullRefund =
+          typeof amount === 'number' && typeof refunded === 'number'
+            ? refunded === amount
+            : null
+        const billing = object.billing_details as
+          | Record<string, unknown>
+          | undefined
+        return {
+          event_type: 'refund',
+          product_id: productId(object),
+          transaction_id: transactionId,
+          buyer_email: asString(billing?.email),
+          github_username: null,
+          is_full_refund: isFullRefund,
+        }
+      }
+
+      case 'charge.dispute.created': {
+        // data.object is a dispute; it carries payment_intent (the same correlation key).
+        const transactionId = asString(object.payment_intent)
+        if (!transactionId) return null
+        return {
+          event_type: 'chargeback',
+          product_id: productId(object),
+          transaction_id: transactionId,
+          buyer_email: null,
+          github_username: null,
+          is_full_refund: null, // chargebacks always revoke under auto_revoke
+        }
+      }
+
+      default:
+        return null // unhandled event type → route returns 400
+    }
+  },
+}

package/src/claim-guard.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import { DurableObject } from 'cloudflare:workers'
+
+/**
+ * Single-flight guard for claim completion (closes the claim over-grant race).
+ *
+ * The claim token is a bearer credential. Without serialization, two concurrent POSTs of DISTINCT
+ * valid handles for the same token both read the (still-present) claim and enqueue distinct
+ * `claim_completed` instances → two grants for one purchase (over-grant / invite-spam). KV has no
+ * atomic compare-and-swap, so we serialize through a Durable Object keyed by the claim
+ * (`{adapter}:{transaction_id}`): a DO is single-threaded, so `acquire()` is atomic.
+ *
+ * State machine: `idle → processing → (idle on release | granted on finalize)`.
+ *   - route POST calls `acquire()` before enqueuing; a second concurrent submit sees `processing`
+ *     and is rejected → at most one grant attempt in flight per claim.
+ *   - the workflow terminal step calls `finalize()` on success / non-user-not-found (locked for good;
+ *     the token is consumed anyway) or `release()` on user-not-found / transient exhaustion so a
+ *     later SEQUENTIAL resubmit with a corrected handle can acquire and run (preserves the corrected-handle retry).
+ */
+
+export type AcquireResult =
+  | { ok: true }
+  | { ok: false; code: 'in_progress' | 'already_claimed' }
+
+type GuardStatus = 'idle' | 'processing' | 'granted'
+
+export class ClaimGuard extends DurableObject {
+  async acquire(): Promise<AcquireResult> {
+    const status = (await this.ctx.storage.get<GuardStatus>('status')) ?? 'idle'
+    if (status === 'granted') return { ok: false, code: 'already_claimed' }
+    if (status === 'processing') return { ok: false, code: 'in_progress' }
+    await this.ctx.storage.put('status', 'processing')
+    return { ok: true }
+  }
+
+  /** Allow a sequential retry: only steps back from `processing` (never resurrects `granted`). */
+  async release(): Promise<void> {
+    if ((await this.ctx.storage.get<GuardStatus>('status')) === 'processing') {
+      await this.ctx.storage.put('status', 'idle')
+    }
+  }
+
+  /** Terminal: the claim is done; no further attempt may acquire. */
+  async finalize(): Promise<void> {
+    await this.ctx.storage.put('status', 'granted')
+  }
+}
+
+/** Resolve the guard stub for a claim, keyed by adapter + transaction_id (route + workflow both have these). */
+export function claimGuard(
+  env: CloudflareBindings,
+  adapter: string,
+  txn: string,
+) {
+  const ns = env.CLAIM_GUARD
+  return ns.get(ns.idFromName(`${adapter}:${txn}`))
+}

package/src/claim-template.tsx

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import { raw } from 'hono/html'
+import type { Branding } from './types'
+
+/**
+ * Claim-page template contract. The claim CONTROLLER
+ * (`claim.tsx`) owns all logic - token validation, inline username validation, ClaimGuard single-flight, workflow
+ * enqueue, `harden()` headers, and the JSON projections - and renders each HTML state through an
+ * injected `ClaimTemplate`. This module is the PUBLIC extension point: a downstream worker (or Pro, in
+ * its own repo) supplies its own `ClaimTemplate` via `createWorker({ claimTemplate })` to
+ * restyle every claim state without forking the controller. Core ships ONLY this contract +
+ * `defaultClaimTemplate`. JSON responses stay controller-owned - templates render HTML only.
+ */
+
+/**
+ * Seller-configurable branding, resolved from `config.branding` by the controller.
+ * The shape lives in `types.ts` (the config contract); re-exported here for template authors.
+ */
+export type { Branding } from './types'
+
+/**
+ * The view the controller hands the template - one variant per claim state. The `form` variant
+ * carries `submitScript`: core's central submit-feedback JS (kept core-owned so the
+ * disable-button + spinner behaviour is uniform across templates). A template MUST embed it as
+ * `<script>{raw(view.submitScript)}</script>` and give its form `id="claim-form"` + its submit
+ * button `id="claim-btn"` (the script targets those ids); it should style a `.spinner` but degrades
+ * gracefully if absent.
+ */
+export type ClaimView =
+  | { kind: 'form'; token: string; error?: string; submitScript: string }
+  | { kind: 'submitted'; token: string; username: string }
+  | { kind: 'busy'; token: string }
+  | { kind: 'invalid' }
+
+/**
+ * A claim-page template: pure `(brand, view) → HTML`. Injected via `createWorker({ claimTemplate })`.
+ * The return is whatever `c.html()` accepts - a Hono JSX node satisfies this (a JSX node is an
+ * `HtmlEscapedString`, i.e. a `string` subtype), as does a plain HTML string or a Promise of one.
+ */
+export type ClaimTemplate = (ctx: {
+  brand: Branding
+  view: ClaimView
+}) => string | Promise<string>
+
+// --- default template --------------------------------------------------------
+
+// Plain descendant selectors only (no `>`/`&`) so the stylesheet survives unescaped via raw().
+const CSS = `
+  :root { color-scheme: light dark }
+  body { font-family: system-ui, sans-serif; margin: 0; padding: 2rem 1rem;
+    display: flex; justify-content: center; background: #f6f7f9; color: #111 }
+  .card { background: #fff; max-width: 28rem; width: 100%; padding: 2rem;
+    border-radius: 12px; box-shadow: 0 1px 3px rgba(0,0,0,.12) }
+  .logo { max-height: 48px; margin-bottom: 1rem }
+  .brand { font-size: 1.1rem; margin: 0 0 1rem; color: #555 }
+  h2 { margin: 0 0 .5rem; font-size: 1.4rem }
+  p { line-height: 1.5; color: #333 }
+  label { display: block; font-weight: 600; margin: 1rem 0 .35rem }
+  input { width: 100%; box-sizing: border-box; padding: .6rem .75rem; font-size: 1rem;
+    border: 1px solid #ccc; border-radius: 8px }
+  button { margin-top: 1.25rem; width: 100%; padding: .7rem; font-size: 1rem; font-weight: 600;
+    color: #fff; background: #1f6feb; border: 0; border-radius: 8px; cursor: pointer }
+  button[disabled] { opacity: .75; cursor: default }
+  .error { color: #b00020; font-weight: 600 }
+  .spinner { display: inline-block; width: 1em; height: 1em; margin-right: .5em; vertical-align: -.15em;
+    border: 2px solid rgba(255,255,255,.55); border-top-color: #fff; border-radius: 50%;
+    animation: spin .6s linear infinite }
+  @keyframes spin { to { transform: rotate(360deg) } }
+`
+
+const Layout = (props: {
+  brand: Branding
+  title: string
+  children: unknown
+}) => (
+  <html lang="en">
+    <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width, initial-scale=1" />
+      <title>
+        {props.title} · {props.brand.name}
+      </title>
+      {props.brand.faviconUrl ? (
+        <link rel="icon" href={props.brand.faviconUrl} />
+      ) : null}
+      <style>{raw(CSS)}</style>
+    </head>
+    <body>
+      <main class="card">
+        {props.brand.logoUrl ? (
+          <img class="logo" src={props.brand.logoUrl} alt={props.brand.name} />
+        ) : (
+          <p class="brand">{props.brand.name}</p>
+        )}
+        {props.children as never}
+      </main>
+    </body>
+  </html>
+)
+
+const ClaimForm = (props: {
+  brand: Branding
+  token: string
+  error?: string
+  submitScript: string
+}) => (
+  <Layout brand={props.brand} title="Claim your access">
+    <h2>Claim your access</h2>
+    <p>
+      Enter your GitHub username to be added to the {props.brand.name}{' '}
+      repositories for your purchase.
+    </p>
+    {props.error ? <p class="error">{props.error}</p> : null}
+    <form id="claim-form" method="post" action={`/claim/${props.token}`}>
+      <label for="github_username">GitHub username</label>
+      <input
+        id="github_username"
+        name="github_username"
+        autocomplete="off"
+        autofocus
+        required
+        placeholder="octocat"
+      />
+      <button id="claim-btn" type="submit">
+        Claim access
+      </button>
+    </form>
+    <script>{raw(props.submitScript)}</script>
+  </Layout>
+)
+
+const ClaimSubmitted = (props: {
+  brand: Branding
+  token: string
+  username: string
+}) => (
+  <Layout brand={props.brand} title="Processing your claim">
+    <h2>Processing your claim</h2>
+    <p>
+      We&apos;re adding <strong>{props.username}</strong> to your repositories.
+      Watch for a GitHub invitation in your email and notifications.
+    </p>
+    <p>
+      If you don&apos;t receive a GitHub invitation (email + notifications)
+      within a minute, you may have mistyped your username -{' '}
+      <a href={`/claim/${props.token}`}>reload this page</a> to correct it and
+      try again.
+    </p>
+  </Layout>
+)
+
+const ClaimBusy = (props: { brand: Branding; token: string }) => (
+  <Layout brand={props.brand} title="Claim in progress">
+    <h2>This claim is already being processed</h2>
+    <p>
+      A submission for this link is in flight or already completed.{' '}
+      <a href={`/claim/${props.token}`}>Reload this page</a> in a moment to see
+      the result - if no GitHub invitation arrives (email + notifications)
+      within a minute, the username may have been mistyped, and you&apos;ll be
+      able to correct it and try again.
+    </p>
+  </Layout>
+)
+
+const ClaimInvalid = (props: { brand: Branding }) => (
+  <Layout brand={props.brand} title="Claim unavailable">
+    <h2>This claim link is invalid or no longer active</h2>
+    <p>
+      If you just submitted your username, your access may already be granted -
+      check your GitHub invitations and notifications. Otherwise this link may
+      have expired; contact support with your order details.
+    </p>
+  </Layout>
+)
+
+/**
+ * Core's default claim template - the current markup, verbatim. Rendered HTML is byte-identical to
+ * the original inline components (that identity is the regression proof: the existing claim tests
+ * pass unchanged). A downstream template can replace this wholesale via createWorker({ claimTemplate }).
+ */
+export const defaultClaimTemplate: ClaimTemplate = ({ brand, view }) => {
+  switch (view.kind) {
+    case 'form':
+      return (
+        <ClaimForm
+          brand={brand}
+          token={view.token}
+          error={view.error}
+          submitScript={view.submitScript}
+        />
+      )
+    case 'submitted':
+      return (
+        <ClaimSubmitted
+          brand={brand}
+          token={view.token}
+          username={view.username}
+        />
+      )
+    case 'busy':
+      return <ClaimBusy brand={brand} token={view.token} />
+    case 'invalid':
+      return <ClaimInvalid brand={brand} />
+  }
+}

package/src/claim.tsx

@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import type { Context } from 'hono'
+import type {
+  AccessWorkflowParams,
+  Branding,
+  NormalizedEvent,
+  RepoAccessConfig,
+} from './types'
+import { workflowInstanceId } from './workflow-id'
+import { isValidGithubUsername } from './username'
+import { claimKey } from './kv-keys'
+import { claimGuard } from './claim-guard'
+import type { ClaimTemplate } from './claim-template'
+
+/**
+ * Claim flow CONTROLLER. A claim is created by the
+ * grant workflow's `claim`-mode fallback when no valid GitHub username is known. This module owns the
+ * LOGIC for the page the buyer lands on; the HTML VIEW is an injected `ClaimTemplate` (the open
+ * extension point - see `claim-template.tsx`):
+ *
+ *   GET  /claim/:token  → JSON (Accept: application/json) or the template's `form` state after KV
+ *                         token validation. A prior failed attempt (user-not-found) re-shows `last_error`.
+ *   POST /claim/:token  → validate the handle inline → enqueue a grant in `username` mode
+ *                         under the instance id `{adapter}-claim_completed-{transaction_id}-{handle}`.
+ *
+ * The handle is folded INTO the instance id: a corrected handle is a new id and re-runs,
+ * while resubmitting the SAME handle dedups against the in-flight/failed instance. The claim token
+ * lifecycle (consume on success / non-user-not-found, RETAIN on user-not-found) lives in the WORKFLOW
+ * terminal step - NOT here - so a failed attempt leaves the token usable for a corrected retry. The
+ * route therefore does not delete the token; it tells the buyer to reload to see the result.
+ *
+ * Handlers are built from a template via `makeClaimGet`/`makeClaimPost` (wired in create-worker.ts).
+ * JSON responses are controller-owned; the template renders HTML only.
+ */
+
+// Encode the route path so `c.req.param('token')` types as `string` (not `string | undefined`):
+// these handlers are only ever mounted at `/claim/:token` (see create-worker.ts), and the `:token`
+// segment is non-optional, so the param is always present.
+type Ctx = Context<{ Bindings: CloudflareBindings }, '/claim/:token'>
+
+interface PendingClaim {
+  adapter: string
+  product_id: string
+  teams: string[]
+  buyer_email: string | null
+  transaction_id: string
+  /** Absolute expiry (epoch seconds) anchored at claim creation - preserved across re-puts. */
+  expires_at?: number
+  /** Set by the workflow on a user-not-found failure so GET re-shows the form with the error. */
+  last_error?: string
+}
+
+// Seller-configurable branding from `config.branding`. Neutral per-field defaults -
+// never hard-code EdgeKits; a partial config sets only the fields it wants.
+function branding(config: RepoAccessConfig): Branding {
+  const b = config.branding
+  return {
+    name: b?.name || 'RepoAccess',
+    logoUrl: b?.logoUrl || '',
+    faviconUrl: b?.faviconUrl || '',
+  }
+}
+
+async function readClaim(
+  env: CloudflareBindings,
+  token: string,
+): Promise<PendingClaim | null> {
+  return (await env.ENTITLEMENTS.get(
+    claimKey(token),
+    'json',
+  )) as PendingClaim | null
+}
+
+function wantsJson(c: Ctx): boolean {
+  return Boolean(c.req.header('accept')?.includes('application/json'))
+}
+
+// Submit-feedback for the claim form (UX only - ClaimGuard enforces single-flight server-side). On
+// submit: disable the button + swap in a spinner so the buyer sees progress during the ~1.5s grant and
+// is discouraged from double-submitting. The button carries no `name`, so disabling it drops no field.
+// Kept core-owned + central (passed into the `form` view as `submitScript`) so the behaviour is uniform
+// across templates; a template embeds it via <script>{raw(view.submitScript)}</script> and targets the
+// `claim-form`/`claim-btn` ids. NOTE: served inline with no nonce because the claim responses set NO
+// Content-Security-Policy (the page already relies on an inline <style>). If a strict script-src CSP is
+// ever added to these responses, nonce this <script> (do NOT add 'unsafe-inline').
+const SUBMIT_JS = `
+;(function () {
+  var f = document.getElementById('claim-form')
+  if (!f) return
+  f.addEventListener('submit', function () {
+    var b = document.getElementById('claim-btn')
+    if (!b || b.disabled) return
+    b.disabled = true
+    b.setAttribute('aria-busy', 'true')
+    b.innerHTML = '<span class="spinner" aria-hidden="true"></span>Claiming…'
+  })
+})()
+`
+
+// The token lives in the URL path → keep it out of Referer (a seller-set brand image host would
+// otherwise receive the full claim URL) and out of shared caches.
+function harden(c: Ctx): void {
+  c.header('Referrer-Policy', 'no-referrer')
+  c.header('Cache-Control', 'no-store')
+}
+
+/** Build the GET handler bound to a claim template. Logic is template-agnostic. */
+export function makeClaimGet(
+  template: ClaimTemplate,
+  config: RepoAccessConfig,
+) {
+  return async function handleClaimGet(c: Ctx): Promise<Response> {
+    harden(c)
+    const token = c.req.param('token')
+    const brand = branding(config)
+    const claim = await readClaim(c.env, token)
+
+    if (!claim) {
+      return wantsJson(c)
+        ? c.json({ error: 'invalid_or_expired' }, 404)
+        : c.html(template({ brand, view: { kind: 'invalid' } }), 404)
+    }
+    if (wantsJson(c)) {
+      // Minimal projection - no buyer_email (PII) over the wire here.
+      return c.json({
+        adapter: claim.adapter,
+        product_id: claim.product_id,
+        teams: claim.teams,
+        last_error: claim.last_error ?? null,
+      })
+    }
+    // A retained claim carries last_error from a failed prior attempt → re-show the form with it.
+    return c.html(
+      template({
+        brand,
+        view: {
+          kind: 'form',
+          token,
+          error: claim.last_error,
+          submitScript: SUBMIT_JS,
+        },
+      }),
+    )
+  }
+}
+
+/** Build the POST handler bound to a claim template. Logic is template-agnostic. */
+export function makeClaimPost(
+  template: ClaimTemplate,
+  config: RepoAccessConfig,
+) {
+  return async function handleClaimPost(c: Ctx): Promise<Response> {
+    harden(c)
+    const token = c.req.param('token')
+    const brand = branding(config)
+    const claim = await readClaim(c.env, token)
+
+    if (!claim) {
+      return wantsJson(c)
+        ? c.json({ error: 'invalid_or_expired' }, 404)
+        : c.html(template({ brand, view: { kind: 'invalid' } }), 404)
+    }
+
+    const body = await c.req.parseBody()
+    const username =
+      typeof body.github_username === 'string'
+        ? body.github_username.trim()
+        : ''
+
+    // Inline username validation → re-prompt on failure (never enqueue a malformed handle).
+    if (!isValidGithubUsername(username)) {
+      const error =
+        'Enter a valid GitHub username - letters, digits and single hyphens, up to 39 characters.'
+      return wantsJson(c)
+        ? c.json({ error: 'invalid_username' }, 400)
+        : c.html(
+            template({
+              brand,
+              view: { kind: 'form', token, error, submitScript: SUBMIT_JS },
+            }),
+            400,
+          )
+    }
+
+    // Build the grant event. event_type is `payment_success` so the workflow runs a GRANT; the instance
+    // id below uses the distinct `claim_completed` event_type so it can't collide with the original
+    // claim-mode `payment_success` instance for this transaction.
+    const event: NormalizedEvent = {
+      event_type: 'payment_success',
+      product_id: claim.product_id,
+      transaction_id: claim.transaction_id,
+      buyer_email: claim.buyer_email,
+      github_username: username,
+      is_full_refund: null,
+    }
+    // Fold the submitted handle into the id: a corrected handle → new id → re-runs the grant
+    // even while a failed attempt is still in its retention window; the SAME handle → same id → dedups.
+    // `username` is charset-safe; workflowInstanceId hash-falls-back if the combined value is
+    // out-of-charset/over-long (the hash includes the handle, so it stays distinct per handle).
+    const id = await workflowInstanceId(
+      claim.adapter,
+      'claim_completed',
+      `${claim.transaction_id}-${username}`,
+    )
+    const params: AccessWorkflowParams = {
+      adapter: claim.adapter,
+      event,
+      from_claim: true,
+    }
+
+    // Single-flight: serialize through the per-claim Durable Object so two concurrent submits
+    // (esp. of DISTINCT handles) can't both enqueue → at most one grant per claim. A second concurrent
+    // submit while one is in flight is rejected; the workflow releases the lock on user-not-found so a
+    // later sequential corrected resubmit can acquire.
+    const guard = claimGuard(c.env, claim.adapter, claim.transaction_id)
+    const acq = await guard.acquire()
+    if (!acq.ok) {
+      return wantsJson(c)
+        ? c.json({ error: acq.code }, 409)
+        : c.html(template({ brand, view: { kind: 'busy', token } }), 409)
+    }
+
+    try {
+      await c.env.ACCESS_WORKFLOW.createBatch([{ id, params }])
+    } catch (err) {
+      // Enqueue failed → release the lock so the buyer can retry (otherwise the claim is stuck).
+      await guard.release()
+      throw err
+    }
+
+    // Do NOT delete the token here - the workflow consumes it on success (or a non-user-not-found
+    // failure) and RETAINS it on user-not-found so the buyer can correct the handle. Tell
+    // the buyer to reload to see the result; `claim.completed` is emitted by the workflow on success.
+    return wantsJson(c)
+      ? c.json({ status: 'processing', github_username: username })
+      : c.html(
+          template({ brand, view: { kind: 'submitted', token, username } }),
+        )
+  }
+}