@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,709 @@
-# Temporary Holding Version
+# Streams Authorization SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Installation
+
+```sh
+npm install @shuttle.technology/authorization
+```
+
+The package ships compiled ESM and TypeScript declarations. Its public entry
+points are:
+
+```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";
+```
+
+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.
+
+### Mode C on a linked wallet
+
+`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`.
+
+`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.
+
+### Limits of a linked wallet
+
+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"}
+```
+
+- `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:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run verify
+```
+
+`verify` runs syntax checks, full TypeScript checking (including fixtures), a
+clean JavaScript build, and package tests.
+
+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:
+
+```sh
+NPM_CLI_JS=/absolute/path/to/npm-cli.js pnpm run package:smoke
+```
+
+The PostgreSQL-backed HTTP integration harness builds first, then invokes:
+
+```sh
+pnpm run build
+pnpm run integration:http -- --fixture /absolute/path/to/sdk-fixture.json
+```
+
+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.
+
+
+### Contract runners against the real Authorization server
+
+`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`:
+
+```sh
+pnpm install --frozen-lockfile
+TEST_DATABASE_URL=... go test ../../internal/authorization/store/postgres -run 'TestCompiledSDK|TestBackendSimulator'
+```
+
+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.
+
+### Required local linked-wallet acceptance
+
+From repository root, using already prepared offline tools/dependencies:
+
+```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.