badges: document multi-use codes and the group

docs/protocol/badges-overview.md

@@ -92,7 +92,7 @@ In SimpleX:
 
 - A badge does not restrict anything that is available today: the defaults are unchanged, and a badge only raises them.
 - A badge does not create an identity: it has no persistent identifier, it is not linked across conversations, and an incognito profile does not show it.
-- A badge cannot be transferred: a code can be redeemed once, and the credential obtained with it is usable only with the master key it was issued for.
+- A badge cannot be transferred: a code can be redeemed once for each use it was issued with (usually one), and the credential obtained with it is usable only with the master key it was issued for.
 - A badge does not exempt its holder from the limits a server applies: it lowers the cost of a resource without removing the limit on it.
 - A badge cannot be revoked; credentials are issued for one month at a time instead.
 
@@ -139,11 +139,11 @@ A purchase is identified by an Ed25519 key pair that the app generates for it an
 
 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.
 
 ### Monthly issuance
 
@@ -203,7 +203,7 @@ Service requests are protected by the double ratchet of the [SimpleX agent](http
 1. A proof discloses no value that links it to another proof or to the purchase.
 2. A proof used in one context, whether a session, a conversation or a file, cannot be used in another context.
 3. The timing of presentations does not identify the holder: all credentials expiring in the same week share the same expiry, and the renewal request and the profile update are made on different days.
-4. Requests to the badge service cannot be linked to each other, to a profile or to a network address, and a request about a purchase can be made only by the holder of the purchase key.
+4. Requests to the badge service cannot be linked to each other, to a profile or to a network address, other than the redemptions of one multi-use code and the codes issued in the service's managed group or redeemed by its members, and a request about a purchase can be made only by the holder of the purchase key.
 5. A credential cannot be forged: the issuer keys are fixed in apps and servers, and the app verifies a credential before storing it.
 6. A missing or failed proof leaves the default limit in place, and a server cannot be configured to grant a badge type less than the default.
 
@@ -217,10 +217,12 @@ This threat model assumes the [SimpleX network threat model](https://github.com/
 
 - See the purchase key of every badge, the master key generated for it, the number of months bought, and the payment record.
 - Issue any credential, or refuse to issue one, as it holds the issuer key.
+- Link a code issued in its managed group to the member who asked for it and to that group, as the group's messages, codes included, are kept in the service's chat database.
+- Link a redemption to a member of its managed group whose profile shows a new badge soon after it.
 
 *cannot:*
 
-- Connect a purchase with a profile, a contact, a group or a session with a server - a proof contains nothing that refers back to the purchase.
+- Connect a purchase with a profile, a contact, a group or a session with a server, other than a code issued in its managed group or redeemed by one of its members, as above - a proof contains nothing that refers back to the purchase.
 - Learn where a badge is shown or used.
 - Learn the network address of the app - requests reach the service through SMP servers, on connections created for the request.
 
@@ -236,6 +238,20 @@ This threat model assumes the [SimpleX network threat model](https://github.com/
 - Reuse a profile proof or a file proof in another context.
 - Distinguish the holder from the other supporters whose badges expire in the same week.
 
+**A member of the badge service's managed group**
+
+*can:*
+
+- Redeem any code issued in the group that is not revoked and has uses left, as every code is posted to the group.
+- See when each use of a multi-use code was redeemed.
+- Issue free codes of any type as a moderator or above, and revoke any code whose text they hold as an admin or above.
+- Become the group's owner by being the first to join it, before an owner is set up.
+- Guess who redeemed a code, when a member's profile shows a new badge soon after the code's message changes.
+
+*cannot:*
+
+- Redeem a revoked code, or a code with no uses left.
+
 **A server operator**
 
 *can:*
@@ -271,7 +287,7 @@ An attacker who obtains the credential and the purchase key can use the badge un
 
 **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**
 

docs/protocol/badges-rpc.md

@@ -19,7 +19,7 @@ A purchase record is created by `redeemBadgeCode`, by `getBadgeInvoice`, or by `
 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.
@@ -31,7 +31,7 @@ A timeout hides the outcome, so the client repeats the identical signed request
 
 - `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.
   - 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.
@@ -63,4 +63,4 @@ An assertion that names an entry the service holds is a prefix: the service proc
 
 ## Errors
 
-`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.