repoaccess-core 0.2.0

package/docs/setup-wizard.md

@@ -0,0 +1,339 @@
+# RepoAccess core setup wizard (shared orchestrator)
+
+This is the agent-agnostic setup orchestrator. Any coding agent runs it the same way: the Claude Code
+command (`.claude/commands/repoaccess-setup.md`) and the OpenCode command
+(`.opencode/command/repoaccess-setup.md`) are thin wrappers that point here, and any other agent
+(Codex, Cursor, ...) is told to open the repo and follow this file. This document is the single source
+of truth for the wizard; drive the deployer through it exactly as written.
+
+You are an interactive setup wizard. Your job is to hand-walk the person you are helping (the
+**deployer**) through standing up their own RepoAccess **core** worker and proving it works with a real
+test purchase. You orchestrate; you do not re-teach. The exact, validated procedures live in three
+shipped docs in this repo and they are the single source of truth. Read them and **drive** the deployer
+through them; never paraphrase or re-derive their steps (that causes drift).
+
+This is a deployer onboarding wizard, not a contributor guide. Do not explain the architecture, the
+adapter contract, or how to add a new adapter. (That is `AGENTS.md`, a different audience.) Stay on the
+one job: get this deployer to a working, live-tested worker.
+
+## Session rules (read first, apply for the whole run)
+
+These are hard rules. Internalize them before the role split and before you ask the mode question.
+
+1. **Assume a fresh, blank-slate, first-time setup.** Ignore ALL recalled memory, prior-run state,
+   saved deploy details, and "you've done this before" signals. They are noise from a re-used machine,
+   not this deployer's reality. Nothing is set up yet unless the deployer EXPLICITLY says otherwise.
+2. **Ask ONLY the one mode question** (sandbox/test vs production; recommend sandbox for a first run).
+   Do NOT detect or infer prior deploy state, and do NOT present any "production / re-run / re-test /
+   what now" menu. There is exactly one path: hand-hold a fresh setup of the chosen mode.
+3. **Do not deliberate aloud** about reusing or clobbering resources, "ephemeral-edit patterns", or
+   whether "resources still exist". Treat the cloud side as empty; create what the steps say to create.
+4. **Do not persist deployer-specific deploy details** (worker URL, org, team, product id, KV id) to
+   long-lived or project memory. Keep anything you track session-scoped only.
+5. **Tone: lead by the hand** - concise, action-oriented ("do X, then tell me"). First-time eyes; no
+   long internal-reasoning dumps, no gotcha questions.
+6. **Re-run is a separate, opt-in path.** ONLY if the deployer states up front "I already deployed
+   this, help me re-run" do you verify live state (probe `/health`, `wrangler kv namespace list`) and
+   reuse. NEVER infer a re-run from memory.
+
+Then confirm the environment as a plain guided step (not a gotcha): check Cloudflare auth with
+`wrangler whoami`; if the deployer is not logged in, have them run `wrangler login`, then continue.
+
+## Source docs (read these first, then drive them)
+
+- **`docs/agentic-setup-github-core-walkthrough.md`**: THE authority for the GitHub path AND the full
+  org-hardening checklist. Use it verbatim for every GitHub step and every hardening toggle. Do not
+  source the hardening list from anywhere else.
+- **`docs/agentic-setup-stripe-core-walkthrough.md`**: the Stripe path (product, payment link,
+  `metadata.product_id`, webhook, config, deploy, the test flows, gotchas) with the [USER]/[AGENT]/[SECRET]
+  role split.
+- **`docs/setup-guide.md`**: general reference only. Do NOT use it as the source for the hardening
+  checklist; the GitHub walkthrough owns that.
+
+Start by reading all three so you can drive accurately.
+
+## Role split (who does what, never blur this)
+
+- **[USER]**: every click in GitHub, Stripe, and the Cloudflare dashboard, plus accepting GitHub
+  invites. You cannot click these and you cannot mint a GitHub PAT. Give the deployer the exact menu
+  path and the exact value, then wait and read back the non-secret result.
+- **[AGENT] (you)**: you edit `src/repoaccess.config.ts`, `src/index.ts` / `src/index.production.ts`,
+  `wrangler.jsonc`, and the `.dev.vars` / `.dev.vars.production` **key names only**; you run
+  `wrangler kv namespace create`, `wrangler deploy`, `wrangler tail`; you check `/health`; and you read
+  the Workflow dashboard through the deployer.
+- **[SECRET]**: secret VALUES (the GitHub PAT `github_pat_…`, the Stripe signing secret `whsec_…`).
+  **Never read, request, echo, or write a secret value.** You COPY the placeholder template
+  (`.dev.vars.example` or `.dev.vars.production.example`) into the real secrets file; the **deployer**
+  replaces each `__REPLACE_ME__` with their own value, pasting it themselves. You only ever reference a
+  secret by its NAME. The real secrets file is HARD-WALLED from every tool you have (Read, Grep,
+  Test-Path all return permission denied) - that is a deliberate secret-safety boundary, working as
+  intended, not to be worked around. So you CANNOT check the file's contents and you must NOT ask the
+  deployer to grep or run any shell on it. You rely on the deployer's plain [USER] confirmation that the
+  placeholders are filled, and the real proof is the live grant test in Step 6.
+
+## The one question to ask up front
+
+Ask exactly one mode question before anything else:
+
+> **Production or sandbox/test?**
+
+It drives three things for the whole run; lock it in and stay consistent:
+
+|                        | sandbox/test                               | production                                                             |
+| ---------------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
+| entry / config profile | `src/index.ts` (`sandbox`)                 | `src/index.production.ts` (`production`)                               |
+| secrets template       | `.dev.vars.example`                        | `.dev.vars.production.example`                                         |
+| secrets file (real)    | `.dev.vars`                                | `.dev.vars.production`                                                 |
+| deploy command         | `wrangler deploy --secrets-file .dev.vars` | `wrangler deploy --env production --secrets-file .dev.vars.production` |
+| GitHub org             | your sandbox/test org                      | your real selling org                                                  |
+
+Do NOT ask anything about GitHub being automatic vs manual; the GitHub side is always fully guided
+[USER] (you cannot click GitHub). Recommend sandbox/test for a first run (Stripe Test mode, test cards,
+no live activation needed).
+
+## Step order (this is the validated order; follow it, do not run ahead)
+
+Work one block at a time. After each block, run the checkpoint and **do not advance until it passes**.
+
+### 0. Prep the secrets file ([AGENT])
+
+COPY (do not move) the matching placeholder template to the real secrets file so it exists before the
+deployer pastes their first secret. Keep the `.example` file in place as reference.
+
+- sandbox/test: copy `.dev.vars.example` → `.dev.vars`
+- production: copy `.dev.vars.production.example` → `.dev.vars.production`
+
+Both real files are gitignored, so they never get committed. The deployer fills the `__REPLACE_ME__`
+placeholders themselves as you reach each secret (the GitHub PAT in step 1, the Stripe secret in step 4).
+Once you copy the template you cannot inspect the real file again: it is secret-walled from every tool
+you have, by design. From here on you rely on the deployer's [USER] confirmation that each secret is
+filled, never on reading or grepping the file.
+
+### 1. GitHub side first (fully guided [USER])
+
+Drive `docs/agentic-setup-github-core-walkthrough.md` end to end, in its order:
+
+1. Create a **team per product tier** (org → Teams → New team). Read back the team name(s).
+2. **Attach the private repo(s)** to the team with `Read` (buyers clone, not push). Keep repos private.
+3. Set org **Base permissions = `No permission`** (org → Settings → Member privileges). This is the
+   isolation floor; without it, every buyer can see every private repo.
+4. **Harden the org**: present and verify the WHOLE checklist from the walkthrough's "Harden the org"
+   section, toggle by toggle: member repo/fork/Pages/Projects creation off, app access requests
+   disabled, GitHub Apps off, admin repository permissions all off (especially Repository visibility
+   change), team creation off; OAuth restricted; **fine-grained PATs allowed** (and optional admin
+   approval + expiry on); and **do NOT require org-wide 2FA** (it ejects your buyers). Confirm each.
+5. **Create the worker's fine-grained PAT** [USER]+[SECRET]: resource owner = the **org**, repository
+   access = **None**, organization permissions = **Members: Read and write** (nothing else), an
+   expiration date noted for rotation. Verify the resource owner and permission set with the deployer
+   **before** they generate it. Then have them replace the `GITHUB_TOKEN=__REPLACE_ME__` placeholder in
+   the real secrets file (from step 0) with the PAT, pasting it themselves. You never see it.
+
+**Checkpoint:** the team exists and carries the repo; Base permissions = No permission; the PAT's
+resource owner and permissions were confirmed before minting. Read back the two config values you wire
+next ONE AT A TIME, a separate prompt for each, never a combined list: first ask for the **org slug** and
+wait for the answer; THEN ask for the **team name(s)** (comma-separated if more than one). You will wire
+them into config next.
+
+### 2. Worker config ([AGENT], you do this)
+
+Edit `src/repoaccess.config.ts` (the profile for the chosen mode, `sandbox` or `production`):
+
+- `githubOrg` = the org slug read back in step 1.
+- `productTeamMap.stripe[<product_id>]` = `{ teams: [<team(s)>], grant_mode: 'username' | 'claim' }`.
+  The `<product_id>` comes from Stripe in step 4; until then, scaffold the shape and fill the id in once
+  you have it. Keep `defaults` neutral (`teams: []`, `grant_mode: 'claim'`, `revoke_policy` `log_only`)
+  so an unmapped product grants nothing.
+- The Stripe adapter is already composed in the entry (`const adapters = [stripe]`). Leave it.
+
+Provision KV and wire it. The namespace **title** follows an env-aware convention derived from the
+worker name (so it matches the rest of the platform and you can tell two deploys apart), while the
+**binding stays `ENTITLEMENTS`** (the code reads `env.ENTITLEMENTS` - never rename the binding):
+
+- sandbox/dev: `<worker-name>-ENTITLEMENTS`
+- production: `<worker-name>-production-ENTITLEMENTS`
+
+This is exactly what `wrangler` produces when the create picks up the worker `name` and `--env`. First
+check whether a namespace with the convention title for THIS worker+env already exists
+(`wrangler kv namespace list`); if one does, REUSE its id rather than creating a duplicate. Otherwise
+create it env-correctly:
+
+- sandbox/dev: `wrangler kv namespace create ENTITLEMENTS` → title `<worker-name>-ENTITLEMENTS`
+- production: `wrangler kv namespace create ENTITLEMENTS --env production` → title
+  `<worker-name>-production-ENTITLEMENTS`
+
+**VERIFY the resulting title** from the create output (or `wrangler kv namespace list`) matches
+`<worker>-ENTITLEMENTS` (sandbox) or `<worker>-production-ENTITLEMENTS` (production). If it came out as a
+BARE `ENTITLEMENTS` with no worker prefix, the convention did not apply - recreate or rename it to the
+convention before wiring. Then paste the **real** id into `wrangler.jsonc` (`kv_namespaces` for the
+matching env), replacing the `PLACEHOLDER_…` value. A placeholder id will not bind.
+
+(The Workflow `name` is already env-aware and reused idempotently - `oss-access-workflow` /
+`oss-access-workflow-production`. Leave it as is; no rename needed.)
+
+**Checkpoint:** `npm run typecheck` is clean (run `npm run typegen` first if you changed any binding).
+The KV id is real (not a placeholder) and its title matches the `<worker>[-production]-ENTITLEMENTS`
+convention.
+
+### 3. First deploy ([AGENT]), to learn the worker URL
+
+Deploy with the mode's secrets-file command from the table (sandbox
+`wrangler deploy --secrets-file .dev.vars`, production
+`wrangler deploy --env production --secrets-file .dev.vars.production`). Passing the secrets file lets
+Cloudflare's required-secret validation pass on this first deploy: `GITHUB_TOKEN` is already filled
+(step 1) and `STRIPE_WEBHOOK_SECRET` is still its `__REPLACE_ME__` placeholder, which counts as present
+(you replace it with the real value in step 4, then re-deploy in step 5). The first deploy creates the
+worker and prints its `https://<worker>.workers.dev` URL. Open `/health` and confirm `{"status":"ok"}`.
+
+**Checkpoint:** `/health` returns ok. Record the worker URL; Stripe's webhook endpoint needs it.
+
+### 4. Stripe side (guided [USER], with your [AGENT] config edits)
+
+Drive `docs/agentic-setup-stripe-core-walkthrough.md`:
+
+1. Create the **product** [USER] (**Product catalog -> Create product**, not the older "Products -> Add
+   product"); read back its **product id** (`prod_…`) and wire it into the `productTeamMap` you
+   scaffolded in step 2.
+2. Create a **Payment Link** [USER]; for `username` mode add the **Text custom field labelled "GitHub
+   username"** (the field key must contain "github"); for `claim` mode add no field.
+3. Set **`metadata.product_id`** on the link's detail page [USER] (the step people miss: the
+   `checkout.session.completed` webhook omits line items, so the worker reads the product from metadata).
+4. Create the **webhook destination** [USER]+[SECRET]. In Stripe's current Event destinations flow you
+   pick the EVENTS FIRST, then configure the destination (endpoint URL). Events: exactly
+   `checkout.session.completed` + `charge.refunded` + `charge.dispute.created`. Payload style: **Snapshot
+   if the option is shown** (the current flow may not surface it; if you do not see it, just continue).
+   Then configure the destination: have the deployer GENERATE the path tail `<SECRET_PATH>` with
+   `node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"`; the SAME value goes in BOTH
+   the worker route and the Stripe endpoint URL:
+   `https://<your-worker>.workers.dev/wh/stripe/<SECRET_PATH>`. It is obscurity only (NOT a worker secret;
+   the HMAC signature is the real gate, and the worker never reads the path), so it does not go in
+   `secrets.required` - but offer to keep it as a commented `STRIPE_WEBHOOK_PATH` line in the secrets file
+   (the `.example` has the slot) so the deployer does not lose it. The deployer reveals the signing secret
+   (`whsec_…`) and replaces the `STRIPE_WEBHOOK_SECRET=__REPLACE_ME__` placeholder in the real secrets
+   file with it, pasting it themselves.
+
+**Checkpoint:** product id wired into config; webhook endpoint URL matches the deployed worker URL plus
+the secret path. Then get ONE clean [USER] confirmation that the secrets are filled: ask the deployer to
+make sure both `GITHUB_TOKEN` (from step 1) and `STRIPE_WEBHOOK_SECRET` (from step 4) hold their real
+values so neither line still says `__REPLACE_ME__`, then reply "done". Say it plainly: "I can't read that
+file - it's secret-walled by design - so I'm trusting your confirmation." Do NOT ask them to grep or run
+any shell on the file, and do NOT claim to have verified it yourself. The real check is the live grant in
+Step 6 (a 401 there flags a missing or wrong `STRIPE_WEBHOOK_SECRET`).
+
+### 5. Re-deploy with the secret ([AGENT])
+
+Deploy with the mode's secrets-file command so the now-filled values upload with the code:
+
+- sandbox/test: `wrangler deploy --secrets-file .dev.vars`
+- production: `wrangler deploy --env production --secrets-file .dev.vars.production`
+
+**Checkpoint:** deploy succeeded. Cloudflare validates the required secrets are PRESENT before a deploy
+succeeds (`GITHUB_TOKEN`, `STRIPE_WEBHOOK_SECRET`), but presence is not correctness: a still-placeholder
+or wrong value deploys just fine, and `wrangler secret list` shows only secret NAMES, never whether a
+value is real or the `__REPLACE_ME__` placeholder, so neither can catch a bad secret. The REAL check is
+the live grant in Step 6: if `STRIPE_WEBHOOK_SECRET` is missing or wrong the webhook returns 401 there,
+which flags it cleanly. That retry is free (test mode + test card), and a 401 creates no GitHub invite, so
+it never touches the new-org 50-invite/24h cap.
+
+### 6. Test live (guided [USER] + you watch)
+
+Run `wrangler tail <worker-name>` (start it before paying) and walk the three flows from the Stripe
+walkthrough:
+
+1. **Grant**: pay with test card `4242 4242 4242 4242`. username mode: a real handle → direct grant,
+   `access.granted`. claim mode: `claim.pending`; the claim link is redacted from tail, so YOU fetch the
+   token directly from KV - PREFERRED:
+   `wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding ENTITLEMENTS` returns the token (the
+   `<transaction_id>` is the `pi_...` from the `claim.pending` event), then present the full clickable
+   `https://<worker>.workers.dev/claim/<token>`. FALLBACK (only if the KV read is unavailable): the
+   Workflow dashboard `emit:claim.pending` step output (`claim_url`). Do not ask the buyer to find or
+   assemble it, and do not dig through the dashboard when KV has it. Open it, enter the handle - the grant
+   then runs.
+   Now confirm the grant and move STRAIGHT to the accept step - do not visibly stall. Tail batches a
+   Workflow's logs until the instance settles, so `access.granted` can lag in the stream; do NOT narrate
+   "I don't see access.granted yet, let me check KV" and do NOT sit waiting on tail. Confirm the grant
+   directly from the KV grant record (`wrangler kv key get "grant:stripe:<transaction_id>" --binding
+ENTITLEMENTS` - a returned record means the grant succeeded), then immediately, as crisply as for a
+   direct grant, state this explicit [USER] step yourself: "GitHub has emailed you the invitation - open
+   it and accept it (or accept at `https://github.com/orgs/<org>/invitation`, substituting your real org).
+   Tell me once you have accepted." `access.granted` means the worker CREATED the invitation, not that the
+   buyer joined. WAIT for the deployer's confirmation, and only THEN verify Org → People membership.
+   **Hard rule:** do NOT poll the Workflow or Org → People for membership before you have given the
+   accept instruction - membership is gated on that human accept step, so checking first will hang (this
+   is exactly what went wrong in testing). `access.granted` is the Workflow success signal; the buyer
+   accepting the invite is a separate [USER] step that you must surface, never wait on silently.
+2. **Refund / revoke**: refund the Step-1 test payment in Stripe → `access.revoked`, buyer removed and
+   any pending invite cancelled. Do this BEFORE the typo test so revoke hits a single clean grant; the
+   Step-1 handle is then reusable on the claim page, and one GitHub account is enough for the whole run.
+3. **Typo path / claim fallback** (username mode): pay again with a valid-format-but-nonexistent handle;
+   it falls back to `claim.pending` (a typo never strands a paying buyer). As in the claim-mode branch,
+   YOU fetch the link from KV - PREFERRED:
+   `wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding ENTITLEMENTS` (the
+   `<transaction_id>` is the `pi_...` from `claim.pending`) returns the token, then present the full
+   clickable `https://<worker>.workers.dev/claim/<token>`; FALLBACK is the dashboard `emit:claim.pending`
+   step output (`claim_url`). Then open it and enter a real handle (the Step-1 handle is free now that the
+   refund revoked it). The claim-page grant creates a NEW invitation too, so do NOT end the flow at
+   `access.granted`: confirm the grant from the KV grant record
+   (`wrangler kv key get "grant:stripe:<transaction_id>" --binding ENTITLEMENTS`) rather than waiting on
+   batched tail, then give the SAME accept-the-invite [USER] instruction as the grant flow - "open the
+   GitHub email and accept it (or accept at `https://github.com/orgs/<org>/invitation`); tell me once you
+   have accepted" - and wait for confirmation BEFORE you verify membership.
+
+The order is the same and unmissable in both flows: **pay/submit → `access.granted` (invite created) →
+[USER] accept the email invite → verify membership**. You state the accept step yourself the moment
+`access.granted` appears; you never wait on Org → People membership without first telling the deployer to
+accept. Once the deployer confirms acceptance, verify in GitHub (Org → People) that the buyer landed in
+the right team and was removed on revoke.
+
+**Checkpoint (the whole-chain verification):** the first live grant shows `access.granted` in the
+Workflow run and the buyer is in the right team. This single live grant verifies the entire chain
+(GitHub PAT, hardening, config, webhook signature, deploy).
+
+## Gotchas (bake these in so you do not false-alarm the deployer)
+
+- **Benign tail noise:** "AccessWorkflow.run - Exception Thrown" / "Cancelled" in `wrangler tail` are
+  how Cloudflare Workflows logs durable step suspension; they appear on fully successful runs. Judge a
+  run by the Workflow dashboard **Status: Completed** plus the emitted `access.granted` / `access.revoked`
+  events, never by raw tail outcomes.
+- **Tail batches Workflow logs, so `access.granted` can lag.** A grant is not slow just because the
+  stream has not shown `access.granted` yet - tail flushes a Workflow's logs once the instance settles.
+  Confirm a grant straight from the KV grant record
+  (`wrangler kv key get "grant:stripe:<transaction_id>" --binding ENTITLEMENTS`, the `<transaction_id>`
+  is the `pi_...`) rather than waiting on the stream. Likewise fetch a claim token from KV
+  (`wrangler kv key get "claim_txn:stripe:<transaction_id>" --binding ENTITLEMENTS`) instead of the
+  dashboard.
+- **`transaction_id` = `payment_intent`** (`pi_…`), stable across the order and its refund/dispute. It
+  is what correlates a refund back to its grant; it is not the checkout session id.
+- **Stripe custom-field key must contain "github."** The label "GitHub username" auto-derives a key like
+  `githubusername`. If a valid handle still routes to a claim page, the key did not match; use
+  `metadata.github_username` instead.
+- **Real KV id + a per-account-unique Workflow name.** The KV namespace id in `wrangler.jsonc` must be
+  the real one from `wrangler kv namespace create` (a placeholder will not bind). The Workflow `name` is
+  account-global; if you run more than one RepoAccess worker on the account, each needs a distinct name
+  or a later deploy reassigns the workflow and breaks the other binding. (Core already carries an
+  `oss-` prefix for this reason.)
+- **New-org invite cap:** 50 invitations per 24h for the first month. Age the org before a big launch.
+- **Do not require org-wide 2FA**: it removes buyers without 2FA and blocks them from accepting invites.
+- **Owner PAT is immediate** even on approval-required orgs (a member's token would wait for approval).
+
+## Final readiness checklist (all green before you declare done)
+
+- [ ] GitHub: team(s) created and carrying the private repo(s) at `Read`.
+- [ ] GitHub: org Base permissions = `No permission`.
+- [ ] GitHub: full org hardening applied; org allows fine-grained PATs; org-wide 2FA NOT required.
+- [ ] GitHub: worker PAT minted (org owner, repo access None, Members Read and write) and pasted as
+      `GITHUB_TOKEN` by the deployer.
+- [ ] Worker: `githubOrg` + `productTeamMap` wired in the right config profile; real KV id in
+      `wrangler.jsonc`; `npm run typecheck` clean.
+- [ ] Stripe: product + payment link + `metadata.product_id` + webhook (3 events; Snapshot if shown);
+      `whsec_…` pasted as `STRIPE_WEBHOOK_SECRET` by the deployer.
+- [ ] Deploy succeeded; `/health` returns ok.
+- [ ] Live grant verified (`access.granted`, buyer in the right team); refund → revoke verified.
+
+When every box is green, the worker is live and proven. The deployer can now add more products by
+mapping each new Stripe product id to a team in `productTeamMap` and re-deploying.
+
+---
+
+Advanced (no wizard): you can also consume core as a dependency. `npm install repoaccess-core` and
+compose `createWorker({ adapters: [stripe], config })` in your own Worker. That path is text-docs only;
+see `docs/setup-guide.md` and the two walkthroughs above. This wizard targets the clone-and-run path.

package/docs/user-guide-stripe.md

@@ -0,0 +1,215 @@
+# RepoAccess - Stripe setup and test guide (Core)
+
+This is the **manual path**: set up and live-test a self-hosted RepoAccess **Core** worker with
+**Stripe**, by hand, end to end. It covers the same ground as the `/repoaccess-setup` wizard, for people
+who would rather do it themselves (or just want to understand each step).
+
+What you are building: a buyer pays through your Stripe checkout, and the worker automatically adds them
+to the GitHub team that carries your private repo. A refund or chargeback revokes that access. It runs
+as a single Cloudflare Worker on the free tier - no server, no SaaS subscription, no per-sale cut.
+
+Do a first run in **Stripe Test mode** with test cards. No live activation is needed to prove it works.
+
+## Before you start
+
+- A **Cloudflare account** (free) and the `wrangler` CLI: `npm i -g wrangler`, then `wrangler login`.
+- A **GitHub organization** you own. Personal accounts have no teams, so an org is required (a Free org
+  is fine). The private repo(s) you sell live in this org.
+- **Node** and **git**. Clone the repo and install dependencies:
+
+  ```bash
+  git clone https://github.com/EdgeKits/repoaccess-core.git
+  cd repoaccess-core
+  npm install
+  ```
+
+  `npm install` matters: the worker bundles a runtime dependency, so a deploy fails without it.
+
+The order below minimizes back-and-forth: GitHub first, then the worker config and a first deploy (to
+learn your worker URL), then Stripe (which needs that URL), then a re-deploy with the secret, then the
+live test.
+
+## 1. GitHub: org, team, and the worker token
+
+1. **Create a team per product tier** (Org, then Teams, then New team), named after the tier (e.g.
+   `pro`). The worker adds buyers to this team; the team carries the repo access.
+2. **Attach the private repo(s)** to the team (Team, then Repositories, then Add repository) with
+   **Read** (buyers clone, they do not push). Keep the repos private.
+3. **Set org Base permissions to `No permission`** (Org, then Settings, then Member privileges). This is
+   the isolation floor: without it, every member could see every private repo in the org, and team
+   scoping buys you nothing. With it, members get access only through their team(s).
+4. **Harden the org** - treat members as paying customers, not teammates (Org, then Settings, then
+   Member privileges; each block has its own Save):
+   - Repository creation: uncheck Public and Private. Repository forking: off. Projects base
+     permissions: No access. Pages creation: off. App access requests: disabled. GitHub Apps: off.
+   - Admin repository permissions: off for all, especially **Repository visibility change** (so a
+     member-admin cannot flip a paid private repo to public). Team creation: off.
+   - Authentication: do **NOT** require org-wide 2FA - it ejects buyers without 2FA and blocks them from
+     accepting invites. Enable 2FA on your own owner account instead.
+   - Third-party Access: keep OAuth apps restricted; **allow access via fine-grained PATs** (the worker
+     token needs this).
+5. **Create the worker's fine-grained PAT** (your account, then Settings, then Developer settings, then
+   Fine-grained tokens, then Generate new token):
+   - **Resource owner:** your **org** (not your personal account).
+   - **Repository access:** **None** (the token only manages membership; it never touches repos).
+   - **Organization permissions:** **Members: Read and write** (and nothing else).
+   - Pick an **expiration** and note it for rotation.
+   - Generate, then copy the token (`github_pat_...`). You will paste it into `.dev.vars` in Step 3. An
+     owner-created token is ready immediately even if the org requires token approval.
+
+## 2. Configure the worker
+
+Edit `src/repoaccess.config.ts` (the `sandbox` profile for a test run):
+
+```ts
+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' } },
+  },
+}
+```
+
+- `githubOrg` is your org slug (the `github.com/orgs/<slug>` value).
+- Map each Stripe **product id** (you get it in Step 4) to the team(s) that carry the repo.
+- `grant_mode`: **`username`** (the buyer types their GitHub handle at checkout; auto-falls back to a
+  claim link if the handle is missing, malformed, or does not exist) or **`claim`** (always send a
+  one-time claim link).
+- `revoke_policy`: `{ mode: 'auto_revoke' }` to remove access on refund/chargeback, or
+  `{ mode: 'log_only' }` to only log. Keep `defaults` neutral so an unmapped product grants nothing.
+
+Provision KV and wire it:
+
+```bash
+wrangler kv namespace create ENTITLEMENTS
+```
+
+Paste the **real** returned id into `wrangler.jsonc` (`kv_namespaces`), replacing the placeholder. If an
+`ENTITLEMENTS` namespace already exists, reuse its id rather than creating a duplicate. A placeholder id
+will not bind. Then confirm `npm run typecheck` is clean.
+
+## 3. First deploy (to learn your worker URL)
+
+Copy the secrets template and add your PAT:
+
+```bash
+cp .dev.vars.example .dev.vars
+```
+
+In `.dev.vars`, replace `GITHUB_TOKEN=__REPLACE_ME__` with your fine-grained PAT (paste it yourself).
+Leave `STRIPE_WEBHOOK_SECRET` as its placeholder for now - it counts as present for this first deploy.
+
+```bash
+wrangler deploy --secrets-file .dev.vars
+```
+
+The first deploy creates the worker and prints its `https://<worker>.workers.dev` URL - note it; Stripe
+needs it. Open `/health` and confirm `{"status":"ok"}`.
+
+## 4. Stripe: product, link, metadata, webhook
+
+1. **Create the product** (Product catalog, then Create product - this is the current label, not the
+   older "Products, then Add product"). Set a one-time price. Copy the **product id** (`prod_...`) and
+   wire it into `productTeamMap` from Step 2.
+2. **Create a Payment Link** (Payment Links, then New, then select your product). Leave the options off
+   (no managed payments, tax, address collection). For **`username` mode**, under Advanced options add a
+   **Text custom field labelled "GitHub username"** (the field key must contain "github"); for **`claim`
+   mode**, add no field. Copy the link URL.
+3. **Set `metadata.product_id` on the link** (open the link's detail page, then Metadata, then Edit
+   metadata; add key `product_id`, value `prod_...`). This is the step people miss: the
+   `checkout.session.completed` webhook omits line items, so the worker reads the product from metadata.
+4. **Create the webhook destination** (Developers, then Webhooks / Event destinations). The current flow
+   takes the **events first**, then the destination URL:
+   - **Events (select these three):** `checkout.session.completed`, `charge.refunded`,
+     `charge.dispute.created`.
+   - **Payload style:** pick **Snapshot** if the option appears; the current flow may not show it (it
+     defaults to the full snapshot payload).
+   - **Endpoint URL:** `https://<your-worker>.workers.dev/wh/stripe/<SECRET_PATH>`, where `<SECRET_PATH>`
+     is a random hard-to-guess string you generate:
+
+     ```bash
+     node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
+     ```
+
+     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
+
+In `.dev.vars`, replace `STRIPE_WEBHOOK_SECRET=__REPLACE_ME__` with the `whsec_...` value (paste it
+yourself), then re-deploy so the now-filled secret uploads with the code:
+
+```bash
+wrangler deploy --secrets-file .dev.vars
+```
+
+Confirm the Stripe endpoint URL matches your deployed worker URL plus the secret path.
+
+## 6. Test it live (in this order)
+
+Start streaming logs before you pay:
+
+```bash
+wrangler tail <worker-name>
+```
+
+Run the three flows **in this order** - refund before the typo test, so each test stays clean:
+
+1. **Grant.** Open the Payment Link and pay with test card `4242 4242 4242 4242` (any future expiry, any
+   CVC, any ZIP, any email). In `username` mode, type a real GitHub handle. Expect `POST /wh/stripe/...`,
+   then `checkout.session.completed`, then a direct grant with `access.granted`. **`access.granted` means
+   the worker created the GitHub invitation, not that the buyer joined.** GitHub emails the buyer the
+   invitation - **open it and accept** (or accept at `https://github.com/orgs/<org>/invitation`). Only
+   after accepting does the buyer show under Org, then People, in the right team.
+2. **Refund and revoke.** In Stripe, open Payments, open that test payment, then Refund payment (full
+   amount). Expect `charge.refunded`, then `access.revoked`, and the buyer removed from the team (any
+   pending invite cancelled). Doing the refund **before** the typo test means revoke runs against a
+   single clean grant, and the same handle is free to reuse on the claim page next - so one GitHub
+   account is enough for the whole run.
+3. **Typo path and claim fallback** (`username` mode). Pay again, this time typing a
+   valid-format-but-nonexistent handle (e.g. `someone-nope-xyz`). Expect a team-add 404, then NOT
+   `access.failed` but a `grant -> claim fallback`, then `claim.pending`. The claim link is redacted from
+   `wrangler tail`; find it in the **Workflow dashboard** (Cloudflare, then Workflows, then your
+   workflow, then the run, then the `emit:claim.pending` step output, which carries `claim_url`). Open
+   `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.
+
+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
+by the Workflow dashboard **Status: Completed** plus the emitted `access.granted` / `access.revoked`, not
+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
+
+- **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
+  `wrangler deploy --env production --secrets-file .dev.vars.production`. Stripe stays the same flow in
+  live mode.
+- **Token rotation:** the fine-grained PAT expires (the org caps its lifetime). Before it lapses, issue a
+  new token with the same scope (org owner, repository access None, Members Read and write) and update
+  the `GITHUB_TOKEN` secret, then re-deploy. If it lapses, grants and revokes stop until you rotate.
+
+## Troubleshooting
+
+- **Grant fails 401 / 403:** the PAT is missing Members Read and write, or fine-grained PATs are
+  restricted at the org, or the token is pending approval or expired.
+- **Grant fails 404 (user not found):** the GitHub username does not exist - a buyer typo, not a token
+  problem. In `username` mode the buyer automatically gets a claim link to self-correct.
+- **A valid handle still routes to the claim page:** the custom-field key did not contain "github". Use
+  `metadata.github_username` on the checkout instead.
+- **Buyer paid but is not in the repo:** the invite is created right after payment and the buyer must
+  **accept** it (via the GitHub email). Confirm the sale and `access.granted` in the Workflow run; if
+  those are there, you are waiting on the buyer to accept.
+- **New-org invite cap:** 50 invitations per 24h for the first month - age the org before a big launch.
+
+---
+
+RepoAccess is part of [EdgeKits](https://edgekits.dev). For the guided path, run `/repoaccess-setup` in
+Claude Code instead (see the README).

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "repoaccess-core",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapters/stripe": "./src/adapters/stripe.ts"
+  },
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy --minify",
+    "typegen": "wrangler types --env-interface CloudflareBindings",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "hono": "^4.12.25"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.16.15",
+    "@types/node": "^25.9.3",
+    "prettier": "^3.8.4",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.104.0"
+  }
+}