repoaccess-core 0.2.4 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repoaccess-core",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "license": "AGPL-3.0-or-later",
   "exports": {

package/src/claim-template.tsx

@@ -38,11 +38,18 @@ export type ClaimView =
   // 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.
-  | { kind: 'pending' }
+  // 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 })`.
@@ -174,13 +181,18 @@ const ClaimBusy = (props: { brand: Branding; token: string }) => (
   </Layout>
 )
 
-const ClaimPending = (props: { brand: Branding }) => (
+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 - refresh this
-      page. If it persists, contact support.
+      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>
 )
 
@@ -194,6 +206,16 @@ const ClaimGranted = (props: { brand: Branding }) => (
   </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>
@@ -232,9 +254,11 @@ export const defaultClaimTemplate: ClaimTemplate = ({ brand, view }) => {
     case 'busy':
       return <ClaimBusy brand={brand} token={view.token} />
     case 'pending':
-      return <ClaimPending brand={brand} />
+      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, claimIndexKey, grantKey, sessionTxnKey } from './kv-keys'
+import {
+  claimKey,
+  claimIndexKey,
+  grantKey,
+  sessionTxnKey,
+  failKey,
+} from './kv-keys'
 import { claimGuard } from './claim-guard'
 import type { ClaimTemplate } from './claim-template'
 
@@ -107,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 {
@@ -253,21 +289,25 @@ 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 → three grant-aware landing states, so ONE redirect URL serves
- *     BOTH grant modes:
+ *   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 → a neutral `pending` view (200).
+ *       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 neither key may exist yet at the instant of the redirect - the (c) case renders a neutral
+ * 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. Read-only: KV existence checks + a redirect, no grant, no workflow enqueue, no side
- * effects. The `granted` branch checks ONLY for the record's existence - it never parses or echoes the
- * grant detail (handle / teams / org), so no purchase data is exposed by the txn-as-bearer-credential.
+ * 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
@@ -311,7 +351,19 @@ export function makeClaimByTxn(
       return c.html(template({ brand, view: { kind: 'granted' } }))
     }
 
-    // (c) Eventual consistency: neither key (yet) present → neutral preparing view, no token exposed.
-    return c.html(template({ brand, view: { kind: 'pending' } }))
+    // (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/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}`
@@ -21,6 +26,14 @@ export const claimKey = (token: string) => `claim:${token}`
 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

package/src/workflow.ts

@@ -33,10 +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'
 
@@ -478,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,
@@ -491,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)
   }
 }
 
@@ -540,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,
@@ -904,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)