@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,1125 @@
-# Temporary Holding Version
+# @shuttle.technology/authorization
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client of a person's session for web and mobile apps. With this one
+package and the public configuration the operator gives you, your app runs the
+whole user side: the person signs in on the provider's hosted page, creates a
+wallet, connects it to your service, sets its limits, sends from it, lets your
+backend forward the transfers it signs (Mode C) or debit the wallet without the
+device, as a card is charged, and withdraws your service's access again.
+
+The app never holds a service key, a Wallet credential or an identity
+provider's credentials. Access tokens stay in memory; on the web the refresh
+lives in the provider's HTTP-only cookie, on mobile in the secure storage the
+app supplies. Your backend reads the wallets people connect to it with its own
+Tenant Access key; that side is not part of this package.
+
+## Install
+
+```sh
+npm install @shuttle.technology/authorization@0.2.0
+```
+
+It is ES modules with TypeScript declarations and no runtime dependencies. It
+needs `fetch` and WebCrypto: a current browser, Node 20 or later, or a mobile
+runtime that provides both (`examples/mobile` shows React Native).
+
+| Import | What it holds |
+|---|---|
+| `@shuttle.technology/authorization` | `initializeAuthorizationClient`, the client, errors and their table |
+| `@shuttle.technology/authorization/device-key` | `generateDeviceKey`: the device key a wallet's share is sealed to, for an app that keeps its own share |
+| `@shuttle.technology/authorization/device-share` | `resealDeviceShare`: the app's own share resealed for one transfer |
+| `@shuttle.technology/authorization/mode-c-linked` | Mode C on a person's wallet: enrollment and signed requests |
+| `@shuttle.technology/authorization/linked-wallets` | the linked-wallet reads and sends, also reachable as `client.linkedWallets()` |
+| `@shuttle.technology/authorization/debit-permissions` | the permissions a service debits a wallet by, also reachable as `client.linkedWallets().debitPermissions()` |
+| `@shuttle.technology/authorization/streams` | the Streams reads, also reachable as `client.streams()` |
+| `@shuttle.technology/authorization/mode-c` | Mode C on a wallet bound in the provider |
+
+## Configure
+
+The operator registers your app as a public client and gives you:
+
+- `publishableClientId`, `tenantId`, `applicationId`, `environmentId`;
+- the exact HTTPS origins and redirects registered for it (web), or the app
+  link redirect and the app's bundle or package identifier (mobile);
+- the sign-in methods the hosted page offers for it;
+- the `service_principal_id` of your backend's service and the name people
+  see for it on the provider's pages;
+- the API address, `authorizationOrigin`.
+
+Keep the API address in your configuration, not in code. Today it is
+`https://demo.shuttle.technology`; after the address move it becomes
+`https://api.shuttle.technology`, and only that value changes.
+
+```ts
+import { initializeAuthorizationClient } from "@shuttle.technology/authorization";
+
+const client = await initializeAuthorizationClient({
+  mode: "mode_b",
+  channel: "web",
+  authorizationOrigin: config.apiOrigin,             // "https://demo.shuttle.technology"
+  publishableClientId: config.publishableClientId,
+  tenantId: config.tenantId,
+  applicationId: config.applicationId,
+  environmentId: config.environmentId,
+  methods: ["google", "telegram", "passkey"],        // exactly the client's registered methods
+}, { currentOrigin: () => location.origin, openHosted });
+```
+
+On the web, `applicationOrigin` and `redirectUri` may be left out: they are
+then the current page's origin and the current page, so the page that starts a
+sign-in also completes it. Give them to pin another return page. Both may be
+https on any host or http on `localhost`, `127.0.0.1` or `[::1]`. A mobile app
+gives `redirectUri`.
+
+Initialization checks the configuration, then reads
+`GET /v1/public/clients/{id}` and refuses a client whose environment, methods,
+provider origin, redirect or platform differ (`invalid_public_configuration`).
+It creates no session.
+
+### The hosted window
+
+Every step the person takes on the provider's pages (sign-in, a passkey, a
+confirmation) goes through `openHosted(url)`. It must open a separate
+top-level browsing context, such as a popup, never a frame, and resolve with
+the registered redirect URL the window came back to. Your callback page hands
+that URL to the opener on the same origin and does nothing else:
+
+```html
+<!-- https://app.example.com/auth/callback -->
+<script>
+  new BroadcastChannel("auth").postMessage({ url: location.href });
+  history.replaceState(null, "", location.pathname);
+</script>
+```
+
+```ts
+let popup: Window | null = null;
+let lastCallback = "";
+const channel = new BroadcastChannel("auth");
+
+// Open the window inside the click handler, before anything is awaited.
+function openWindow() { popup = window.open("about:blank", "auth", "popup,width=520,height=760"); }
+
+function openHosted(url: string): Promise<string> {
+  return new Promise((resolve) => {
+    channel.onmessage = ({ data }) => { lastCallback = data.url; resolve(data.url); };
+    popup!.location.href = url;
+  });
+}
+```
+
+`demo/app.js` is a complete host: one window for every step, a timeout, a
+closed window, refusals the provider shows in the window, and the quiet
+session renewal of `demo/renew.js`. Mobile apps supply a
+`MobileBrowserBridge` instead (see "Mobile apps" below).
+
+### Confirming an operation
+
+Giving or withdrawing a grant, changing limits, enrolling a Mode C key and
+giving or ending a debit permission are operations the person confirms with a passkey on the provider's page, which
+says what the operation does and for whom. Each takes the same four calls:
+
+```ts
+import type { LocalOperation } from "@shuttle.technology/authorization";
+
+async function confirmAndExecute(operation: LocalOperation) {
+  await client.challengeOperation(operation.id, credentialId);   // opens the provider's page
+  const confirmed = await client.completeOperationConfirmation(lastCallback);
+  if (confirmed.state !== "authorized") throw new Error("not confirmed");
+  const executed = await client.executeOperation(confirmed.id, confirmed.version, crypto.randomUUID());
+  return client.operationResult(executed.id);                    // { result: { kind, targetId, newVersion, state } }
+}
+```
+
+`credentialId` is the person's passkey: `client.identities()` names it for an
+identity of method `passkey`, and `completePasskeyBootstrap()` returns it for a
+new one. The SDK confirms and executes on its own one operation only, the
+recovery of a wallet's device share onto this device (see "The device share"
+below), always through the provider's page and the person's passkey; it
+never retries a write.
+
+Every write takes an `Idempotency-Key`: make one per action the person asked
+for and reuse it only to repeat that same request.
+
+## The user side, step by step
+
+### 1. Sign in
+
+```ts
+openWindow();
+await client.login();                     // or signup() for a new account
+const session = await client.exchangeHandoff(lastCallback);
+```
+
+`login()` and `signup()` open the provider's hosted sign-in page
+(`/v1/auth/start`), which names your app and offers its methods: Google,
+Telegram and passkey, as registered. A first sign-in with an unknown Google or
+Telegram identity creates the account, without a wallet; accounts are never
+merged by email. The browser comes back to your redirect with a one-use `code`
+and the `state` only; `exchangeHandoff` exchanges the code with the S256
+verifier it keeps in memory and refuses any other redirect. No token is ever
+in a URL.
+
+On page load, `refreshSession()` takes up a session the provider's cookie
+still holds, with no window (`POST /v1/auth/renew`, "Background renewal"
+below); when it throws `web_renewal_requires_navigation`, the app starts
+`restoreSession()`, the provider's top-level restore, from the person's click,
+or signs the person in again where the restore cannot see the cookie (an app
+on a site of its own). `demo/renew.js`, on the provider's site, runs the
+restore quietly. The access token lives five minutes; the SDK renews it in
+the background when it needs to. `logout()`
+clears the session locally and asks the provider to end it: it resolves with
+`serverDisposition` `server_revoked` when the provider ended it, or
+`server_unconfirmed` when that could not be confirmed, in which case the
+provider's session may live on until it expires.
+
+`login(method)` and `signup(method)` still start one method directly
+(`POST /v1/auth/attempts`); their redirect back also names `attempt_id`.
+
+### 2. Who is signed in: `me()`
+
+```ts
+const me = await client.me();
+// me.account: { accountId, version, setupRequired }, me.sessionId, me.serverTime
+// me.wallets: [{ walletId, kind: "wallet" | "linked_wallet", network, address, state }]
+```
+
+`me()` reads `GET /v1/me`, the live check of the session. `wallets` is every
+wallet of the account: `kind` is `wallet` for a wallet the provider holds for
+the account and `linked_wallet` for one the person created through this SDK,
+`walletId` an identifier of that kind, `state` `active` or `disabled` (a
+listed linked wallet is active). Own wallets come first, then linked ones, at
+most 1000 of each; an account with more is refused with
+`ADAPTER_INTEGRITY_CONFLICT`, never listed in part. A revoked or expired
+session answers `UNAUTHORIZED`. The answer is read strictly: an SDK older
+than the server's `wallets` refuses it.
+
+Your backend learns who the user is from the access token. `accessToken()`
+returns it, renewed first when it has less than 30 seconds to live; send it
+to your own backend in the `Authorization` header of each call:
+
+```ts
+const response = await fetch("https://backend.example.com/orders", {
+  headers: { Authorization: `Bearer ${await client.accessToken()}` },
+});
+```
+
+The token lives only in the SDK's memory: never store it (no
+`localStorage`, no cookie of yours) and never put it in a URL. Your backend
+verifies it against `/.well-known/jwks.json` on the API address (identity and
+expiry), or calls `GET /v1/me` with it (live state). Neither is consent to any
+wallet operation. Without a session `accessToken()` refuses with
+`session_unavailable`; a renewal that fails refuses as `restoreSession()`
+does. A signal passed to it ends only that caller's wait: callers share one
+renewal, which no caller's signal stops. The same holds for the signal of
+`exchangeHandoff()`, `logout()`, `refreshSession()` and `restoreSession()`:
+what the call already set going (installing or clearing the credentials)
+still completes. A web restore, which holds a window, stops only once every
+caller waiting for it aborted; its host then closes the window, and a call
+made after that starts afresh rather than joining it. A sign-in installs only if no newer sign-in or logout began
+since it started. A renewal or restore installs only while the session it
+renews is still the one installed: a sign-in that installed meanwhile, a
+logout or a definitive refusal ends that. A renewal of the installed session
+while a sign-in is still pending does install, and the sign-in replaces it
+when it completes. Once the provider refuses the session for good (`UNAUTHORIZED` from
+a renewal, or from a read the SDK already renewed the token for), the SDK
+forgets it (unless a newer sign-in replaced that session meanwhile),
+`hasSession` turns false and every call that needs the session,
+`accessToken()` included, refuses with `session_unavailable` until the person
+signs in again; a failure that passes, such as `DEPENDENCY_UNAVAILABLE`, keeps
+the session, but a token a read was refused with is handed out no more: the
+next call renews first, and refuses while the renewal fails. A write the
+provider refuses `UNAUTHORIZED` ends the session it was made with the same
+way, and is never repeated. On mobile the secure storage writes of
+renewals, sign-ins and logouts go one after another: a write that a newer
+sign-in or a logout overtook is taken back, and a stored token that was
+refused or logged out but could not be deleted is never sent again.
+
+### 3. The first wallet
+
+A passkey is needed before the first wallet. A new account has
+`setupRequired`:
+
+```ts
+if (me.account.setupRequired) {
+  await client.bootstrapPasskey();                       // the provider's passkey page
+  credentialId = (await client.completePasskeyBootstrap(lastCallback)).credentialId;
+}
+```
+
+Then the wallet, confirmed with that passkey:
+
+```ts
+// The SDK makes the device key (non-extractable P-256) and keeps the share.
+let operation = await client.createWallet({ network: "ethereum" }, crypto.randomUUID());
+await client.challengeWalletOperation(operation.id, credentialId);
+operation = await client.completeWalletOperationConfirmation(lastCallback);
+operation = await client.executeWalletOperation(operation.id, operation.version, crypto.randomUUID());
+while (!["succeeded", "failed", "denied", "canceled", "expired"].includes(operation.state)) {
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+  operation = await client.walletOperation(operation.id);
+}
+const { result } = await client.walletOperationResult(operation.id);
+if (!result.wallet) throw new Error("the wallet was not created");
+const created = result.wallet;                           // the SDK has kept its device share
+```
+
+The share arrives sealed to the device key; the provider never opens it and
+gives the result only to the account that created the wallet. No service can
+read the result, export, recover or re-own a person's wallet
+(`RECOVERY_UNAVAILABLE`). The SDK keeps the key handle and the sealed share
+together in the origin's IndexedDB (on mobile in the `deviceShares` store the
+app supplies, see "The device share" below), so the app stores nothing.
+`createWallet()` with the app's own `recipientPublicKey` still works: the app
+then keeps the share itself and passes it to every send.
+
+The wallet then appears among the account's linked wallets:
+
+```ts
+const linked = client.linkedWallets();
+await linked.refresh();                                  // binds the account's Wallet identity
+const wallet = (await linked.list()).items.find((item) => item.address === created.address);
+// wallet.id is the linkedWalletId every later step names
+```
+
+#### Create and connect in one confirmation
+
+`createWallet()` can open the new wallet to your service in the same passkey
+confirmation, so the person confirms once instead of twice (creation, then
+step 4). The provider's page names the service and what it will see
+("Создать кошелёк <сеть> и открыть его сервису <name>: кошелёк и баланс,
+операции, события"):
+
+```ts
+let operation = await client.createWallet({
+  network: "ethereum",
+  grant: { servicePrincipalId: config.servicePrincipalId, scopes: ["wallet:read", "operation:read", "streams:read"], externalRef: yourUserId },
+}, crypto.randomUUID());
+// challengeWalletOperation, completeWalletOperationConfirmation, executeWalletOperation and the wait, as above
+const { result } = await client.walletOperationResult(operation.id);
+switch (result.grant?.state) {
+  case "succeeded": break;                               // your backend reads the wallet now
+  case "pending_target_fence":                           // a first streams:read grant waits for Streams
+    // read client.operation(result.grant.operationId!) until it is no longer pending_target_fence
+    break;
+  case "not_set":                                        // result.grant.code says why; the wallet exists all the same
+    if (result.grant.code === "DEPENDENCY_UNAVAILABLE") { /* read the result again */ }
+    else { /* step 4: createServiceGrant() alone, with its own passkey confirmation */ }
+}
+```
+
+The grant follows the rules of step 4 and is checked before anything is
+confirmed: an unknown service is `NOT_FOUND`, a scope it does not hold
+`SCOPE_DENIED`, an inactive service `AUTHORIZATION_STALE`, a server that
+cannot promise the grant `CAPABILITY_UNAVAILABLE`, and a malformed grant
+(no scope, an unknown or repeated one, a long `externalRef`) is refused
+locally with `invalid_operation_create`. The SDK sends the scopes in the
+provider's order and checks that the operation's display names the grant
+back (`display.grant`). Reading the result is what sets the grant, for the
+session that confirmed the creation and within an hour of it: a result read
+later or from another session answers `not_set` with `AUTHORIZATION_STALE` or
+`OPERATION_EXPIRED`. `result.grant.linkedWalletId` is the wallet's linked
+wallet ID.
+
+**Debits come with the grant.** When your service holds the platform scope
+`wallet:debit:user`, the same creation passkey also creates your service's
+debit permission on the new wallet (step 8): wallet, grant and debit
+permission in one confirmation. There is no parameter for it: the ceilings
+are your service's setting on the platform, set by the operator, the same for
+every person, and the person sees them on the confirmation page before
+confirming (per asset the most one debit and 24 hours may move, and the
+recipients). `display.debit` names them. Once `walletOperationResult()` reads
+the result, the SDK executes the permission the consent authorized with the
+device share it keeps, sealed to the platform share keeper's key, without
+another passkey:
+
+```ts
+const { result } = await client.walletOperationResult(operation.id);
+// present when your service holds wallet:debit:user:
+// result.debit: { state: "succeeded", operationId } — operationId is the debit permission's ID
+//            or { state: "not_set", operationId?, code } — AUTHORIZATION_STALE, OPERATION_EXPIRED, DEPENDENCY_UNAVAILABLE, …
+```
+
+Without the scope there is no permission, and a later one costs the person
+another passkey (step 8, `createDebitPermission()`). The SDK must keep the
+device share for this (no `recipientPublicKey` of your own); a result read
+from another session, or more than an hour after the confirmation, says
+`not_set`.
+
+### 4. Connect the wallet to your service
+
+```ts
+const connect = await client.createServiceGrant({
+  walletId: wallet.id,
+  servicePrincipalId: config.servicePrincipalId,
+  enabled: true,
+  scopes: ["wallet:read", "operation:read", "streams:read"],
+  externalRef: yourUserId,                               // optional, opaque, at most 128 printable ASCII
+}, crypto.randomUUID());
+await confirmAndExecute(connect);                        // result.kind "service_grant", state "active"
+```
+
+A creation that named the grant (above) skips this step. The provider's page
+names your service and what it gets; the person confirms with the passkey.
+When your service holds `wallet:debit:user`, the page also names its debit
+ceilings and the same passkey creates its debit permission on the wallet:
+`client.operationResult(connect.id)` settles it as for a creation, and its
+`result.debit` says `succeeded` or `not_set` with `code`. Withdrawing the
+grant (step 9) or disconnecting the wallet ends the permission.
+From then on your backend reads, with its key, the wallet
+and its balances (`wallet:read`), its operations (`operation:read`) and its
+registrations and events (`streams:read`); it finds the wallet with
+`GET /v1/service/grants?external_ref=…`. Without an active grant every such
+read answers `NOT_FOUND`, as for a wallet that does not exist. A scope your
+service does not hold is refused with `SCOPE_DENIED`, an unknown service or
+someone else's wallet with `NOT_FOUND`. `externalRef` is stored as given and
+returned only to your service; it proves nothing about the account.
+
+`serviceGrants()` lists the grants the account gave, newest first, in every
+state, so your app can show them:
+
+```ts
+const page = await client.serviceGrants({ limit: 50 });  // then { cursor: page.nextCursor } while page.hasMore
+// [{ servicePrincipalId, walletId, walletKind: "wallet" | "linked_wallet", network, address,
+//    scopes, state: "pending_source" | "active" | "revoked" | "stale", grantedAt, externalRef? }]
+```
+
+`pending_source` is a first `streams:read` grant on a wallet that waits until
+Streams opens the wallet's events to the service; only events from that
+moment on reach it. `stale` is a grant whose wallet or service changed since it was set: the
+service reads nothing under it until the person sets it again. `network` and
+`address` are empty for a wallet that is no longer the one granted.
+
+### 5. Limits
+
+```ts
+const limits = await linked.limits(wallet.id);           // revision "0": never set, bounds nothing
+const change = await linked.setLimits(wallet.id, {
+  ceilings: [{ network: "eip155:1", asset: "native", perTransferRaw: "100000000000000000", perDayRaw: "500000000000000000" }],
+  recipients: [],                                        // none: any recipient
+  revision: limits.revision,
+}, crypto.randomUUID());
+await confirmAndExecute(change);                         // result.kind "wallet_limits"
+```
+
+Per network and asset (`native`, `usdt`, `usdc`): an optional ceiling on one
+transfer and on 24 hours, in that network's minimal units, and one recipient
+list. Every send obeys them, Mode C included. Details under "Limits of a
+linked wallet" below.
+
+### 6. Send (Mode B)
+
+A send needs no passkey: the live session authorizes it, and the wallet's
+limits bound it. Three calls, one after another:
+
+```ts
+let send = await linked.send({ linkedWalletId: wallet.id, network: "eip155:1", asset: "native", recipient, amountRaw: "1000000000000000" }, crypto.randomUUID());
+send = await linked.prepare(send.id);                    // the fee estimate is in send.display
+await linked.executeSend(send.id, send.version, crypto.randomUUID());   // the SDK seals its kept share
+const status = await linked.transferStatus(send.id);     // read until status.final
+```
+
+In a browser that holds no share of the wallet (your app on a new domain,
+cleared site data, another browser or a new device) `executeSend()` first
+recovers it: the provider's page asks for the passkey once, as at the
+wallet's creation, and then the send goes on. Nothing else changes for the
+app; see "The device share" below.
+
+The operation ends `succeeded` once the Wallet accepted the transfer and named
+its hash; `transferStatus()` then says what the network did with it. See
+"Sending from a linked wallet" below for every state and refusal.
+
+### 7. Transfers your backend forwards (Mode C)
+
+The person sets bounds once and confirms them with the passkey; then the app
+signs each transfer with a key that never leaves the device, and your backend
+forwards it unchanged with its service key, or refuses to.
+
+```ts
+import {
+  ModeCServerClock, buildLinkedRequestGrantEnrollment, generateRequestSigningKey,
+  pairLinkedRequestGrant, prepareLinkedMediatedTransfer, signLinkedMediatedRequest,
+  type LinkedRequestGrantEnrollment,
+} from "@shuttle.technology/authorization/mode-c-linked";
+
+const key = await generateRequestSigningKey(crypto);     // non-extractable P-256, in memory
+const enrollment: LinkedRequestGrantEnrollment = {
+  ownerId: me.account.accountId, servicePrincipalId: config.servicePrincipalId, linkedWalletId: wallet.id,
+  network: "eip155:1", assets: [{ asset: "native", maxAmountRaw: "500000000000000000" }],
+  maxFeeRaw: "1000000000000000", recipientAllowlist: [],
+};
+const enrolled = await confirmAndExecute(await client.createOperation(buildLinkedRequestGrantEnrollment(key, enrollment), crypto.randomUUID()));
+const grant = enrolled.result.grant;                    // present for a request_grant result
+if (!grant) throw new Error("no grant");
+const paired = pairLinkedRequestGrant(key, grant, enrollment);
+const clock = new ModeCServerClock(grant.serverTime, Date.now());
+
+// Each transfer, with no prompt:
+const prepared = prepareLinkedMediatedTransfer(paired, { asset: "native", recipient, amountRaw: "100000000000000000" });
+const sealed = await linked.deviceShareFor(wallet.id);   // the kept share resealed for this transfer
+const signed = await signLinkedMediatedRequest({ grant: paired, prepared, deviceShare: sealed, crypto, serverNowSeconds: clock.nowSeconds(Date.now()) });
+// Hand signed.request and signed.idempotencyKey to your backend. It posts the request unchanged to
+// POST /v1/service/mediated-operations with its key and that Idempotency-Key, within the proof's minute.
+```
+
+The grant lives at most 15 minutes and never past the session; the session's
+end on the provider (a `logout()` answered `server_revoked`, or a confirmed
+session revocation) or the removal of the enrolling passkey ends it sooner
+(see step 9). The proof
+binds the wallet, its binding revision, the exact transfer and the share's
+digest: the backend cannot change the amount, recipient, asset or network,
+swap the share or replay the request. The person reads a forwarded transfer
+like any send (`walletOperation()`, `linked.sends()`), with basis
+`user_request_signed`. Details under "Mode C on a linked wallet" below.
+
+### 8. Debits your backend makes without the device (for a card)
+
+The normal path is the grant: a service that holds `wallet:debit:user` gets
+its debit permission with every wallet the person opens to it, in that
+passkey confirmation, with the ceilings the platform set for it (step 3,
+"Create and connect in one confirmation", and step 4). What follows is the
+separate permission, with its own passkey: for a wallet opened to your
+service before it held the scope, or bounds of the person's own choosing.
+
+The person lets one service debit one wallet within bounds, until they revoke
+it: for one to three assets the most one debit and the most 24 hours may move,
+the recipients (none: any) and an optional end. The provider's page says it in
+words and asks for the passkey. The execute hands the wallet's device share to
+the platform's share keeper, sealed to a key the keeper made for this
+operation; the provider never opens it, and the device keeps its own copy, so
+sends from the app go on as before.
+
+```ts
+const debits = linked.debitPermissions();
+const asked = await debits.createDebitPermission({
+  walletId: wallet.id, servicePrincipalId: config.servicePrincipalId,
+  assets: [{ asset: "usdt", perDebitRaw: "25000000", perDayRaw: "100000000" }],   // minimal units; per debit <= per day
+  recipients: [],                                         // none: any recipient
+  expiresAt: "2027-01-01T00:00:00Z",                      // left out: until revoked
+}, crypto.randomUUID());
+await client.challengeOperation(asked.id, credentialId);
+const confirmed = await client.completeOperationConfirmation(lastCallback);
+// asked.display.shareKeeperPublicKey present: the keeper needs the share, and the execute reseals the one the SDK keeps.
+const applied = await debits.executeDebitPermission(confirmed.id, confirmed.version, crypto.randomUUID());  // result.kind "debit_permission"
+
+const { items } = await debits.listDebitPermissions();   // newest first: active, revoked or expired
+const ending = await debits.revokeDebitPermission(items[0].id, crypto.randomUUID());
+await confirmAndExecute(ending);                         // result.state "revoked"
+```
+
+`executeDebitPermission()` reads the operation first. When its display names
+`shareKeeperPublicKey`, it reseals the share the SDK keeps for the wallet to
+that key and sends it (recovering it first with one passkey confirmation when
+this browser holds none); an app that keeps its own share passes
+`{ devicePrivateKey, deviceShare }` and it is resealed with
+`resealDeviceShare`. Without that key the keeper holds this wallet's share
+already (an earlier permission handed it over) and nothing is sent. The debits themselves are made by your
+backend with its key and the scopes `wallet:debit:user` and `operation:read`
+(`docs/integration/backend.md`); a debit outside every active permission of
+the service on the wallet is `DEBIT_PERMISSION_INVALID`, over its bounds or the
+wallet's limits one of `WalletLimitRefusals`. A revocation refuses every debit
+not yet executed.
+
+### 9. Withdraw the access
+
+```ts
+const withdrawal = await client.revokeServiceGrant({ walletId: wallet.id, servicePrincipalId: config.servicePrincipalId }, crypto.randomUUID());
+await confirmAndExecute(withdrawal);                     // result.state "revoked"
+```
+
+`revokeServiceGrant` is `service_grant.set` with `enabled: false` and no
+scopes; a grant listed by `serviceGrants()` can be passed as it is. From the
+next read on, your backend gets `NOT_FOUND` for the wallet and for every read
+under the grant, its events included; the account still lists the grant,
+`revoked`. The area's shared event stream (WebSocket, pull, webhooks) is not
+bound to grants yet and goes on delivering the wallet's events
+(`docs/integration/backend.md`, section 5). Mode C ends when the
+provider ends the session, or when the enrolling passkey is removed: a
+`logout()` that resolves with `serverDisposition` `server_revoked`, or a
+`createSessionRevocation(sessionId, key)` confirmed like the above. A
+`server_unconfirmed` logout proves nothing on the provider; revoke the session
+with `createSessionRevocation` from another session of the account, or let
+the grant run out (at most 15 minutes).
+
+## Errors
+
+Two kinds of error reach the app:
+
+- `AuthorizationError`: the provider refused. `code` is one of
+  `AuthorizationErrorCodes`, exactly the ErrorCode enum of the provider's
+  OpenAPI document, typed as `AuthorizationErrorCode`; with it come `status`,
+  `retryable`, `nextAction`, `requestId`, and `operationId` where the caller
+  may look up the operation the refusal names. An answer that does not match
+  the table below is refused as a `ClientFlowError` `invalid_error_response`.
+- `ClientFlowError`: the SDK refused locally. Most such refusals come before
+  any request, and then nothing changed on the server: a malformed input
+  (`invalid_operation_create`, `invalid_page_request`, …), a missing session
+  (`session_unavailable`), a redirect that is not the one expected
+  (`state_mismatch`, `invalid_callback`). Two come after the request, when the
+  answer is outside its closed form: `invalid_server_response` and
+  `invalid_error_response`. After a write, such a refusal does not say whether
+  the write happened: keep its `Idempotency-Key`, read the operation (or
+  repeat the same request with the same key, which answers the first) before
+  starting anything new.
+
+```ts
+import { isAuthorizationError, WalletLimitRefusals } from "@shuttle.technology/authorization";
+
+try {
+  await linked.executeSend(send.id, send.version, key, share);
+} catch (error) {
+  if (isAuthorizationError(error, ...WalletLimitRefusals)) showLimitRefusal(error.code);  // nothing was sent
+  else if (isAuthorizationError(error, "UNAUTHORIZED")) await signInAgain();
+  else if (isAuthorizationError(error) && error.retryable) retryLater(error.nextAction);
+  else throw error;
+}
+```
+
+Repeat a request only when `retryable` is true, with the same body and the
+same `Idempotency-Key`. A `DEPENDENCY_UNAVAILABLE`, `TENANT_AUTH_UNAVAILABLE`,
+`AUDIT_UNAVAILABLE` or `INTERNAL_ERROR` that carries an `operationId`, with
+`retryable` false and `nextAction` `lookup_operation`, may have committed:
+read that operation before doing anything else. `AuthorizationErrorContracts`
+holds the table in code, and `isAuthorizationErrorCode(value)` tells a code.
+
+| Code | Status | Retry | Next action | Meaning |
+|---|---|---|---|---|
+| `INVALID_REQUEST` | 400 | no | none | The request is malformed or names what it may not, such as a service as a wallet's result recipient. |
+| `CURSOR_INVALID` | 400 | no | none | The cursor is not one this read gave this session; read from the start. |
+| `UNSUPPORTED_VERSION` | 400 | no | none | A version the provider does not speak. |
+| `UNAUTHORIZED` | 401 | no | reauthenticate | No live session (a read has already renewed the token once). Sign in again. |
+| `SCOPE_DENIED` | 403 | no | none | The caller lacks the scope, or a grant asks for a scope the service does not hold. |
+| `ORIGIN_NOT_ALLOWED` | 403 | no | none | The origin is not registered for the client. |
+| `LIMIT_PER_TRANSFER_EXCEEDED` | 403 | no | none | Over the wallet's ceiling for one transfer, or a Mode C grant's ceiling. Nothing was sent. |
+| `LIMIT_DAILY_EXCEEDED` | 403 | no | none | Over the wallet's ceiling for 24 hours. Nothing was sent. |
+| `RECIPIENT_NOT_ALLOWED` | 403 | no | none | Not on the wallet's recipient list, or the Mode C grant's. Nothing was sent. |
+| `CONFIRMATION_METHOD_UNAVAILABLE` | 403 | no | use_passkey | The account has no passkey to confirm with. |
+| `USER_PROOF_REQUIRED` | 403 | no | sign_user_request | A Mode C request without the app's signature. |
+| `USER_PROOF_INVALID` | 403 | no | sign_user_request | The signature does not match the request, the share or the key. |
+| `REQUEST_GRANT_INVALID` | 403 | no | use_passkey | The Mode C grant is another service's, has ended or was enrolled on other bounds; enroll again. |
+| `DEBIT_PERMISSION_INVALID` | 403 | no | none | No active debit permission of the service covers this debit on this wallet: none was given, or it was revoked or ended. Nothing was sent. |
+| `NOT_FOUND` | 404 | no | none | No such resource for this caller, including a wallet a service has no active grant on. |
+| `REGISTRATION_SCOPE_SELECTION_REQUIRED` | 409 | no | none | The wallet's Streams history has several scopes: name a registration. |
+| `IDENTITY_NOT_REGISTERED` | 409 | no | start_signup | No account for this identity yet. |
+| `IDENTITY_ALREADY_REGISTERED` | 409 | no | start_login | An account exists for this identity. |
+| `IDENTITY_ALREADY_LINKED` | 409 | no | none | The identity belongs to an account already. |
+| `LAST_FACTOR` | 409 | no | none | The last sign-in method cannot be removed. |
+| `CONFIRMATION_REPLAYED` | 409 | no | none | That confirmation was used already. |
+| `CANNOT_CANCEL` | 409 | no | none | The operation can no longer be canceled. |
+| `VERSION_CONFLICT` | 409 | no | refresh_resource | The resource changed since it was read, or the step is out of order; read it again. |
+| `AUTHORIZATION_STALE` | 409 | no | refresh_resource | An authority the operation was admitted under changed; create a new one. |
+| `IDEMPOTENCY_CONFLICT` | 409 | no | lookup_operation | The key was used with another request; `operationId` names the first. |
+| `USER_PROOF_REPLAYED` | 409 | no | lookup_operation | The signed Mode C request was used already. |
+| `OPERATION_NOT_AUTHORIZED` | 409 | no | use_passkey | Executed before it was confirmed. |
+| `RESULT_NOT_READY` | 409 | yes | wait_for_result | The effect is still running; `operationId` names it. |
+| `TRANSFER_IN_FLIGHT` | 409 | yes | retry_same_request | An earlier transfer of the wallet holds its place in the network's sequence. |
+| `ATTEMPT_EXPIRED` | 410 | no | reauthenticate | The sign-in took too long; start again. |
+| `OPERATION_EXPIRED` | 410 | no | none | The operation's time ran out; nothing was done. |
+| `RESULT_EXPIRED` | 410 | no | none | The result is past its retention. |
+| `RESYNC_REQUIRED` | 410 | no | resync_streams | The events cursor is past its window; `window` says where to read again. |
+| `USER_PROOF_EXPIRED` | 410 | no | sign_user_request | The signed Mode C request is past its minute; sign it again. |
+| `CAPABILITY_UNAVAILABLE` | 422 | no | none | This server does not serve the function. |
+| `RECOVERY_UNAVAILABLE` | 422 | no | none | No way to recover or re-own the wallet: never through a service key or support. |
+| `PAYLOAD_NOT_SUPPORTED` | 422 | no | none | The network, asset or content is not supported, or the Wallet refused the transfer. |
+| `RATE_LIMITED` | 429 | yes | retry_same_request | Too many requests; wait. |
+| `DEPENDENCY_UNAVAILABLE` | 503 | yes | retry_same_request | The Wallet, a node or another dependency did not answer. |
+| `NETWORK_FEE_TOO_HIGH` | 503 | yes | retry_same_request | The network fee is above the ceiling; try later. |
+| `TENANT_AUTH_UNAVAILABLE` | 503 | yes | retry_same_request | Tenant Access did not answer. |
+| `AUDIT_UNAVAILABLE` | 503 | yes | retry_same_request | The provider could not write its audit record. |
+| `ADAPTER_INTEGRITY_CONFLICT` | 503 | no | none | The provider's records disagree; report it with the `requestId`. |
+| `INTERNAL_ERROR` | 500 | yes | retry_same_request | An unexpected failure. |
+
+Two groups the app usually explains to the person:
+
+- `WalletLimitRefusals`: `LIMIT_PER_TRANSFER_EXCEEDED`, `LIMIT_DAILY_EXCEEDED`,
+  `RECIPIENT_NOT_ALLOWED` (`isWalletLimitRefusal(code)`).
+- `ModeCRefusals`: what a forwarded Mode C transfer is refused with besides
+  the common answers: the proof (`USER_PROOF_*`, `IDEMPOTENCY_CONFLICT`), the
+  grant (`REQUEST_GRANT_INVALID`), the amount and recipient against the
+  grant's bounds and the wallet's limits (`LIMIT_PER_TRANSFER_EXCEEDED`,
+  `LIMIT_DAILY_EXCEEDED`, `RECIPIENT_NOT_ALLOWED`) and the fee
+  (`NETWORK_FEE_TOO_HIGH`) (`isModeCRefusal(code)`). A server that does not
+  check the grant's bounds before the Wallet prepares the transfer answers
+  `REQUEST_GRANT_INVALID` for an amount or a recipient outside them. Your
+  backend receives these and passes the code back to the app.
+
+## Mobile apps
+
+On the mobile channel `login()` and `signup()` are one call each:
+
+```ts
+const client = await initializeAuthorizationClient({
+  mode: "mode_b", channel: "mobile", authorizationOrigin: config.apiOrigin,
+  redirectUri: "https://app.example.com/auth/callback", mobileApplicationIdentifier: "com.example.app",
+  publishableClientId, tenantId, applicationId, environmentId, methods: ["google", "telegram", "passkey"],
+}, { browserBridge, secureStorage });
+const { session } = await client.login();
+```
+
+The SDK has the operating system verify the app link of the redirect, opens
+the hosted page with `MobileBrowserBridge.openSystemBrowser`, takes the app
+link the system browser's authentication session hands back, checks that it
+is exactly the registered redirect with the one-use `code` and this sign-in's
+own `state`, exchanges the code and resolves with the session. A closed
+browser fails with `mobile_redirect_unavailable`, another state with
+`state_mismatch`, anything but the exact app link with `invalid_callback`. The
+app sends no `Origin`: the provider binds a mobile sign-in to the exact
+registered redirect, its state and its S256 verifier, and returns the refresh
+token in the exchange answer for `MobileSecureStorage` only.
+
+The app supplies:
+
+- `MobileBrowserBridge`: `verifyAssociatedRedirect` asks the operating system
+  to validate the HTTPS app link association for the exact redirect and the
+  configured bundle or package identifier, at initialization and before every
+  sign-in; `openSystemBrowser` opens the authentication session
+  (`ASWebAuthenticationSession` with an HTTPS callback on iOS, a Custom Tab on
+  Android) and resolves with the URL it ended on. There is no default
+  verifier, no custom-scheme fallback and no embedded web view.
+- `MobileSecureStorage`, backed by the Keychain or the Keystore. The refresh
+  token's key uses letters, digits, dots, hyphens and underscores only.
+
+The bridge's verification result is a contract of the host, not a proof this
+package makes. On iOS no API reports that an associated domain was verified:
+the system checks it when the authentication session with the HTTPS callback
+starts, and does not start one for an app the domain does not name; a bridge
+that answers for that check (as `examples/mobile` does) fails there, before
+any page loads and before any code comes back.
+
+If secure storage cannot keep a rotated refresh token, the SDK deletes the
+previous one best-effort, clears its session and reports
+`secure_storage_unavailable`; the way back is a new sign-in.
+
+### What the integrator hosts and registers
+
+No custom URL scheme is accepted for channel `mobile`, and no embedded web
+view. Registered with the operator, for one public client:
+
+- channel (`platform`) `mobile`;
+- the exact redirects: app link URLs such as
+  `https://app.example.com/auth/callback` (no wildcard, query or fragment);
+- the origins: the app link's domain, such as `https://app.example.com`;
+- the sign-in methods the hosted page may offer.
+
+Hosted on that domain, over HTTPS with a publicly trusted certificate and
+without redirects:
+
+- `/.well-known/apple-app-site-association`, served as `application/json`,
+  naming the app (`<Team ID>.<bundle ID>`) under `webcredentials` (the iOS
+  17.4+ authentication session hands an HTTPS callback back only to an app
+  listed there) and under `applinks` for the redirect's path:
+
+  ```json
+  {
+    "applinks": { "details": [{ "appIDs": ["ABCDE12345.com.example.app"], "components": [{ "/": "/auth/callback*" }] }] },
+    "webcredentials": { "apps": ["ABCDE12345.com.example.app"] }
+  }
+  ```
+
+- `/.well-known/assetlinks.json`, naming the Android package and its signing
+  certificate's SHA-256 fingerprint:
+
+  ```json
+  [{
+    "relation": ["delegate_permission/common.handle_all_urls"],
+    "target": { "namespace": "android_app", "package_name": "com.example.app", "sha256_cert_fingerprints": ["<SHA-256 of the signing certificate>"] }
+  }]
+  ```
+
+In the app: the iOS entitlement `com.apple.developer.associated-domains` with
+`applinks:app.example.com` and `webcredentials:app.example.com`; on Android an
+intent filter with `android:autoVerify="true"` for the redirect's host and
+path. `examples/mobile` is a React Native (Expo) app that does all of it.
+
+## Reference
+
+### Web session renewal
+
+`restoreSession()` is a top-level handoff: the SDK keeps a fresh state and
+S256 verifier in memory and calls `openHosted` with the provider's restore URL
+and a signal that aborts once no caller waits for the restore; the host
+returns the registered redirect URL the restore came back to. A popup is one valid host; a hidden frame on the same
+site is another (`demo/renew.js`). A full-page navigation that destroys the
+SDK instance is not supported: when the host cannot return the redirect, the
+restore fails locally with `restore_redirect_unavailable`. The SDK never
+stores restore state, verifier, access token, CSRF token or refresh cookie in
+browser storage.
+
+#### Background renewal
+
+On the web `refreshSession()`, and every call that finds its access token
+expired or refused, renews in the background: `POST /v1/auth/renew` with
+`credentials: "include"`, no window. The provider's refresh cookie is
+`__Host-authorization_refresh`, `Secure; HttpOnly; SameSite=None;
+Partitioned` (CHIPS), so the browser sends it from the application's own site
+and from no other, and the renewal is answered only for the exact `Origin` of
+one of the client's registered origins. Within a page's life the SDK sends
+the session's CSRF token in `X-CSRF-Token`. A page that holds none, a reload
+or a new tab, renews from the cookie alone (`X-Authorization-Renew: 1`) and
+gets a new token, so on load an application calls `refreshSession()`. A token another
+tab replaced is followed by one renewal from the cookie. The tabs of one
+application renew and restore in turn under one Web Lock, which a restore
+holds until `openHosted` settles or its signal aborts; on abort the host
+closes the window it opened. A renewal or restore that a logout or a newer
+sign-in overtook while it waited for the lock asks the provider nothing, and
+what it answers installs only while the session it renews is still the one
+installed. The web keeps no refresh token: the cookie is the provider's. When the browser sends no cookie the
+SDK throws `ClientFlowError` with code `web_renewal_requires_navigation`
+(`webRenewalRequiresNavigation`) and does not navigate: the application
+calls `restoreSession()` itself, or signs the person in again where the
+restore cannot see the cookie (an application on a site of its own).
+
+A renewal or restore answers only the session it renews. The cookie is one
+per site, and a sign-in in another tab, perhaps to another account, puts its
+own session there: the next renewal of this page's session would answer that
+one. The SDK then installs nothing, ends the session it held and throws
+`ClientFlowError` `session_replaced`; the application takes up the session
+the cookie holds with `refreshSession()` (and checks whose it is with
+`me()`), or signs the person in again. A sign-in whose answer a `logout()`
+or a newer sign-in overtook is not installed, and the SDK revokes its
+session, so the cookie it set holds nothing a reload could take up; when
+another tab replaced that session's CSRF token meanwhile, it renews once
+from the cookie under the tabs' lock and revokes with those tokens, only
+while the cookie still holds that session. A `logout()` waits for the
+sign-ins it overtook and answers `server_unconfirmed` unless each such
+revocation was confirmed; a sign-in whose answer was lost, unread or
+malformed counts as unconfirmed, one the provider refused as clean. It does
+not wait when it has nothing of its own to confirm, nor for a revocation
+that must wait for the tabs' lock: it answers `server_unconfirmed` at once
+and the revocation goes on. Logout
+clears the cookie only while it holds the session logged out of: the cookie
+of a newer sign-in stays. A signal passed to `exchangeHandoff()` or
+`logout()` ends only that caller's wait, never the request.
+
+One session per origin: two registered origins of one site share the cookie
+but not the lock, so if both renew at the same moment the provider takes it
+as a replay and ends the session. A sign-in's exchange goes out under the
+same lock as a renewal and a restore, so a renewal in another tab is answered
+before it and never puts the older session back in the cookie. A restore in
+another tab holds the lock while its window is open, and the sign-in waits
+for it.
+
+### Passkeys and the account's own operations
+
+`bootstrapPasskey()` and `verifyIdentity(method)` start provider-hosted flows
+with a fresh state and S256 verifier held in memory; the host delivers the
+redirect to `completePasskeyBootstrap()` or `completeIdentityVerification()`.
+Those redirects carry only one-use `code`, `state` and `flow_id` values, and a
+hosted URL or flow ID alone is never authority.
+
+The account's local operations are `identity.link`
+(`createIdentityLink(handle, key)` after `verifyIdentity`), `identity.unlink`
+(`createIdentityUnlink`), `session.revoke` (`createSessionRevocation`),
+`service_grant.set` (`createServiceGrant`, `revokeServiceGrant`),
+`wallet_limits.set` (`linkedWallets().setLimits`) and
+`session.authorize_requests` (Mode C enrollment). Creation, confirmation,
+execution and the protected result read are separate calls; a safe result
+holds only `kind`, `targetId`, `newVersion` and `state`. `identities()` lists
+the account's sign-in methods (an array, not paged); `sessions()` its sessions
+and `wallets()` its own wallets (`kind` `wallet` in `me()`) are paged with
+`{ limit, cursor }`.
+
+### Mode C on a linked wallet
+
+1. `generateRequestSigningKey(crypto)` makes the key;
+   `buildLinkedRequestGrantEnrollment(key, enrollment)` the closed
+   `session.authorize_requests` body: the linked wallet, the network the
+   transfers are made on (the wallet's own, or for an EVM wallet another EVM
+   network), one to three assets (`native`, `usdt`, `usdc`) each with the most
+   one transfer may move (`maxAmountRaw`), the most the network fee may be
+   (`maxFeeRaw`, compared with the Wallet's estimate when the transfer is
+   prepared) and up to ten recipients, none for any (compared as the provider
+   compares addresses: EVM without case, TON in its raw form). The executed
+   operation's result carries the grant (`result.grant`);
+   `pairLinkedRequestGrant` keeps it beside its key and refuses a grant on
+   other bounds. The grant survives the person's later sign-ins and
+   confirmations with the same passkey.
+2. `prepareLinkedMediatedTransfer(paired, { asset, recipient, amountRaw, comment? })`
+   is the transfer the app shows; what the grant does not cover is refused
+   locally. A comment is carried on TON only.
+3. The app takes the device share resealed for this transfer
+   (`linkedWallets().deviceShareFor()`, which recovers it first in a browser
+   that holds none; an app that keeps its own share reseals it to
+   `transportKey()` with `resealDeviceShare`), and
+   `signLinkedMediatedRequest({ grant, prepared, deviceShare, crypto, serverNowSeconds })`
+   signs the 2.0 proof over the transfer and over the SHA-256 of the share
+   (`deviceShareDigest`). It returns `request` (`{ operation, user_proof,
+   device_share }`) and `idempotencyKey` (the proof's `jti`).
+   `examples/backend-client` (`cli.ts mediate <file>`) is a backend that
+   forwards it.
+
+`ModeCServerClock` carries the provider's time: it is seeded from the grant's
+`serverTime` and moved only by a current `me()`; a proof is signed by it, and
+a clock disagreement is resolved by signing a new proof with a new `jti` while
+the grant is live. The proof shows that the enrolled key acted, not that a
+person was present: compromised app code can misuse a live grant within its
+bounds. Speed-up and cancel are not offered through Mode C.
+
+`./mode-c` is the same for a wallet bound in the provider rather than
+linked: `buildRequestGrantEnrollment`, `enrollRequestGrant` (create, passkey
+confirmation, execute and result behind one function), `RequestGrantStore`,
+`prepareMediatedTransfer` and `signMediatedRequest` (proof 1.0, native coin).
+Neither module sends anything: forwarding and refusal are the backend's.
+
+### Tracking a linked wallet in Streams
+
+Tracking needs no passkey: `linkedWallets().register({ linkedWalletId, network, activityTypes? }, key)`
+comes back `authorized` with basis `session_authorized`, and
+`executeRegistration(operation.id, operation.version, key)` dispatches it. A
+registration covers one network; an EVM wallet has one address on every EVM
+network, so register it once per EVM network, and `events()` returns the
+events of all of them, each with its `networkId`. `activityTypes` names the
+kinds of activity asked for beside deposits (such as `"transaction"`,
+`"erc20.approval"`): at most 16, each matching
+`^[a-z][a-z0-9]*(?:[._][a-z0-9]+)*$`; omitted or empty means deposits only,
+and Streams refuses a kind the network does not have. A Solana wallet is
+registered on `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`; its activity types
+are `transaction`, `native.transfer`, `spl.transfer`, `spl.approval`,
+`contract.raw`, `contract.decoded` and `native.action`.
+
+`linkedWallets().signals(linkedWalletIds, { onOpen, onWallets, signal })`
+opens one signal stream for 1 to 32 linked wallets. It carries no event: it
+names the wallets that have new ones, which are read with `events()`. Read
+every wallet once at `onOpen`, so nothing falls between that read and the
+first signal. The promise resolves with why the stream ended (`expired`,
+`server_draining`, `connection_closed`); a stream lives no longer than an
+access token, so open the next one. A signal is a hint: keep a slower timed
+read for the times no stream is open (`demo/live.js`).
+
+### Sending from a linked wallet
+
+1. `send(input, key)` admits the send: `authorized`, basis
+   `session_authorized`, `nextAction` `none`; nothing is asked of the Wallet
+   yet. `replaceSend({ linkedWalletId, operationId, action }, key)` admits a
+   speed-up (`speed_up`) or a cancel (`cancel`) of an EVM send the network has
+   not included, as a send of its own.
+2. `prepare(operation.id)` has the Wallet prepare the transfer and estimate
+   the fee, and answers the operation with what was prepared; calling it again
+   answers the same prepared send. The display then carries the network,
+   asset, amount, recipient, `comment` where there is one, `preparedSummary`
+   and `feeEstimate`: `estimated` with `estimatedFeeRaw` in minimal units of
+   the network's coin, paid on top of the amount, or `unavailable`, which is
+   never a fee of zero.
+3. `executeSend(operation.id, operation.version, key)`: the SDK reads the
+   transport key and reseals the share it keeps, recovering it first in a
+   browser that holds none. An app that keeps its own share passes it as a
+   fourth argument, resealed (`transportKey()`, `resealDeviceShare()`), and
+   the SDK then recovers nothing.
+
+The preparation caps the operation at 150 seconds: an `executeSend()` after
+that is `OPERATION_EXPIRED`, and the send is started again. An `executeSend()`
+of a send never prepared is `VERSION_CONFLICT`. `prepare()` can be refused
+`TRANSFER_IN_FLIGHT` (an earlier transfer of the wallet is not in a block yet;
+Ethereum, BNB Smart Chain and TON) or `NETWORK_FEE_TOO_HIGH`, both retryable
+with nothing prepared, and `DEPENDENCY_UNAVAILABLE` when the Wallet or a node
+did not answer in time. An execution the Wallet refuses for good ends the
+operation `failed` with `effectState` `no_effect`.
+
+`transferStatus(operationId)` answers for the one transfer the operation
+prepared: `prepared`, `executing`, `broadcasting`, `submitted`, `confirmed`,
+`failed` or `expired`, `final` for the last three. `transactionHash` is
+present once it is signed; `failureReason` is the network's reason, or
+`expired` (never executed, moved nothing), `nonce_used` (another transaction
+took its place: `replacedByOperationId` names the account's own send that did,
+when it was one) or `not_sent` (signed only after its authorization ran out).
+`authorizationExpiresAt` is the deadline of the owner's authorization while
+the transfer is not final; a transfer `submitted` past it ends `confirmed`, or
+`failed` once another transaction of the wallet takes its place. Read it until
+`final`: the first final state is recorded and answered from the record
+afterwards. On Ethereum `confirmed` may wait twelve blocks, on BNB Smart Chain
+a hundred. A send never prepared is `NOT_FOUND`; one whose fate was not read
+before the 30-day material retention is `RESULT_EXPIRED`.
+
+A send on TON can carry a comment: 1 to 120 bytes of UTF-8 with no control,
+line-separator or reordering character (`transferComment(value)`,
+`MaxTransferCommentBytes`), sent exactly as given and written into the signed
+transaction for the coin and for a token alike. A comment on any other network
+is refused locally and with `PAYLOAD_NOT_SUPPORTED` by the provider.
+
+A replacement spends the same place in the wallet's sequence as the send it
+replaces, so the network includes at most one: read `transferStatus()` of
+both. It counts against the limits like a new transfer, except that a speed-up
+adds nothing to the daily total and a cancel is judged by no limit. Refusals:
+`NOT_FOUND` for an operation that is not the account's send from that wallet,
+`VERSION_CONFLICT` for a send the Wallet has not accepted or whose fate is
+recorded, `PAYLOAD_NOT_SUPPORTED` for a network that is not EVM or a
+replacement the Wallet refuses, `RESULT_EXPIRED` past the material retention.
+
+`sends({ limit, cursor })` is the account's history of sends, newest first:
+state, network, asset, recipient, amount, the sending address, the
+`transactionHash` once accepted and `transfer`, the recorded final fate (a row
+with a hash and no `transfer` has not been read final yet). A replacement is
+a row of its own with `replacesOperationId` and `replaceAction`; past the
+material retention a send stays listed with `materialPurged`.
+`sendEvents(send, events)` picks the events of a listed send's transaction on
+the EVM networks, TRON and Solana.
+
+### The device share
+
+A wallet's key is three shares, any two of which sign; the device share is
+this device's. The SDK keeps it, with the non-extractable device key it is
+sealed to, in the origin's IndexedDB, under the client's configuration, for
+every wallet it made the key for (`createWallet()` without a key) or
+recovered onto this device. On mobile pass a `deviceShares` store in the
+dependencies (`DeviceShareStore`: `load(walletId)` and `save(record)`, with
+records `{ walletId, privateKey, publicKeyHex, deviceShare }` keyed by the
+Wallet's wallet ID, the linked wallet's `externalWalletId`, or a pending
+recovery's `{ walletId, privateKey, publicKeyHex, pendingOperationId,
+executeKey, pendingLinkedWalletId }`; keep every member as given); a web app
+may pass one too.
+
+A browser that holds no share of a wallet recovers it the first time a call
+needs it: `executeSend()` without a share, `deviceShareFor()` (Mode C), or
+`recoverDevice()`. The SDK makes a new device key, admits a `wallet.recover`
+of the linked wallet (`linked_wallet_id` and the new key), opens the
+provider's page through `openHosted`, where the person confirms with the
+passkey (the page says "Вернуть доступ к кошельку <address> на этом
+устройстве"), executes it, waits for the Wallet, checks that the recovered
+share opens with the new key and keeps it. The session alone never yields a
+share. Once the recovery succeeds, the share the wallet had in any other
+browser or device stops working. Each kept share carries its device key's
+public key, and before it uses one the SDK reads the device key of the
+wallet's latest creation or recovery from the provider
+(`deviceKey(linkedWalletId)`, `GET /v1/linked-wallets/{id}/device-key`): a
+kept share sealed to another key was replaced elsewhere, and that browser
+recovers too, with one passkey confirmation. A share is current while the
+provider names its key, or names none. The tabs of one browser take turns
+under one Web Lock per wallet: a second tab waits and uses the share the
+first one recovered.
+
+A confirmed recovery is kept as pending, with its device key, operation and
+execute key, before it is executed. A recovery whose end the SDK could not
+learn (the execute answer was lost, or the Wallet has not answered within
+about five minutes) fails the call with `device_recovery_failed` and stays
+pending; the next call, in this tab or another, resumes that same operation
+rather than starting another one, also after a reconnection gave the wallet
+another linked wallet ID, and a new recovery starts only once the pending one
+ended without effect, or can have none: never executed, and past its deadline
+or no longer claimable by this sign-in. The provider refuses to execute a recovery
+while another recovery of the wallet is unresolved (`DEPENDENCY_UNAVAILABLE`,
+retryable): the call fails with that refusal, the recovery stays pending,
+and a later call executes it with its own key. A share resumed or recovered
+is read against the provider's device key once more; when another device
+recovered meanwhile the call recovers once more, then gives up with
+`device_recovery_failed` rather than chase the other device. A creation's
+result read late never replaces a recovery another tab kept for the wallet.
+
+The SDK needs the redirect back from `openHosted` (resolve it with the
+callback URL, as the hosted window above does) and confirms with the
+account's newest passkey; `recoverDevice(linkedWalletId, { credentialId })`
+names another. A press that may lead to a recovery should open the hosted
+window inside the click: `hasDeviceShare(linkedWalletId)` tells whether this
+browser holds a current share. `recoverDevice()` recovers only when it holds
+none and answers whether it did; call it ahead of a transfer to have the
+passkey asked before the send is prepared (a prepared send lasts 150
+seconds). `recoverDevice(linkedWalletId, { force: true })` recovers even
+when a current share is kept.
+
+The provider's refusals of the recovery come as `AuthorizationError`:
+`NOT_FOUND` (not the account's linked wallet), `SCOPE_DENIED` (the app is not
+one the wallet profile serves), `AUTHORIZATION_STALE` (the wallet is no longer
+active), `CAPABILITY_UNAVAILABLE` (the server does not recover); a refusal of
+the device-key read surfaces as it comes. The SDK's own
+are `ClientFlowError`: `device_share_unavailable` (no store),
+`device_recovery_requires_passkey`, `hosted_callback_unavailable`,
+`device_recovery_not_confirmed`, `device_recovery_failed`. Nothing is sent
+after any of them.
+
+### Limits of a linked wallet
+
+`limits(linkedWalletId)` reads them with the session alone.
+`setLimits(linkedWalletId, { ceilings, recipients, revision }, key)` replaces
+them as a whole (empty `ceilings` and `recipients` remove every limit) and is
+confirmed with a passkey; the result kind is `wallet_limits`. A ceiling names
+its network because a token's decimals differ between networks (USDT has 6 on
+Ethereum and 18 on BNB Smart Chain). `revision` is the revision the change was
+edited from: when the limits changed since, the change is refused with
+`VERSION_CONFLICT` and overwrites nothing. A ceiling on a network the wallet
+does not send on, a pair named twice or a malformed amount is refused before
+anything is admitted.
+
+`send()` and `replaceSend()` are refused `LIMIT_PER_TRANSFER_EXCEEDED` or
+`RECIPIENT_NOT_ALLOWED` at once, unless the same key repeats a send already
+created; `executeSend()` is judged again against the limits as they are then,
+with the daily total including sends that may have moved, and may answer any
+of the three. The Wallet's own signing policies apply on top.
+
+### Balances
+
+`linkedWallets().balances(linkedWalletId)` answers, for each network the
+wallet's key has an address on, the network's coin and the tokens the stand
+names there, in minimal units with their decimals, read from the provider's
+own nodes. A network whose node gave nothing is `unavailable`, or `partial`
+with some amounts; an unread asset has no `amountRaw` and is never zero.
+Without nodes the read is `CAPABILITY_UNAVAILABLE`. Stellar is not read.
+
+### Streams reads and wallet events 3.0
+
+`client.streams()` binds the account's Streams reads to the session
+(`/v1/wallets/{wallet_id}/registrations` and `/events`); a backend constructs
+`StreamsReads` from `./streams` with `scope: "service"` and its own
+authorized GET. Events are read in one shape, wallet event 3.0
+(`WalletEvent`): `kind` `deposit`, `withdrawal` or `activity` (with
+`activity_type`), `status` `completed` (in a block), `finalized` (the block is
+final) or `reverted`, `revision` counting a subject's statuses from `"1"`, and
+`cursor`, the event's place in the stream. Every subject is told at least
+twice, completed and then finalized; where a block is final as soon as it
+exists the two arrive together. `eventTypes` filters a page after it is read
+without changing its cursor, so a filtered page may be short or empty and
+still continue: follow `hasMore`.
+
+`resumeCursor(page)` is the cursor to keep between rounds: `nextCursor` while
+`hasMore`, then `window.latestCursor`, which returns only what came after the
+end of the stream as that read saw it. A cursor ends with its session and with
+a change of the wallet's registrations (`CURSOR_INVALID`: read from the start).
+An expired boundary is `RESYNC_REQUIRED` with its `window`; the restart is a
+fresh read without a cursor. `pollStreamsDeposits` and `pollAuthoritative`
+poll at least two seconds apart and stop at sixty.
+
+### A backend client of an organization (Mode A)
+
+A customer backend with a Tenant Access key acts for its organization on the
+`/v1/service/...` routes (`api/authorization/openapi.yaml`): it creates the
+organization's wallets, tracks and reads them, sets their limits and sends
+from them, with no passkey. `examples/backend-client` is such a backend in a
+small Node program, the counterpart of the demo page; it reuses this
+package's `resealDeviceShare`.
+
+## Demo
+
+`demo/` is a static page that runs the whole user side against a provider:
+sign-in, the passkey, a wallet, its tracking and events, the connection to the
+backend's service and its withdrawal, limits, sends with speed-up and cancel,
+and Mode C. See `demo/README.md`.
+
+## Developing this package
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run verify          # syntax checks, typecheck, build, unit tests
+npm pack                 # builds dist and writes shuttle.technology-authorization-<version>.tgz
+```
+
+The contract runners `test/http-integration-*.mjs` drive the compiled SDK
+(`dist/`), the demo page's modules and the backend simulator against the real
+Authorization HTTP server over TLS, with PostgreSQL, the decision signer,
+claimer, worker and native Wallet adapter; only the Wallet, Tenant Access's
+producer side and the stand's nodes are stand-ins, and every answer is checked
+against the OpenAPI document. The Go tests `TestCompiledSDK*` and
+`TestBackendSimulator*` in `internal/authorization/store/postgres` and
+`TestCompiled*` in `internal/authorization/runtime` run them, each building
+the SDK from the current source. From the repository root:
+
+```sh
+TEST_DATABASE_URL=... go test ./internal/authorization/store/postgres -run 'TestCompiledSDK|TestBackendSimulator'
+TEST_DATABASE_URL=... go test ./internal/authorization/runtime -run 'TestCompiled|TestBuiltSDK'
+```
+
+The required local linked-wallet acceptance runs from the repository root with
+prepared offline tools and a separate SDK dependency isolate (Go 1.26.7,
+Node 24.19.0, PostgreSQL 18.6); it installs and downloads nothing:
+
+```sh
+make authorization-linked-wallet-local GO="$GO_BIN" NODE="$NODE_BIN" \
+  PG_BINDIR="$PG18_BINDIR" AUTH_SDK_DEPENDENCY_ISOLATE="$SDK_DEPENDENCY_ISOLATE"
+```