@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to `@shuttle.technology/authorization`. Versions follow
+[Semantic Versioning](https://semver.org/); before 1.0.0 a minor version may
+change the public API.
+
+## 0.2.0 — release candidate
+
+- Uses the public package name `@shuttle.technology/authorization`.
+- Preserves all eight current entry points, including
+  `./debit-permissions`, and the latest recovery, wallet-create grant,
+  registration, debit, session, wallet, and Streams behavior described below.
+- Ships compiled ESM JavaScript and TypeScript declarations only; source maps,
+  TypeScript source, tests, demos, examples, and local state are excluded.
+
+### Any domain, and the current page by default
+
+- `initializeAuthorizationClient()` takes `ClientSettings`: on the web,
+  `applicationOrigin` and `redirectUri` are optional and default to the current
+  page's origin and the current page.
+- The app's origin and redirect may be http on a loopback host (`localhost`,
+  `127.0.0.1`, `[::1]`) for local development, besides https.
+- A public client registered for any origin answers `redirects: ["*"]`; the
+  SDK accepts it and any redirect its own checks accept.
+
+### Debits come with the grant
+
+- A service that holds `wallet:debit:user` gets its debit permission with
+  every wallet the person opens to it, in the same passkey confirmation:
+  `createWallet({ network, grant })` and `createServiceGrant()` take nothing
+  new. The creation's and the grant's display name the service's ceilings
+  (`display.debit`), and the provider's page says them.
+- `walletOperationResult()` and `operationResult()` execute the permission
+  the consent authorized, with the device share the SDK keeps sealed to the
+  share keeper's key, and report `result.debit`: `succeeded` (with the
+  permission's operation ID) or `not_set` with `code`.
+- `debitPermissions().executeDebitPermission()` without keys hands the share
+  the SDK keeps; the keys of an app that keeps its own share are unchanged.
+
+### A wallet keeps working in a new browser
+
+- The SDK keeps each wallet's device share itself, with the non-extractable
+  device key it is sealed to: in the origin's IndexedDB on the web, in the
+  `deviceShares` store (`DeviceShareStore`) the app passes in the
+  dependencies on mobile (and optionally on the web).
+- `createWallet({ network })` without `recipientPublicKey` makes the device
+  key in the SDK; `walletOperationResult()` keeps the created share. Calls
+  with the same `Idempotency-Key`, also at once, name the same key. The call with the app's
+  own key is unchanged.
+- `linkedWallets().executeSend(id, version, key)` without a share sends with
+  the kept one, resealed to the transport key read right before.
+  `linkedWallets().deviceShareFor(linkedWalletId)` is that share for a Mode C
+  request (`signLinkedMediatedRequest`). A share the app passes itself is sent
+  as before and the SDK recovers nothing for it.
+- In a browser that holds no share of the wallet (a new domain, cleared site
+  data, another browser or device) these calls first recover it: one passkey
+  confirmation on the provider's page (`wallet.recover` naming
+  `linked_wallet_id` and the new device key), after which the share the
+  wallet had elsewhere stops working. The tabs of one browser recover a wallet
+  once between them, under one Web Lock per wallet.
+- A kept share that a recovery on another device replaced is told by the
+  device key the provider names for the wallet (`linkedWallets().deviceKey()`,
+  `GET /v1/linked-wallets/{id}/device-key`) and recovered with one passkey
+  confirmation. Every kept record carries its device key's `publicKeyHex`.
+- A confirmed recovery is kept pending (its device key, operation and execute
+  key, no share) before it is executed. One whose end is not known yet fails
+  the call with `device_recovery_failed`, and the next call, in any tab,
+  resumes that same operation instead of starting another, also after an
+  execution the provider refused while another recovery of the wallet was
+  unresolved. A share resumed or recovered while another device recovered
+  after it is recovered once more, then `device_recovery_failed`. A creation's
+  result read late never replaces a recovery another tab kept.
+- Optional: `linkedWallets().hasDeviceShare(linkedWalletId)` and
+  `linkedWallets().recoverDevice(linkedWalletId, { credentialId?, signal?, force? })`;
+  `force` recovers even when a current share is kept.
+- New `ClientFlowError` codes: `device_share_unavailable`,
+  `device_recovery_requires_passkey`, `hosted_callback_unavailable`,
+  `device_recovery_not_confirmed`, `device_recovery_failed`.
+- `challengeOperation()` and `challengeWalletOperation()` answer
+  `callbackUri`, the redirect the host's `openHosted` resolved with, when it
+  resolved one.
+- `walletOperationResult()` reads a `device_share_recovered` result
+  (`linkedWalletId`, `deviceShare`), and a wallet operation may be a
+  `wallet.recover` of a linked wallet (`LinkedRecoverDisplay`). Code that told
+  a linked send's display by `"linkedWalletId" in display` now also checks
+  `display.kind === "wallet.send"`.
+- The demo page sends from a wallet in any browser of the account: the first
+  send there asks for the passkey once.
+
+### Create a wallet and connect it in one confirmation
+
+- `createWallet({ network, recipientPublicKey?, grant? })`: `grant`
+  (`{ servicePrincipalId, scopes, externalRef? }`, the rules of
+  `createServiceGrant()`, one to three scopes) opens the new wallet to a
+  service in the same passkey confirmation. The SDK checks it locally
+  (`invalid_operation_create`), sends the scopes in the provider's order and
+  refuses a display that does not name the grant back.
+- The `wallet.create` display carries `grant`, and a `wallet_created` result
+  carries `grant: { state, operationId?, linkedWalletId?, code? }`:
+  `succeeded`, `pending_target_fence` (read `client.operation(operationId)`
+  until it ends) or `not_set` with `code` (`DEPENDENCY_UNAVAILABLE`: read the
+  result again; any other: `createServiceGrant()` alone). The plain call is
+  unchanged.
+- The demo page offers its backend's service (`backendService`) in the
+  creation's confirmation, on by default, and says whether the service sees
+  the wallet.
+
+### Current capability summary
+
+(Integration of 28 October 2026: an account's grant list may show `pending_source`, a first
+`streams:read` grant waiting for Streams.)
+
+The first release: the client of a person's session for web and mobile apps.
+
+### Package
+
+- ES modules in `dist/` with TypeScript declarations. Entry points: the root
+  (`AuthorizationClient`), `./mode-c-linked`, `./mode-c`, `./linked-wallets`,
+  `./debit-permissions`, `./streams`, `./device-key`, `./device-share`.
+- No runtime dependencies. Needs `fetch` and WebCrypto: a current browser,
+  Node 20 or later, or a mobile runtime that provides both. The web channel
+  also needs the Web Locks API (`navigator.locks`).
+
+### Sign-in and session
+
+- `login()` and `signup()` open the provider's hosted sign-in page, where the
+  person picks a method; `exchangeHandoff()` turns the redirect back into the
+  session. `login(method)` and `signup(method)` still start one method.
+- Mobile: one `login()` call opens the hosted page in the system browser,
+  checks the app link and returns the session; the refresh token lives in the
+  secure storage the app supplies.
+- `me()` returns the account, the session and every wallet of the account
+  (own and linked).
+- `accessToken()` returns the session's access token for the app's own
+  backend, renewed first when it has less than 30 seconds to live.
+- Web: the session renews in the background (`refreshSession()`, and every
+  call that needs a fresh token) from the provider's partitioned cookie, with
+  no window; the tabs of one app take turns under one Web Lock, and a
+  sign-in's exchange goes out under it too, so a late renewal never brings
+  back an older session. Without the
+  cookie the SDK raises `web_renewal_requires_navigation` and the app calls
+  `restoreSession()`, the top-level restore.
+- Web: a renewal or restore answers only the session it renews. When a
+  sign-in in another tab put its own session in the shared cookie, the SDK
+  installs nothing, ends the session it held and raises `session_replaced`;
+  the app takes up the cookie's session with `refreshSession()` or signs the
+  person in again. A sign-in answer a logout or a newer sign-in overtook is
+  revoked, through the cookie when another tab replaced its CSRF token, and a
+  logout that overtook it confirms nothing until that revocation is
+  confirmed (an answer lost or malformed counts as unconfirmed). A caller's signal ends only its wait for an exchange or a
+  logout, never the request.
+
+### Wallets
+
+- First wallet with a passkey (`bootstrapPasskey()`, `createWallet()`), the
+  device share sealed to a key of the device.
+- Linked wallets: list, balances, events and a live signal stream, Streams
+  tracking, sends with the session (Mode B), speed-up and cancel, transfer
+  status, and the wallet's limits, changed with a passkey.
+- Mode C: request-key enrollment on a linked wallet and the signed request a
+  service forwards.
+- Debit permissions (`linkedWallets().debitPermissions()`): a service debits a
+  linked wallet without the device, within bounds the person confirms with a
+  passkey; the execute hands the device share to the platform share keeper,
+  sealed to the keeper's key. List and revoke.
+
+### Service grants
+
+- `createServiceGrant()` gives a service read access to one wallet, with an
+  optional `externalRef`.
+- `serviceGrants()` lists the grants the account gave, in every state, paged.
+- `revokeServiceGrant()` withdraws one.
+
+### Errors
+
+- `AuthorizationError.code` is typed: one of `AuthorizationErrorCodes`, the
+  codes of the provider's OpenAPI document, with `AuthorizationErrorContracts`
+  giving the status, `retryable` and `nextAction` of each.
+- `isAuthorizationError(error, ...codes)`, `WalletLimitRefusals` and
+  `ModeCRefusals` for the refusals an app explains to the person.
+  `DEBIT_PERMISSION_INVALID` (403): a debit no active permission covers.
+
+## 0.1.0 — published 24 October 2026
+
+- Initial public ESM package under `@shuttle.technology/authorization` with
+  TypeScript declarations and seven entry points.
+- Supplied the then-current Authorization wallet/session and Streams client
+  surface. Version 0.2.0 adds the later session, recovery, wallet-create grant,
+  registration, debit-permission, and related API behavior recorded above.
+- The published 0.1.0 archive is the authority for that version's exact
+  surface.