repoaccess-core 0.2.0

package/src/workflow.ts

@@ -0,0 +1,926 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+import {
+  WorkflowEntrypoint,
+  type WorkflowEvent,
+  type WorkflowStep,
+} from 'cloudflare:workers'
+import { NonRetryableError } from 'cloudflare:workflows'
+import type {
+  AccessWorkflowParams,
+  ApiCallbackPing,
+  NormalizedEvent,
+  PaymentAdapter,
+  ProductConfig,
+  ProductTeamMap,
+  RawRequest,
+  RepoAccessConfig,
+} from './types'
+import { assertProductTeamMap, resolveProductConfig } from './config'
+import { sha256Hex } from './workflow-id'
+import { verifyApiCallback } from './verify'
+import { isValidGithubUsername } from './username'
+import { github, isRateLimited, type GithubResult } from './github'
+import {
+  buildEnvelope,
+  createEventSink,
+  logSink,
+  type EnvelopeField,
+  type EventSink,
+  type OutboundEventType,
+} from './events'
+import {
+  CLAIM_TTL_SEC,
+  GRANT_TTL_SEC,
+  grantKey,
+  claimKey,
+  claimIndexKey,
+} from './kv-keys'
+import { claimGuard } from './claim-guard'
+
+const KV_MIN_TTL_SEC = 60 // Cloudflare KV floor for expirationTtl
+
+const MAX_GH_ATTEMPTS = 8 // rate-limit / 5xx backoff cap; durable sleeps span >1 day before giving up
+
+// Outbound delivery retry policy. The emit step lets the durable engine retry transient
+// delivery failures; after exhaustion the emit step swallows the error (the grant already happened -
+// delivery must NEVER fail the grant).
+const EMIT_RETRY = {
+  retries: { limit: 5, delay: '10 seconds', backoff: 'exponential' },
+} as const
+
+// api_callback entity-fetch retry policy. A THROWN fetch error (network/5xx - Gumroad-class APIs can
+// be slow/down) is retried durably by the engine; after exhaustion the step throws and the workflow
+// surfaces access.failed. A returned null (not-found/forged id) is NOT retried - it is terminal.
+const FETCH_ENTITY_RETRY = {
+  retries: { limit: 5, delay: '10 seconds', backoff: 'exponential' },
+} as const
+
+/**
+ * The stable, coarse vocabulary for the `reason` field on a delivered `access.failed` envelope. The
+ * wire value is ALWAYS one of these fixed codes - never raw error text, an HTTP status, a team slug, or
+ * `String(err)` (those leak internal/inconsistent detail to the seller's endpoint). The full,
+ * descriptive detail is preserved in the structured `log()` calls (the `detail` field) so debugging
+ * loses nothing. Pre-0.2.0 hardening (Info-1): the event SHAPE is unchanged (`reason` stays a string),
+ * only its VALUE space is fixed.
+ *
+ *   - invalid_username     handle absent/malformed/nonexistent where a valid one was required
+ *   - github_error         a GitHub API call failed un-correctably (auth/permission/validation/status)
+ *   - fetch_failed         an api_callback entity fetch threw, or returned not-found/unverifiable
+ *   - parse_failed         an api_callback adapter's parse() threw on the fetched entity
+ *   - unhandled_event      the fetched entity parsed to null (an event kind we don't act on)
+ *   - unverifiable_adapter the enqueued api_callback adapter wasn't passed to createAccessWorkflow
+ *   - grant_error          a grant died on an exhausted-retry / unexpected throw (terminal catch)
+ */
+export type AccessFailedReason =
+  | 'invalid_username'
+  | 'github_error'
+  | 'fetch_failed'
+  | 'parse_failed'
+  | 'unhandled_event'
+  | 'unverifiable_adapter'
+  | 'grant_error'
+
+interface GrantRecord {
+  github_username: string
+  org: string
+  teams: string[]
+  product_id: string
+  granted_at: string
+}
+
+function log(
+  level: string,
+  msg: string,
+  extra: Record<string, unknown> = {},
+): void {
+  console.log(JSON.stringify({ level, msg, ...extra }))
+}
+
+function backoffMs(result: GithubResult, attempt: number): number {
+  if (result.retryAfterSec !== null)
+    return Math.max(1, result.retryAfterSec) * 1000
+  return Math.min(60 * 2 ** attempt, 3600) * 1000 // 1 min → cap 1 h (hours-scale, durable)
+}
+
+/**
+ * Run one GitHub op inside a durable step. 5xx and rate-limit (429 / 403+signal) → `step.sleep`
+ * backoff and retry (NEVER fail the grant on a transient/limit) up to a generous cap.
+ * Returns the (serializable) result for the caller to classify (e.g. 404 vs 200).
+ */
+async function ghStep(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  label: string,
+  op: (env: CloudflareBindings) => Promise<GithubResult>,
+): Promise<GithubResult> {
+  for (let attempt = 0; attempt <= MAX_GH_ATTEMPTS; attempt++) {
+    const result = await step.do(`${label}#${attempt}`, () => op(env))
+    if (result.status < 500 && !isRateLimited(result)) return result
+    if (attempt === MAX_GH_ATTEMPTS) {
+      throw new NonRetryableError(
+        `${label}: GitHub unavailable after ${attempt} retries (last status ${result.status})`,
+      )
+    }
+    log('warn', 'github backoff', { label, attempt, status: result.status })
+    await step.sleep(`${label} backoff#${attempt}`, backoffMs(result, attempt))
+  }
+  throw new NonRetryableError(`${label}: exhausted`)
+}
+
+async function emitEvent(
+  step: WorkflowStep,
+  org: string,
+  sink: EventSink,
+  type: OutboundEventType,
+  event: NormalizedEvent,
+  extra: Record<string, EnvelopeField>,
+): Promise<void> {
+  try {
+    // The sink throws on a transient delivery failure → the durable engine retries this step per
+    // EMIT_RETRY. Side-effect-free retry: re-running only re-sends the event.
+    await step.do(
+      `emit:${type}:${event.transaction_id}`,
+      EMIT_RETRY,
+      async () => {
+        const envelope = buildEnvelope(org, type, event, extra)
+        await sink(envelope)
+        return envelope
+      },
+    )
+  } catch (err) {
+    // Retries exhausted (or a non-retryable error). Log and continue - the grant already happened;
+    // outbound delivery must never fail it.
+    log('warn', 'event delivery exhausted', {
+      type,
+      transaction_id: event.transaction_id,
+      error: String(err),
+    })
+  }
+}
+
+function generateToken(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32)) // 256-bit, ≥128-bit requirement
+  return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+function collectAllTeams(map: ProductTeamMap): string[] {
+  const teams = new Set<string>()
+  const add = (cfg: ProductConfig | undefined) => {
+    for (const slug of cfg?.teams ?? []) teams.add(slug)
+  }
+  for (const [key, value] of Object.entries(map)) {
+    if (key === 'defaults') add(value as ProductConfig)
+    else
+      for (const cfg of Object.values(value as Record<string, ProductConfig>))
+        add(cfg)
+  }
+  return [...teams]
+}
+
+// --- grant ------------------------------------------------------------------
+
+async function runGrant(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  org: string,
+  adapter: string,
+  event: NormalizedEvent,
+  config: ProductConfig,
+  sink: EventSink,
+  fromClaim: boolean,
+): Promise<void> {
+  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.
+  const mode = fromClaim ? 'username' : (config.grant_mode ?? 'claim')
+  const username = event.github_username
+
+  // `username` mode requires a present + well-formed handle; otherwise fall back to `claim`.
+  // (`email` mode is not in v1 → also falls back to claim.) Malformed handles never reach the API,
+  // so they can't burn the 50/24h invitation quota.
+  if (mode !== 'username' || !isValidGithubUsername(username)) {
+    if (fromClaim) {
+      // Unreachable in practice (the claim POST validates first); fail loudly rather than spawn
+      // another claim and loop. Not a user-not-found → consume the token.
+      await terminalFailure(
+        step,
+        env,
+        org,
+        adapter,
+        event,
+        sink,
+        teams,
+        username,
+        'invalid_username',
+        'claim completion with invalid username',
+        false,
+        true,
+      )
+      return
+    }
+    const reason =
+      mode === 'username'
+        ? username
+          ? 'malformed username'
+          : 'no username'
+        : mode === 'email'
+          ? 'email mode not supported'
+          : 'claim mode'
+    await runClaimFallback(step, env, org, adapter, event, teams, sink, reason)
+    return
+  }
+
+  const grantedTeams: string[] = []
+  for (const slug of teams) {
+    // Reconcile: 200 = already active OR pending → converged, skip. 404 = not a member → invite.
+    const current = await ghStep(
+      step,
+      env,
+      `team-get:${slug}:${username}`,
+      (e) => github.getTeamMembership(e, org, slug, username),
+    )
+    if (current.status === 200) {
+      grantedTeams.push(slug)
+      continue
+    }
+    if (current.status !== 404) {
+      // Not user-correctable (auth/permission/unexpected) → consume any claim token.
+      await terminalFailure(
+        step,
+        env,
+        org,
+        adapter,
+        event,
+        sink,
+        teams,
+        username,
+        'github_error',
+        `team-get ${slug} → ${current.status}`,
+        false,
+        fromClaim,
+      )
+      return
+    }
+    // PUT auto-invites non-members; an existing org member is added directly.
+    const put = await ghStep(step, env, `team-put:${slug}:${username}`, (e) =>
+      github.addTeamMembership(e, org, slug, username),
+    )
+    if (put.status !== 200 && put.status !== 201) {
+      const userNotFound = put.status === 404
+      // 404 = the GitHub login does not exist (user not found). For a NON-claim grant the buyer's
+      // up-front handle was simply wrong; this 404 lands on the FIRST team-add (a nonexistent login
+      // fails immediately, so no teams are granted yet), so fall the whole grant back to a claim -
+      // mint a token + emit claim.pending so the buyer can self-correct, rather than terminal
+      // access.failed. A claim-originated 404 instead retains the existing token for a fixed resubmit.
+      if (userNotFound && !fromClaim) {
+        await runClaimFallback(
+          step,
+          env,
+          org,
+          adapter,
+          event,
+          teams,
+          sink,
+          'username not found, falling back to claim',
+        )
+        return
+      }
+      // Otherwise terminal: a claim-originated 404 RETAINS the token for a corrected resubmit
+      // (userNotFound); 422 etc. are not correctable here. A 404 means the GitHub login doesn't exist
+      // (invalid_username); any other status is an un-correctable GitHub error.
+      await terminalFailure(
+        step,
+        env,
+        org,
+        adapter,
+        event,
+        sink,
+        teams,
+        username,
+        userNotFound ? 'invalid_username' : 'github_error',
+        `team-put ${slug} → ${put.status}`,
+        userNotFound,
+        fromClaim,
+      )
+      return
+    }
+    grantedTeams.push(slug)
+  }
+
+  const record: GrantRecord = {
+    github_username: username,
+    org,
+    teams: grantedTeams,
+    product_id: event.product_id,
+    granted_at: new Date().toISOString(),
+  }
+  await step.do(`grant-record:${adapter}:${event.transaction_id}`, async () => {
+    // 180d TTL - covers the refund + ~120d card-chargeback window so a late chargeback can
+    // still resolve; also deleted on revoke.
+    await env.ENTITLEMENTS.put(
+      grantKey(adapter, event.transaction_id),
+      JSON.stringify(record),
+      { expirationTtl: GRANT_TTL_SEC },
+    )
+    return true
+  })
+
+  await emitEvent(step, org, sink, 'access.granted', event, {
+    github_username: username,
+    teams: grantedTeams,
+    status: 'success',
+  })
+
+  // A grant that originated from a completed claim also closes the claim: emit claim.completed and
+  // consume the single-use token (+ reverse index) here in the workflow's terminal step - NOT at the
+  // route, so a failed attempt can retain the token for a corrected retry.
+  if (fromClaim) {
+    await emitEvent(step, org, sink, 'claim.completed', event, {
+      github_username: username,
+      teams: grantedTeams,
+      status: 'success',
+    })
+    await consumeClaim(step, env, adapter, event.transaction_id)
+    await guardFinalize(step, env, adapter, event.transaction_id)
+  }
+}
+
+async function runClaimFallback(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  org: string,
+  adapter: string,
+  event: NormalizedEvent,
+  teams: string[],
+  sink: EventSink,
+  reason: string,
+): Promise<void> {
+  log('info', 'grant → claim fallback', {
+    adapter,
+    transaction_id: event.transaction_id,
+    reason,
+  })
+  const token = await step.do(
+    `claim-token:${adapter}:${event.transaction_id}`,
+    async () => {
+      const t = generateToken()
+      // Anchor expiry at creation (epoch seconds) so re-puts (last_error) preserve it, never
+      // resetting a fresh 30 days.
+      const expiresAt = Math.floor(Date.now() / 1000) + CLAIM_TTL_SEC
+      const pending = JSON.stringify({
+        adapter,
+        product_id: event.product_id,
+        teams,
+        buyer_email: event.buyer_email,
+        transaction_id: event.transaction_id,
+        expires_at: expiresAt,
+      })
+      await env.ENTITLEMENTS.put(claimKey(t), pending, {
+        expirationTtl: CLAIM_TTL_SEC,
+      })
+      await env.ENTITLEMENTS.put(
+        claimIndexKey(adapter, event.transaction_id),
+        t,
+        {
+          expirationTtl: CLAIM_TTL_SEC,
+        },
+      )
+      return t
+    },
+  )
+
+  // claim_url is relative until the claim page lands / the seller prepends their domain.
+  await emitEvent(step, org, sink, 'claim.pending', event, {
+    claim_url: `/claim/${token}`,
+    teams,
+  })
+}
+
+async function fail(
+  step: WorkflowStep,
+  org: string,
+  event: NormalizedEvent,
+  sink: EventSink,
+  teams: string[],
+  username: string | null,
+  reason: AccessFailedReason,
+  detail?: string,
+): Promise<void> {
+  // The wire envelope carries ONLY the coarse code; the raw detail stays in the log.
+  log('error', 'grant failed', {
+    transaction_id: event.transaction_id,
+    username,
+    reason,
+    detail,
+  })
+  await emitEvent(step, org, sink, 'access.failed', event, {
+    github_username: username,
+    teams,
+    status: 'failure',
+    reason,
+  })
+}
+
+/**
+ * A terminal grant failure. Always emits `access.failed` (seller-facing). For a claim-originated
+ * grant it then manages the claim-token lifecycle:
+ *   - `userNotFound` (GitHub login doesn't exist) is buyer-correctable → RETAIN the token and stamp
+ *     `last_error` so `GET /claim/:token` re-shows the form with the error;
+ *   - any other terminal failure is not correctable on the claim page → consume the token.
+ */
+async function terminalFailure(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  org: string,
+  adapter: string,
+  event: NormalizedEvent,
+  sink: EventSink,
+  teams: string[],
+  username: string | null,
+  reason: AccessFailedReason,
+  detail: string | undefined,
+  userNotFound: boolean,
+  fromClaim: boolean,
+): Promise<void> {
+  await fail(step, org, event, sink, teams, username, reason, detail)
+  if (!fromClaim) 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.
+    await recordClaimError(
+      step,
+      env,
+      adapter,
+      event.transaction_id,
+      `GitHub user "${username}" was not found - check the spelling and try again.`,
+    )
+    await guardRelease(step, env, adapter, event.transaction_id)
+  } else {
+    // Not correctable here → consume the token and lock the claim for good.
+    await consumeClaim(step, env, adapter, event.transaction_id)
+    await guardFinalize(step, env, adapter, event.transaction_id)
+  }
+}
+
+/** Release the single-flight lock (back to idle) so a corrected sequential resubmit can acquire. */
+async function guardRelease(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  adapter: string,
+  txn: string,
+): Promise<void> {
+  await step.do(`claim-guard-release:${adapter}:${txn}`, async () => {
+    await claimGuard(env, adapter, txn).release()
+    return true
+  })
+}
+
+/** Lock the claim terminally (granted/closed) so no further attempt can acquire. */
+async function guardFinalize(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  adapter: string,
+  txn: string,
+): Promise<void> {
+  await step.do(`claim-guard-finalize:${adapter}:${txn}`, async () => {
+    await claimGuard(env, adapter, txn).finalize()
+    return true
+  })
+}
+
+/** Delete the single-use claim token (+ reverse index) for this transaction, if one exists. */
+async function consumeClaim(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  adapter: string,
+  txn: string,
+): Promise<void> {
+  await step.do(`claim-consume:${adapter}:${txn}`, async () => {
+    const token = await env.ENTITLEMENTS.get(claimIndexKey(adapter, txn))
+    if (token) {
+      await env.ENTITLEMENTS.delete(claimKey(token))
+      await env.ENTITLEMENTS.delete(claimIndexKey(adapter, txn))
+    }
+    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,
+  env: CloudflareBindings,
+  adapter: string,
+  txn: string,
+  message: string,
+): Promise<void> {
+  await step.do(`claim-error:${adapter}:${txn}`, async () => {
+    const token = await env.ENTITLEMENTS.get(claimIndexKey(adapter, txn))
+    if (!token) return false
+    const claim = (await env.ENTITLEMENTS.get(
+      claimKey(token),
+      'json',
+    )) as Record<string, unknown> | null
+    if (!claim) return false
+    claim.last_error = message
+    // KV has no in-place update; re-put must restate the TTL. Preserve the ORIGINAL expiry anchored at
+    // creation - never reset to a fresh 30 days, or repeated failures would extend the
+    // token indefinitely. Floor at the KV minimum; fall back to a full window for legacy records.
+    const expiresAt =
+      typeof claim.expires_at === 'number' ? claim.expires_at : null
+    const ttl = expiresAt
+      ? Math.max(KV_MIN_TTL_SEC, expiresAt - Math.floor(Date.now() / 1000))
+      : CLAIM_TTL_SEC
+    await env.ENTITLEMENTS.put(claimKey(token), JSON.stringify(claim), {
+      expirationTtl: ttl,
+    })
+    return true
+  })
+}
+
+// --- revoke -----------------------------------------------------------------
+
+async function runRevoke(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  org: string,
+  adapter: string,
+  event: NormalizedEvent,
+  map: ProductTeamMap,
+  sink: EventSink,
+): Promise<void> {
+  // Read the grant record FIRST - it, not the event, is the authoritative source of which product was
+  // sold. Refund/adjustment events frequently lack a usable product_id (e.g. a Paddle adjustment
+  // references item_id, so product_id is ''), so resolving the revoke policy from the EVENT would fall
+  // through to `defaults` (log_only) and wrongly SKIP an auto_revoke product. Resolve the policy from
+  // the GRANT RECORD's product_id instead.
+  const record = (await step.do(
+    `grant-read:${adapter}:${event.transaction_id}`,
+    () => env.ENTITLEMENTS.get(grantKey(adapter, event.transaction_id), 'json'),
+  )) as GrantRecord | null
+
+  if (!record) {
+    // No grant record (refund events often lack github_username) → can't resolve teams. Warn and
+    // stop; reconciliation from buyer_email needs an email→login index we don't keep in v1.
+    log('warn', 'revoke: grant record absent', {
+      transaction_id: event.transaction_id,
+      has_buyer_email: Boolean(event.buyer_email), // never log raw PII
+    })
+    return
+  }
+
+  const config = resolveProductConfig(map, adapter, record.product_id)
+  const policy = config.revoke_policy ?? { mode: 'log_only' }
+
+  if (policy.mode !== 'auto_revoke') {
+    log('info', 'revoke skipped: log_only', {
+      transaction_id: event.transaction_id,
+    })
+    return
+  }
+  // Partial refund does NOT revoke; chargeback (is_full_refund null) always revokes.
+  if (
+    event.event_type === 'refund' &&
+    policy.full_refund_only &&
+    event.is_full_refund !== true
+  ) {
+    log('info', 'revoke skipped: partial refund', {
+      transaction_id: event.transaction_id,
+    })
+    return
+  }
+
+  const username = record.github_username
+  const teams = record.teams ?? []
+
+  for (const slug of teams) {
+    // DELETE is idempotent: 204 (removed) or 404 (already gone) both converge.
+    await ghStep(step, env, `team-del:${slug}:${username}`, (e) =>
+      github.removeTeamMembership(e, org, slug, username),
+    )
+  }
+
+  // Cancel any pending org invitation for this user.
+  const invites = await ghStep(step, env, 'invites-list', (e) =>
+    github.listInvitations(e, org),
+  )
+  if (Array.isArray(invites.json)) {
+    for (const invite of invites.json as Array<{
+      id?: number
+      login?: string
+    }>) {
+      if (invite.login === username && typeof invite.id === 'number') {
+        await ghStep(step, env, `invite-cancel:${invite.id}`, (e) =>
+          github.cancelInvitation(e, org, invite.id as number),
+        )
+      }
+    }
+  }
+
+  // Reconcile org membership against LIVE state: drop org membership only if the user is in no
+  // product team anymore (they may hold other entitlements). Never a KV scan.
+  let stillInATeam = false
+  for (const slug of collectAllTeams(map)) {
+    const m = await ghStep(step, env, `team-check:${slug}:${username}`, (e) =>
+      github.getTeamMembership(e, org, slug, username),
+    )
+    if (m.status === 200) {
+      stillInATeam = true
+      break
+    }
+  }
+  if (!stillInATeam) {
+    await ghStep(step, env, `org-del:${username}`, (e) =>
+      github.removeOrgMembership(e, org, username),
+    )
+  }
+
+  // Clean up KV: pending claim (if any) + the grant record.
+  await step.do(`cleanup:${adapter}:${event.transaction_id}`, async () => {
+    const token = await env.ENTITLEMENTS.get(
+      claimIndexKey(adapter, event.transaction_id),
+    )
+    if (token) {
+      await env.ENTITLEMENTS.delete(claimKey(token))
+      await env.ENTITLEMENTS.delete(
+        claimIndexKey(adapter, event.transaction_id),
+      )
+    }
+    await env.ENTITLEMENTS.delete(grantKey(adapter, event.transaction_id))
+    return true
+  })
+
+  await emitEvent(step, org, sink, 'access.revoked', event, {
+    github_username: username,
+    teams,
+    trigger: event.event_type,
+  })
+}
+
+// --- api_callback (fetch-in-workflow) ---------------------------------------
+
+type ApiCallbackResolution =
+  | { ok: true; event: NormalizedEvent }
+  | { ok: false; reason: AccessFailedReason; detail?: string }
+
+/**
+ * Resolve a `NormalizedEvent` for an api_callback ping by fetching the authoritative entity and
+ * parsing it - the never-trust-the-payload anchor. The fetch + parse run in ONE durable step so the
+ * opaque `VerifiedEntity` never has to cross the step boundary (it may not be JSON-serializable) and
+ * `parse` (pure) stays beside the fetch. A THROWN fetch error retries per FETCH_ENTITY_RETRY; a null
+ * entity (forged/unknown id) and a null/throwing parse (unhandled) are terminal.
+ */
+async function resolveApiCallbackEvent(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  adapterName: string,
+  adapters: PaymentAdapter[],
+  ping: ApiCallbackPing,
+): Promise<ApiCallbackResolution> {
+  const adapter = adapters.find((a) => a.name === adapterName)
+  if (!adapter || adapter.verification.kind !== 'api_callback') {
+    // Fail-closed: the deploy enqueued an api_callback ping but didn't pass this adapter to
+    // createAccessWorkflow(config, adapters). Terminal - never grant from an unverifiable ping.
+    return {
+      ok: false,
+      reason: 'unverifiable_adapter',
+      detail: `no api_callback adapter "${adapterName}" in the workflow's adapter set`,
+    }
+  }
+  const strategy = adapter.verification
+  // Minimal RawRequest from the enqueued ping. Headers are intentionally empty - the entity is
+  // fetched from the provider API, never derived from (untrusted) inbound headers.
+  const raw: RawRequest = {
+    bodyText: ping.bodyText,
+    bodyForm: new URLSearchParams(ping.form),
+    headers: new Headers(),
+  }
+  return step.do(
+    `fetch-entity:${adapterName}`,
+    FETCH_ENTITY_RETRY,
+    async () => {
+      // Reuse the engine's fetch + null-reject (the single audited "never trust the payload" point); it
+      // just runs here, inside a durable retriable step, instead of on the ack path. The opaque entity
+      // is consumed by parse() in THIS step, so it never crosses the step boundary (where it might not be
+      // JSON-serializable).
+      const verified = await verifyApiCallback(strategy, raw, env)
+      if (!verified.ok) {
+        return {
+          ok: false,
+          reason: 'fetch_failed',
+          detail: 'entity fetch failed or not found',
+        } as const
+      }
+      let parsed: NormalizedEvent | null
+      try {
+        parsed = adapter.parse(raw, verified.entity)
+      } catch (err) {
+        return {
+          ok: false,
+          reason: 'parse_failed',
+          detail: `parse error: ${String(err)}`,
+        } as const
+      }
+      if (!parsed) return { ok: false, reason: 'unhandled_event' } as const
+      return { ok: true, event: parsed } as const
+    },
+  )
+}
+
+/**
+ * Emit access.failed for an api_callback ping that never resolved to a real event (entity fetch
+ * failed/not found, or parse returned null). No NormalizedEvent exists, so synthesize a minimal one
+ * whose transaction_id is derived (deterministically) from the ping body for correlation.
+ */
+async function emitApiCallbackFailure(
+  step: WorkflowStep,
+  org: string,
+  sink: EventSink,
+  ping: ApiCallbackPing,
+  reason: AccessFailedReason,
+  detail?: string,
+): Promise<void> {
+  const digest = await sha256Hex(ping.bodyText)
+  const synthetic: NormalizedEvent = {
+    event_type: 'payment_success',
+    product_id: '',
+    transaction_id: `apicallback-${digest.slice(0, 32)}`,
+    buyer_email: null,
+    github_username: null,
+    is_full_refund: null,
+  }
+  // The wire envelope carries ONLY the coarse code; the raw detail stays in the log.
+  log('error', 'api_callback resolution failed', {
+    adapter_event: 'access.failed',
+    transaction_id: synthetic.transaction_id,
+    reason,
+    detail,
+  })
+  await emitEvent(step, org, sink, 'access.failed', synthetic, {
+    github_username: null,
+    teams: [],
+    status: 'failure',
+    reason,
+  })
+}
+
+// --- entrypoint -------------------------------------------------------------
+
+/**
+ * Grant vs revoke decided by `event.event_type`. Reconciliation-based: every step reads
+ * current GitHub state and converges, so duplicate/retried runs are no-ops. `appConfig` carries the
+ * deployment config (org + product map) - no longer read from env vars. `sink` is
+ * injectable for tests; production uses the signed-HTTP delivery sink (`createEventSink`).
+ *
+ * `adapters` is needed ONLY for api_callback pings (to run the in-workflow entity fetch + parse);
+ * hmac enqueues carry the already-parsed `event` and ignore it (default `[]`).
+ */
+export async function executeAccessWorkflow(
+  step: WorkflowStep,
+  env: CloudflareBindings,
+  appConfig: RepoAccessConfig,
+  params: AccessWorkflowParams,
+  sink: EventSink = logSink,
+  adapters: PaymentAdapter[] = [],
+): Promise<void> {
+  const { adapter } = params
+  const org = appConfig.githubOrg
+  const map = assertProductTeamMap(appConfig.productTeamMap)
+
+  // Resolve the NormalizedEvent. hmac path: parsed on the (fast) ack path → carried in params.event.
+  // api_callback path: fetch the authoritative entity + parse here, in a durable step (outbound I/O
+  // kept off the ack path; the ping body is never trusted).
+  let event: NormalizedEvent
+  if (params.ping) {
+    let resolution: ApiCallbackResolution
+    try {
+      resolution = await resolveApiCallbackEvent(
+        step,
+        env,
+        adapter,
+        adapters,
+        params.ping,
+      )
+    } catch (err) {
+      // Transient fetch retries exhausted (or unexpected throw). Emit access.failed, then re-throw to
+      // mark the instance failed for observability (mirrors the grant exhausted-retry path).
+      await emitApiCallbackFailure(
+        step,
+        org,
+        sink,
+        params.ping,
+        'fetch_failed',
+        `entity fetch error: ${String(err)}`,
+      )
+      throw err
+    }
+    if (!resolution.ok) {
+      // Clean terminal (forged/unknown id, or unhandled event) → access.failed, no retry storm.
+      await emitApiCallbackFailure(
+        step,
+        org,
+        sink,
+        params.ping,
+        resolution.reason,
+        resolution.detail,
+      )
+      return
+    }
+    event = resolution.event
+  } else if (params.event) {
+    event = params.event
+  } else {
+    log('error', 'workflow params missing both event and ping', { adapter })
+    return
+  }
+
+  const config = resolveProductConfig(map, adapter, event.product_id)
+
+  try {
+    if (event.event_type === 'payment_success') {
+      await runGrant(
+        step,
+        env,
+        org,
+        adapter,
+        event,
+        config,
+        sink,
+        Boolean(params.from_claim),
+      )
+    } else {
+      // runRevoke resolves its own product config from the grant record's product_id - the event's
+      // product_id is unreliable on refund/adjustment events (see runRevoke).
+      await runRevoke(step, env, org, adapter, event, map, sink)
+    }
+  } catch (err) {
+    log('error', 'workflow terminal failure', {
+      adapter,
+      transaction_id: event.transaction_id,
+      event_type: event.event_type,
+      error: String(err),
+    })
+    // Surface an access.failed for grants that died on an exhausted-retry / unexpected error. The wire
+    // reason is the coarse code; the raw String(err) detail is in the log line above.
+    if (event.event_type === 'payment_success') {
+      await emitEvent(step, org, sink, 'access.failed', event, {
+        github_username: event.github_username,
+        teams: config.teams ?? [],
+        status: 'failure',
+        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).
+      if (params.from_claim) {
+        await guardRelease(step, env, adapter, event.transaction_id)
+      }
+    }
+    throw err // mark the Workflow instance failed for observability (the event already fired)
+  }
+}
+
+/**
+ * Factory for the single static Workflow class, bound to a deployment `config`. The
+ * `AccessWorkflow` is instantiated by the Workers runtime - NOT by `createWorker` - so the
+ * `createWorker` closure can't reach it; the factory's closure is how config crosses that boundary.
+ * The user entry exports the result under the name wrangler's `class_name` expects:
+ *
+ *   const adapters = [stripe]
+ *   export class AccessWorkflow extends createAccessWorkflow(config, adapters) {}
+ *
+ * `extends <factory()>` (not a bare `const`) so the export is a class - a value AND a type - which
+ * `worker-configuration.d.ts` references as `import('./src/index').AccessWorkflow`.
+ * `run()` reads SECRETS from `this.env` (GITHUB_TOKEN, EVENT_WEBHOOK_SECRET) and everything else from
+ * the closed-over `config`. Grant/revoke are run params.
+ *
+ * `adapters` (additive 2nd param, default `[]`) is the SAME list passed to `createWorker` - the
+ * Workflow needs it ONLY to run an api_callback adapter's `fetchEntity` + `parse` in-step. A deploy
+ * with only hmac adapters can omit it; one composing an api_callback adapter MUST pass it, or
+ * api_callback pings fail closed (access.failed, no grant). Pre-0.2.0 signature change (intentional).
+ */
+export function createAccessWorkflow(
+  config: RepoAccessConfig,
+  adapters: PaymentAdapter[] = [],
+) {
+  return class extends WorkflowEntrypoint<
+    CloudflareBindings,
+    AccessWorkflowParams
+  > {
+    async run(
+      event: WorkflowEvent<AccessWorkflowParams>,
+      step: WorkflowStep,
+    ): Promise<void> {
+      // Production sink = structured log + signed HTTP delivery. Tests call executeAccessWorkflow
+      // directly with their own sink.
+      await executeAccessWorkflow(
+        step,
+        this.env,
+        config,
+        event.payload,
+        createEventSink(this.env, config),
+        adapters,
+      )
+    }
+  }
+}