find the buyer by key or label, and refuse a tie (#10)

Stripe's API requires a key on every checkout custom field; Stripe's
dashboard never asks for one and never shows one, and it will not add a
field to a payment link that already exists. So the setup pages asked a
seller to type a key they cannot set, on a link they cannot edit. Their
field read to fulfillment as no field at all: paid orders skipped, a green
run, and a buyer with nothing. Stores this engine built are unaffected,
because init.js sets the key over the API.

Fulfillment now ranks three signals and never pools them: the exact key, the
key ignoring case and punctuation, then the label. Where several fields tie,
the shape of the value breaks it; where even that cannot, nothing is invited
and both keys are named, because an invitation to a private repo has no undo.
The needs-attention row now carries which of the three reasons applied.

Docs give the API call that adds the field to a link in use, with the URL
unchanged, and say plainly that the dashboard route only exists for a new
link, which gets a new URL.

Co-authored-by: Lucide <279298543+LucideLarp@users.noreply.github.com>

Author: LucideLarp

README.md

@@ -86,8 +86,8 @@ buyer ──▶ storefront (GitHub Pages, static)
                      ──▶ appends your (private) sales ledger
 ```
 
-The fulfillment path is two dependency-free Node files: a 397-line driver on a
-473-line pure logic core (which is why it can be unit-tested without a
+The fulfillment path is two dependency-free Node files: a 403-line driver on a
+593-line pure logic core (which is why it can be unit-tested without a
 network). Read both: [`scripts/fulfill.js`](scripts/fulfill.js)
 and [`scripts/lib/fulfill-core.js`](scripts/lib/fulfill-core.js).
 

docs/bring-your-own-store.md

@@ -58,20 +58,72 @@ and there is still no reason to publish your product mapping.
 ## The one change to your checkout
 
 Every module here ties a payment to a buyer through one fact: the GitHub
-username asked for at checkout. If your link does not ask for it yet, add it
-once, in the Stripe dashboard, under Payment Links, your link, Edit, Add custom
-field:
+username asked for at checkout. If your links already collect it, you are done,
+and the rest of this section is reference.
+
+What to add is a **required text field**, labelled
+
+> **GitHub username (for repo access)**
+
+Copy that label. Custom fields also carry a `key`, which is what an integration
+would normally match on, and on a link built in the dashboard the key is not
+yours: Stripe's API requires every custom field to have one, and the dashboard
+neither asks for a key nor shows you the one it stores. So the modules identify
+the field three ways, in order. The key `github_username` where you set it over
+the API. The same key through differences of case and punctuation. Otherwise the
+label, which is the only thing a dashboard-made field gives you to go on.
+
+Keep to one such field per link. Where two could each be the username, an order
+is resolved by the shape of what the buyer typed if that separates them, and
+stopped with both field keys named if it does not, because an invitation to a
+private repo cannot be taken back and a wrong one is worse than a late one.
+
+### Adding it to a link you already sell through
+
+**The dashboard cannot do this.** On a payment link that already exists, Edit is
+unavailable, so there is no clicking route to add a field to it. One API call
+does, and **the link URL is unchanged**, so nothing you have published goes
+stale and no buyer sees a difference:
+
+```bash
+curl https://api.stripe.com/v1/payment_links/plink_XXXXXXXXXXXXXXXXXXXXXX \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "custom_fields[0][key]=github_username" \
+  -d "custom_fields[0][type]=text" \
+  -d "custom_fields[0][label][type]=custom" \
+  -d "custom_fields[0][label][custom]=GitHub username (for repo access)"
+```
+
+Send every field the link should end up with, not only the new one: read what is
+already there with `GET /v1/payment_links/<id>` first.
+
+That call is a write, and it is the only write anywhere in this document. It
+needs a key with write access to Payment Links, which is not one of the scopes
+in the table further down, because no module here ever writes to Stripe. Do it
+once, then go back to the read-only key the tools run on.
+
+### Or start a new link
 
-- label: **GitHub username (for repo access)**
-- key: `github_username`
-- type: text, required
+Then the dashboard route works: Options, Add custom fields, Text, type the
+label, mark it required. It will not ask you for a key. What a new link does
+give you is a **new URL**, so anything already pointing at the old one has to be
+updated, which is the reason the API call above is the better move for a link
+already in use.
 
-The key is the load-bearing part. `github_username` is the exact string every
-module looks for (`reconcile/lib/reconcile-core.js`, `ops-bots/bots.js`), so a
-field with a different key reads as no field at all.
+### Knowing it worked, before a buyer tests it for you
+
+The doctor reads your links and says, per link, whether anything here could find
+a buyer on them and what it matched on:
+
+```
+[ OK ] stripe: plink_XXXXXXXXXXXXXXXXXXXXXX collects a GitHub username (matched on its label)
+```
 
-That is the whole migration. Two minutes, and **the link URL does not change**,
-so nothing you have already published goes stale and no buyer sees a difference.
+A link that collects nothing it can read is a `[FAIL]` with the fix attached,
+not a silent pass, and the audit makes the same judgement standing, across every
+active link in the account rather than only the ones your config names. That
+pairing is deliberate: a link nobody can deliver against is the one setup
+mistake that stays invisible until a stranger has already paid.
 
 ### The orders you took before the field existed
 
@@ -221,11 +273,11 @@ config  /tmp/acme-ops/store.config.json
          shipped defect: real bug, reproduced, no victim (2026-07-20)
          no force-push guard that misses the refspec form
 
-Live checks skipped (--static-only): payment-link coverage, forked-checkout
-detection, dead buy buttons, advertised-price drift, coupon exposure and
-invitation expiry all need read credentials. An entry above marked OK was
-judged on its static half only, and an entry with no live-checkable half
-is not listed at all.
+Live checks skipped (--static-only): payment-link coverage, unreadable
+checkouts, forked-checkout detection, dead buy buttons, advertised-price
+drift, coupon exposure and invitation expiry all need read credentials. An
+entry above marked OK was judged on its static half only, and an entry with
+no live-checkable half is not listed at all.
 
 10 entries checked: 0 exposed · 0 warn · 3 unchecked · 7 guarded
 

docs/failure-catalogue.md

@@ -25,8 +25,8 @@ This file is generated from `audit/lib/catalogue.js` (the same data the
 checks run against) by `node audit/audit.js --catalogue`. It is meant to be
 worth reading even if you never run the tool.
 
-**13 entries.** 5 are incidents that happened on this store's own
-infrastructure. 4 are real defects we shipped and caught by execution before
+**14 entries.** 5 are incidents that happened on this store's own
+infrastructure. 5 are real defects we shipped and caught by execution before
 a buyer hit them. 4 have never happened here and are labelled as such: they are
 guarded because the first occurrence would be unrecoverable and invisible.
 
@@ -72,8 +72,11 @@ GitHub expires an unaccepted repository invitation after 7 days. That is
 documented behaviour, not a secret: GitHub's changelog of 5 February 2020,
 "Self-expiring repository and organization invitations", says invitations to
 become a collaborator on a repository expire seven days after they are created.
-The REST API states no period of its own, so the engine also watches GitHub's
-`expired` flag rather than only the calendar. The non-obvious part is architectural:
+It is the only place GitHub says it. The REST API carries no period at all, so
+this check treats seven days as an assumption: it acts on GitHub's own `expired`
+flag, measures against a shorter window if an invitation on your store has
+actually died sooner, and says which of the two it used rather than presenting a
+deadline. The non-obvious part is architectural:
 NOTHING IN THE PIPELINE EVER REVISITS AN INVITATION IT SENT.
 
 The engine invites the buyer and writes the ledger row in the same breath.
@@ -116,6 +119,46 @@ CI.
 **Checked by:** `grant-shape` (static)  
 **Not checked:** None. Pure config shape, no credentials, runs on every push.
 
+## A checkout that collects nothing you can deliver against
+
+`unreadable-checkout` · shipped defect: real bug, reproduced, no victim · 2026-07-24
+· evidence: the exact-key lookup these modules shared (reconcile/lib/reconcile-core.js, ops-bots/bots.js), and the setup pages that asked a seller to type a key the dashboard does not offer (honorbox docs/setup.md, docs/bring-your-own-store.md)
+· cost: none here. Our own links are made over the API, which is the only route that can set a key at all
+
+Every module in this suite answers one question first: which GitHub account
+does this payment belong to? It reads that off a custom field on the
+checkout. Get that wrong and nothing downstream can be right, because there
+is no other thread from a payment to a person.
+
+The suite used to find that field by one exact key, `github_username`, and
+the setup instructions told you to type that key in when you added the field.
+Two facts make that instruction unfollowable. Stripe's API requires a unique
+`key` on every custom field, so a key always exists on the object. Stripe's
+DASHBOARD never asks for one and never shows one: the Add custom fields panel
+offers a field type, one "Label name" input and a few checkboxes, and no key
+appears afterwards on the field either. A seller who built their link by
+clicking cannot set the key, cannot read it, and cannot be told to use ours.
+
+Their field is therefore a field, on a working checkout, that every tool
+reads as no field at all. The buyer types their username. The money lands.
+The order is skipped, the run is green, and nobody is invited. It is the same
+silent shape as a payment link with no fulfillment row, arrived at by
+following the setup guide correctly.
+
+The fix has two halves and both are here. The modules now identify the field
+by its key OR by its label, and where more than one field could be it, they
+resolve by the shape of what the buyer typed and REFUSE where even that
+cannot separate them, because inviting a stranger to a private repo has no
+undo. This check is the other half: it reads your live links and tells you
+which ones nothing could deliver against, before a buyer finds out for you.
+
+Worth saying plainly: this did not cost us anything, because our own links
+are made over the API and carry the key explicitly. It would have cost the
+next person who set one up by hand, which is exactly who the suite is for.
+
+**Checked by:** `unreadable-checkout` (live)  
+**Not checked:** Needs a Stripe key to read your links. It judges the field DEFINITION, so it cannot tell you whether buyers are filling it in sensibly, only whether anything here could find it.
+
 ## A forked store still selling through the original author's checkout
 
 `foreign-checkout` · shipped defect: real bug, reproduced, no victim · 2026-07-19 / 2026-07-20
@@ -234,7 +277,7 @@ so buyers stop being delivered to. And the symptom is not an error, it is a
 cron that quietly stopped. Nothing in your store reports it. You find out
 from a customer.
 
-Fixed by sizing the cadence to the tier (17,47 = 1,488 min/month, 512 minutes
+Fixed by sizing the cadence to the tier (*/30 = 1,488 min/month, 512 minutes
 of headroom) rather than by rewording the pricing claim.
 
 Now the other half, because a catalogue that only frightens people is as

docs/least-privilege.md

@@ -3,7 +3,7 @@
 "You want my Stripe secret key in a GitHub Action?" No. HonorBox never
 needs your full secret key, and it never needs a broad GitHub token.
 Delivering a sale is two calls, both visible in
-[`scripts/fulfill.js`](../scripts/fulfill.js) (397 lines, read it):
+[`scripts/fulfill.js`](../scripts/fulfill.js) (403 lines, read it):
 
 | Call | Why | Secret |
 |---|---|---|

docs/pro-evidence.md

@@ -103,19 +103,19 @@ config  /tmp/widget-store/store.config.json
          shipped defect: real bug, reproduced, no victim (2026-07-20)
          no force-push guard that misses the refspec form
 
-Live checks skipped (--static-only): payment-link coverage, forked-checkout
-detection, dead buy buttons, advertised-price drift, coupon exposure and
-invitation expiry all need read credentials. An entry above marked OK was
-judged on its static half only, and an entry with no live-checkable half
-is not listed at all.
+Live checks skipped (--static-only): payment-link coverage, unreadable
+checkouts, forked-checkout detection, dead buy buttons, advertised-price
+drift, coupon exposure and invitation expiry all need read credentials. An
+entry above marked OK was judged on its static half only, and an entry with
+no live-checkable half is not listed at all.
 
 10 entries checked: 4 exposed · 0 warn · 0 unchecked · 6 guarded
 The 4 exposed hold 5 separate findings, each listed above with its fix.
 
 Each EXPOSED line above is a specific way this store loses a sale without
 telling you. They are listed with the fix; there is no score to improve.
 
-13 catalogue entries · 5 from incidents here, 4 from defects we shipped and caught, 4 guarded before they happened.
+14 catalogue entries · 5 from incidents here, 5 from defects we shipped and caught, 4 guarded before they happened.
 Known gaps we have NOT closed (1). Read audit/CATALOGUE.md:
   - A 200 that acknowledges dispatch, not delivery: A short secondary throttle is retried in-run (30s per wait, 60s per run, 3 attempts); anything longer, including a primary rate limit, is declined by design and falls to the scheduled poll, whose real recovery time is the next run that actually fires, measured here at up to 3h08m on a quiet private repo.
 ```
@@ -187,15 +187,15 @@ config  /tmp/widget-store/store.config.json
          shipped defect: real bug, reproduced, no victim (2026-07-20)
          no force-push guard that misses the refspec form
 
-Live checks skipped (--static-only): payment-link coverage, forked-checkout
-detection, dead buy buttons, advertised-price drift, coupon exposure and
-invitation expiry all need read credentials. An entry above marked OK was
-judged on its static half only, and an entry with no live-checkable half
-is not listed at all.
+Live checks skipped (--static-only): payment-link coverage, unreadable
+checkouts, forked-checkout detection, dead buy buttons, advertised-price
+drift, coupon exposure and invitation expiry all need read credentials. An
+entry above marked OK was judged on its static half only, and an entry with
+no live-checkable half is not listed at all.
 
 10 entries checked: 0 exposed · 0 warn · 0 unchecked · 10 guarded
 
-13 catalogue entries · 5 from incidents here, 4 from defects we shipped and caught, 4 guarded before they happened.
+14 catalogue entries · 5 from incidents here, 5 from defects we shipped and caught, 4 guarded before they happened.
 Known gaps we have NOT closed (1). Read audit/CATALOGUE.md:
   - A 200 that acknowledges dispatch, not delivery: A short secondary throttle is retried in-run (30s per wait, 60s per run, 3 attempts); anything longer, including a primary rate limit, is declined by design and falls to the scheduled poll, whose real recovery time is the next run that actually fires, measured here at up to 3h08m on a quiet private repo.
 ```

docs/setup.md

@@ -54,8 +54,39 @@ correctly-configured Payment Link, and wires `store.config.json` +
    [subscription enforcement](subscriptions.md). Delivery works either way, but
    without enforcement a cancellation does nothing and access stays forever.
 2. Create a **Payment Link** for that price:
-   - Add a **custom field**: label "GitHub username (for delivery)",
-     key `github_username`, type text, **required**.
+   - Add a **custom field**, type text, **required**, labelled exactly
+     **GitHub username (for repo access)**. Copy the label, because on a link
+     made in the dashboard the label is the only part you control: Stripe's API
+     requires every custom field to carry a `key`, and the dashboard neither
+     asks for one nor shows you the one it stores. Fulfillment handles both
+     cases. It matches the key `github_username` where the field was created
+     over the API (which is what `init.js` does), it matches that key through
+     differences of case and punctuation, and where the key is not one it
+     recognises it identifies the field by that label. Keep to one such field
+     per link: where two could each be the username, an order is resolved by
+     the shape of what the buyer typed if that separates them, and stopped for
+     a human if it does not, because an invitation to a private repo cannot be
+     taken back.
+
+     **Adding this field to a link that already exists is not a dashboard
+     job.** Once a link is created, Edit is unavailable on it, so there is no
+     dashboard route to add a field. One API call does it, and the link URL is
+     unchanged, so nothing you have already published goes stale:
+
+     ```bash
+     curl https://api.stripe.com/v1/payment_links/plink_YOURLINKID \
+       -u "$STRIPE_SECRET_KEY:" \
+       -d "custom_fields[0][key]=github_username" \
+       -d "custom_fields[0][type]=text" \
+       -d "custom_fields[0][label][type]=custom" \
+       -d "custom_fields[0][label][custom]=GitHub username (for repo access)"
+     ```
+
+     Send every field the link should end up with, not only the new one: read
+     what is already there with `GET /v1/payment_links/<id>` first. This is a
+     write, so it needs a key with write access to Payment Links. Fulfillment
+     itself never writes to Stripe, so go back to the read scopes in
+     [least-privilege.md](least-privilege.md) once the field exists.
    - After payment → show a confirmation message like: *"You're in. Your GitHub
      account will be invited to the private repo, usually within minutes and
      always within a few hours. Watch for the email from GitHub and accept the

pages/deliver-digital-products-github.md

@@ -53,8 +53,8 @@ something must read it and send the invite:
    MIT-licensed [HonorBox](https://github.com/Honorboxx/honorbox) engine
    does)*. A GitHub Action lists recent paid sessions and invites each
    buyer. No server, no webhook secret, delivery in minutes. The engine is
-   870 dependency-free lines you can read before trusting: a 397-line driver on
-   a 473-line pure core.
+   996 dependency-free lines you can read before trusting: a 403-line driver on
+   a 593-line pure core.
 3. **By hand.** Works for the first sales; does not survive a weekend away.
 
 Whichever you pick: make fulfillment **idempotent** (track processed session

pages/sell-code-without-a-marketplace.md

@@ -84,7 +84,7 @@ carrying the buyer's username. Something has to read it and send the invite:
 3. **A scheduled poll from CI** *(the section where we sell you something:
    this is what [HonorBox](https://github.com/Honorboxx/honorbox) does)*. A
    GitHub Action runs every few minutes, lists recent paid sessions, and
-   invites each buyer. The engine is MIT, 870 dependency-free lines of
+   invites each buyer. The engine is MIT, 996 dependency-free lines of
    Node you can read before trusting it. It also builds the storefront: a static
    site on GitHub Pages with your products, checkout buttons, and this same
    guide layout. Delivery lands in minutes rather than seconds; an opt-in

products/honorbox-pro.md

@@ -84,9 +84,10 @@ buyer to a private repo, with glue you wrote once and have not opened since.
 That is the setup this was built for, and you do not have to adopt the engine to
 put Pro on it. Write a minimal config naming the payment links and product repos
 you already have, and add one custom field to your payment link asking for the
-buyer's GitHub username: a two-minute edit in the Stripe dashboard, and the link
-URL does not change, so nothing you have already published goes stale and no
-buyer sees a difference. Reconcile, stats, the refund and dispute guards, the
+buyer's GitHub username. On a link you already sell through that is one API
+call, not a dashboard edit, because Stripe offers no way to edit a payment link
+once it exists. It takes a minute, and **the link URL does not change**, so
+nothing you have already published goes stale and no buyer sees a difference. Reconcile, stats, the refund and dispute guards, the
 store doctor and the suite's money-path checks then run in full against your
 setup as it stands.