repoaccess-core 0.2.0

package/docs/setup-guide.md

@@ -0,0 +1,422 @@
+---
+title: RepoAccess Worker - Setup Guide (for sellers)
+type: guide
+audience: buyers / OSS users deploying their own worker
+status: draft
+created: 2026-06-14
+note: >-
+  Draft of the customer-facing setup guide. Will become the OSS README / doc-site onboarding,
+  and is the seed corpus for the future support-agent (RAG). Generic - contains NO EdgeKits
+  secrets or account IDs. Re-verify each provider's dashboard steps at publish time.
+---
+
+# Deliver GitHub repo access on payment - setup guide
+
+This guide gets your **self-hosted RepoAccess Worker** live: a buyer pays through your payment
+provider, and they're automatically added to the right GitHub team (which carries access to your
+private repo). Runs on the **Cloudflare Workers free tier** - no server, no SaaS fees.
+
+**Target: ~10 minutes** once you have the accounts below.
+
+## Prerequisites
+
+- A **Cloudflare account** (free) + the `wrangler` CLI (`npm i -g wrangler`, then `wrangler login`).
+- A **GitHub organization** that owns the private repo(s) you sell.
+- An account with a **webhook-capable payment provider** (Stripe, Paddle, Gumroad, Lemon Squeezy, …).
+- Node.js + npm.
+
+---
+
+## Step 1 - Get the worker
+
+Install the core (or, for the Pro adapters, use your Pro build):
+
+```bash
+npm install repoaccess-core
+```
+
+Your entry composes the adapters you use and passes your typed config. It exports the three things the
+Cloudflare runtime needs - the worker (`fetch`), the Workflow class, and the claim-guard Durable Object:
+
+```ts
+// src/index.ts
+import { createWorker, createAccessWorkflow, ClaimGuard } from 'repoaccess-core'
+import { stripe } from 'repoaccess-core/adapters/stripe'
+import { config } from './repoaccess.config'
+
+// Pass the SAME adapter list to both: createWorker (verifies + acks the webhook) and
+// createAccessWorkflow (the Workflow that grants/revokes - and, for api_callback adapters, fetches
+// the authoritative entity). Keep the two lists identical.
+const adapters = [stripe]
+
+export default createWorker({ adapters, config })
+export class AccessWorkflow extends createAccessWorkflow(config, adapters) {}
+export { ClaimGuard }
+```
+
+Your settings live in a typed `repoaccess.config.ts` (Step 5) - no escaped-JSON env vars. Secrets stay
+in the runtime env (Step 6).
+
+## Step 2 - Cloudflare bindings
+
+In `wrangler.jsonc`: add a **Workflows** binding (`AccessWorkflow`), a **KV namespace**
+(`ENTITLEMENTS`), and a **Durable Object** binding (`CLAIM_GUARD`). There are **no `vars`** - your
+non-secret config lives in `repoaccess.config.ts` (Step 5), not in `wrangler.jsonc`. Create the KV
+namespace env-correctly:
+
+```bash
+# sandbox / dev  -> title <worker-name>-ENTITLEMENTS
+wrangler kv namespace create ENTITLEMENTS
+# production     -> title <worker-name>-production-ENTITLEMENTS
+wrangler kv namespace create ENTITLEMENTS --env production
+```
+
+The namespace **title** follows an env-aware convention derived from the worker name -
+`<worker-name>-ENTITLEMENTS` (sandbox) or `<worker-name>-production-ENTITLEMENTS` (production) - which is
+what `wrangler` produces when the create picks up the worker `name` and `--env`. The **binding stays
+`ENTITLEMENTS`** (the code reads `env.ENTITLEMENTS`; never rename the binding). Verify the created title
+carries the worker prefix - if it came out as a bare `ENTITLEMENTS`, the convention did not apply;
+recreate or rename it before wiring. Then paste the returned id into `wrangler.jsonc` for the matching
+env. (Workflows are available on the free plan.)
+
+> **The Workflow `name` must be unique per worker.** A Workflow `name` is account-global and belongs
+> to exactly one worker. If you run more than one RepoAccess worker on the same Cloudflare account
+> (e.g. a Pro worker alongside this one, or separate staging/production deploys), give each a
+> **distinct** workflow `name` - otherwise the later deploy silently reassigns the Workflow and breaks
+> the other worker's binding.
+
+## Step 3 - GitHub
+
+1. **Teams = product tiers.** In your org, create a team per tier (e.g. `pro`). Buyers get added here.
+2. **Attach your private repo(s) to the team** (Team → Repositories → Add). The team carries repo
+   access - the worker never adds direct collaborators.
+3. **⚠️ Set org Base permissions to `No permission`** (Org → Settings → Member privileges → Base
+   permissions). This is the setting that makes per-product isolation actually work. Base permissions are
+   the floor that **every** org member gets to **every** repo in the org. If it is `Read` (or higher) -
+   and on many orgs the default is `Read` - then any buyer of any product can see all your private repos,
+   and team scoping buys you nothing. With `No permission`, members get access **only** through their
+   team(s), so buying product A (team A → repo A) grants repo A alone and other products' repos stay
+   invisible. Keep the repos **private** (paid repos already are).
+4. **Fine-grained PAT** (Settings → Developer settings → Fine-grained tokens):
+   - Resource owner = **your org** (enable fine-grained PATs in Org → Settings → Personal access tokens first).
+   - Repository access = **none** (the token only manages membership).
+   - Organization permissions → **Members: Read and write** (and nothing else).
+   - This token → secret `GITHUB_TOKEN` (Step 6). Your org slug goes in `config.githubOrg` (Step 5).
+   - ⚠️ New orgs cap invitations at **50/24h for the first month** - age the org before a big launch.
+
+### Harden the org (members = paying customers)
+
+In this org, **"members" are buyers, not teammates** - treat them as untrusted and disable every member
+privilege. Access comes **only** through team membership. Org **Owners keep full access regardless** -
+these toggles restrict members, never you.
+
+**Org → Settings → Member privileges** (each block has its own Save):
+
+- **Base permissions → `No permission`** - the critical one (above).
+- **Repository creation** → uncheck **Public and Private** (members don't create repos).
+- **Repository forking** → off (no forking of private repos into member accounts).
+- **Projects base permissions** → `No access`.
+- **Pages creation** → uncheck **Public and Private**.
+- **App access requests** → `Disable app access requests`.
+- **GitHub Apps** ("Allow repository admins to install…") → off.
+- **Admin repository permissions** → off for all: **Repository visibility change** (else a member-admin
+  could flip a private paid repo to **public**), **Repository deletion and transfer**, **Issue deletion**,
+  **Branch renames**.
+- **Member team permissions → Team creation** → off.
+
+**Org → Settings → Authentication security:**
+
+- **Do NOT** "Require two-factor authentication for everyone" - it **removes** members without 2FA (your
+  buyers) and blocks them from accepting invites. Same goes for an IP allow list. Enable 2FA on your own
+  **owner** account instead.
+
+**Org → Settings → Third-party Access:**
+
+- **OAuth app policy** → keep **Access restricted** (approved apps only).
+- **Personal access tokens → Fine-grained tokens** → **Allow access via fine-grained PATs** (the worker's
+  `GITHUB_TOKEN` needs this; "Restrict" breaks grants). Optionally **Require administrator approval** for
+  members' tokens.
+- **Token expiry** → leave **"Fine-grained PATs must expire"** on (good hygiene) - which means the worker
+  token expires too; see rotation below.
+
+**Token rotation (operational).** The worker's `GITHUB_TOKEN` is a fine-grained PAT and **will expire**.
+Before it does: issue a new token with the same scope → update the `GITHUB_TOKEN` secret
+(`wrangler secret`) → re-approve it if approval is required. GitHub emails a warning before expiry; set a
+calendar reminder too. If it lapses, grants/revokes stop until you rotate.
+
+**Optional - Discussions as a feedback channel.** Enabling "Allow users with read access to create
+discussions" gives buyers a built-in Q&A/feedback space. Note: discussions in a **private** repo are
+visible to **everyone with access to that repo** (your other buyers) - a shared space, not private 1:1
+support.
+
+## Step 4 - Your payment provider
+
+The pattern is the same for every provider:
+
+1. **Create your product + price** in the provider's dashboard. Note the **product id**.
+2. **Create a webhook** pointing at your worker:
+   `https://<your-worker-url>/wh/<adapter>/<SECRET_PATH>`
+   - `<adapter>` = `stripe` / `paddle` / `gumroad` / … ; `<SECRET_PATH>` = a random string you choose
+     (`node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"`) - a hard-to-guess URL
+     segment for obscurity. It lives **only in this
+     webhook URL** (and your own notes) - it is **not** a worker secret: signature verification is the
+     real gate, so the worker doesn't validate the path. (Signature-less adapters like Gumroad are the
+     exception - there the path is a checked credential; see the per-adapter notes.)
+   - Subscribe only to the events your adapter needs (purchase + refund/chargeback). See the
+     per-adapter notes.
+3. **Copy the webhook signing secret** → `<ADAPTER>_WEBHOOK_SECRET`.
+
+Per-provider specifics (events, signature scheme, gotchas) are in the per-adapter reference. Quick
+examples:
+
+- **Stripe:** events `checkout.session.completed`, `charge.refunded`, `charge.dispute.created`;
+  signing secret `whsec_…`. (You can also test locally with the Stripe CLI.) Set
+  **`metadata.product_id`** (and, for username mode, **`metadata.github_username`**) on your Checkout
+  Session / Payment Link - Stripe's checkout webhook omits line items, so the worker reads the
+  product from metadata; if it's missing, the buyer falls through to your `defaults` mapping.
+  _No-code Payment Link:_ the link _builder_ has no metadata field, but the **created link's detail
+  page has an editable Metadata section** - add `product_id` there (Stripe copies a Payment Link's
+  metadata onto every Checkout Session it creates). One-time per link.
+- **Paddle:** events `transaction.completed`, `adjustment.created`, `adjustment.updated`; one-time
+  prices only (no subscription events); destination secret from the notification destination. **No
+  native buyer-input checkout field** - pass `github_username` as seller `customData` or use `claim`
+  mode (see Step 5).
+- **Lemon Squeezy:** events `order_created`, `order_refunded`; `X-Signature` HMAC-SHA256 over the raw
+  body (no timestamp); signing secret is one **you choose** when creating the webhook (6–40 chars).
+  **No native buyer-input checkout field** - pass `github_username` as seller `custom_data`
+  (`checkout[custom][github_username]=…`) or use `claim` mode (see Step 5). Chargebacks: LS's
+  `dispute_*` events are undocumented and not yet handled, so `auto_revoke` covers refunds only -
+  revoke a chargeback manually for now.
+- **Gumroad:** **no webhook signature at all** (ignore any `x-gumroad-signature` - it doesn't exist).
+  Here the **secret path segment IS a validated credential**, so it's a real secret
+  (`GUMROAD_WEBHOOK_PATH`), not just obscurity. Register `sale` / `refund` / `dispute` via
+  `PUT /v2/resource_subscriptions` pointed at `…/wh/gumroad/<path>`. The worker confirms every event by
+  calling `GET /v2/sales/{id}` with your **`GUMROAD_ACCESS_TOKEN`** - so that token is required too.
+  `github_username` via a Gumroad **custom field** the buyer fills at checkout (Gumroad has a native
+  buyer-input field), or use `claim` mode.
+
+## Step 5 - Configure (`repoaccess.config.ts`)
+
+All non-secret config is a **typed object** you author - full editor autocomplete, real comments, no
+escaped-JSON env vars:
+
+```ts
+// src/repoaccess.config.ts
+import type { RepoAccessConfig } from 'repoaccess-core'
+
+export const config: RepoAccessConfig = {
+  githubOrg: 'your-org',
+  productTeamMap: {
+    // adapter → product_id → mapping
+    stripe: { prod_ABC: { teams: ['pro'], grant_mode: 'username' } },
+    // reserved fallback for any unmapped product (keep it neutral - see the warning)
+    defaults: {
+      teams: [],
+      grant_mode: 'claim',
+      revoke_policy: { mode: 'log_only' },
+    },
+  },
+  branding: { name: 'Acme', logoUrl: '', faviconUrl: '' }, // optional - claim-page look
+  // eventWebhook: { url: "https://you.example/events", allowlist: ["you.example"] }, // optional
+}
+```
+
+- **`productTeamMap`** is keyed **adapter → product_id → mapping**. The adapter key (`stripe`,
+  `paddle`, …) is the adapter's `name` and matches its webhook route `/wh/<adapter>/…` - there's no
+  separate "which provider" switch.
+- **`grant_mode`:** `username` (use the buyer's GitHub username if your checkout collected it, else
+  falls back to `claim`) or `claim` (buyer enters their username on a claim page after paying).
+- **`revoke_policy`:** `{ mode: "auto_revoke" }` (remove access on refund/chargeback) or
+  `{ mode: "log_only" }`. **Auto-revoke horizon:** the worker keeps each grant record for **180 days**,
+  so `auto_revoke` covers refunds and card chargebacks within that window (a typical refund window plus
+  the ~120-day chargeback window). A dispute after 180 days won't auto-revoke - handle it manually.
+
+> **Chargebacks & disputes.** A chargeback (the buyer's bank reverses the charge, bypassing you) is
+> handled separately from a refund. Under `auto_revoke` the worker revokes access **when the dispute
+> is raised** - each adapter maps its provider's dispute-opened event to this (Stripe
+> `charge.dispute.created`, Paddle a `chargeback` adjustment, Razorpay `payment.dispute.created`),
+> while pre-dispute _early-warning_ signals are deliberately ignored. The worker **never auto-restores**
+> access if you later win the dispute - re-grant manually (Team → Members → **Add a member**, or
+> re-issue the claim link); it reconciles around manual changes. Per-provider event names and nuances
+> live in each provider's reference.
+
+> **Keep `defaults` empty / `log_only` unless you mean it.** Any product that isn't in the map - and
+> any stray webhook from an adapter you composed - falls through to `defaults`. Empty `defaults.teams`
+> is a safe no-op; a real team there becomes a **catch-all** that grants on anything. Only set a
+> non-empty `defaults` if you genuinely want a catch-all tier.
+
+### Sandbox vs production (optional)
+
+`env` isn't available at module load in Workers, so pick the profile **at build time**, not from a
+runtime var. Two clean options:
+
+- **Single env (simplest):** export one `config` and point both `createWorker` / `createAccessWorkflow`
+  at it (as in Step 1). Most deployers need only this.
+- **Sandbox/prod split:** export two profiles from `repoaccess.config.ts` (e.g. `sandbox` and
+  `production` sharing a base), add a second tiny entry `src/index.production.ts` that imports
+  `production`, and set `[env.production].main = "src/index.production.ts"` in `wrangler.jsonc`.
+  `wrangler deploy` then uses the sandbox profile; `wrangler deploy --env production` uses the prod one.
+
+### Collecting the buyer's GitHub username
+
+The buyer always supplies their own username - you never type it per-buyer. Two ways, matching the
+two `grant_mode`s:
+
+- **At checkout (`username` mode).** Add a **custom field** labelled e.g. "GitHub username" to your
+  checkout, so the buyer fills it in while paying. \*\*A native buyer-input field is provider-dependent
+  - check yours:\*\*
+  - _Stripe Payment Link / Checkout:_ Dashboard → your Payment Link → **Custom fields** → add a text
+    field (or set `custom_fields` when creating the Checkout Session). The worker reads it from the
+    `checkout.session.completed` event.
+  - _Gumroad:_ add a **custom field** to the product (Gumroad has a native buyer-input field) named
+    `github_username`; the worker reads it from the fetched sale entity.
+  - _Providers with no buyer-input field (e.g. Paddle, Lemon Squeezy):_ some hosted checkouts have
+    **no field the buyer can type into** - their "custom data" is **seller-passed**, meant for values
+    you already know before checkout, not buyer input. Paddle: `customData` via Paddle.js /
+    `data-custom-data` / the API. Lemon Squeezy: a `checkout[custom][github_username]=…` URL parameter
+    or the API. On these, either use **`claim` mode** (the natural fit), or collect the username on
+    **your own page before checkout** and pass it through as that seller-passed custom data.
+  - _Your own checkout page (any provider):_ collect the username yourself and pass it through as the
+    provider's custom-data/metadata field (Stripe `metadata.github_username`, Paddle `customData`,
+    LS `checkout[custom][github_username]`).
+- **After checkout (`claim` mode).** Collect nothing at checkout. The buyer receives a one-time claim
+  link after paying and enters their username on the claim page. Use this if you can't (or don't want
+  to) add a checkout field. `username` mode automatically falls back to `claim` when no username is
+  present.
+
+**What if the buyer mistypes it?** The worker never grants access directly - GitHub sends an
+**invitation that only the real owner of that account can accept**. A wrong or non-existent handle
+just means the invite is never accepted (the buyer contacts you to fix it); it can't silently let the
+wrong person in. There's deliberately **no "Login with GitHub"** step - the invite-acceptance is the
+ownership check, and the worker never phones home.
+
+## Step 6 - Secrets
+
+**Only secrets** go in the runtime env - everything non-secret is in `repoaccess.config.ts` (Step 5).
+Local dev → `.dev.vars`; production → `wrangler secret put <NAME>` (add `--env production` for a
+separate prod environment):
+
+```
+GITHUB_TOKEN              # the fine-grained PAT (Step 3)
+<ADAPTER>_WEBHOOK_SECRET  # the provider's signing secret (Step 4) - one per adapter
+EVENT_WEBHOOK_SECRET      # optional - signs outbound events (32-byte hex; same node one-liner with 32)
+```
+
+Not secrets, so **not** here (they're in `repoaccess.config.ts`): `githubOrg`, the product map,
+branding, and `eventWebhook` (url + allowlist). And `<ADAPTER>_WEBHOOK_PATH` isn't a secret either -
+your path segment lives in the webhook URL (Step 4), not the env (HMAC adapters don't validate it).
+Never commit `.dev.vars` (git-ignored by default).
+
+## Step 7 - Deploy
+
+```bash
+wrangler deploy --secrets-file .dev.vars
+```
+
+(`secrets.required` in `wrangler.jsonc` gates the deploy, so upload the secrets inline the first time.
+For a separate prod env: `wrangler deploy --env production --secrets-file .dev.vars.production`.)
+
+Take the resulting `https://<worker>.workers.dev` URL and make sure your provider's webhook points at
+`…/wh/<adapter>/<SECRET_PATH>`. (Optional: put it on a custom domain via `wrangler` routes.)
+
+## Step 8 - Test it
+
+Do a **sandbox/test purchase** in your provider. You should see:
+
+- the buyer added to the right team (username mode), **or** a `claim.pending` event with a claim
+  link (claim mode) → buyer opens it, enters their GitHub username, gets added;
+- a refund/chargeback (if `auto_revoke`) removes them and cancels any pending invite.
+
+`wrangler tail` shows structured logs of exactly what the worker did and why.
+
+## Troubleshooting
+
+- **Signature verification fails:** the worker must see the raw request body byte-for-byte. If you
+  proxy/transform requests, don't re-serialize the body before it reaches the worker.
+- **Buyer not added:** check `config.productTeamMap` has the exact provider `product_id`; check the
+  PAT has `Members: Read & write` on the org; check the team is attached to the repo.
+- **`429` from GitHub:** invitation rate limit - the worker backs off and retries automatically;
+  if you're launching, age the org first.
+- **Webhook never arrives:** verify the URL + secret path; re-send from the provider's dashboard
+  (the endpoint is idempotent - replays are safe).
+- **`wrangler tail` shows `Exception Thrown` / `Canceled` on a run that actually succeeded:** expected
+  Cloudflare Workflows behavior, not a failure. The durable engine surfaces step
+  suspension/checkpointing and instance lifecycle as `exception` / `Canceled` _outcomes_ in tail (and
+  batches a step's logs until the instance finishes), even when everything worked. Judge success by the
+  **instance Status** in the Workflows dashboard (`Completed` vs `Errored`) and by the **emitted
+  events** (`access.granted` / `access.revoked` / `claim.pending`; a real failure emits `access.failed`
+  and ends `Errored`) - not by raw tail exception lines.
+
+## A buyer says they didn't get access
+
+Most "I paid but I'm not in" tickets are an **unaccepted invite** or a **mistyped username** - both
+are quick to resolve. Work down this list.
+
+**First, tell the buyer to check for the invite.** Adding someone to a team sends a GitHub
+**invitation** they must accept - access isn't active until they do.
+
+1. Check email (incl. spam) for a GitHub invite to your org, **and** the dashboard:
+   `https://github.com/orgs/<your-org>` shows a pending-invitation banner; the org invite link is
+   `https://github.com/orgs/<your-org>/invitation`.
+2. Accept it → they land in the team that carries the repo. Done in the common case.
+
+**If there's no invite, diagnose on your side:**
+
+1. **Read the event / logs.** Your outbound events tell you exactly what happened:
+   `access.granted` (it worked - it's an unaccepted invite, see above), `access.failed` with a
+   `reason` (e.g. user not found, rate-limited), or `claim.pending` (claim mode - they never opened
+   the link). No event store? Run `wrangler tail` and replay the provider's webhook.
+2. **`access.failed → user not found`** = mistyped/non-existent username. Cancel any stale pending
+   invite (Org → People → **Pending invitations**), then re-collect: re-send the claim link, or just
+   invite them by hand (Team → Members → **Add a member**).
+3. **`access.failed → rate-limited` (`429`)** = new-org invite cap (50/24h in the first month). The
+   worker backs off and retries automatically - it'll land within the window. For a launch, age the
+   org first.
+4. **`claim.pending`, never completed** = the buyer didn't finish the claim page. Claim links are
+   **single-use and expire after 30 days** - re-issue a fresh link if theirs lapsed.
+5. **No event at all** = the webhook didn't arrive or didn't verify. Check the provider sent it
+   (re-send from its dashboard), the URL + secret path are right, and signature verification passed
+   (a transformed/re-serialized body breaks the HMAC - see above).
+
+**Fastest manual override (any case):** as an org owner, add them directly - Team → Members → **Add a
+member** → their GitHub username. The worker reconciles around manual changes, so this won't conflict
+with it.
+
+> **Why there's no "Login with GitHub":** the worker never logs the buyer in or phones home. The
+> GitHub invitation _is_ the identity check - only the real owner of an account can accept it - which
+> is why a wrong username is harmless (the invite simply sits unaccepted) and why fixing one is just
+> re-issuing the invite to the correct handle.
+
+---
+
+> _This is a draft. Final wording lives in the OSS README / doc-site; it also seeds the support
+> agent's knowledge base._
+
+<!--
+SUPPORT CATALOG - complete the exhaustive version at M2 (doc-site / README pass), grounded in
+as-built behavior. Accrue failure modes phase-by-phase as the build reports them; do NOT write the
+full catalog speculatively now. Categories to cover, each as symptom → cause → fix (seller + buyer
+wording):
+
+- Verification: signature fails (raw-body transformed, wrong secret, expired ts, clock skew);
+  per-provider quirks (Stripe v1 rotation, Paddle destination secret, form-urlencoded providers).
+- Mapping: product_id not in PRODUCT_TEAM_MAP → silent fall-through to defaults; price-id vs
+  product-id confusion; Stripe metadata.product_id unset.
+- Username: malformed handle; well-formed but non-existent (404 → access.failed); wrong-but-real
+  handle (invite unaccepted); already-an-org-member edge case.
+- Invitations: invite not accepted; invite expired; pending-invite cleanup; org membership vs team
+  membership.
+- Claim flow: link expired (30d) / already used / lost; claim.pending never completed; re-issue.
+- GitHub auth/permissions: PAT expired; fine-grained PAT not enabled at org; missing Members:R&W;
+  wrong GITHUB_ORG slug; team not attached to repo.
+- Rate limits: 50/24h new-org cap, 500/24h, secondary limits, 422 - durable backoff behavior.
+- Revoke: log_only vs auto_revoke; partial refund does NOT revoke; chargeback always revokes;
+  grant record missing → reconciliation fallback.
+- Webhooks/infra: wrong secret path; duplicate delivery (idempotent); KV/Workflows binding
+  misconfig; secrets not set in prod (wrangler secret put); custom domain/routes.
+- Outbound events: EVENT_WEBHOOK_URL unreachable/SSRF-blocked; signature on outbound; delivery
+  failure never blocks the grant.
+
+Cross-link each entry to the relevant docs/providers/*.md and PRD section. This block also seeds the
+support-agent RAG corpus.
+-->