@shuttle.technology/authorization 0.1.0 → 0.2.0

package/README.md

@@ -1,709 +1,1125 @@
-# Streams Authorization SDK
+# @shuttle.technology/authorization
 
-This package is the framework-independent TypeScript client for the public
-Mode B authorization flow. It holds access tokens in memory. Web refresh uses
-the provider's secure HTTP-only cookie; mobile refresh tokens are available
-only through the required secure-storage port.
+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.
 
-## Installation
+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
+npm install @shuttle.technology/authorization@0.2.0
 ```
 
-The package ships compiled ESM and TypeScript declarations. Its public entry
-points are:
+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";
-import { signMediatedRequest } from "@shuttle.technology/authorization/mode-c";
-import { signLinkedMediatedRequest } from "@shuttle.technology/authorization/mode-c-linked";
-import { StreamsReads } from "@shuttle.technology/authorization/streams";
-import { LinkedWallets } from "@shuttle.technology/authorization/linked-wallets";
-import { generateDeviceKey } from "@shuttle.technology/authorization/device-key";
-import { resealDeviceShare } from "@shuttle.technology/authorization/device-share";
+
+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 });
 ```
 
-Publishing the package changes only how applications install it. It does not
-add a server-managed custody mode. Mode A still requires the customer backend
-to retain its device key and the sealed device share, then reseal and submit
-that share when a wallet operation is executed.
-
-## Web initialization
-
-`initializeAuthorizationClient` checks the current HTTPS application origin,
-then reads `GET /v1/public/clients/{id}`. It accepts only the exact configured
-client, environment, method set, provider origin, redirect, and web platform.
-Initialization creates no session authority.
-
-Web restore is a top-level handoff. `restoreSession` keeps a fresh state and
-S256 verifier in memory, then calls `openHosted` with the provider restore URL.
-The host must open a separate top-level browsing context and return the exact
-registered-app redirect URL after completion. A popup is one valid host
-implementation. Full-page navigation that destroys the calling SDK instance
-is not supported silently: if the host cannot return the redirect,
-`restoreSession` fails locally. The SDK never stores restore state, verifier,
-access token, CSRF token, or refresh cookie in browser storage.
-
-## Mobile host boundary
-
-Mobile configuration embeds only public provider configuration and a public
-bundle/package identifier. The caller must supply:
-
-- `MobileBrowserBridge`, implemented by the host/native layer;
-- `MobileSecureStorage`, backed by platform-protected storage.
-
-`MobileBrowserBridge.verifyAssociatedRedirect` must ask the operating system
-to validate the registered HTTPS app/universal-link association for the exact
-redirect URL and configured bundle/package identifier. The same bridge opens
-the system browser. There is no default verifier, claimed bundle header,
-custom-scheme fallback, or embedded webview.
-
-The structured verification result is a host-port contract. It is not
-cryptographic proof generated by this TypeScript package. A missing bridge,
-unavailable or failing OS check, or any redirect/application mismatch fails
-locally before an authentication request or browser launch.
-
-If secure storage cannot persist a rotated mobile refresh successor, the SDK
-deletes the predecessor best-effort, clears its in-memory session, and reports
-`secure_storage_unavailable`. This prevents the SDK from knowingly retaining a
-consumed predecessor. A failing storage provider can prevent proof that the
-predecessor was erased; recovery is a new login, and the SDK does not report
-server revocation from this local failure.
-
-## Passkey proof and local operations
-
-`bootstrapPasskey` and `verifyIdentity` start provider-hosted flows with a
-fresh state and outer S256 verifier held only in memory. The host browser bridge
-opens the returned HTTPS location and later delivers the exact registered-app
-redirect to `completePasskeyBootstrap` or `completeIdentityVerification`.
-Those redirects contain only one-use `code`, `state`, and `flow_id` values. A
-hosted URL or flow ID alone is never authority, and neither web refresh cookies
-nor mobile refresh storage are used as confirmation authority.
-
-New passkey verification is a server-hosted registration followed by a
-separate possession assertion. Fresh operation confirmation instead uses an
-already linked passkey. The SDK requests that challenge, opens the server
-confirmation page, validates the returned `state` and `operation_id`, and then
-rereads authoritative operation status. It never accepts caller-supplied
-WebAuthn options, auto-confirms, or auto-executes an operation.
-
-The Slice 4 local-operation helpers cover `identity.link`, `identity.unlink`,
-`session.revoke`, and `service_grant.set`. Creation, confirmation, execution,
-and protected result reads remain separate calls. Write failures are returned
-to the caller without automatic retries; `executeOperation` requires the
-explicit operation version and idempotency key. Safe results expose only
-`kind`, `targetId`, canonical `newVersion`, and `state`.
-
-`createOperation` accepts the source-defined optional closed
-`result_recipient`. Omitting it requests the owner-account default. Supplying
-it does not grant result access: the server must resolve and authorize that
-account or service before freezing the operation, and later rechecks current
-recipient authority on the protected result read.
-
-## Mode C: request-key enrollment and typed request proofs
-
-`src/modeC.ts` is the package's second entry point (`@shuttle.technology/authorization/mode-c`).
-It exposes exactly two client responsibilities and nothing else.
-
-`generateRequestSigningKey` creates the non-extractable P-256 WebCrypto key of
-source §2.5 and exports only its `kty/crv/x/y` JWK and RFC 7638 thumbprint. The
-private `CryptoKey` never leaves that object, refuses `exportKey`, and is held
-only in memory. `buildRequestGrantEnrollment` produces the closed
-`session.authorize_requests` payload; `enrollRequestGrant` drives that operation
-through the four separate calls the operation contract requires — create, fresh
-provider-hosted passkey confirmation, explicit execute, and the protected
-result read — behind one function. Enrollment never runs from a refresh, reload
-or login callback.
-
-`RequestGrantStore` retains one protected grant result beside the exact key that
-produced it, in memory only. It refuses to pair a result whose RFC 7638
-thumbprint, owner, service, wallet, network or bounds disagree with the
-enrollment that was submitted, and it reports
-`request_grant_reenrollment_required` when the pairing is absent, released or
-past its deadline. It never renews, re-enrolls or serializes the grant.
-
-`prepareMediatedTransfer` derives the displayed typed intent and the exact
-closed `OperationCreate` from the grant binding: the caller supplies only the
-recipient, amount and fee, and every value outside the frozen allowlist and
-ceilings is refused locally. `signMediatedRequest` rederives that intent from
-the grant and refuses a display that disagrees with the signed body before any
-crypto call; it then canonicalizes with RFC 8785, takes the lowercase SHA-256
-`request_hash`, mints a 256-bit `jti` that is also the `Idempotency-Key`, bounds
-`exp` to sixty seconds and the grant deadline, and produces the compact ES256
-JWS with the closed `{alg,typ,kid}` protected header. It accepts no bytes, no
-payload and no proof from a caller, so arbitrary or backend-supplied material is
-rejected with `opaque_signing_input_refused` and never signed.
-
-`ModeCServerClock` carries the authenticated server time: it is seeded from the
-grant result's `server_time` and refreshed only from a current `/v1/me`
-response. Clock disagreement is resolved by adopting that reading and signing a
-new proof with a new `jti` while the grant is still live; no local override or
-tolerance exists.
-
-Forwarding and refusal are the customer backend's, not the SDK's. This package
-exports no forward, approve, refuse or backend-signing helper, and proof
-generation performs no HTTP. `test/customerBackendFixture.ts` is a test-only
-stand-in for that backend. Operation status and result reads use the generic
-helpers in `client.ts`.
-
-`session.authorize_requests` is not served yet, so `enrollRequestGrant` is
-exercised against the operation contract rather than the live route; the
-runtime harness supplies the protected grant result through its fixture and the
-SDK's own payload builder, result parser and pairing rules still run unchanged.
+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>
+```
 
-### Mode C on a linked wallet
+```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;
+  });
+}
+```
 
-`src/modeCLinked.ts` (`@shuttle.technology/authorization/mode-c-linked`) is Mode C for the
-wallets a person created through Authorization (owner decision of 14 October
-2026). The person allows, once and with the passkey, transfers their app signs
-and their app's backend forwards; each transfer then goes with no passkey.
-
-1. `generateRequestSigningKey` makes the key; `buildLinkedRequestGrantEnrollment`
-   makes the closed `session.authorize_requests` body: the linked wallet, the
-   network the transfers are made on, 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 (each
-   compared as the provider compares addresses: EVM without case, TON in its
-   raw form). `client.createOperation()` admits it,
-   `challengeOperation()` and `completeOperationConfirmation()` take the passkey,
-   `executeOperation()` issues the grant and `operationResult()` returns it
-   (`result.grant`). `pairLinkedRequestGrant` keeps it beside its key and refuses
-   a grant on other bounds. The grant lives at most 15 minutes, never past the
-   session, and survives the person's later sign-ins and confirmations with the
-   same passkey; removing that passkey ends it.
-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 reads the Wallet's transport key (`linkedWallets().transportKey()`)
-   and reseals the device share for this transfer (`resealDeviceShare`), then
-   `signLinkedMediatedRequest({grant, prepared, deviceShare, crypto,
-   serverNowSeconds})` signs the 2.0 proof over the transfer and over the
-   SHA-256 of the share (`deviceShareDigest`), and returns `request`
-   (`{operation, user_proof, device_share}`) and `idempotencyKey` (the proof's
-   `jti`). The backend forwards `request` unchanged with its service key and
-   that Idempotency-Key, within the proof's minute, to
-   `POST /v1/service/mediated-operations`
-   (`examples/backend-client`: `cli.ts mediate <file>`).
-
-The backend cannot change the transfer, swap the share or sign a new request.
-The wallet's own limits apply to every transfer.
-
-The person reads a forwarded transfer on their own session like any send:
-`client.walletOperation(id)` and `linkedWallets().sends()` read it in the
-mediated projection the provider serves for it (`src/mediatedOperation.ts`):
-`authorizationBasis` `user_request_signed`, `linkedWallet` naming the wallet,
-and a display with no result recipient (`MediatedLinkedSendDisplay`; a
-transfer from a wallet bound in the provider has `walletId` and a
-`MediatedSendDisplay`). `transferStatus()` and `replaceSend()` work for it as
-for a session send.
-
-## Creating a wallet and reaching it
-
-`src/deviceKey.ts` is the package's device-key entry point
-(`@shuttle.technology/authorization/device-key`). `generateDeviceKey` creates a
-non-extractable ECDH P-256 key pair and returns its compressed public key, the
-`recipientPublicKey` of `createWallet`. The module persists nothing: the
-application keeps the private key handle and the sealed device share it later
-receives in storage that can hold a non-extractable key.
-
-A completed `wallet.create` releases a `wallet_created` result through
-`walletOperationResult`: the public wallet identity and the device share
-exactly as the own-wallet system sealed it. The provider never opens the share.
-Where the server has no native Wallet profile the creation stays
-`CAPABILITY_UNAVAILABLE`, as before.
-
-`linkedWallets().refresh()` binds the account to the Wallet identity the
-provider owns for it and synchronizes the public wallet inventory. It carries
-no Wallet token; `challenge`, `connect` and `sync` with a caller-supplied token
-remain for deployments without that profile.
-
-Tracking a linked wallet needs no passkey: it signs with no wallet key, so the
-account's session authorizes it. `linkedWallets().register()` comes back
-`authorized` with the basis `session_authorized`, and
-`executeRegistration(operation.id, operation.version, key)` dispatches it; no
-hosted step takes part. A registration covers one network. An EVM wallet has
-one address on every EVM network, so register it once per EVM network;
-`events()` then returns the events of all of them, each with its
-`networkId`.
-
-`register()` takes an optional `activityTypes`: the kinds of activity events
-asked for beside deposits, for example `"transaction"` or `"erc20.approval"`.
-It accepts at most 16 distinct kinds, each matching
-`^[a-z][a-z0-9]*(?:[._][a-z0-9]+)*$`, and refuses any other value with
-`invalid_operation_create` before a request is sent. `activity_types` is sent
-only when the list is not empty; omitted or empty means deposits only. The
-server sorts the kinds. Streams decides which kinds a network has and refuses
-the registration otherwise. `createRegistration()` accepts the same list as
-`payload.activity_types`.
+`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).
 
-`linkedWallets().signals(linkedWalletIds, { onOpen, onWallets, signal })`
-opens one signal stream for 1 to 32 linked wallets and reads it to its end. On
-the stream Authorization names the wallets that have new events; it carries no
-event, and the wallets named are read with `events()`. `onOpen` says the
-stream is live: read every wallet once then, so that nothing falls between
-that read and the first signal. `onWallets` receives the wallets to read now.
-The promise resolves with why the stream ended: `expired`, `server_draining`
-or `connection_closed`. A stream lives no longer than an access token, so the
-caller opens the next one; the SDK renews the token when needed. The promise
-rejects with the server's refusal, with the abort reason, or when the
-connection fails or the answer is not this protocol. A signal is a hint: keep
-a timed read, only slower, for the times no stream is open. `demo/live.js`
-shows the loop.
-
-A send from a linked wallet needs no passkey either (owner decision, 14
-October 2026): the account's live session authorizes it. A passkey is still
-asked at sign-in, when a wallet is created and when its limits change
-(below). A send takes three calls, which the application makes one after
-another; the demo page makes all three on one press of «Отправить», with no
-confirmation step (Tony's decision, 15 October 2026), and says the fee
-estimate once the transfer was sent:
-
-1. `linkedWallets().send(input, key)` admits it. It comes back `authorized`
-   with the basis `session_authorized`, `nextAction` `none` and no
-   `confirmationLocation`; nothing is asked of the own-wallet system yet.
-2. `linkedWallets().prepare(operation.id)` has the own-wallet system prepare
-   the transfer and name its estimate of the network fee, and answers the
-   operation with what was prepared. It takes no body, key or version; the
-   transfer is prepared once, and calling it again answers the same prepared
-   send. The display then carries `network`, `asset`, `amountRaw`,
-   `recipient`, `comment` where there is one, `preparedSummary` and the fee.
-3. Read `transportKey()`, reseal the device share to it
-   (`resealDeviceShare`) and call `executeSend(operation.id,
-   operation.version, key, share)`.
-
-The display carries `feeEstimate` from the preparation on: `estimated` with
-`estimatedFeeRaw`, in minimal units of the network's own coin, or
-`unavailable` where that system could estimate none, which is never a fee of
-zero. The fee is paid on top of the amount, also for a token. It is an
-estimate: it does not bound what the network takes. The preparation caps the
-operation at 150 seconds: an `executeSend()` after that is refused with
-`OPERATION_EXPIRED` and the send is started again with `send()`. An `executeSend()` of a send
-that was never prepared is refused with `VERSION_CONFLICT` before anything is
-claimed. A send an earlier version of the provider admitted that still waits
-for its passkey is confirmed the old way (`challengeWalletOperation()`, the hosted
-page, `completeWalletOperationConfirmation()`); `prepare()` refuses it with
-`VERSION_CONFLICT`.
-
-A send from a linked wallet (`send()`, `prepare()`, `executeSend()`) ends as
-an operation when the own-wallet system
-accepted the transfer and named its hash: the operation is `succeeded` and its
-result carries the hash as `receiptId`. What the network then did with the
-transfer is read with `linkedWallets().transferStatus(operationId)`. It answers
-for the one transfer that operation prepared, with the own-wallet system's
-state of it: `prepared`, `executing`, `broadcasting`, `submitted`, `confirmed`,
-`failed` or `expired`. `final` is true for the last three. `transactionHash` is
-present once the transfer is signed; `failureReason` is the network's reason
-for a failure, when it gave one: its error code, or the own-wallet system's
-`expired`, `nonce_used` or `bounced`. `expired` means the transfer was never
-executed and moved no funds. Read it until `final`: while the state can still
-change the own-wallet system is asked on every read; the first final state is
-recorded by the provider and answered from the record afterwards. A send that
-was never prepared has no transfer and answers `NOT_FOUND`; a transfer whose
-fate was never read final before the 30-day material retention removed its
-identifier answers `RESULT_EXPIRED`; an own-wallet system that did not answer
-is `DEPENDENCY_UNAVAILABLE` and worth repeating.
-
-The preparation of a send can be refused in two ways that pass by themselves;
-both are `retryable` with `nextAction` `retry_same_request`, nothing is
-prepared, and the same `prepare()` succeeds later:
-
-- `TRANSFER_IN_FLIGHT` (409): an earlier transfer of the same wallet is not in
-  a block yet and holds the wallet's place in the network's sequence. It comes
-  on Ethereum, BNB Smart Chain and TON from an own-wallet system that sends one
-  transfer of a wallet at a time.
-- `NETWORK_FEE_TOO_HIGH` (503): the network fee is above the ceiling the
-  own-wallet system sends at. The preparation of a replacement answers it too.
-
-A preparation the own-wallet system or its network node could not serve in time
-answers `DEPENDENCY_UNAVAILABLE` (503), also to be repeated. It no longer
-answers `CAPABILITY_UNAVAILABLE`, which is left for a network the provider
-itself sends nothing on.
-
-An execution the own-wallet system refuses for good ends the operation
-`failed` with `effectState` `no_effect`: another transfer of the wallet took
-this one's place before it was signed, the place a replacement would take is
-already used (the replaced transfer went through or was replaced), or the
-node refused the transaction. Start the send again where it is still wanted.
-
-`transferStatus()` also tells:
-
-- `authorizationExpiresAt`, while the transfer is not final: the deadline of
-  the owner's authorization. Past it the own-wallet system signs and sends
-  nothing more for this transfer, but a transaction the network already has
-  can still be included. A transfer that is `submitted` past that instant is
-  neither done nor safely gone: it ends `confirmed`, or `failed` once another
-  transaction of the wallet takes its place. On an EVM network it can be sped
-  up or cancelled (`replaceSend()`).
-- `replacedByOperationId`, with `failureReason` `nonce_used`: the account's own
-  send whose transaction the network included instead, its speed-up or
-  cancellation or the next transfer of the same wallet. The funds may have
-  moved by that send. It is absent when the place was taken from outside the
-  own-wallet system, or by a send older than the account's last hundred. A
-  listed send carries it in `transfer.replacedByOperationId`.
-- `failureReason` `not_sent`: the transfer was signed only after its
-  authorization ran out and was never sent.
-
-On Ethereum an own-wallet system may report `confirmed` only when the block is
-twelve blocks deep, about two and a half minutes, and on BNB Smart Chain a
-hundred blocks deep: keep reading `submitted` for that long.
-
-A send on TON can carry a comment, the text an exchange or a custodian credits
-a deposit by: `linkedWallets().send({ ..., comment })`. It is 1 to 120 bytes
-of UTF-8 with no control character, line separator or character that reorders
-text (`transferComment(value)` is the rule, `MaxTransferCommentBytes` the
-bound), and it is sent exactly as given, spaces included. The own-wallet
-system writes it into the signed transaction, for the coin and for a token
-alike. The provider accepts the preparation only when it carries exactly that
-text and freezes it with the transfer: the display carries `comment` and the
-prepared summary quotes it. A comment on any other network is refused before any request by
-the SDK and with `PAYLOAD_NOT_SUPPORTED` by the provider. Stellar memos are
-not sent. A listed send (`sends()`) carries its `comment` too.
-
-A send on an EVM network that the network has not included can be replaced:
-`linkedWallets().replaceSend({ linkedWalletId, operationId, action }, key)`,
-where `operationId` is the account's own send from that wallet and `action` is
-`speed_up`, the same transfer again with a higher fee, or `cancel`, nothing
-sent to the wallet's own address in its place. The request names nothing of
-what is moved: the provider takes it from the transfer frozen in that
-operation. The answer is a `wallet.send` operation of its own, whose display
-carries `replacesOperationId` and `replaceAction`, and for a cancel
-`amountRaw` `"0"` of `native` to the wallet's own address. It is authorized
-by the session, prepared with `prepare()` and executed with `executeSend()`
-exactly like a send (on the demo page, on one press of «Ускорить» or
-«Отменить»); the own-wallet system prepares
-the replacement at `prepare()`, and the display then carries its fee
-estimate. Both transactions spend the same place
-in the wallet's sequence, so the network includes at most one: read
-`transferStatus()` of both, the other ends `failed`. The own-wallet system
-counts a replacement against the wallet's limits like a new transfer. Refusals:
-`NOT_FOUND` for an operation that is not the account's send from that wallet;
-`VERSION_CONFLICT` for a send the own-wallet system has not accepted, one whose
-final fate is recorded, and, at `prepare()`, one that system says no longer
-waits; `PAYLOAD_NOT_SUPPORTED` for a network that is not EVM and for a
-replacement that system refuses, for instance when the coin does not cover the
-higher fee; `RESULT_EXPIRED` once the send's material retention has passed. A
-replacement that waits can itself be replaced the same way.
+### Confirming an operation
 
-### Limits of a linked wallet
+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:
 
-Every send from a linked wallet obeys the wallet's own limits (owner decision
-of 14 October 2026): for each network and asset (`native`, `usdt`, `usdc`) an
-optional ceiling on one transfer (`perTransferRaw`) and on what the wallet's
-sends of that asset on that network may move in 24 hours (`perDayRaw`), in
-that network's minimal units, and a list of recipients, where an empty list
-means any recipient. A ceiling names its network because a token's decimals
-differ between networks (USDT has 6 on Ethereum and 18 on BNB Smart Chain);
-a send is judged only by the ceiling of its own network and asset. A wallet
-whose limits were never set (`revision` `"0"`) bounds nothing.
-
-- `linkedWallets().limits(linkedWalletId)` reads them with the session alone.
-- `linkedWallets().setLimits(linkedWalletId, { ceilings, recipients,
-  revision }, key)` asks to replace them as a whole; empty `ceilings` and
-  `recipients` remove every limit. `revision` is the revision of the limits
-  the change was edited from, as `limits()` read it: when the limits changed
-  since, in another tab for instance, the change is refused with
-  `VERSION_CONFLICT` when it is created or when it is executed, and never
-  overwrites them; read them again and redo the change. The answer is a local operation of kind `wallet_limits.set`,
-  `awaiting_confirmation` with `nextAction` `use_passkey`, whose display is
-  the wallet's address and the new limits as the provider will keep them
-  (recipients in the form the network compares addresses by). Nothing changes
-  until the owner confirms it with a passkey: `challengeOperation(id,
-  credentialId)` opens the provider's page, which says the new limits in
-  words, `completeOperationConfirmation(callback)` reads the confirmed
-  operation, and `executeOperation(id, version, key)` applies it; the result
-  kind is `wallet_limits`. A ceiling on a network the wallet does not send on,
-  a network and asset named twice, or a malformed amount is refused before
-  anything is admitted; another account's wallet is `NOT_FOUND`.
-
-A send the limits do not allow is refused with `403` and one of
-`WalletLimitRefusals`; nothing is sent, and the same send goes through only
-after the limits change:
-
-- `LIMIT_PER_TRANSFER_EXCEEDED`: the amount is over the ceiling of one
-  transfer of its asset on its network.
-- `LIMIT_DAILY_EXCEEDED`: with what the wallet's sends of that asset on that
-  network moved, or may have moved, in the last 24 hours, the send would pass
-  the daily ceiling.
-- `RECIPIENT_NOT_ALLOWED`: the wallet has a recipient list and the recipient
-  is not in it.
-
-`send()` and `replaceSend()` are answered `LIMIT_PER_TRANSFER_EXCEEDED` or
-`RECIPIENT_NOT_ALLOWED` at once, unless the same key repeats a send already
-created, which answers that send whatever the limits say now;
-`executeSend()` is judged again against the limits as they are then, with
-the daily total, and may answer any of the three. A speed-up is judged by
-the ceiling of one transfer and the list and adds nothing to the daily
-total, where the transfer it replaces is counted, but is refused when the
-day already holds more than the daily ceiling as it is now; a cancel is
-judged by none. `isWalletLimitRefusal(code)` tells these refusals
-from the others. The own-wallet system's own signing policies still apply on
-top of them.
-
-`linkedWallets().balances(linkedWalletId)` answers what a linked wallet holds:
-for each network its key has an address on, the network's own coin and the
-tokens the stand names there, in minimal units with their decimals. The
-provider reads its own stand's nodes, so the application hands the address to
-no node operator and needs no token list of its own. An EVM wallet has one
-entry for each EVM network of the stand. A network whose node gave nothing is
-in the answer with `status` `unavailable`, or `partial` when it gave some
-amounts, and an unread asset has no `amountRaw`: it is never zero. The assets
-are always named. Where the server has no nodes configured the read is
-`CAPABILITY_UNAVAILABLE`. Stellar is not read.
-
-`linkedWallets().sends({ limit, cursor })` is the account's history of sends,
-newest first: one page of `GET /v1/operations?kind=wallet.send`. Each row
-carries the send's state, its network, asset, recipient and amount in minimal
-units, the sending address of a linked wallet, its `transactionHash` once the
-own-wallet system accepted it, and `transfer`, the recorded final fate. A row
-with a hash and no `transfer` has not been read final yet: `transferStatus()`
-reads it and records it. A replacement is a row of its own with
-`replacesOperationId` and `replaceAction`. Listing asks nothing of the own-wallet system. Past
-the material retention a send stays listed with `materialPurged` and without
-details. The route lists every kind of account operation and takes any one
-`kind`; the SDK has a typed reader for sends only.
-
-`sendEvents(send, events)` picks from wallet events those of a listed send's
-transaction: its withdrawal and any activity of the same transaction.
-`eventOfTransaction(event, networkId, transactionHash)` is the test it uses. It
-answers on the EVM networks and TRON, where an event's `sourceReference` is the
-transaction hash in hexadecimal, and on Solana, where both are the
-transaction's signature in base58; it answers `undefined` elsewhere. On TON an
-event names the transaction the network made and the own-wallet system names
-the message it sent, so nothing ties the two yet.
-
-Solana is tracked like every other network once the stand's Streams serves it:
-`register({ linkedWalletId, network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" })`
-for a Solana wallet, whose address is taken as the own-wallet system gives it.
-Its assets are `<network>/slip44:501` for SOL and `<network>/spl:<mint>` for a
-token; its activity types are `transaction`, `native.transfer`, `spl.transfer`,
-`spl.approval`, `contract.raw`, `contract.decoded` and `native.action`. Its
-events are wallet events 3.0 with the transaction's signature as
-`sourceReference`.
-
-`demo/` is a static page that walks the whole path; see `demo/README.md`.
-
-## Authorized Streams reads
-
-`src/streams.ts` is the package's third entry point
-(`@shuttle.technology/authorization/streams`). It owns the client half of the four served
-reads and nothing else: it builds their exact `/v1` paths, enforces the page
-bounds before a request leaves the client, and parses the two closed responses.
-
-`AuthorizationClient.streams()` binds those reads to the current session, so an
-account caller reuses one access-token and refresh path and addresses
-`/v1/wallets/{wallet_id}/registrations` and `/events`. A service caller is a
-customer backend holding a tenant-access service credential, which this package
-never holds: it constructs `StreamsReads` with `scope: "service"` and its own
-authorized GET, exactly as the Mode C customer backend supplies its own
-forwarding, and addresses the `/v1/service/wallets/{wallet_id}` variants.
-
-The registrations route releases the permitted set in one page and issues no
-cursor, so the helper accepts only a limit and refuses a cursor locally. The
-events route accepts a cursor, a limit and the filter `eventTypes`; a wrapper
-carries its own original limit, so resuming omits the limit and repeating a
-different one is the server's `CURSOR_INVALID`. Every limit outside `[1,100]` is refused before a request
-exists, and the default page is 50.
-
-A page that has no next page still tells where to read on from:
-`window.latestCursor` is accepted as `cursor` and returns only what came after
-the end of the stream as that read saw it. `resumeCursor(page)` is the cursor
-to keep between rounds: `nextCursor` while `hasMore` is true, `latestCursor`
-after. A client walks a history once and from then on asks only for what is
-new. `window.earliestCursor` is never accepted as a cursor. Every cursor ends
-with its session and with a change of the wallet's registrations; a refused
-one is `CURSOR_INVALID` and the history is read from its start again. The same
-holds for `linkedWallets().events()`.
-
-The parsers are closed. An unknown or missing member, a noncanonical
-`amount_raw`, a nonintegral `revision`, a non-UTC `observed_at`, a `next_cursor`
-without `has_more` or the reverse, a `reverted` flag that disagrees with its
-`reverted_by_event_id`, and a malformed window are all refused rather than
-projected. `revision`, `project_cursor`, the reversion fields and every source
-position are released exactly as Streams owns them; no balance or finality is
-inferred and no event is reconstructed.
-
-### Wallet events 3.0: one shape for deposits, withdrawals and activity
-
-Events are read in one shape, the wallet event 3.0 (`WalletEvent`,
-`parseWalletEvent`, in `src/walletEvents.ts`):
-`client.linkedWallets().events(id, options)` for a linked wallet,
-`events(walletId, options)` on the account and service reads. There is no
-other read of events: the stored shapes the older `deposits()` released
-(`"2.0"`, `"activity:1.0"`, `"activity:2.0"`) are gone, and a page that
-carries one is refused.
-
-`eventTypes` filters by kind: `["deposit"]`, `["withdrawal"]`,
-`["deposit","withdrawal"]`, `["activity"]`, or `"activity:<type>"` for one
-type of activity, in any combination; left out, every kind. The filter is
-applied to the page that was read and does not change its cursor, so a
-filtered page may hold fewer events than the limit, or none, and still
-continue: follow `hasMore`, not the number of events.
-
-```json
-{"contract_version":"3.0","event_id":"project-event:v1:…:1","cursor":"2.1",
- "kind":"deposit","status":"completed","revision":"1",
- "subject_id":"deposit-id:v1:…","registration_id":"…","network_id":"eip155:1",
- "address":"0x…","asset":"eip155:1/slip44:60","raw_amount":"10000000000000",
- "source_reference":"0x…","observed_at":"2026-10-09T09:54:47Z"}
+```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 } }
+}
 ```
 
-- `kind` is `deposit` (value came in), `withdrawal` (value went out) or
-  `activity` (anything else; it has `activity_type` and may have a body).
-- `status` is `completed` (it is in a block), `finalized` (the block is final)
-  or `reverted` (the block was replaced; `invalidation_reason` may say why).
-- `revision` counts a subject's statuses from `"1"`; `subject_id` is what they
-  are about. completed is always revision 1.
-- `cursor` is the event's own place in the stream, an opaque text no two
-  events share. A stream of wallet events is continued after it.
-
-Every subject is told at least twice, completed and then finalized, on every
-network. Where a block is final as soon as it exists the two arrive together;
-on Ethereum a deposit is completed within seconds and finalized thirteen to
-nineteen minutes later. A client that acts once a transfer is in a block waits
-for `completed` and may ignore what follows it, except `reverted`.
-
-What is told today: a deposit, a withdrawal and an activity on every network.
-On Ethereum all three are completed within seconds and finalized later; an
-activity's completed event carries its payload up to 16 KiB. BNB Smart Chain,
-TRON and TON are read as each block becomes final, so there both revisions of
-any event arrive together.
-
-The page is `WalletEventPage`. One stored event gives no event, one or two, so
-a page holds at most twice the limit asked for.
-
-Read a deposit's `status` as where the transfer stands, not as whether it
-happened. `pending` is the fact: the transfer lies, successful, in a block of
-the chain as it stands, and the recipient can already spend it; show it to the
-user as received. `confirmed` comes after the fact and adds that the block is
-final and cannot be replaced; it is the moment to credit a balance kept outside
-the chain. `detected` precedes both, and `reverted` ends a deposit whose block
-was replaced before it became final. On Ethereum a block becomes final thirteen
-to nineteen minutes after it appears.
-
-An activity event carries no status. On Ethereum it is released when its block
-is final, so an outgoing transfer of a tracked wallet is seen that much later
-than it happened; on BNB Smart Chain, TRON and TON the wait is seconds.
-
-An expired boundary is the server's `RESYNC_REQUIRED`, which the SDK rethrows
-unchanged and never retries. `streamsResync(error)` returns the typed authorized
-window, and `parseAuthorizationError` already refuses a window on any other code
-and a `RESYNC_REQUIRED` without one. Those two values are window wrappers, not
-pagination wrappers: the server binds each released wrapper to its own boundary
-and answers `CURSOR_INVALID` for a substituted one, so the restart is a fresh
-cursorless read. The SDK never converts a window value into a cursor and never
-invents a position.
-
-`pollStreamsDeposits` follows a page until the server itself reports no further
-retained work. It adds no bound of its own and delegates to the same
-`pollAuthoritative` helper, so at-least-two-second intervals and the
-sixty-second ceiling stay enforced in one place, and cancellation or timeout
-returns the last observed page with its local disposition rather than a claimed
-server outcome.
-
-## A backend client of an organization (Mode A)
-
-This package is the client of a person's session. A customer's backend that
-holds a Tenant Access key acts for its organization instead (owner decision,
-14 October 2026): it creates the organization's wallets with a device key it
-keeps itself, tracks them, reads them, their balances, events and its own
-operations, sets each wallet's limits (per asset a ceiling on one transfer
-and on 24 hours, and a recipient list where the empty list means any
-recipient) and sends the network coin, USDT and USDC from them with a
-prepare and an execute that carries the device share, with no passkey. The
-service routes are `/v1/service/operations` (with `/prepare`) and
-`/v1/service/wallets` (with `/balances`, `/transport-key`, `/limits`,
-`/registrations`, `/events`); see `api/authorization/openapi.yaml`.
-
-`examples/backend-client` is that backend in a small Node program, the
-backend counterpart of the demo page. It reuses this package's device share
-crypto (`resealDeviceShare`) and keeps the device key, extractable, in a
-private state file. Its README says how to run it and what the stand's
-operator must set first. `test/backendClient.test.ts` covers its pure parts.
-
-## Local verification
-
-Use the package-local pinned toolchain:
+`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.
 
-```sh
-pnpm install --frozen-lockfile
-pnpm run verify
+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 }]
 ```
 
-`verify` runs syntax checks, full TypeScript checking (including fixtures), a
-clean JavaScript build, and package tests.
+`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.
 
-Release packaging is checked from an installed tarball with the reviewed npm
-CLI. The smoke check imports every public entry point, compiles a TypeScript
-consumer against the installed declarations, verifies that consumer installs
-do not include TypeScript, and rejects unexpected tarball files:
+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:
 
-```sh
-NPM_CLI_JS=/absolute/path/to/npm-cli.js pnpm run package:smoke
+```ts
+const response = await fetch("https://backend.example.com/orders", {
+  headers: { Authorization: `Bearer ${await client.accessToken()}` },
+});
 ```
 
-The PostgreSQL-backed HTTP integration harness builds first, then invokes:
+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`:
 
-```sh
-pnpm run build
-pnpm run integration:http -- --fixture /absolute/path/to/sdk-fixture.json
+```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"
 ```
 
-The fixture runner accepts only local TLS endpoints rooted in its supplied CA.
-It drives the compiled SDK through public initialization, Google signup,
-handoff exchange, safe reads, logout and revoked-token denial, then logs in the
-same signed provider subject and verifies that it resolves to the same account.
+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
+```
 
-### Contract runners against the real Authorization server
+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.
 
-`test/http-integration-{linked-send,limits,modec-linked,mode-a,demo}.mjs` drive
-the compiled SDK (`dist/`), the backend simulator's own modules
-(`examples/backend-client/`) and the demo page's (`demo/*.js`, without the DOM)
-against the real Authorization HTTP server
-over TLS, composed as the runtime composes it, with PostgreSQL, the decision
-signer, claimer, worker and native Wallet adapter; only the Wallet, Tenant
-Access's producer side (behind the shipped Tenant Access client) and the
-stand's nodes are stand-ins. The Go tests `TestCompiledSDK*` and
-`TestBackendSimulatorModeA*` in `internal/authorization/store/postgres` run
-them, each compiling the SDK from the current source into a scratch directory
-with the installed TypeScript compiler (`tests/authorization/tooling/sdkrunner`),
-with the Node of `NODE_BIN` or of `PATH`:
+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
-TEST_DATABASE_URL=... go test ../../internal/authorization/store/postgres -run 'TestCompiledSDK|TestBackendSimulator'
+pnpm run verify          # syntax checks, typecheck, build, unit tests
+npm pack                 # builds dist and writes shuttle.technology-authorization-<version>.tgz
 ```
 
-Each runner prints one summary line; the Go side checks that the runner
-loads the SDK only from `dist/`, that the build it reports is the build it
-compiled, and that every HTTP call it counted came from that build. Every
-answer the server gives in these flows is also checked against the committed
-OpenAPI document. The joined linked-wallet test
-(`internal/authorization/wallethttp`, `test/http-integration-linked-wallets.mjs`)
-runs the same way, with the Node of `AUTH_SDK_NODE_BIN` or of `PATH`, and uses
-the build of `AUTH_SDK_WORKDIR` when the local acceptance below prepared one.
+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:
 
-### Required local linked-wallet acceptance
+```sh
+TEST_DATABASE_URL=... go test ./internal/authorization/store/postgres -run 'TestCompiledSDK|TestBackendSimulator'
+TEST_DATABASE_URL=... go test ./internal/authorization/runtime -run 'TestCompiled|TestBuiltSDK'
+```
 
-From repository root, using already prepared offline tools/dependencies:
+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"
 ```
-
-Provide Go1.26.7, Node24.19.0, PostgreSQL18.6 and an explicit separate SDK dependency
-isolate prepared for the current package/lock. No install or download runs. The target
-checks dependency manifest/installed lock/version provenance, copies current worktree
-SDK source/config/runner to new scratch and builds fresh dist with the prepared tsc.
-Unused isolate src/dist never supply execution code. Its dependency symlink is trusted
-reuse, not a filesystem read-only sandbox; existing dependencies are not mutated.
-
-The disposable-PG race run requires the actual SDK/TLS/Auth/Streams test plus direct
-and lost-response/store-reopen cases, each present and passed with zero skips. Missing
-inputs, stale dependency manifests, omitted tests or a skipped result fail the command.
-Generic suites retain optional SDK behavior; this explicit target is mandatory local
-proof. Source effects/events are synthetic and passkey is virtual crypto. It needs no
-external pilot pins or lookup and makes no deployed-provider/browser/indexer claim.