repoaccess-core 0.2.3 → 0.2.5

package/README.md

@@ -57,6 +57,11 @@ org and team plus the privacy settings that keep your repos private, the Stripe
 your secrets, deploy, and a live end-to-end test. It edits the config files for you and guides the
 dashboard clicks (no digging through docs), and it never sees your secret values.
 
+During the wizard, your coding agent runs setup commands (wrangler, npm) and edits two config files
+(`src/repoaccess.config.ts` and `wrangler.jsonc`) for you. It will ask you to approve each step -
+approve them to continue (you can pick 'yes, and don't ask again' for a repeated command). The agent
+never reads your secret file (`.dev.vars`); you paste your secrets there yourself.
+
 **Other agents (Codex, OpenCode, Cursor, ...):** the wizard is agent-agnostic. Claude Code and
 [OpenCode](https://opencode.ai) both expose it as the `/repoaccess-setup` command; for any other coding
 agent, open the cloned repo and ask your agent to follow `docs/setup-wizard.md` - the same shared

package/docs/user-guide-stripe.md

@@ -66,7 +66,11 @@ export const config: RepoAccessConfig = {
   githubOrg: 'your-org-slug',
   productTeamMap: {
     stripe: { 'prod_...': { teams: ['pro'], grant_mode: 'username' } }, // product id filled in Step 4
-    defaults: { teams: [], grant_mode: 'claim', revoke_policy: { mode: 'log_only' } },
+    defaults: {
+      teams: [],
+      grant_mode: 'claim',
+      revoke_policy: { mode: 'log_only' },
+    },
   },
 }
 ```
@@ -134,6 +138,7 @@ needs it. Open `/health` and confirm `{"status":"ok"}`.
 
      It is obscurity only (the HMAC signature is the real gate; the worker never reads the path), so it
      is NOT a worker secret. Keep it in your notes.
+
    - Reveal the **Signing secret** (`whsec_...`) for the next step.
 
 ## 5. Add the secret and re-deploy
@@ -176,7 +181,8 @@ Run the three flows **in this order** - refund before the typo test, so each tes
    `https://<worker>.workers.dev/claim/<token>`, enter a real handle (reuse the Step-1 handle, now that
    it was revoked), and submit. The claim grant creates a NEW GitHub invitation too - **accept the email
    invite** (or at `https://github.com/orgs/<org>/invitation`) to become a member. A typo never strands a
-   paying buyer.
+   paying buyer. (In production you do not dig this link out by hand: Step 7 wires a post-payment redirect
+   that lands the buyer on the claim page automatically.)
 
 Benign noise: `AccessWorkflow.run - Exception Thrown` and `Cancelled` in `wrangler tail` are how
 Cloudflare Workflows logs durable step suspension - they appear on fully successful runs too. Judge a run
@@ -186,7 +192,37 @@ by raw tail lines.
 That single live grant verifies the whole chain: the PAT, the org hardening, the config, the webhook
 signature, and the deploy.
 
-## 7. Going live and operating
+## 7. Deliver the claim link automatically (the post-payment redirect)
+
+In `claim` mode every buyer needs the one-time claim link, and in `username` mode a buyer who mistypes
+their handle falls back to one (Step 6, flow 3). Rather than make them dig it out of a dashboard, send
+them straight there: point your Stripe checkout's post-payment redirect at the worker, which resolves the
+buyer's transaction to their claim page.
+
+The worker exposes a resolver: `GET /claim/by-txn/stripe/<id>`. Hand it the buyer's transaction and it
+302-redirects to the live claim page (`/claim/<token>`); if access was already granted directly (the
+`username` happy path) it shows a short "you are all set, accept the GitHub invite" page; and in the few
+seconds before the grant workflow finishes it shows a neutral "setting up, refresh shortly" page. It is
+read-only and re-queryable, so a buyer who closes the tab can open the same link again.
+
+Wire it on the Payment Link: open the link, then **Confirmation page**, choose **Don't show a
+confirmation page**, and set the redirect URL to
+
+```
+https://<your-worker>.workers.dev/claim/by-txn/stripe/{CHECKOUT_SESSION_ID}
+```
+
+Stripe substitutes `{CHECKOUT_SESSION_ID}` with the real id at redirect time. That id is the **checkout
+session** (`cs_...`), while the worker keys the claim by the **payment intent** (`pi_...`); the worker
+bridges the two automatically (it recorded the mapping when the payment arrived), so the path just works.
+For a custom, API-created Checkout Session, set `success_url` to the same path with the same
+`{CHECKOUT_SESSION_ID}` placeholder.
+
+To test it, repeat the Step 6 grant in `claim` mode (or the typo fallback) with the redirect configured:
+after paying you land on the claim page directly, no dashboard lookup. The Workflow-dashboard method in
+Step 6 stays available as a manual fallback.
+
+## 8. Going live and operating
 
 - **Add more products:** map each new Stripe product id to a team in `productTeamMap` and re-deploy.
 - **Production:** repeat with the `production` config profile and `.dev.vars.production`, deploying with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repoaccess-core",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "license": "AGPL-3.0-or-later",
   "exports": {
@@ -31,6 +31,6 @@
     "prettier": "^3.8.4",
     "typescript": "5.9.3",
     "vitest": "^4.1.0",
-    "wrangler": "^4.104.0"
+    "wrangler": "^4.105.0"
   }
 }

package/src/adapters/stripe.ts

@@ -126,6 +126,9 @@ export const stripe: PaymentAdapter = {
             asString(customer?.email) ?? asString(object.customer_email),
           github_username: githubUsername(object),
           is_full_refund: null,
+          // The success_url redirect carries the checkout session id (cs_...), not the
+          // payment_intent. Alias it -> transaction_id so /claim/by-txn resolves from the redirect.
+          redirect_alias_id: asString(object.id) ?? undefined, // cs_... (checkout session id)
         }
       }
 

package/src/claim-template.tsx

@@ -35,6 +35,21 @@ export type ClaimView =
   | { kind: 'submitted'; token: string; username: string }
   | { kind: 'busy'; token: string }
   | { kind: 'invalid' }
+  // Resolve-by-transaction (claim-link delivery, ADR-0042): the neutral "preparing" state shown when
+  // the claim is not yet resolvable by transaction (the grant workflow runs async after the webhook
+  // ack, so `claim_txn` may be absent at the instant of the post-checkout redirect). No token here.
+  // Carries `pollScript`: core's central auto-poll JS (kept core-owned, like `form`'s submitScript) so
+  // the page self-refreshes across the KV eventual-consistency window and the loop self-terminates once
+  // a terminal view replaces it. A template MUST embed it as `<script>{raw(view.pollScript)}</script>`.
+  | { kind: 'pending'; pollScript: string }
+  // Resolve-by-transaction (ADR-0042): the access has already been granted directly (grant_mode
+  // `username` happy path, which produces no claim) - so one redirect URL serves both grant modes.
+  // No handle/teams/grant detail echoed.
+  | { kind: 'granted' }
+  // Resolve-by-transaction (0.2.5): a TERMINAL grant failure was recorded for this transaction (bad
+  // handle on a username grant / un-correctable GitHub error / exhausted retries). Neutral copy, no
+  // detail echoed - so the buyer gets a definite signal instead of looping on `pending` forever.
+  | { kind: 'failed' }
 
 /**
  * A claim-page template: pure `(brand, view) → HTML`. Injected via `createWorker({ claimTemplate })`.
@@ -166,6 +181,41 @@ const ClaimBusy = (props: { brand: Branding; token: string }) => (
   </Layout>
 )
 
+const ClaimPending = (props: { brand: Branding; pollScript: string }) => (
+  <Layout brand={props.brand} title="Setting up your access">
+    <h2>Setting up your access</h2>
+    <p>
+      If you just completed payment, this can take a few seconds - this page
+      refreshes itself automatically. If it persists, contact support.
+    </p>
+    <p id="bytxn-slow" class="error" style="display:none">
+      This is taking longer than expected - refresh the page, or contact support
+      if it persists.
+    </p>
+    <script>{raw(props.pollScript)}</script>
+  </Layout>
+)
+
+const ClaimGranted = (props: { brand: Branding }) => (
+  <Layout brand={props.brand} title="Access granted">
+    <h2>Access granted</h2>
+    <p>
+      Your access is set up. Check your email for the GitHub invitation and
+      accept it.
+    </p>
+  </Layout>
+)
+
+const ClaimFailed = (props: { brand: Branding }) => (
+  <Layout brand={props.brand} title="Access setup failed">
+    <h2>Something went wrong setting up your access</h2>
+    <p>
+      We could not finish setting up your access. Please contact support with
+      your order details and we&apos;ll sort it out.
+    </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>
@@ -203,6 +253,12 @@ export const defaultClaimTemplate: ClaimTemplate = ({ brand, view }) => {
       )
     case 'busy':
       return <ClaimBusy brand={brand} token={view.token} />
+    case 'pending':
+      return <ClaimPending brand={brand} pollScript={view.pollScript} />
+    case 'granted':
+      return <ClaimGranted brand={brand} />
+    case 'failed':
+      return <ClaimFailed brand={brand} />
     case 'invalid':
       return <ClaimInvalid brand={brand} />
   }

package/src/claim.tsx

@@ -12,7 +12,13 @@ import type {
 } from './types'
 import { workflowInstanceId } from './workflow-id'
 import { isValidGithubUsername } from './username'
-import { claimKey } from './kv-keys'
+import {
+  claimKey,
+  claimIndexKey,
+  grantKey,
+  sessionTxnKey,
+  failKey,
+} from './kv-keys'
 import { claimGuard } from './claim-guard'
 import type { ClaimTemplate } from './claim-template'
 
@@ -42,6 +48,12 @@ import type { ClaimTemplate } from './claim-template'
 // segment is non-optional, so the param is always present.
 type Ctx = Context<{ Bindings: CloudflareBindings }, '/claim/:token'>
 
+// Same trick for the resolve-by-transaction route: both `:adapter` and `:txn` are non-optional.
+type ByTxnCtx = Context<
+  { Bindings: CloudflareBindings },
+  '/claim/by-txn/:adapter/:txn'
+>
+
 interface PendingClaim {
   adapter: string
   product_id: string
@@ -101,6 +113,36 @@ const SUBMIT_JS = `
 })()
 `
 
+// Auto-poll for the resolve-by-transaction `pending` view: the grant workflow runs async AFTER the
+// <100ms webhook ack, and a KV key-miss is edge-cached for ~60s (cacheTtl floor, cannot go lower), so
+// even a SUCCESSFUL grant can read as `pending` for up to ~60s until the miss-cache expires. This
+// reloads the page every ~4s so the buyer lands on the terminal view (302 / granted / failed) without
+// manually refreshing. The loop SELF-TERMINATES because only the `pending` view carries this script -
+// a terminal view has no script. Capped at ~15 reloads (~60-75s) via a per-path sessionStorage counter
+// so a genuinely stuck case stops looping and reveals a quiet "taking longer" line (#bytxn-slow)
+// instead of refreshing forever. Core-owned + central (passed into the `pending` view as `pollScript`)
+// like SUBMIT_JS, so the behaviour is uniform across templates. Served inline with no nonce for the
+// same reason as SUBMIT_JS (these responses set no CSP); if a strict script-src CSP is ever added,
+// nonce this <script> (do NOT add 'unsafe-inline').
+const POLL_JS = `
+;(function () {
+  try {
+    var KEY = 'repoaccess_bytxn:' + location.pathname
+    var MAX = 15
+    var n = 0
+    try { n = parseInt(sessionStorage.getItem(KEY) || '0', 10) || 0 } catch (e) {}
+    if (n >= MAX) {
+      try { sessionStorage.removeItem(KEY) } catch (e) {}
+      var el = document.getElementById('bytxn-slow')
+      if (el) el.style.display = ''
+      return
+    }
+    try { sessionStorage.setItem(KEY, String(n + 1)) } catch (e) {}
+    setTimeout(function () { location.reload() }, 4000)
+  } catch (e) {}
+})()
+`
+
 // 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 {
@@ -242,3 +284,86 @@ export function makeClaimPost(
         )
   }
 }
+
+/**
+ * Build the resolve-by-transaction handler (claim-link delivery, DEC-11 / ADR-0042) bound to a claim
+ * template.
+ *
+ *   GET /claim/by-txn/:adapter/:txn → four grant-aware landing states, so ONE redirect URL serves
+ *     BOTH grant modes and reflects a terminal failure:
+ *       a. `claim_txn:{adapter}:{txn}` present → 302 to the single-use `/claim/:token` flow
+ *          (grant_mode `claim`, OR a username typo-fallback that produced a claim).
+ *       b. else `grant:{adapter}:{txn}` present → a neutral `granted` view (200) - the access was
+ *          granted directly (grant_mode `username` happy path produces no claim).
+ *       c. else `fail:{adapter}:{txn}` present → a neutral `failed` view (200) - the grant failed
+ *          terminally (the workflow wrote the marker), so the buyer gets a definite signal.
+ *       d. else → a neutral `pending` view (200) that auto-polls across the KV consistency window.
+ *
+ * This is the re-queryable delivery channel: it survives a dropped or closed post-checkout redirect
+ * (the deployer can resolve the same txn again). The grant workflow runs async AFTER the <100ms webhook
+ * ack, so no key may exist yet at the instant of the redirect - the (d) case renders a neutral
+ * "preparing" page rather than 404, leaking no distinction between not-yet-written and never-existed and
+ * exposing no token; its client poll (POLL_JS) reloads every ~4s (capped ~15x) so a successful grant
+ * surfaces without a manual refresh once KV's ~60s key-miss cache expires. Read-only: KV existence
+ * checks + a redirect, no grant, no workflow enqueue, no side effects. The `granted` and `failed`
+ * branches check ONLY for the record's existence - they never parse or echo the grant detail (handle /
+ * teams / org) or the failure detail, so no purchase data is exposed by the txn-as-bearer-credential.
+ *
+ * The `:txn` segment is alias-resolved first (see `sessionTxnKey`): a merchant redirect that carries
+ * an id differing from the transaction_id (Stripe `cs_...` session id vs the `pi_...` claim key) is
+ * mapped through `session_txn:{adapter}:{id}` before the lookups; a direct transaction_id resolves
+ * unchanged. The mechanism is generic - adapters whose redirect id IS the transaction_id (Paddle)
+ * write no alias and need no change.
+ *
+ * `adapterNames` gates the `:adapter` segment (unknown adapter → 404), mirroring the `/wh` lookup.
+ */
+export function makeClaimByTxn(
+  template: ClaimTemplate,
+  config: RepoAccessConfig,
+  adapterNames: ReadonlySet<string>,
+) {
+  return async function handleClaimByTxn(c: ByTxnCtx): Promise<Response> {
+    harden(c)
+    const adapter = c.req.param('adapter')
+    if (!adapterNames.has(adapter)) return c.notFound() // unknown adapter → 404
+
+    const txn = c.req.param('txn')
+    const brand = branding(config)
+
+    // Alias-resolve transparently: a merchant redirect may carry an id that differs from the
+    // transaction_id that keys the claim/grant (Stripe's success_url carries the checkout session id
+    // cs_..., while the claim is keyed by the payment_intent pi_...). The workflow wrote
+    // session_txn:{adapter}:{cs_} -> {pi_} on payment_success. A direct transaction_id (no alias
+    // entry) resolves unchanged (mapped === null → realTxn = txn).
+    const mapped = await c.env.ENTITLEMENTS.get(sessionTxnKey(adapter, txn))
+    const realTxn = mapped ?? txn
+
+    // (a) A pending claim exists → hand off to the single-use claim flow via a same-origin redirect.
+    const token = await c.env.ENTITLEMENTS.get(claimIndexKey(adapter, realTxn))
+    if (token) {
+      return c.redirect(`/claim/${token}`, 302)
+    }
+
+    // (b) No claim, but a grant record exists → access was granted directly (username happy path).
+    // Existence check only - never read/parse the record, so no handle/teams/org leaks here.
+    const granted = await c.env.ENTITLEMENTS.get(grantKey(adapter, realTxn))
+    if (granted !== null) {
+      return c.html(template({ brand, view: { kind: 'granted' } }))
+    }
+
+    // (c) No claim and no grant, but a terminal-failure marker exists → the grant failed for good
+    // (bad handle on a username grant / un-correctable GitHub error / exhausted retries). Show a
+    // terminal `failed` view so the buyer gets a definite signal instead of looping on `pending`.
+    // Existence check only - the marker value is the coarse code and is never echoed.
+    const failed = await c.env.ENTITLEMENTS.get(failKey(adapter, realTxn))
+    if (failed !== null) {
+      return c.html(template({ brand, view: { kind: 'failed' } }))
+    }
+
+    // (d) Eventual consistency: no key (yet) present → neutral preparing view (no token exposed) that
+    // auto-polls (POLL_JS) across the ~60s KV miss-cache window until a terminal view replaces it.
+    return c.html(
+      template({ brand, view: { kind: 'pending', pollScript: POLL_JS } }),
+    )
+  }
+}

package/src/create-worker.ts

@@ -11,7 +11,7 @@ import type {
 import { captureRawRequest } from './raw-request'
 import { apiCallbackInstanceId, workflowInstanceId } from './workflow-id'
 import { timingSafeEqualString, verifyRequest } from './verify'
-import { makeClaimGet, makeClaimPost } from './claim'
+import { makeClaimGet, makeClaimPost, makeClaimByTxn } from './claim'
 import { defaultClaimTemplate, type ClaimTemplate } from './claim-template'
 
 export interface CreateWorkerOptions {
@@ -57,6 +57,15 @@ export function createWorker({
   app.get('/claim/:token', makeClaimGet(claimTemplate, config))
   app.post('/claim/:token', makeClaimPost(claimTemplate, config))
 
+  // Resolve-by-transaction (claim-link delivery, DEC-11 / ADR-0042). A re-queryable lookup the deployer
+  // wires their post-checkout redirect to: claim_txn:{adapter}:{txn} -> token -> 302 /claim/{token},
+  // or a neutral `pending` view while the (async) grant workflow has not yet written claim_txn. No
+  // route collision: this is 4 path segments vs the 2 of /claim/:token. Read-only (KV read + redirect).
+  app.get(
+    '/claim/by-txn/:adapter/:txn',
+    makeClaimByTxn(claimTemplate, config, new Set(adaptersByName.keys())),
+  )
+
   /**
    * Inbound payment webhooks. The request path does ONLY: resolve adapter → capture raw body →
    * [verify | secret-path check] → enqueue the Workflow (deterministic id) → ack. No GitHub calls,

package/src/kv-keys.ts

@@ -10,6 +10,11 @@ export const CLAIM_TTL_SEC = 30 * 24 * 60 * 60 // 30 days
 // so records don't grow unbounded.
 export const GRANT_TTL_SEC = 180 * 24 * 60 * 60
 
+// 24 hours - a terminal grant-failure marker so a buyer returning to /claim/by-txn within a day sees
+// the `failed` state instead of perpetual `pending`. Deliberately short: this is a transient,
+// best-effort UX signal; the authoritative failure record is the emitted access.failed event.
+export const FAIL_TTL_SEC = 24 * 60 * 60
+
 /** Grant correlation record - 180d TTL, also deleted on revoke. */
 export const grantKey = (adapter: string, txn: string) =>
   `grant:${adapter}:${txn}`
@@ -20,3 +25,20 @@ 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}`
+
+/**
+ * Terminal grant-failure marker, keyed by transaction so /claim/by-txn can show a `failed` state for a
+ * doomed transaction instead of looping on `pending`. Value is the coarse, non-sensitive failure code
+ * only (never handle/teams/secret). FAIL_TTL_SEC; written by the workflow's terminal-failure paths.
+ */
+export const failKey = (adapter: string, txn: string) =>
+  `fail:${adapter}:${txn}`
+
+/**
+ * Alias index: a merchant redirect id (e.g. Stripe checkout session id cs_...) -> transaction_id, so
+ * /claim/by-txn resolves a redirect whose id differs from the claim/grant key. GRANT_TTL_SEC so it
+ * outlives both the claim and the grant window. Adapters whose redirect id IS the transaction_id (e.g.
+ * Paddle) write no alias.
+ */
+export const sessionTxnKey = (adapter: string, id: string) =>
+  `session_txn:${adapter}:${id}`

package/src/types.ts

@@ -100,6 +100,12 @@ export interface NormalizedEvent {
   github_username: string | null
   /** Refund events only: true=full, false=partial, null=n/a. */
   is_full_refund: boolean | null
+  /**
+   * An id the merchant's post-checkout redirect will carry when it differs from transaction_id
+   * (e.g. Stripe checkout session id cs_..., while transaction_id is the payment_intent pi_...).
+   * Used to alias-resolve /claim/by-txn. Unset when the redirect id IS the transaction_id (e.g. Paddle).
+   */
+  redirect_alias_id?: string
 }
 
 export interface RawRequest {

package/src/workflow.ts

@@ -33,9 +33,12 @@ import {
 import {
   CLAIM_TTL_SEC,
   GRANT_TTL_SEC,
+  FAIL_TTL_SEC,
   grantKey,
   claimKey,
   claimIndexKey,
+  sessionTxnKey,
+  failKey,
 } from './kv-keys'
 import { claimGuard } from './claim-guard'
 
@@ -181,6 +184,34 @@ function collectAllTeams(map: ProductTeamMap): string[] {
 
 // --- grant ------------------------------------------------------------------
 
+/**
+ * Write the redirect-alias index when the adapter set `redirect_alias_id` - the merchant's
+ * post-checkout redirect will carry an id that differs from transaction_id (Stripe: the checkout
+ * session id cs_... vs the payment_intent pi_... that keys the claim/grant). Maps the redirect id ->
+ * transaction_id so /claim/by-txn alias-resolves it transparently. No-op when unset (e.g. Paddle,
+ * whose redirect id IS the transaction_id). GRANT_TTL_SEC so the alias outlives BOTH the claim window
+ * and the grant window. NOT deleted on revoke: the refund/dispute event carries no redirect_alias_id,
+ * and the alias is a harmless indirection - once the underlying claim/grant are gone, by-txn falls
+ * through to the pending view; the alias then expires by TTL.
+ */
+async function writeSessionAlias(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  adapter: string,
+  event: NormalizedEvent,
+): Promise<void> {
+  const aliasId = event.redirect_alias_id
+  if (!aliasId) return
+  await step.do(`claim-alias:${adapter}:${event.transaction_id}`, async () => {
+    await env.ENTITLEMENTS.put(
+      sessionTxnKey(adapter, aliasId),
+      event.transaction_id,
+      { expirationTtl: GRANT_TTL_SEC },
+    )
+    return true
+  })
+}
+
 async function runGrant(
   step: WorkflowStep,
   env: CloudflareBindings,
@@ -191,6 +222,10 @@ async function runGrant(
   sink: EventSink,
   fromClaim: boolean,
 ): Promise<void> {
+  // Alias the merchant redirect id (if any) -> transaction_id BEFORE the grant-vs-claim branch, so
+  // /claim/by-txn resolves for BOTH outcomes (direct grant AND claim fallback).
+  await writeSessionAlias(step, env, adapter, event)
+
   const teams = config.teams ?? []
   // Claim completion forces `username` mode - the product's mode is `claim`, which would loop back
   // into another claim. The handle was already validated at the claim POST.
@@ -445,10 +480,17 @@ async function terminalFailure(
   fromClaim: boolean,
 ): Promise<void> {
   await fail(step, org, event, sink, teams, username, reason, detail)
-  if (!fromClaim) return
+  if (!fromClaim) {
+    // Non-claim grant, terminally failed (e.g. a bad up-front handle that 404s mid-grant, or a 403/
+    // auth error): no claim and no grant record will be written, so mark it failed → /claim/by-txn
+    // shows `failed` rather than perpetual `pending`.
+    await writeFailMarker(step, env, adapter, event.transaction_id, reason)
+    return
+  }
   if (userNotFound) {
     // Buyer-correctable → retain the token AND release the single-flight lock so a later sequential
-    // resubmit with a corrected handle can acquire.
+    // resubmit with a corrected handle can acquire. NOT terminal: write NO fail marker (and
+    // /claim/by-txn 302s to the still-present claim regardless).
     await recordClaimError(
       step,
       env,
@@ -458,9 +500,11 @@ async function terminalFailure(
     )
     await guardRelease(step, env, adapter, event.transaction_id)
   } else {
-    // Not correctable here → consume the token and lock the claim for good.
+    // Not correctable here → consume the token, lock the claim for good, and mark it failed so
+    // /claim/by-txn (the claim is now consumed) shows `failed` instead of `pending`.
     await consumeClaim(step, env, adapter, event.transaction_id)
     await guardFinalize(step, env, adapter, event.transaction_id)
+    await writeFailMarker(step, env, adapter, event.transaction_id, reason)
   }
 }
 
@@ -507,6 +551,29 @@ async function consumeClaim(
   })
 }
 
+/**
+ * Write a terminal grant-failure marker so /claim/by-txn shows a definite `failed` state for a doomed
+ * transaction instead of looping on `pending`. Stores ONLY the coarse, non-sensitive
+ * `AccessFailedReason` code (the same value already carried on the access.failed wire envelope) - never
+ * raw detail, secrets, the handle, or team slugs. FAIL_TTL_SEC is the backstop; a later revoke cleanup
+ * for the same txn may remove it sooner, and the TTL guarantees it never lingers. Deterministic step
+ * id → idempotent across durable retries.
+ */
+async function writeFailMarker(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  adapter: string,
+  txn: string,
+  reason: AccessFailedReason,
+): Promise<void> {
+  await step.do(`fail-marker:${adapter}:${txn}`, async () => {
+    await env.ENTITLEMENTS.put(failKey(adapter, txn), reason, {
+      expirationTtl: FAIL_TTL_SEC,
+    })
+    return true
+  })
+}
+
 /** Stamp `last_error` on the retained claim record so the buyer sees it on GET and can retry. */
 async function recordClaimError(
   step: WorkflowStep,
@@ -871,9 +938,20 @@ export async function executeAccessWorkflow(
         reason: 'grant_error',
       })
       // A claim-originated grant that died on a transient/unexpected error must release its
-      // single-flight lock so the buyer can resubmit (the token was retained).
+      // single-flight lock so the buyer can resubmit (the token was retained) - /claim/by-txn 302s to
+      // that retained claim, so no fail marker. A NON-claim grant (rate-limit / 5xx exhausted, or an
+      // unexpected throw) leaves no claim and no grant record, so mark it failed → /claim/by-txn shows
+      // `failed` rather than perpetual `pending`.
       if (params.from_claim) {
         await guardRelease(step, env, adapter, event.transaction_id)
+      } else {
+        await writeFailMarker(
+          step,
+          env,
+          adapter,
+          event.transaction_id,
+          'grant_error',
+        )
       }
     }
     throw err // mark the Workflow instance failed for observability (the event already fired)