A purchase is identified by an Ed25519 key pair that the app generates for it and does not use for any other purpose. Every request concerning the purchase, the redemption and each monthly renewal, is signed with this key, and the signature covers the request together with a value derived from the ratchet of that exchange, so it is valid for that exchange only and cannot be replayed. The agent verifies the signature and delivers the verified public key to the service with the request, and the service accepts a request about a purchase only when the verified key is the purchase key.
A badge is bought for one or more months, either on the web or in the app.
-On the web the purchase produces a code, which is then redeemed in the app. The code is the only data passed from the web site to the app: the web site does not learn which app redeems a code, and the app does not see the payment. The code is generated in the buyer's browser, and the service stores only its hash; at redemption the app presents the code itself, and the service matches it against the stored hash. A badge issued without a sale, for example in compensation for a problem, is a code generated by the operator and redeemed in the same way.
+On the web the purchase produces a code, which is then redeemed in the app. The code is the only data passed from the web site to the app: the web site does not learn which app redeems a code, and the app does not see the payment. The code is generated in the buyer's browser, and the service stores only its hash; at redemption the app presents the code itself, and the service matches it against the stored hash. A badge issued without a sale, for example in compensation for a problem, is a code generated by the operator, or by a moderator of the service's managed group, and redeemed in the same way.
In the app, the user pays by card, in cryptocurrency, or through the app store. The app requests an invoice from the service, or presents the receipt of the app store, and the service issues the credential once the payment is confirmed.
-In both cases the app generates the master key and the purchase key pair before the purchase. To redeem a code, the app sends the code and the master key to the service, which issues the credential. A code redeemed a second time with the same purchase key returns the same credential; a code redeemed with a different purchase key is refused.
+In both cases the app generates the master key and the purchase key pair before the purchase. To redeem a code, the app sends the code and the master key to the service, which issues the credential. A code redeemed a second time with the same purchase key returns its latest credential; a code redeemed with a different purchase key is refused once all its uses are taken.
A credential is issued for one month at a time, however many months were bought. The service keeps a count of the months remaining for each purchase key, and issues the next credential when the app asks for it. Unused months, e.g. if the app was offline, lapse at the next badge issuance.
Credentials are issued monthly to limit what the expiry date discloses. If credentials were issued for the whole term, a user who bought a year would hold a credential expiring on a day a year ahead, when few other credentials expire, and this date would be disclosed in every proof for a year. Instead, every credential is issued for one month, and its expiry is rounded to the end of the Monday following the end of the paid month (UTC). For example, if the paid month ends on Wednesday 14 October 2026, the credential expires at the end of Monday 19 October, and so does every credential whose month ends between Monday 12 and Sunday 18 October. All credentials whose paid month ends in the same week thus expire at the same instant.
@@ -1070,7 +1070,7 @@ window.addEventListener('click',(e)=>{cannot:
A member of the badge service's managed group
+can:
+cannot:
+A server operator
can:
Compromise of the user's device or backup
An attacker who obtains the credential and the purchase key can use the badge until it expires and renew it while months remain. There is no revocation, so the loss is limited to the months bought.
Interception of a code
-A code is a bearer secret until it is redeemed; once redeemed, it is refused to any other purchase key.
+A code is a bearer secret until its last use is taken; after that, it is refused to any other purchase key.
A passive network observer
can:
A timeout hides the outcome, so the client repeats the identical signed request at its next trigger, never on a poll timer.
getBadgeInvoice — returns the open invoice again; a new invoice is created only when none is open.redeemBadgeCode — a code already redeemed by the signing key returns the same badgeCredential and writes nothing; redeemed by another key, code_used. The client must therefore keep the key it first signed with, or a retry cannot be recognised.redeemBadgeCode — a code already redeemed by the signing key returns its latest badgeCredential and writes nothing; once other keys have taken all its uses, code_used. The client must therefore keep the key it first signed with, or a retry cannot be recognised.purchaseBadge — a payment already credited returns the same badgeCredential and writes nothing.upgradeBadgeSubscription — evidence already applied returns the same result and writes nothing.issueBadge — repeated within an issued period, returns the cached credential and writes nothing.getBadgeCatalog → badgeCatalog — the prices and offers; signed, also the purchase's badgeStatement. Store builds never send it: prices come from the store and SKUs from app config.getBadgeInvoice → badgeInvoice — prices the purchase for badgeInfo and paymentVia (card — Stripe; crypto — btc, xmr). The response holds the generic invoice — invoiceId, price, discount, the upgrade credit, amount = price − discount − credit, currency, expiresAt, and paymentTo (url for card; address and cryptoAmount for crypto) — beside the badge part, badgeType and months. priceId pins the price the client displayed; offerId selects a discounted duration, and its absence buys one month at that price. Price and offer status is checked here only: deprecated is still accepted, disabled is rejected; a badge type with no active price yields product_unavailable.redeemBadgeCode → badgeCredential — redeems a code, records the credit, and issues the first credential, in one round trip. It carries masterKey and code and no badgeRequest: a code states no tier and no expiry, so the credential is what reports them. Errors: code_invalid for an unknown or malformed code, code_used when another key redeemed it, code_expired past a redemption deadline.redeemBadgeCode → badgeCredential — redeems a code, records the credit, and issues the first credential, in one round trip. It carries masterKey and code and no badgeRequest: a code states no tier and no expiry, so the credential is what reports them. Errors: code_invalid for an unknown or malformed code, code_used when other keys have taken all its uses (a code has one use unless issued with more), code_expired past a redemption deadline.purchaseBadge → badgeCredential — verifies the funding (apple JWS offline; google token via the Publisher API; invoice against webhook-confirmed settlement, payment_pending until it lands; receipt), records the credit, and issues the first credential, in one round trip. The response receipt is the recovery bearer secret (model § recovery); the service stores its hash; lifetime badges receive none.
receipt is a transfer (post-MVP): the unissued months of the purchase that receipt belongs to move to the signing key, recorded as debit(transferOut) on the source and credit(transferIn) on the new purchase, and the presented receipt is retired for a fresh one. The transferred period's issuance debits a month like any other. Lifetime badges hold no receipt, so support handles them.balance — lastEntry, the client's last entry, asserting the position and the months it believes it holds.
An assertion that names an entry the service holds is a prefix: the service proceeds and returns what follows it. Otherwise the service heals its own ledger first — provider evidence for charges, time for lapses — proceeds, and returns either the complete history or one opening credit. An opening entry is an absolute restatement: the ledger is reset to the amount it states, without relation to the preceding entry, which also serves a new device and, later, the discarding of old history into a brought-forward balance.
retryAfter marks the transient codes: payment_pending, provider_unavailable, rate_limited. offer_disabled calls for a catalog refresh. code_invalid covers unknown, malformed and revoked codes alike, so a guesser learns nothing from the difference; code_used — redeemed under another key; code_expired — past its redemption deadline. receipt_invalid covers unknown receipts. All other codes are terminal for the attempted command.
retryAfter marks the transient codes: payment_pending, provider_unavailable, rate_limited. offer_disabled calls for a catalog refresh. code_invalid covers unknown, malformed and revoked codes alike, so a guesser learns nothing from the difference; code_used — all its uses taken by other keys; code_expired — past its redemption deadline. receipt_invalid covers unknown receipts. All other codes are terminal for the attempted command.