@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/slice4.js

@@ -0,0 +1,299 @@
+import { ClientFlowError, canonicalDecimal, deadlineAfter, identityMethods, integer, isNextAction, opaqueId, record, rfc3339UTC, unexpiredRFC3339, } from "./auth.js";
+import { parseWalletLimitsDisplay } from "./walletLimits.js";
+import { parseDebitPermissionDisplay, parseDebitPermissionRevokeDisplay } from "./debitPermissionWire.js";
+import { parseConsentDebitOutcome, parseDebitTerms } from "./consentDebit.js";
+import { parseLinkedEnrollmentDisplay, parseLinkedRequestGrantResult, validateLinkedEnrollmentCreate, } from "./modeCLinked.js";
+/** parseIdentityList accepts the closed answer of GET /v1/identities. */
+export function parseIdentityList(payload) {
+    const root = record(payload, ["request_id", "items"]);
+    if (!opaqueId(root.request_id) || !Array.isArray(root.items) || root.items.length > 1000)
+        throw new ClientFlowError("invalid_server_response");
+    const items = root.items.map((value) => {
+        const item = record(value, ["identity_id", "method", "created_at"], ["credential_id"]);
+        const passkey = item.method === "passkey";
+        if (!opaqueId(item.identity_id) || typeof item.method !== "string" || !identityMethods.includes(item.method) || typeof item.created_at !== "string" || Number.isNaN(Date.parse(item.created_at)) ||
+            passkey !== (item.credential_id !== undefined) || (passkey && (typeof item.credential_id !== "string" || !/^[A-Za-z0-9_-]{1,1024}$/.test(item.credential_id)))) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        const identity = { identityId: item.identity_id, method: item.method, createdAt: item.created_at };
+        if (passkey)
+            identity.credentialId = item.credential_id;
+        return identity;
+    });
+    if (new Set(items.map((item) => item.identityId)).size !== items.length)
+        throw new ClientFlowError("invalid_server_response");
+    return items;
+}
+export function parseHostedIdentityFlow(payload, now) {
+    const root = record(payload, ["request_id", "flow_id", "launch_url", "expires_at"]);
+    if (!opaqueId(root.request_id) || !opaqueId(root.flow_id) || !httpsURL(root.launch_url) || !integer(root.expires_at) || root.expires_at <= now / 1_000) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return { requestId: root.request_id, flowId: root.flow_id, launchUrl: root.launch_url, expiresAt: root.expires_at };
+}
+export function parsePasskeyBootstrapResult(payload) {
+    const root = record(payload, ["request_id", "credential_id", "version", "state"]);
+    if (!opaqueId(root.request_id) || !opaqueId(root.credential_id) || !canonicalDecimal(root.version) || root.state !== "active") {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return { requestId: root.request_id, credentialId: root.credential_id, version: root.version, state: root.state };
+}
+export function parseVerifiedIdentityResult(payload, now) {
+    const root = record(payload, ["request_id", "verified_identity_handle", "expires_at"]);
+    if (!opaqueId(root.request_id) || !opaqueId(root.verified_identity_handle) || !integer(root.expires_at) || root.expires_at <= now / 1_000) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return { requestId: root.request_id, verifiedIdentityHandle: root.verified_identity_handle, expiresAt: root.expires_at };
+}
+export function parseIdentityFlowCallback(value, expectedRedirect) {
+    let callback;
+    let target;
+    try {
+        callback = new URL(value);
+        target = new URL(expectedRedirect);
+    }
+    catch {
+        throw new ClientFlowError("invalid_callback");
+    }
+    if (`${callback.origin}${callback.pathname}` !== `${target.origin}${target.pathname}` || callback.hash !== "" || callback.searchParams.size !== 3) {
+        throw new ClientFlowError("invalid_callback");
+    }
+    const code = callback.searchParams.getAll("code");
+    const state = callback.searchParams.getAll("state");
+    const flowId = callback.searchParams.getAll("flow_id");
+    if (code.length !== 1 || state.length !== 1 || flowId.length !== 1 || !opaqueId(code[0]) || !opaqueId(state[0]) || !opaqueId(flowId[0])) {
+        throw new ClientFlowError("invalid_callback");
+    }
+    return { code: code[0], state: state[0], flowId: flowId[0] };
+}
+export function validateLocalOperationCreate(value, expectedOwnerId) {
+    const common = record(value, ["kind", "owner_type", "owner_id", "payload"], ["wallet_id", "result_recipient"]);
+    if (common.owner_type !== "account" || common.owner_id !== expectedOwnerId || !opaqueId(common.owner_id))
+        throw new ClientFlowError("invalid_operation_create");
+    if (common.result_recipient !== undefined) {
+        const recipient = record(common.result_recipient, ["type", "id"]);
+        if ((recipient.type !== "account" && recipient.type !== "service") || !opaqueId(recipient.id))
+            throw new ClientFlowError("invalid_operation_create");
+    }
+    switch (common.kind) {
+        case "identity.link": {
+            if (common.wallet_id !== undefined)
+                throw new ClientFlowError("invalid_operation_create");
+            const payload = record(common.payload, ["verified_identity_handle"]);
+            if (!opaqueId(payload.verified_identity_handle))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "identity.unlink": {
+            if (common.wallet_id !== undefined)
+                throw new ClientFlowError("invalid_operation_create");
+            const payload = record(common.payload, ["identity_id"]);
+            if (!opaqueId(payload.identity_id))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "session.revoke": {
+            if (common.wallet_id !== undefined)
+                throw new ClientFlowError("invalid_operation_create");
+            const payload = record(common.payload, ["session_id"]);
+            if (!opaqueId(payload.session_id))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "service_grant.set": {
+            if (!opaqueId(common.wallet_id))
+                throw new ClientFlowError("invalid_operation_create");
+            const payload = record(common.payload, ["service_principal_id", "enabled", "scopes"], ["external_ref"]);
+            if (!opaqueId(payload.service_principal_id) || typeof payload.enabled !== "boolean" || !serviceScopes(payload.scopes) || (payload.external_ref !== undefined && !printableReference(payload.external_ref))) {
+                throw new ClientFlowError("invalid_operation_create");
+            }
+            break;
+        }
+        case "session.authorize_requests":
+            validateLinkedEnrollmentCreate(value, expectedOwnerId);
+            break;
+        default:
+            throw new ClientFlowError("invalid_operation_create");
+    }
+    return value;
+}
+export function parseOperationEnvelope(payload) {
+    const root = record(payload, ["request_id", "operation"]);
+    if (!opaqueId(root.request_id))
+        throw new ClientFlowError("invalid_server_response");
+    return { requestId: root.request_id, operation: parseOperation(root.operation) };
+}
+export function parseOperation(payload) {
+    const root = record(payload, [
+        "id", "version", "kind", "state", "effect_state", "authorization_basis", "owner_type", "owner_id", "requester_id",
+        "request_fingerprint", "operation_fingerprint", "display", "created_at", "expires_at", "next_action",
+    ], ["wallet_id", "confirmation_location", "result_kind"]);
+    if (!opaqueId(root.id) || !canonicalDecimal(root.version) || !localOperationKind(root.kind) || !operationState(root.state) || !effectState(root.effect_state) || (root.authorization_basis !== "" && root.authorization_basis !== "user_confirmed") || root.owner_type !== "account" || !opaqueId(root.owner_id) || !opaqueId(root.requester_id) || (root.wallet_id !== undefined && !opaqueId(root.wallet_id)) || !lowerHexDigest(root.request_fingerprint) || !lowerHexDigest(root.operation_fingerprint) || !rfc3339UTC(root.created_at) || !rfc3339UTC(root.expires_at) || !deadlineAfter(root.created_at, root.expires_at) || (root.confirmation_location !== undefined && !httpsURL(root.confirmation_location)) || (root.result_kind !== undefined && !localResultKind(root.result_kind)) || !isNextAction(root.next_action)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const display = parseDisplay(root.display, root.kind);
+    if (display.ownerId !== root.owner_id || display.requesterId !== root.requester_id) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if (root.kind === "service_grant.set") {
+        if (display.kind !== "service_grant.set" || root.wallet_id === undefined || display.walletId !== root.wallet_id)
+            throw new ClientFlowError("invalid_server_response");
+    }
+    else if (root.wallet_id !== undefined) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const operation = {
+        id: root.id,
+        version: root.version,
+        kind: root.kind,
+        state: root.state,
+        effectState: root.effect_state,
+        authorizationBasis: root.authorization_basis,
+        ownerType: root.owner_type,
+        ownerId: root.owner_id,
+        requesterId: root.requester_id,
+        requestFingerprint: root.request_fingerprint,
+        operationFingerprint: root.operation_fingerprint,
+        display,
+        createdAt: root.created_at,
+        expiresAt: root.expires_at,
+        nextAction: root.next_action,
+    };
+    if (root.wallet_id !== undefined)
+        operation.walletId = root.wallet_id;
+    if (root.confirmation_location !== undefined)
+        operation.confirmationLocation = root.confirmation_location;
+    if (root.result_kind !== undefined)
+        operation.resultKind = root.result_kind;
+    return operation;
+}
+export function parseConfirmationChallenge(payload, now) {
+    const root = record(payload, ["request_id", "challenge_id", "public_key", "confirmation_location", "expires_at"]);
+    const publicKey = record(root.public_key, ["challenge", "rp_id", "timeout_ms", "allow_credentials", "user_verification"]);
+    if (!opaqueId(root.request_id) || !opaqueId(root.challenge_id) || !base64url(publicKey.challenge) || typeof publicKey.rp_id !== "string" || publicKey.rp_id.length === 0 || !integer(publicKey.timeout_ms) || publicKey.timeout_ms < 1 || publicKey.timeout_ms > 120_000 || !Array.isArray(publicKey.allow_credentials) || publicKey.allow_credentials.length !== 1 || publicKey.user_verification !== "required" || !httpsURL(root.confirmation_location) || !unexpiredRFC3339(root.expires_at, now)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const credential = record(publicKey.allow_credentials[0], ["type", "id"]);
+    if (credential.type !== "public-key" || !base64url(credential.id))
+        throw new ClientFlowError("invalid_server_response");
+    return {
+        requestId: root.request_id,
+        challengeId: root.challenge_id,
+        publicKey: { challenge: publicKey.challenge, rpId: publicKey.rp_id, timeoutMs: publicKey.timeout_ms, allowCredentials: [{ type: "public-key", id: credential.id }], userVerification: "required" },
+        confirmationLocation: root.confirmation_location,
+        expiresAt: root.expires_at,
+    };
+}
+export function parseOperationConfirmationCallback(value, expectedRedirect) {
+    let callback;
+    let target;
+    try {
+        callback = new URL(value);
+        target = new URL(expectedRedirect);
+    }
+    catch {
+        throw new ClientFlowError("invalid_callback");
+    }
+    if (`${callback.origin}${callback.pathname}` !== `${target.origin}${target.pathname}` || callback.hash !== "" || callback.searchParams.size !== 2)
+        throw new ClientFlowError("invalid_callback");
+    const state = callback.searchParams.getAll("state");
+    const operationId = callback.searchParams.getAll("operation_id");
+    if (state.length !== 1 || operationId.length !== 1 || !opaqueId(state[0]) || !opaqueId(operationId[0]))
+        throw new ClientFlowError("invalid_callback");
+    return { state: state[0], operationId: operationId[0] };
+}
+export function parseLocalOperationResult(payload) {
+    const root = record(payload, ["request_id", "result"]);
+    const result = record(root.result, ["kind", "target_id", "new_version", "state"], ["grant", "debit"]);
+    if (!opaqueId(root.request_id) || !localResultKind(result.kind) || !opaqueId(result.target_id) || !canonicalDecimal(result.new_version) || (result.state !== "active" && result.state !== "revoked") ||
+        (result.grant !== undefined) !== (result.kind === "request_grant") || (result.debit !== undefined && result.kind !== "service_grant")) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const parsed = { kind: result.kind, targetId: result.target_id, newVersion: result.new_version, state: result.state };
+    if (result.grant !== undefined) {
+        parsed.grant = parseLinkedRequestGrantResult(result.grant);
+        if (parsed.grant.requestGrantId !== result.target_id)
+            throw new ClientFlowError("invalid_server_response");
+    }
+    if (result.debit !== undefined)
+        parsed.debit = parseConsentDebitOutcome(result.debit);
+    return { requestId: root.request_id, result: parsed };
+}
+function parseDisplay(value, kind) {
+    if (kind === "identity.link") {
+        const display = record(value, ["kind", "owner_id", "requester_id", "method"]);
+        if (display.kind !== kind || !opaqueId(display.owner_id) || !opaqueId(display.requester_id) || typeof display.method !== "string" || !identityMethods.includes(display.method))
+            throw new ClientFlowError("invalid_server_response");
+        return { kind, ownerId: display.owner_id, requesterId: display.requester_id, method: display.method };
+    }
+    if (kind === "identity.unlink") {
+        const display = record(value, ["kind", "owner_id", "requester_id", "identity_id"]);
+        if (display.kind !== kind || !opaqueId(display.owner_id) || !opaqueId(display.requester_id) || !opaqueId(display.identity_id))
+            throw new ClientFlowError("invalid_server_response");
+        return { kind, ownerId: display.owner_id, requesterId: display.requester_id, identityId: display.identity_id };
+    }
+    if (kind === "wallet_limits.set")
+        return parseWalletLimitsDisplay(value);
+    if (kind === "session.authorize_requests")
+        return parseLinkedEnrollmentDisplay(value);
+    if (kind === "debit_permission.create")
+        return parseDebitPermissionDisplay(value);
+    if (kind === "debit_permission.revoke")
+        return parseDebitPermissionRevokeDisplay(value);
+    if (kind === "session.revoke") {
+        const display = record(value, ["kind", "owner_id", "requester_id", "session_id"]);
+        if (display.kind !== kind || !opaqueId(display.owner_id) || !opaqueId(display.requester_id) || !opaqueId(display.session_id))
+            throw new ClientFlowError("invalid_server_response");
+        return { kind, ownerId: display.owner_id, requesterId: display.requester_id, sessionId: display.session_id };
+    }
+    const display = record(value, ["kind", "owner_id", "requester_id", "wallet_id", "service_principal_id", "enabled", "scopes"], ["external_ref", "debit"]);
+    if (display.kind !== kind || !opaqueId(display.owner_id) || !opaqueId(display.requester_id) || !opaqueId(display.wallet_id) || !opaqueId(display.service_principal_id) || typeof display.enabled !== "boolean" || !serviceScopes(display.scopes) || (display.external_ref !== undefined && !printableReference(display.external_ref)))
+        throw new ClientFlowError("invalid_server_response");
+    const result = { kind, ownerId: display.owner_id, requesterId: display.requester_id, walletId: display.wallet_id, servicePrincipalId: display.service_principal_id, enabled: display.enabled, scopes: display.scopes };
+    if (display.external_ref !== undefined)
+        result.externalRef = display.external_ref;
+    if (display.debit !== undefined)
+        result.debit = parseDebitTerms(display.debit);
+    return result;
+}
+function localOperationKind(value) {
+    return value === "identity.link" || value === "identity.unlink" || value === "session.revoke" || value === "service_grant.set" || value === "wallet_limits.set" || value === "session.authorize_requests" ||
+        value === "debit_permission.create" || value === "debit_permission.revoke";
+}
+function localResultKind(value) {
+    return value === "identity" || value === "session" || value === "service_grant" || value === "wallet_limits" || value === "request_grant" || value === "debit_permission";
+}
+function operationState(value) {
+    return value === "awaiting_confirmation" || value === "authorized" || value === "pending_target_fence" || value === "succeeded" || value === "failed" ||
+        value === "denied" || value === "canceled" || value === "expired";
+}
+function effectState(value) {
+    return value === "no_effect" || value === "known";
+}
+function lowerHexDigest(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+function base64url(value) {
+    return typeof value === "string" && /^[A-Za-z0-9_-]+$/.test(value);
+}
+/** serviceScopes accepts the read scopes of a service grant: at most the three, each once (none: a withdrawal). */
+export function serviceScopes(value) {
+    if (!Array.isArray(value) || value.length > 3 || new Set(value).size !== value.length)
+        return false;
+    return value.every((scope) => scope === "wallet:read" || scope === "operation:read" || scope === "streams:read");
+}
+/** printableReference accepts a grant's external_ref: 1 to 128 printable ASCII characters. */
+export function printableReference(value) {
+    return typeof value === "string" && /^[\x20-\x7E]{1,128}$/.test(value);
+}
+function httpsURL(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/streams.d.ts

@@ -0,0 +1,212 @@
+import { type PollResult } from "./poll.ts";
+import { type WalletEvent } from "./walletEvents.ts";
+export { pollAuthoritative } from "./poll.ts";
+export type { PollDisposition, PollOptions, PollResult } from "./poll.ts";
+export { AuthorizationError, ClientFlowError } from "./auth.ts";
+export type { NextAction } from "./auth.ts";
+export { MaxWalletEventPayloadLength, parseWalletEvent } from "./walletEvents.ts";
+export type { WalletEvent, WalletEventKind, WalletEventStatus } from "./walletEvents.ts";
+export { TrackedWallets, TrackedWalletsPath, parseTrackedWalletPage, trackedWalletsPath } from "./trackedWallets.ts";
+export type { TrackedWallet, TrackedWalletKind, TrackedWalletPage, TrackedWalletPageOptions, TrackedWalletsGet } from "./trackedWallets.ts";
+/** DefaultStreamsPageLimit is the served page size when no limit is supplied (source §2.8). */
+export declare const DefaultStreamsPageLimit = 50;
+/** MaxStreamsPageLimit is the largest page the deposit route accepts (source §2.8). */
+export declare const MaxStreamsPageLimit = 100;
+/** MaxStreamsCursorLength bounds one opaque scope-bound wrapper. */
+export declare const MaxStreamsCursorLength = 4096;
+/** MaxStreamsAssets bounds one registration's validated asset list. */
+export declare const MaxStreamsAssets = 32;
+/** MaxStreamsActivityTypes bounds the activity kinds one registration may ask for. */
+export declare const MaxStreamsActivityTypes = 16;
+/** MaxStreamsAddressLength bounds one released address. */
+export declare const MaxStreamsAddressLength = 256;
+/**
+ * StreamsReadScope selects which credential class the path belongs to. The
+ * account routes accept only the account access JWT and the service routes only
+ * a tenant-access service credential; neither body nor header can select
+ * another tenant (source §2.2).
+ */
+export type StreamsReadScope = "account" | "service";
+/** StreamsRegistrationStatus is the closed source registration status set. */
+export type StreamsRegistrationStatus = "pending" | "active";
+/** StreamsRegistration is one authorized registration exactly as the source owns it. */
+export interface StreamsRegistration {
+    readonly registrationId: string;
+    readonly walletId: string;
+    /** Streams-owned identifier, never inferred from and never equal to an Authorization identifier. */
+    readonly sourceRegistrationId: string;
+    readonly network: string;
+    readonly address: string;
+    readonly assets: readonly string[];
+    readonly status: StreamsRegistrationStatus;
+    readonly effectiveFrom: string;
+    readonly revision: number;
+    readonly sourceVersion: string;
+}
+/**
+ * StreamsRegistrationList is the closed registrations response. The unique
+ * wallet and network binding bounds the permitted set, so the route releases it
+ * in one page and issues no cursor.
+ */
+export interface StreamsRegistrationList {
+    readonly items: readonly StreamsRegistration[];
+    readonly hasMore: boolean;
+}
+/**
+ * StreamsWindow is the authorized visible boundary, as two opaque wrappers.
+ * latestCursor is also a place to read on from: what came after the end of
+ * the stream as the read saw it. earliestCursor is never accepted as a cursor.
+ */
+export interface StreamsWindow {
+    readonly earliestCursor: string;
+    readonly latestCursor: string;
+}
+/**
+ * WalletEventPage is one page of a wallet's retained events as wallet events
+ * 3.0: deposits, withdrawals and other activity in one shape. One stored
+ * event gives no event, one or two, so a page holds at most twice the limit
+ * asked for; a page filtered by kind may hold fewer, or none, and still go
+ * on. `nextCursor` is present exactly when `hasMore` is true.
+ */
+export interface WalletEventPage {
+    readonly events: readonly WalletEvent[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
+    readonly window: StreamsWindow;
+}
+/**
+ * resumeCursor is the cursor to pass to the next read of the same wallet so
+ * that it returns only what this page did not: the next page while there is
+ * one, and at the end of the stream what comes after it. Keep it between
+ * rounds instead of reading a history again from its start. It ends with the
+ * session, like every cursor; a refused one means the history is read anew.
+ */
+export declare function resumeCursor(page: WalletEventPage): string;
+/** StreamsListOptions is the closed registrations query: a limit only. */
+export interface StreamsListOptions {
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+/** StreamsRegistrationReadOptions adds the caller-owned replay key to a list read. */
+export interface StreamsRegistrationReadOptions extends StreamsListOptions {
+    /** Stable across retries of this exact route and query; never generated by the SDK. */
+    readonly idempotencyKey: string;
+}
+/**
+ * StreamsPageOptions is the closed events query. A wrapper carries its own
+ * original limit, so omitting `limit` while resuming keeps it and supplying a
+ * different one is CURSOR_INVALID at the server (source §2.6).
+ *
+ * `eventTypes` is the kinds of wallet event the caller wants: "deposit",
+ * "withdrawal" and "activity" in any combination, or "activity:<type>" for
+ * one type of activity. Left out, every kind. The filter is applied to the
+ * page that was read and does not change its cursor.
+ */
+export interface StreamsPageOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly eventTypes?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+/** MaxWalletEventTypes is how many selectors a filter may name. */
+export declare const MaxWalletEventTypes = 64;
+/**
+ * appendEventTypes writes the filter by kind into a query. Each selector is
+ * named once; what the server makes of a combination is the server's to say.
+ */
+export declare function appendEventTypes(query: URLSearchParams, value: unknown): void;
+/** StreamsEventsReadOptions adds the caller-owned replay key to one events read. */
+export interface StreamsEventsReadOptions extends StreamsPageOptions {
+    /** Stable across retries of this exact route and query; never generated by the SDK. */
+    readonly idempotencyKey: string;
+}
+/**
+ * StreamsResync is the typed expired-boundary outcome: the authorized visible
+ * boundary the caller must restart from.
+ *
+ * Its two values are the window's wrappers. The server binds every released
+ * wrapper to the boundary it was issued for. A caller that wants the retained
+ * history restarts with a fresh read of this wallet with no cursor and pages
+ * forward again; one that wants only what comes from now on reads from
+ * latestCursor. earliestCursor is never accepted as a cursor. This module
+ * never retries the failed read and never derives a position of its own.
+ */
+export interface StreamsResync {
+    readonly requestId: string;
+    readonly window: StreamsWindow;
+}
+/**
+ * streamsRegistrationsPath builds the exact registrations path. The route
+ * declares no cursor at all, so this builder accepts none: a cursor member is
+ * refused here rather than sent and answered INVALID_REQUEST.
+ */
+export declare function streamsRegistrationsPath(scope: StreamsReadScope, walletId: string, options?: StreamsListOptions): string;
+/** streamsEventsPath builds the exact wallet events path with its closed query. */
+export declare function streamsEventsPath(scope: StreamsReadScope, walletId: string, options?: StreamsPageOptions): string;
+/** parseStreamsRegistrationList parses the closed registrations response. */
+export declare function parseStreamsRegistrationList(payload: unknown): StreamsRegistrationList;
+/** parseWalletEventPage parses the closed page of wallet events 3.0. */
+export declare function parseWalletEventPage(payload: unknown): WalletEventPage;
+/** parseStreamsWindow parses the required two-wrapper authorized window. */
+export declare function parseStreamsWindow(payload: unknown): StreamsWindow;
+/**
+ * streamsResync reports the authorized window of an expired boundary and
+ * nothing else. `parseAuthorizationError` already refuses a RESYNC_REQUIRED
+ * without its window and a window on any other code, so this returns undefined
+ * for every other failure instead of guessing a recovery position.
+ */
+export declare function streamsResync(error: unknown): StreamsResync | undefined;
+/**
+ * StreamsAuthorizedGet performs one authorized GET and returns its parsed JSON
+ * body. Implementations must send `idempotencyKey` as the Idempotency-Key
+ * header; retries of the same request must pass through the exact same key.
+ */
+export type StreamsAuthorizedGet = (path: string, signal: AbortSignal | undefined, idempotencyKey: string) => Promise<unknown>;
+/** StreamsReadsDependencies is the closed construction input of `StreamsReads`. */
+export interface StreamsReadsDependencies {
+    readonly scope: StreamsReadScope;
+    readonly get: StreamsAuthorizedGet;
+}
+/**
+ * StreamsReads is the two authorized reads bound to one caller's own authorized
+ * GET. It owns no credential: the account caller receives one already bound to
+ * its session from `AuthorizationClient.streams()`, and a service caller
+ * supplies a GET that carries its own tenant-access service credential. Each
+ * read requires the caller's stable key; reuse it only for retries of the same
+ * route and query because the server conflicts when a key is bound to changed
+ * request material.
+ */
+export declare class StreamsReads {
+    #private;
+    readonly scope: StreamsReadScope;
+    constructor(dependencies: StreamsReadsDependencies);
+    /** registrations reads the wallet's authorized registrations in one page. */
+    registrations(walletId: string, options: StreamsRegistrationReadOptions): Promise<StreamsRegistrationList>;
+    /**
+     * events reads one page of the wallet's retained events as wallet events
+     * 3.0: deposits, withdrawals and other activity in one shape with a status,
+     * those of the kinds `eventTypes` names. A denial is thrown exactly as the
+     * server classified it: an expired boundary raises the RESYNC_REQUIRED
+     * AuthorizationError carrying its authorized window, which this method
+     * never catches, retries or converts into an empty success.
+     */
+    events(walletId: string, options: StreamsEventsReadOptions): Promise<WalletEventPage>;
+}
+/** StreamsPollOptions is the closed input of `pollStreamsEvents`. */
+export interface StreamsPollOptions {
+    readonly read: (signal: AbortSignal) => Promise<WalletEventPage>;
+    readonly signal?: AbortSignal;
+    readonly intervalMs?: number;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * pollStreamsEvents follows a page of wallet events until the server itself reports no
+ * further retained work. It adds no bound of its own: it delegates to the one
+ * `pollAuthoritative` helper, so the source §2.8 bounds — at least two seconds
+ * between polls and at most sixty seconds in total — are enforced in a single
+ * place, and cancellation or timeout returns the last observed page with its
+ * local disposition rather than a claimed server outcome.
+ */
+export declare function pollStreamsEvents(options: StreamsPollOptions): Promise<PollResult<WalletEventPage>>;