repoaccess-core 0.2.2 → 0.2.4

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.2",
+  "version": "0.2.4",
   "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

@@ -1,3 +1,4 @@
+/** @jsxRuntime automatic */
 /** @jsxImportSource hono/jsx */
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright (C) 2026 Gary Stupak
@@ -34,6 +35,14 @@ 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.
+  | { kind: 'pending' }
+  // 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' }
 
 /**
  * A claim-page template: pure `(brand, view) → HTML`. Injected via `createWorker({ claimTemplate })`.
@@ -165,6 +174,26 @@ const ClaimBusy = (props: { brand: Branding; token: string }) => (
   </Layout>
 )
 
+const ClaimPending = (props: { brand: Branding }) => (
+  <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.
+    </p>
+  </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 ClaimInvalid = (props: { brand: Branding }) => (
   <Layout brand={props.brand} title="Claim unavailable">
     <h2>This claim link is invalid or no longer active</h2>
@@ -202,6 +231,10 @@ export const defaultClaimTemplate: ClaimTemplate = ({ brand, view }) => {
       )
     case 'busy':
       return <ClaimBusy brand={brand} token={view.token} />
+    case 'pending':
+      return <ClaimPending brand={brand} />
+    case 'granted':
+      return <ClaimGranted brand={brand} />
     case 'invalid':
       return <ClaimInvalid brand={brand} />
   }

package/src/claim.tsx

@@ -1,3 +1,4 @@
+/** @jsxRuntime automatic */
 /** @jsxImportSource hono/jsx */
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright (C) 2026 Gary Stupak
@@ -11,7 +12,7 @@ import type {
 } from './types'
 import { workflowInstanceId } from './workflow-id'
 import { isValidGithubUsername } from './username'
-import { claimKey } from './kv-keys'
+import { claimKey, claimIndexKey, grantKey, sessionTxnKey } from './kv-keys'
 import { claimGuard } from './claim-guard'
 import type { ClaimTemplate } from './claim-template'
 
@@ -41,6 +42,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
@@ -241,3 +248,70 @@ 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:
+ *       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).
+ *
+ * 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
+ * "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.
+ *
+ * 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) Eventual consistency: neither key (yet) present → neutral preparing view, no token exposed.
+    return c.html(template({ brand, view: { kind: 'pending' } }))
+  }
+}

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

@@ -20,3 +20,12 @@ 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}`
+
+/**
+ * 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

@@ -36,6 +36,7 @@ import {
   grantKey,
   claimKey,
   claimIndexKey,
+  sessionTxnKey,
 } from './kv-keys'
 import { claimGuard } from './claim-guard'
 
@@ -181,6 +182,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 +220,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.