badges: document multi-use codes and the group

apps/simplex-badge-service/README.md

@@ -21,8 +21,10 @@ At this stage the service:
 
 - creates a double-ratchet contact address on first start (service RPC requires DR, see [`docs/protocol/badges-rpc.md`](../../docs/protocol/badges-rpc.md)),
 - listens for service requests (`CEvtServiceRequest`) on that address, rejects a request whose `purchaseKey` is not the key the agent verified the signature against, and answers `redeemBadgeCode`,
-- issues redemption codes, storing only their `SHA-256` and printing each code once,
-- does not accept contact requests unless `[dev] chat_redeem` is on: the address is for RPC only,
+- issues redemption codes, storing only their `SHA-256` in its code table,
+- does not accept contact requests: the address is for RPC only,
+- in service mode with `[group]` in the ini, manages one SimpleX group and serves `/issue`, `/bulk`
+  and `/revoke` in it (see [Issuing codes](#issuing-codes)),
 - in service mode with `--service-config`, also serves the built web app (`npm run build` in `web/`), `POST /api/invoice` and `GET /api/invoice/:id`, the BTCPay and Stripe webhook routes, and a payment poller, seeding its price/offer catalog on every start,
 - owns the `sx_badge_service_`-prefixed tables and its own migrations table (`sx_badge_service_migrations`).
 
@@ -47,8 +49,9 @@ simplex-badge-service --help
 - default (no `--run-cli`): background service mode, no interactive terminal.
 - `--run-cli`: interactive CLI that also processes service requests (mirrors
   `simplex-directory-service --run-cli`). This mode is the chat/RPC side and the `//` commands
-  below: it starts no web listener and no poller, and `[dev] chat_redeem` does not apply to it,
-  whatever `--service-config` says.
+  below: it starts no web listener and no poller, and serves no group commands, whatever
+  `--service-config` says. It still updates a code's group message when the code is redeemed or
+  revoked.
 - `--no-address`: skip address creation on start-up (for operators who provision the address themselves).
 The service cannot sign credentials without an issuer key and refuses to start without one:
 
@@ -92,7 +95,9 @@ Other options:
 
 `badge_service.ini` holds the listener bind address and `static_dir`, an optional
 `[btcpay]` section (omitting it disables Bitcoin and Monero), an optional `[stripe]`
-section (omitting it disables card payments) and the poll cadence.
+section (omitting it disables card payments), an optional `[group]` section (omitting it
+turns off the group's commands, though a group created earlier still has its code messages updated)
+and the poll cadence.
 `badge_service.ini.example` is the committed template; `badge_service.ini` itself is
 gitignored, since a real one holds API keys and webhook secrets.
 
@@ -199,27 +204,15 @@ the exception: each answers 200, 400 or 413 with an empty body, because its prov
 caller and nothing it could read would change what the route does. A wrong verb on any route, those
 two included, answers `method_not_allowed`.
 
-### Redeeming over chat, for local testing
-
-```ini
-[dev]
-chat_redeem = on
-```
-
-With this on, the service accepts contact requests and answers `/redeem <code>` from a contact
-with the credential as one-line JSON, ready to paste into a client as `/badge add <json>`. Off by
-default, and only `on`/`off` parse, so a typo cannot silently arm it. It applies to the service
-mode only; `--run-cli` ignores it.
-
-Keep it off anywhere real. The service RPC signs over a master key only the client holds; here
-there is no client key, so the service generates one and hands it over with the credential, which
-means it can link every badge it issues this way. `simplex-chat badge sign` has the same property
-and is the offline equivalent.
-
 ## Issuing codes
 
-Issuing a code is an operator command sent to the running service in `--run-cli` mode, not a way
-to start it — so codes are issued without a second process touching the service's database:
+Operators issue codes two ways: from the service's own command line in `--run-cli` mode, and from the
+managed group in service mode. Both are commands to a running process, so no second process
+touches the service's database.
+
+### From the command line
+
+The command is sent to the running service in `--run-cli` mode, not a way to start it:
 
 ```
 //issue <badge_type> [months] [paid|unpaid|free]
@@ -241,8 +234,75 @@ A code that leaked, or that was refunded, is withdrawn the same way:
 ```
 
 A revoked code answers redemption with `code_invalid`, as if it had never existed, so its holder
-learns nothing from trying. Revoking is not repeatable: the second attempt says so. A code that
-was already redeemed cannot be revoked: its badge was issued, and the command answers with an error.
+learns nothing from trying. A client that redeemed it before the revoke still gets its own badge
+back when it asks again. Revoking it again answers "already revoked" and fixes its group
+message if the first revoke didn't. A code with no uses left can't be revoked, because its badges
+were already given out, and the command answers with an error. A multi-use code with uses left can
+be revoked, which stops the uses that remain.
 
 Core parses `//...` into `CustomChatCommand` and leaves it to the service's `preCmdHook`, which is
 why issuing codes lives in the service rather than in core.
+
+### From the group
+
+With `[group]` in `badge_service.ini`, the service manages one group and serves three commands in
+it: `/issue <type> [months <M>] [uses <N>]` and `/bulk <type> [months <M>] count <B>` for moderators
+and above, `/revoke <code>` for admins and owners. `months` is 1 to 255, `uses` 1 to 1000 and
+`count` 1 to 100; a value outside these gets the usage reply. A member's role is checked as the
+service last saw it, so a command sent by a moderator just demoted or removed can still run if it
+reaches the service first; revoke any code the service posts for them after the change. `uses`
+above 1 makes a multi-use code, tracked by a group message counting what is left of it. Every reply carrying a code is read by every member,
+since the group has no private lane, so a code issued there is only as private as its least trusted
+member.
+Those replies are also kept as plain text in the service's chat database, so a copy of the database
+holds every code issued in the group. Keep the group's visible history off: with it on, each new
+member receives recent messages, and the codes in them, when they join. A multi-use code's message
+carries the code, and every redemption edits it or, after a day, posts it again; either way every
+current member receives it, so a member who joined after the code was issued gets the code while it
+still has uses left. A message replaced by a new post stays in the group with its old count. Keep
+disappearing messages off in the group and set no message TTL for the service's chats: a code's
+message that expires is treated as deleted and never posted again, so its counter and its "fully
+redeemed" notice stop.
+Every member can see when a multi-use code's message was edited, which is when each use was redeemed.
+`/revoke <code>` names the code in an ordinary group message, so every member holds it before the
+service reads the command, and the code stays redeemable until the service acts on it — for the
+whole of any downtime. Revoke a code that is not already public in the group, a refunded one above
+all, with `//revoke` in `--run-cli` mode. A `/revoke <code>` with nothing after the code, from a
+member below admin, is answered that the code was not revoked and is now visible to the group. A
+group command the service received but had not run when it stopped, or received while it ran in
+`--run-cli` mode, is dropped with no reply, so resend it, or use `//revoke`.
+
+The first member to join through the link is promoted to owner, so the operator joins before sharing
+it. Keep the service an owner too: below owner it cannot update the group's command menu, and below
+author it cannot post codes or replies. A failed promotion is logged at once, and an owner who left
+is logged at the next start or join. Then make the member you choose owner with the `/mr` command
+that the log line names, in `--run-cli` mode; the service never promotes anyone once the first
+promotion was attempted.
+
+The join link logged when the group is created stays valid: anyone who has it can join later, as a
+member, and read every code posted or edited from then on. That includes a removed member, who can
+rejoin through it, so removing a member does not stop them seeing new codes. Keep the log that holds
+it private. The link is also stored in the `group_link` column of `sx_badge_service_group`, where it
+can be read again.
+
+If an owner deletes the group, or removes the service from it, the service logs an error on start
+and stops serving the group. To create a new group, stop the service, delete the row, and start it
+again: with SQLite, run `DELETE FROM sx_badge_service_group;` on the `<prefix>_chat.db` file
+(`~/.simplex/simplex_badge_service_chat.db` by default), opened with `sqlcipher` and the database key
+if one is set; with PostgreSQL, run
+`DELETE FROM <schema-prefix>_chat_schema.sx_badge_service_group;` (`simplex_v1_chat_schema` by default).
+Multi-use codes issued in the old group stay redeemable, but their messages there are no longer
+updated, so revoke with `//revoke` any that should not stay live.
+
+The group is identified by the single `sx_badge_service_group` row. Rolling back past the
+`20260918_badge_group_ops` migration drops that table, so a later re-upgrade creates a second group
+and orphans the first one with its members and roles; multi-use codes come back single-use with
+their claims re-derived, and outstanding trackers come back unanchored. Redeemed credentials are
+preserved and no code becomes redeemable again, though while the old version runs, only the holder
+whose credential ends last gets it back on a retry, and any other holder of a multi-use code gets
+`code_used`; every holder of a revoked code gets `code_invalid`. Rolling back means re-creating and
+re-sharing the group; delete the orphaned one with `/d #'<old local name>'` in `--run-cli` mode, as its
+join link still works and its messages hold every code posted there.
+
+The configured `display_name` and `description` apply only to the group the service creates. Editing
+them later is logged as not applied and changes nothing.

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.