@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/streams.js

@@ -0,0 +1,282 @@
+// Authorized Streams reads (source §1.7, §1.11, §2.2, §2.6).
+//
+// This module is the package's third entry point
+// (`@shuttle.technology/authorization/streams`). It owns exactly the client half of the
+// served reads: it builds their exact `/v1` paths, enforces the page bounds
+// of source §2.8 before a request leaves the client, and parses the two
+// closed response shapes. Events are read in one shape, wallet events 3.0,
+// owned by `./walletEvents.ts` and re-exported here.
+//
+// It holds no credential and performs no HTTP itself. The account caller binds
+// it to its own session through `AuthorizationClient.streams()`; a service
+// caller is a customer backend that holds the tenant-access service credential,
+// so it supplies its own authorized GET exactly as the Mode C customer backend
+// supplies its own forwarding (source §2.2, AUTH-009-A05).
+//
+// Streams owns registration admission, event identity, lifecycle revisions,
+// cursors, replay and reversions. This module therefore renumbers nothing,
+// reconstructs nothing, infers no balance or finality, and never invents a
+// cursor: an expired boundary is handed back as the authorized window and the
+// caller decides whether to restart from it.
+import { AuthorizationError, ClientFlowError, integer, opaqueId, record, } from "./auth.js";
+import { pollAuthoritative } from "./poll.js";
+import { parseWalletEvent } from "./walletEvents.js";
+export { pollAuthoritative } from "./poll.js";
+export { AuthorizationError, ClientFlowError } from "./auth.js";
+export { MaxWalletEventPayloadLength, parseWalletEvent } from "./walletEvents.js";
+export { TrackedWallets, TrackedWalletsPath, parseTrackedWalletPage, trackedWalletsPath } from "./trackedWallets.js";
+/** DefaultStreamsPageLimit is the served page size when no limit is supplied (source §2.8). */
+export const DefaultStreamsPageLimit = 50;
+/** MaxStreamsPageLimit is the largest page the deposit route accepts (source §2.8). */
+export const MaxStreamsPageLimit = 100;
+/** MaxStreamsCursorLength bounds one opaque scope-bound wrapper. */
+export const MaxStreamsCursorLength = 4096;
+/** MaxStreamsAssets bounds one registration's validated asset list. */
+export const MaxStreamsAssets = 32;
+/** MaxStreamsActivityTypes bounds the activity kinds one registration may ask for. */
+export const MaxStreamsActivityTypes = 16;
+/** MaxStreamsAddressLength bounds one released address. */
+export const MaxStreamsAddressLength = 256;
+/**
+ * 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 function resumeCursor(page) {
+    return page.hasMore ? page.nextCursor : page.window.latestCursor;
+}
+/** MaxWalletEventTypes is how many selectors a filter may name. */
+export const MaxWalletEventTypes = 64;
+const eventTypePattern = /^(deposit|withdrawal|activity|activity:[a-z0-9_.]{1,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 function appendEventTypes(query, value) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value) || value.length < 1 || value.length > MaxWalletEventTypes ||
+        value.some((selector) => typeof selector !== "string" || !eventTypePattern.test(selector)) ||
+        new Set(value).size !== value.length) {
+        throw new ClientFlowError("invalid_streams_request");
+    }
+    query.set("event_types", value.join(","));
+}
+// Streams admits its legacy binding spelling and the canonical CAIP-2 form
+// validated by the Authorization Streams port. Keep this local to Streams
+// reads; generic wallet network contracts have different bounds.
+const networkPattern = /^([a-z][a-z0-9-]{0,31}|[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32})$/;
+const assetPattern = /^[a-z][a-z0-9_.:-]{0,63}$/;
+const sourcePositionPattern = /^[A-Za-z0-9_.:-]{1,256}$/;
+const sourceVersionPattern = /^[0-9]+\.[0-9]+$/;
+/**
+ * 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 function streamsRegistrationsPath(scope, walletId, options = {}) {
+    const declared = closedOptions(options, ["limit", "signal"]);
+    const query = new URLSearchParams();
+    appendLimit(query, declared.limit);
+    return suffixed(walletPrefix(scope, walletId), "/registrations", query);
+}
+/** streamsEventsPath builds the exact wallet events path with its closed query. */
+export function streamsEventsPath(scope, walletId, options = {}) {
+    const declared = closedOptions(options, ["cursor", "limit", "eventTypes", "signal"]);
+    const query = new URLSearchParams();
+    if (declared.cursor !== undefined) {
+        if (!cursorValue(declared.cursor))
+            throw new ClientFlowError("invalid_streams_request");
+        query.set("cursor", declared.cursor);
+    }
+    appendLimit(query, declared.limit);
+    appendEventTypes(query, declared.eventTypes);
+    return suffixed(walletPrefix(scope, walletId), "/events", query);
+}
+/** parseStreamsRegistrationList parses the closed registrations response. */
+export function parseStreamsRegistrationList(payload) {
+    const root = record(payload, ["items", "has_more"]);
+    if (!Array.isArray(root.items) || typeof root.has_more !== "boolean")
+        throw new ClientFlowError("invalid_server_response");
+    return Object.freeze({ items: Object.freeze(root.items.map(parseStreamsRegistration)), hasMore: root.has_more });
+}
+/** parseWalletEventPage parses the closed page of wallet events 3.0. */
+export function parseWalletEventPage(payload) {
+    const root = record(payload, ["events", "has_more", "window"], ["next_cursor"]);
+    if (!Array.isArray(root.events) || root.events.length > 2 * MaxStreamsPageLimit || typeof root.has_more !== "boolean") {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    // next_cursor is present exactly when has_more is true. Both directions are
+    // refused, so a page can neither hide its continuation nor offer one it did
+    // not declare.
+    const declaresCursor = Object.prototype.hasOwnProperty.call(root, "next_cursor");
+    if (root.has_more !== declaresCursor)
+        throw new ClientFlowError("invalid_server_response");
+    if (declaresCursor && !cursorValue(root.next_cursor))
+        throw new ClientFlowError("invalid_server_response");
+    const window = parseStreamsWindow(root.window);
+    const events = Object.freeze(root.events.map(parseWalletEvent));
+    if (!root.has_more)
+        return Object.freeze({ events, hasMore: false, window });
+    return Object.freeze({ events, nextCursor: root.next_cursor, hasMore: true, window });
+}
+/** parseStreamsWindow parses the required two-wrapper authorized window. */
+export function parseStreamsWindow(payload) {
+    const window = record(payload, ["earliest_cursor", "latest_cursor"]);
+    if (!cursorValue(window.earliest_cursor) || !cursorValue(window.latest_cursor))
+        throw new ClientFlowError("invalid_server_response");
+    return Object.freeze({ earliestCursor: window.earliest_cursor, latestCursor: window.latest_cursor });
+}
+/**
+ * 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 function streamsResync(error) {
+    if (!(error instanceof AuthorizationError) || error.code !== "RESYNC_REQUIRED" || error.window === undefined)
+        return undefined;
+    return Object.freeze({
+        requestId: error.requestId,
+        window: Object.freeze({ earliestCursor: error.window.earliestCursor, latestCursor: error.window.latestCursor }),
+    });
+}
+/**
+ * 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 class StreamsReads {
+    scope;
+    #get;
+    constructor(dependencies) {
+        const declared = closedOptions(dependencies, ["scope", "get"]);
+        if ((declared.scope !== "account" && declared.scope !== "service") || typeof declared.get !== "function") {
+            throw new ClientFlowError("invalid_streams_request");
+        }
+        this.scope = declared.scope;
+        this.#get = declared.get;
+    }
+    /** registrations reads the wallet's authorized registrations in one page. */
+    async registrations(walletId, options) {
+        const declared = closedOptions(options, ["limit", "signal", "idempotencyKey"]);
+        if (!validStreamsReadIdempotencyKey(declared.idempotencyKey))
+            throw new ClientFlowError("invalid_streams_request");
+        const path = streamsRegistrationsPath(this.scope, walletId, { limit: declared.limit });
+        return parseStreamsRegistrationList(await this.#get(path, declared.signal, declared.idempotencyKey));
+    }
+    /**
+     * 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.
+     */
+    async events(walletId, options) {
+        const declared = closedOptions(options, ["cursor", "limit", "eventTypes", "signal", "idempotencyKey"]);
+        if (!validStreamsReadIdempotencyKey(declared.idempotencyKey))
+            throw new ClientFlowError("invalid_streams_request");
+        const path = streamsEventsPath(this.scope, walletId, {
+            cursor: declared.cursor,
+            limit: declared.limit,
+            eventTypes: declared.eventTypes,
+        });
+        return parseWalletEventPage(await this.#get(path, declared.signal, declared.idempotencyKey));
+    }
+}
+/**
+ * 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 function pollStreamsEvents(options) {
+    const declared = closedOptions(options, ["read", "signal", "intervalMs", "timeoutMs", "now", "sleep"]);
+    if (typeof declared.read !== "function")
+        throw new ClientFlowError("invalid_streams_request");
+    return pollAuthoritative({
+        read: declared.read,
+        terminal: (page) => page.hasMore === false,
+        signal: declared.signal,
+        intervalMs: declared.intervalMs,
+        timeoutMs: declared.timeoutMs,
+        now: declared.now,
+        sleep: declared.sleep,
+    });
+}
+function parseStreamsRegistration(value) {
+    const item = record(value, [
+        "registration_id", "wallet_id", "source_registration_id", "network", "address",
+        "assets", "status", "effective_from", "revision", "source_version",
+    ]);
+    if (!opaqueId(item.registration_id) || !opaqueId(item.wallet_id) || !opaqueId(item.source_registration_id) ||
+        !matches(networkPattern, item.network) || !bounded(item.address, MaxStreamsAddressLength) || !assetList(item.assets) ||
+        (item.status !== "pending" && item.status !== "active") || !matches(sourcePositionPattern, item.effective_from) ||
+        !positive(item.revision) || !matches(sourceVersionPattern, item.source_version)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return Object.freeze({
+        registrationId: item.registration_id, walletId: item.wallet_id, sourceRegistrationId: item.source_registration_id,
+        network: item.network, address: item.address, assets: Object.freeze([...item.assets]),
+        status: item.status, effectiveFrom: item.effective_from, revision: item.revision, sourceVersion: item.source_version,
+    });
+}
+function walletPrefix(scope, walletId) {
+    if ((scope !== "account" && scope !== "service") || !opaqueId(walletId))
+        throw new ClientFlowError("invalid_streams_request");
+    const base = scope === "account" ? "/v1/wallets/" : "/v1/service/wallets/";
+    return base + encodeURIComponent(walletId);
+}
+function suffixed(prefix, suffix, query) {
+    const path = prefix + suffix;
+    return query.size === 0 ? path : `${path}?${query.toString()}`;
+}
+/**
+ * appendLimit enforces the source §2.8 page bound before any request. The value
+ * must be a safe integer in [1,100]; every other value, including 0, 101 and a
+ * noninteger, is refused locally rather than sent.
+ */
+function appendLimit(query, value) {
+    if (value === undefined)
+        return;
+    if (!integer(value) || value < 1 || value > MaxStreamsPageLimit)
+        throw new ClientFlowError("invalid_streams_request");
+    query.set("limit", String(value));
+}
+function closedOptions(value, allowed) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new ClientFlowError("invalid_streams_request");
+    const result = value;
+    const permitted = new Set(allowed);
+    if (Object.keys(result).some((member) => !permitted.has(member)))
+        throw new ClientFlowError("invalid_streams_request");
+    return result;
+}
+function cursorValue(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= MaxStreamsCursorLength;
+}
+function validStreamsReadIdempotencyKey(value) {
+    return typeof value === "string" && value.length >= 1 && value.length <= 128 &&
+        [...value].every((character) => character.charCodeAt(0) >= 33 && character.charCodeAt(0) <= 126);
+}
+function bounded(value, maximum) {
+    return typeof value === "string" && value.length > 0 && value.length <= maximum;
+}
+function matches(pattern, value) {
+    return typeof value === "string" && pattern.test(value);
+}
+function positive(value) {
+    return integer(value) && value >= 1;
+}
+function assetList(value) {
+    return Array.isArray(value) && value.length <= MaxStreamsAssets && value.every((asset) => matches(assetPattern, asset));
+}

package/dist/trackedWallets.d.ts

@@ -0,0 +1,53 @@
+/** The served path of the read. */
+export declare const TrackedWalletsPath = "/v1/service/registrations";
+/** `wallet` is a wallet Authorization created, `linked_wallet` one its owner connected. */
+export type TrackedWalletKind = "wallet" | "linked_wallet";
+/** TrackedWallet is one tracked wallet and the registration its events carry. */
+export interface TrackedWallet {
+    readonly registrationId: string;
+    /** The registration identifier Streams puts on every event of this wallet. */
+    readonly sourceRegistrationId: string;
+    readonly walletKind: TrackedWalletKind;
+    /** An identifier of the kind `walletKind` names. */
+    readonly walletId: string;
+    readonly ownerType: "organization" | "account";
+    readonly ownerId: string;
+    readonly network: string;
+    readonly address: string;
+    readonly status: "pending" | "active";
+}
+/** TrackedWalletPage is one page, ordered by `registrationId`. */
+export interface TrackedWalletPage {
+    readonly items: readonly TrackedWallet[];
+    /** Present exactly when `hasMore` is true. */
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
+}
+/** TrackedWalletPageOptions is the closed input of `TrackedWallets.page`. */
+export interface TrackedWalletPageOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+/** TrackedWalletsGet is the backend's own authorized GET of one `/v1` path. */
+export type TrackedWalletsGet = (path: string, signal: AbortSignal | undefined) => Promise<unknown>;
+/** trackedWalletsPath builds the exact path of one read and refuses a request the server would. */
+export declare function trackedWalletsPath(options?: {
+    readonly sourceRegistrationId?: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}): string;
+/** parseTrackedWalletPage parses the closed response of the read. */
+export declare function parseTrackedWalletPage(payload: unknown): TrackedWalletPage;
+/** TrackedWallets is the read bound to one backend's own authorized GET. */
+export declare class TrackedWallets {
+    #private;
+    constructor(get: TrackedWalletsGet);
+    /** page reads one page of every tracked wallet of the backend's environment. */
+    page(options?: TrackedWalletPageOptions): Promise<TrackedWalletPage>;
+    /**
+     * forEvent returns the wallet behind the registration an event names, or
+     * undefined when the environment tracks no such registration.
+     */
+    forEvent(sourceRegistrationId: string, signal?: AbortSignal): Promise<TrackedWallet | undefined>;
+}

package/dist/trackedWallets.js

@@ -0,0 +1,104 @@
+// The read a customer backend resolves a Streams event with.
+//
+// A backend takes events straight from Streams. An event names the Streams
+// registration, its network and its address; which wallet that is, and whose,
+// only Authorization knows. `TrackedWallets` asks it: for one event, or for
+// every tracked wallet of the backend's own environment.
+//
+// Like the other service reads of this package it holds no credential and
+// performs no HTTP itself: the backend supplies a GET that carries its own
+// tenant-access service credential (`Authorization: Service …`). That key
+// never belongs in a browser.
+import { ClientFlowError, integer, opaqueId, record } from "./auth.js";
+/** The served path of the read. */
+export const TrackedWalletsPath = "/v1/service/registrations";
+const maxPageLimit = 100;
+const maxCursorLength = 4096;
+const maxAddressLength = 256;
+const networkPattern = /^([a-z][a-z0-9-]{0,31}|[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32})$/;
+/** trackedWalletsPath builds the exact path of one read and refuses a request the server would. */
+export function trackedWalletsPath(options = {}) {
+    const declared = closed(options, ["sourceRegistrationId", "cursor", "limit"]);
+    const query = new URLSearchParams();
+    if (declared.sourceRegistrationId !== undefined) {
+        if (!opaqueId(declared.sourceRegistrationId) || declared.cursor !== undefined)
+            throw new ClientFlowError("invalid_streams_request");
+        query.set("source_registration_id", declared.sourceRegistrationId);
+    }
+    if (declared.cursor !== undefined) {
+        if (typeof declared.cursor !== "string" || declared.cursor.length === 0 || declared.cursor.length > maxCursorLength) {
+            throw new ClientFlowError("invalid_streams_request");
+        }
+        query.set("cursor", declared.cursor);
+    }
+    if (declared.limit !== undefined) {
+        if (!integer(declared.limit) || declared.limit < 1 || declared.limit > maxPageLimit)
+            throw new ClientFlowError("invalid_streams_request");
+        query.set("limit", String(declared.limit));
+    }
+    return query.size === 0 ? TrackedWalletsPath : `${TrackedWalletsPath}?${query.toString()}`;
+}
+/** parseTrackedWalletPage parses the closed response of the read. */
+export function parseTrackedWalletPage(payload) {
+    const page = record(payload, ["items", "has_more"], ["next_cursor"]);
+    if (!Array.isArray(page.items) || page.items.length > maxPageLimit || typeof page.has_more !== "boolean" ||
+        (page.next_cursor !== undefined) !== page.has_more ||
+        (page.next_cursor !== undefined && (typeof page.next_cursor !== "string" || page.next_cursor.length === 0 || page.next_cursor.length > maxCursorLength))) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const items = Object.freeze(page.items.map(parseTrackedWallet));
+    return Object.freeze(page.has_more ? { items, nextCursor: page.next_cursor, hasMore: true } : { items, hasMore: false });
+}
+/** TrackedWallets is the read bound to one backend's own authorized GET. */
+export class TrackedWallets {
+    #get;
+    constructor(get) {
+        if (typeof get !== "function")
+            throw new ClientFlowError("invalid_streams_request");
+        this.#get = get;
+    }
+    /** page reads one page of every tracked wallet of the backend's environment. */
+    async page(options = {}) {
+        const declared = closed(options, ["cursor", "limit", "signal"]);
+        const path = trackedWalletsPath({ cursor: declared.cursor, limit: declared.limit });
+        return parseTrackedWalletPage(await this.#get(path, declared.signal));
+    }
+    /**
+     * forEvent returns the wallet behind the registration an event names, or
+     * undefined when the environment tracks no such registration.
+     */
+    async forEvent(sourceRegistrationId, signal) {
+        const page = parseTrackedWalletPage(await this.#get(trackedWalletsPath({ sourceRegistrationId }), signal));
+        if (page.items.length > 1 || page.hasMore || (page.items.length === 1 && page.items[0].sourceRegistrationId !== sourceRegistrationId)) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        return page.items[0];
+    }
+}
+function parseTrackedWallet(value) {
+    const item = record(value, [
+        "registration_id", "source_registration_id", "wallet_kind", "wallet_id", "owner_type", "owner_id", "network", "address", "status",
+    ]);
+    if (!opaqueId(item.registration_id) || !opaqueId(item.source_registration_id) || !opaqueId(item.wallet_id) || !opaqueId(item.owner_id) ||
+        (item.wallet_kind !== "wallet" && item.wallet_kind !== "linked_wallet") ||
+        (item.owner_type !== "organization" && item.owner_type !== "account") ||
+        typeof item.network !== "string" || !networkPattern.test(item.network) ||
+        typeof item.address !== "string" || item.address.length === 0 || item.address.length > maxAddressLength ||
+        (item.status !== "pending" && item.status !== "active")) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return Object.freeze({
+        registrationId: item.registration_id, sourceRegistrationId: item.source_registration_id, walletKind: item.wallet_kind,
+        walletId: item.wallet_id, ownerType: item.owner_type, ownerId: item.owner_id, network: item.network, address: item.address,
+        status: item.status,
+    });
+}
+function closed(value, allowed) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new ClientFlowError("invalid_streams_request");
+    const result = value;
+    const permitted = new Set(allowed);
+    if (Object.keys(result).some((member) => !permitted.has(member)))
+        throw new ClientFlowError("invalid_streams_request");
+    return result;
+}

package/dist/transferStatus.d.ts

@@ -0,0 +1,45 @@
+/** The own-wallet system's states of a prepared transfer, in the order a transfer passes them. */
+export declare const TransferStates: readonly ['prepared', 'executing', 'broadcasting', 'submitted', 'confirmed', 'failed', 'expired'];
+export type TransferState = (typeof TransferStates)[number];
+/**
+ * What became of a transfer. confirmed: in a block with a successful result.
+ * failed: refused by the network, failed in a block, replaced or dropped;
+ * failureReason carries the network's reason when it gave one. expired: never
+ * executed, no funds moved. Every other state is still on its way.
+ */
+export interface TransferStatus {
+    readonly requestId: string;
+    readonly operationId: string;
+    readonly state: TransferState;
+    /** True for confirmed, failed and expired: the state can no longer change. */
+    readonly final: boolean;
+    /** The network's transaction hash, present once the transfer is signed. */
+    readonly transactionHash?: string;
+    /**
+     * The network's reason for a failed transfer: its error code, or the
+     * own-wallet system's expired, nonce_used, bounced or not_sent (signed only
+     * after its authorization ran out, so never sent).
+     */
+    readonly failureReason?: string;
+    /**
+     * The account's own send whose transaction the network included in this
+     * transfer's place: its speed-up or cancellation, or the next transfer of
+     * the same wallet. Present only with failureReason nonce_used, and absent
+     * when the place was taken from outside the own-wallet system or by none of
+     * the account's last hundred sends. The funds may have moved by that send.
+     */
+    readonly replacedByOperationId?: string;
+    /**
+     * The deadline of the owner's authorization, present while the transfer is
+     * not final. 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 this instant is neither done
+     * nor safely gone.
+     */
+    readonly authorizationExpiresAt?: string;
+}
+/** Reports that a transfer in this state can no longer change. */
+export declare function transferFinal(state: TransferState): boolean;
+export declare function transferStatusPath(operationId: string): string;
+/** Parses the closed transfer status answer of the operation that was asked about. */
+export declare function parseTransferStatus(payload: unknown, expectedOperationId: string): TransferStatus;

package/dist/transferStatus.js

@@ -0,0 +1,43 @@
+// The fate of the one transfer a send from a linked wallet prepared. A send's
+// operation ends when the own-wallet system accepted the transfer and named
+// its hash; what the network then did with it is read here, for that same
+// transfer and no other.
+import { ClientFlowError, opaqueId, record, rfc3339UTC } from './auth.js';
+/** The own-wallet system's states of a prepared transfer, in the order a transfer passes them. */
+export const TransferStates = ['prepared', 'executing', 'broadcasting', 'submitted', 'confirmed', 'failed', 'expired'];
+/** Reports that a transfer in this state can no longer change. */
+export function transferFinal(state) {
+    return state === 'confirmed' || state === 'failed' || state === 'expired';
+}
+export function transferStatusPath(operationId) {
+    if (!opaqueId(operationId))
+        throw new ClientFlowError('invalid_linked_wallet_request');
+    return `/v1/operations/${operationId}/transfer`;
+}
+/** Parses the closed transfer status answer of the operation that was asked about. */
+export function parseTransferStatus(payload, expectedOperationId) {
+    const root = record(payload, ['request_id', 'transfer']);
+    const t = record(root.transfer, ['operation_id', 'state'], ['transaction_hash', 'failure_reason', 'replaced_by_operation_id', 'authorization_expires_at']);
+    const state = t.state;
+    const hash = t.transaction_hash, reason = t.failure_reason, replacedBy = t.replaced_by_operation_id, deadline = t.authorization_expires_at;
+    if (!opaqueId(root.request_id) || t.operation_id !== expectedOperationId || typeof t.state !== 'string' || !TransferStates.includes(state) ||
+        (hash !== undefined && (typeof hash !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/.test(hash))) ||
+        ((state === 'submitted' || state === 'confirmed') && hash === undefined) ||
+        (reason !== undefined && (state !== 'failed' || typeof reason !== 'string' || reason.length === 0 || new TextEncoder().encode(reason).length > 1024 || /[\x00-\x1f\x7f-\x9f]/.test(reason))) ||
+        // Another send replaced it only by using its nonce, and no send replaces itself.
+        (replacedBy !== undefined && (reason !== 'nonce_used' || !opaqueId(replacedBy) || replacedBy === expectedOperationId)) ||
+        // The deadline is told only while the transfer can still change.
+        (deadline !== undefined && (!rfc3339UTC(deadline) || transferFinal(state)))) {
+        throw new ClientFlowError('invalid_server_response');
+    }
+    const out = { requestId: root.request_id, operationId: expectedOperationId, state, final: transferFinal(state) };
+    if (hash !== undefined)
+        out.transactionHash = hash;
+    if (reason !== undefined)
+        out.failureReason = reason;
+    if (replacedBy !== undefined)
+        out.replacedByOperationId = replacedBy;
+    if (deadline !== undefined)
+        out.authorizationExpiresAt = deadline;
+    return Object.freeze(out);
+}

package/dist/walletDisplayParts.d.ts

@@ -0,0 +1,15 @@
+import type { ResultRecipient } from "./slice4.ts";
+export type DisplayCommon = {
+    ownerId: string;
+    requesterId: string;
+    resultRecipient: ResultRecipient;
+    walletId?: string;
+};
+export declare const walletRecipient: RegExp;
+export declare function displayCommon(display: Record<string, unknown>): DisplayCommon;
+export declare function summaryOf(value: unknown): {
+    preparedSummary?: string;
+};
+export declare function rawQuantity(value: unknown, positive: boolean): value is string;
+export declare function bindingRevision(value: unknown): value is string;
+export declare function lowerUUID(value: unknown): value is string;

package/dist/walletDisplayParts.js

@@ -0,0 +1,43 @@
+// Parts every safe display of a wallet operation is read with: the identity
+// members each display carries, and the closed value forms shared by the
+// displays of own wallets and of linked wallets.
+import { ClientFlowError, canonicalDecimal, opaqueId, record } from "./auth.js";
+/** maxUint256 bounds every raw quantity as source §2.4 requires. */
+const maxUint256 = (1n << 256n) - 1n;
+export const walletRecipient = /^[\x21-\x7e]{1,256}$/;
+export function displayCommon(display) {
+    if (!opaqueId(display.owner_id) || !opaqueId(display.requester_id) || (display.wallet_id !== undefined && !opaqueId(display.wallet_id))) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const common = { ownerId: display.owner_id, requesterId: display.requester_id, resultRecipient: resultRecipientOf(display.result_recipient) };
+    if (display.wallet_id !== undefined)
+        common.walletId = display.wallet_id;
+    return common;
+}
+function resultRecipientOf(value) {
+    const recipient = record(value, ["type", "id"]);
+    if (recipient.type !== "account" && recipient.type !== "service")
+        throw new ClientFlowError("invalid_server_response");
+    if (!opaqueId(recipient.id))
+        throw new ClientFlowError("invalid_server_response");
+    return { type: recipient.type, id: recipient.id };
+}
+export function summaryOf(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "string" || value.length === 0)
+        throw new ClientFlowError("invalid_server_response");
+    return { preparedSummary: value };
+}
+export function rawQuantity(value, positive) {
+    if (!canonicalDecimal(value))
+        return false;
+    const quantity = BigInt(value);
+    return quantity <= maxUint256 && (!positive || quantity > 0n);
+}
+export function bindingRevision(value) {
+    return canonicalDecimal(value) && value !== "0" && value.length <= 16 && BigInt(value) <= BigInt(Number.MAX_SAFE_INTEGER);
+}
+export function lowerUUID(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value);
+}

package/dist/walletEvents.d.ts

@@ -0,0 +1,43 @@
+/** MaxWalletEventPayloadLength bounds the body text one activity event releases whole. */
+export declare const MaxWalletEventPayloadLength = 131072;
+export type WalletEventKind = "deposit" | "withdrawal" | "activity";
+export type WalletEventStatus = "completed" | "finalized" | "reverted";
+/** WalletEvent is one wallet event 3.0. */
+export interface WalletEvent {
+    readonly contractVersion: "3.0";
+    /** Unique per subject and revision. */
+    readonly eventId: string;
+    /**
+     * The event's own place in the stream of events: an opaque text no two
+     * events share. A stream of wallet events is continued after it.
+     */
+    readonly cursor: string;
+    readonly kind: WalletEventKind;
+    readonly status: WalletEventStatus;
+    /** Native decimal revision, from "1"; it is never converted to a JavaScript number. */
+    readonly revision: string;
+    /** What the revisions are about: one transfer in, one transfer out, or one activity. */
+    readonly subjectId: string;
+    readonly registrationId: string;
+    readonly networkId: string;
+    /** The tracked address. */
+    readonly address: string;
+    /** Present for a deposit and a withdrawal, and for an activity that names an asset. */
+    readonly asset?: string;
+    /** Canonical unsigned decimal string in minimal units. Present for a deposit and a withdrawal. */
+    readonly rawAmount?: string;
+    readonly counterparty?: string;
+    /** Present for an activity: its kind as Streams names it. */
+    readonly activityType?: string;
+    readonly sourceReference: string;
+    readonly observedAt: string;
+    /** Present for reverted, when Streams names a reason. */
+    readonly invalidationReason?: string;
+    /** The body of an expanded activity as its canonical JSON text, and the same read as an object. */
+    readonly payloadJson?: string;
+    readonly payload?: Readonly<Record<string, unknown>>;
+    /** Present instead of payloadJson when the body is too large for this read. */
+    readonly payloadOmittedBytes?: number;
+}
+/** parseWalletEvent parses one wallet event 3.0, closed. */
+export declare function parseWalletEvent(value: unknown): WalletEvent;