diff --git a/docs/protocol/badges-rpc.md b/docs/protocol/badges-rpc.md index 1581bcf2bd..ffe04298c3 100644 --- a/docs/protocol/badges-rpc.md +++ b/docs/protocol/badges-rpc.md @@ -27,18 +27,19 @@ A timeout hides the outcome, so the client repeats the identical signed request ## Commands -No command lets the client state what is signed. The tier is that of whatever funded the purchase, the expiry is the `sundayAfter` of the period issued (`endOfMondayAfter` in code), which every credential of that week shares, and `badgeExtra` is reserved and always empty. A client-proposed expiry, even one capped by the funded coverage, would fall off that shared boundary and mark its credential out of the week's anonymity set. `issueBadge` carries no `badgeRequest`: the tier, the master key and the expiry are all the service's own, so there is nothing for the client to state. `upgradeBadgeSubscription` still carries `badgeRequest` in the schema, and that shape is known to be wrong: the field must be dropped when the command is implemented, since it works on a purchase whose master key the service already holds and, like `issueBadge`, has nothing to state. +The client never states what is signed. The tier is that of whatever funded the purchase; the expiry is the `sundayAfter` of the period issued (`endOfMondayAfter` in code), shared by every credential of that week; `badgeExtra` is reserved and empty. A client-proposed expiry, even one capped by the funded coverage, would fall off that shared boundary and single its holder out of the week's anonymity set — so no command carries `badgeRequest`. `upgradeBadgeSubscription` still has the field in the schema; that is wrong and it must be dropped when the command is implemented. - `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. -- `purchaseBadge` → `badgeCredential` — verifies the funding (`apple` JWS offline; `google` product id and 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. It carries `masterKey` and no `badgeRequest`: the tier and months are those of the product the funding proves, and the expiry is the one every credential for that week shares, so the client has nothing to state. Errors: `receipt_invalid` for a receipt the store has refused for good, whether forged, malformed, another app's or refunded, and for a test purchase, which cost nothing; `receipt_used` when another key was credited with it; `product_unavailable` for a product that grants no badge; `payment_pending` while the store has not settled it and `provider_unavailable` while the store cannot be asked or has not answered about the purchase, both recording nothing; `provider_not_configured` when this deployment has no verifier for the store, recording nothing and terminal for the request, since retrying cannot deploy one. A receipt already credited to the signing key is answered from the service's record without asking the store. A store transaction is claimed by its own id, read from the evidence before verification, and credited only when the verified transaction carries the same id. The client does not finish the store transaction, and keeps the keys it signed with, on `product_unavailable` or `provider_not_configured`: the purchase is paid, and a product the service does not price or a store it cannot verify is its operator's error, so the transaction is presented again at the next trigger rather than retried now. The response `receipt` is the recovery bearer secret (model § recovery); the service stores its hash; lifetime badges receive none. - - A store verifier's answer falls in one of three classes, and the class decides what happens to a paid purchase. On `receipt_invalid` the client deletes the keys it signed with and finishes the store transaction — consumed on Play, finished on StoreKit — so a purchase answered `receipt_invalid` by mistake is lost to its buyer for good: the money has moved and nothing can present the transaction again. The opposite mistake costs one request at each of the client's own triggers, and Play refunds a purchase that is not acknowledged within three days. An answer that is not certainly in the first class is in the third. - - Terminal, `receipt_invalid`: the store has answered about this purchase, and the answer cannot change — an Apple signature that does not verify, a chain that does not lead to Apple's root, another app's bundle id, a test purchase (Apple's Sandbox, Play's `purchaseType` test), a revoked or refunded purchase, Play's `purchaseState` canceled. - - Pending, `payment_pending`: the store knows the purchase and it is not complete — Play's `purchaseState` pending. - - Unreachable, `provider_unavailable`: the store was not asked or has not answered about the purchase — network failures, timeouts, 5xx, quota, this service's own authentication or permission failures, and a 404 when reading the purchase (`purchases.products.get`, `purchases.subscriptionsv2.get`). Play may not yet know a token it has just issued, and no answer tells that apart from a token it never issued. Play is asked under this app's package name, so another app's token is treated the same way, and so is every other Play error response, a 400 or 410 that calls the token invalid included: only a purchase record Play returns is a verdict. A token outside the characters this service will put in a request to Play is not sent, and is answered in this class too: Play documents no grammar for a token, so the service's check is not Play's verdict. A product id outside the characters Play documents for one is `receipt_invalid`, since no product of this app can have it. - - Apple is verified offline, so it has no "not yet": a negative answer about the signed evidence itself is terminal. A failure of the verifier's own, such as a root certificate it could not load, is not Apple's answer: it is answered `internal`, on which the client keeps the purchase. Google is asked, so its silence and its 404 are not verdicts. - - A product this service does not price is not the store's refusal: the verifier vouches for the transaction, and the service answers `product_unavailable`, on which the client keeps the purchase. +- `purchaseBadge` → `badgeCredential` — verifies the funding (`apple` JWS offline; `google` product id and 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. It carries `masterKey` and no `badgeRequest`. The response `receipt` is the recovery bearer secret (model § recovery); the service stores its hash; lifetime badges receive none. + - A store transaction is claimed by its own id, read from the evidence before verification, and credited only when the verified transaction carries that same id. A receipt already credited to the signing key is answered from the record, without asking the store. + - Errors: `receipt_invalid`, `payment_pending`, `provider_unavailable` — see the classes below; `receipt_used` when another key was credited with it; `product_unavailable` for a product this service does not price; `provider_not_configured` when this deployment has no verifier for the store, terminal for the request since retrying cannot deploy one. `receipt_invalid` and `receipt_used` are the only answers on which the client drops the keys it signed with and finishes the store transaction. Every other answer records nothing and leaves the purchase with its keys, to be presented again at the next trigger. + - **What a verifier may answer.** On `receipt_invalid` the client deletes its keys and finishes the store transaction — consumed on Play, finished on StoreKit — so a mistaken `receipt_invalid` loses the buyer's money for good. The opposite mistake costs one request per client trigger, and Play refunds a purchase unacknowledged for three days. So an answer that is not certainly terminal is unreachable. + - **Terminal**, `receipt_invalid` — the store answered about this purchase and cannot change its mind: an Apple signature or certificate chain that does not verify, another app's bundle id, a test purchase (Apple Sandbox, Play `purchaseType` test), a refunded or revoked purchase, Play `purchaseState` canceled. + - **Pending**, `payment_pending` — Play `purchaseState` pending. + - **Unreachable**, `provider_unavailable` — the store was not asked or did not answer: network, timeout, 5xx, quota, this service's own auth or permission failures, and every Play error response, a 404 from `purchases.products.get` or `purchases.subscriptionsv2.get` and a 400 or 410 calling the token invalid included. Only a purchase record Play returns is a verdict: Play may not yet know a token it has just issued, and nothing tells that apart from one it never issued. A token outside the characters this service will send is not sent, and lands here too, since Play documents no token grammar and our check is not Play's verdict. A product id outside the characters Play does document is terminal, since no product of this app can have one. + - Apple is verified offline, so it has no "not yet" and a negative answer about the signed evidence is terminal. Two things are not the store's answer and leave the client holding the purchase: the verifier's own failure, such as a root certificate it could not load, which is `internal`; and a product this service does not price, which is `product_unavailable` — the verifier vouched for the transaction either way. - Funding by `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. - `upgradeBadgeSubscription` → `badgeCredential` — the app-led store subscription change, on the same key: verifies the store evidence of the replaced subscription and records the new plan; an immediate upgrade returns the new credential, a deferred change returns none. Its `badgeRequest` is to be dropped (see above). - `issueBadge` → `badgeCredential` — issues the next period from the balance, the only source of issuance. It carries `balance` alone: the credential is signed with the purchase's stored master key, for the type the balance funds, expiring at the `sundayAfter` of the period issued. The ledger is advanced first; the credential is signed before the `debit(badge)` and issuance rows are written, in one transaction. An exhausted balance yields no `credential`; the `statement` shows why. Issuing on a paused badge resumes it (model 2.13).