@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/walletEvents.js

@@ -0,0 +1,97 @@
+// The wallet event 3.0: one shape for everything a client hears about a
+// tracked wallet.
+//
+//   kind     "deposit" (value came in), "withdrawal" (value went out),
+//            "activity" (anything else)
+//   status   "completed" (it is in a block), "finalized" (the block is final),
+//            "reverted" (the block was replaced)
+//   revision "1" for the first status of a subject, "2" for the next
+//
+// 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 finalized follows completed after thirteen to
+// nineteen minutes. A client that acts on a transfer once it is in a block
+// waits for completed and may ignore what follows.
+//
+// The parser is closed, like every parser of this package: a member that is
+// missing, unknown or owned by another kind refuses the event.
+import { ClientFlowError, integer, opaqueId, record, rfc3339UTC } from "./auth.js";
+/** MaxWalletEventPayloadLength bounds the body text one activity event releases whole. */
+export const MaxWalletEventPayloadLength = 131072;
+const kinds = ["deposit", "withdrawal", "activity"];
+const statuses = ["completed", "finalized", "reverted"];
+const decimalPattern = /^[1-9][0-9]{0,255}$/;
+const revisionPattern = /^[1-9][0-9]{0,19}$/;
+const cursorPattern = /^[1-9][0-9]{0,18}\.[1-9]$/;
+const optional = ["asset", "raw_amount", "counterparty", "activity_type", "invalidation_reason", "payload_json", "payload_omitted_bytes"];
+/** parseWalletEvent parses one wallet event 3.0, closed. */
+export function parseWalletEvent(value) {
+    const event = record(value, [
+        "contract_version", "event_id", "cursor", "kind", "status", "revision", "subject_id",
+        "registration_id", "network_id", "address", "source_reference", "observed_at",
+    ], optional);
+    const has = (member) => Object.prototype.hasOwnProperty.call(event, member);
+    const transfer = event.kind === "deposit" || event.kind === "withdrawal";
+    if (event.contract_version !== "3.0" || !text(event.event_id, 512) || !matches(cursorPattern, event.cursor) ||
+        typeof event.kind !== "string" || !kinds.includes(event.kind) ||
+        typeof event.status !== "string" || !statuses.includes(event.status) ||
+        !matches(revisionPattern, event.revision) || (event.status === "completed") !== (event.revision === "1") ||
+        !text(event.subject_id, 256) || !opaqueId(event.registration_id) || !text(event.network_id, 256) ||
+        !text(event.address, 256) || !text(event.source_reference, 512) || !rfc3339UTC(event.observed_at) ||
+        // A transfer names its asset and its amount and nothing an activity owns.
+        (transfer && (!text(event.asset, 512) || !matches(decimalPattern, event.raw_amount) || has("activity_type") ||
+            has("payload_json") || has("payload_omitted_bytes"))) ||
+        (!transfer && (!text(event.activity_type, 128) || (has("asset") && !text(event.asset, 512)) ||
+            (has("raw_amount") && !matches(decimalPattern, event.raw_amount)) ||
+            (has("payload_json") && has("payload_omitted_bytes")))) ||
+        (has("counterparty") && !text(event.counterparty, 512)) ||
+        (has("invalidation_reason") && (event.status !== "reverted" || !text(event.invalidation_reason, 128))) ||
+        (has("payload_omitted_bytes") && !(integer(event.payload_omitted_bytes) && event.payload_omitted_bytes >= 1))) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const parsed = {
+        contractVersion: "3.0", eventId: event.event_id, cursor: event.cursor, kind: event.kind, status: event.status,
+        revision: event.revision, subjectId: event.subject_id, registrationId: event.registration_id,
+        networkId: event.network_id, address: event.address, sourceReference: event.source_reference,
+        observedAt: event.observed_at,
+    };
+    if (has("asset"))
+        parsed.asset = event.asset;
+    if (has("raw_amount"))
+        parsed.rawAmount = event.raw_amount;
+    if (has("counterparty"))
+        parsed.counterparty = event.counterparty;
+    if (has("activity_type"))
+        parsed.activityType = event.activity_type;
+    if (has("invalidation_reason"))
+        parsed.invalidationReason = event.invalidation_reason;
+    if (has("payload_json")) {
+        parsed.payload = payloadObject(event.payload_json);
+        parsed.payloadJson = event.payload_json;
+    }
+    if (has("payload_omitted_bytes"))
+        parsed.payloadOmittedBytes = event.payload_omitted_bytes;
+    return Object.freeze(parsed);
+}
+/** Only the JSON text of an object within the bound is a body; anything else refuses the event. */
+function payloadObject(value) {
+    if (typeof value !== "string" || value.length < 1 || value.length > MaxWalletEventPayloadLength) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new ClientFlowError("invalid_server_response");
+    return Object.freeze(parsed);
+}
+function text(value, maximum) {
+    return typeof value === "string" && value.length >= 1 && value.length <= maximum;
+}
+function matches(pattern, value) {
+    return typeof value === "string" && pattern.test(value);
+}

package/dist/walletLimits.d.ts

@@ -0,0 +1,65 @@
+export type LimitAsset = 'native' | 'usdt' | 'usdc';
+/** At most this many network and asset pairs, and this many recipients. */
+export declare const MaxLimitCeilings = 24;
+export declare const MaxLimitRecipients = 100;
+/** The ceilings of one asset on one network, in that network's minimal units. An absent ceiling bounds nothing. */
+export interface WalletCeiling {
+    network: string;
+    asset: LimitAsset;
+    perTransferRaw?: string;
+    perDayRaw?: string;
+}
+/** A wallet's limits now. revision "0" is a wallet whose limits were never set; no recipient means any recipient. */
+export interface WalletLimits {
+    requestId: string;
+    walletId: string;
+    revision: string;
+    ceilings: readonly WalletCeiling[];
+    recipients: readonly string[];
+}
+/**
+ * The whole of a wallet's new limits. Empty ceilings and recipients remove every limit. revision is the
+ * revision of the limits they were edited from, as limits() read it: a change made from limits that
+ * changed since (in another tab, say) is refused with VERSION_CONFLICT; read them again and redo it.
+ */
+export interface WalletLimitsInput {
+    ceilings: readonly WalletCeiling[];
+    recipients: readonly string[];
+    revision: string;
+}
+/** What the owner confirms: the wallet's address and its new limits as they will be kept, recipients in the form the network compares them by. */
+export interface WalletLimitsDisplay {
+    kind: 'wallet_limits.set';
+    ownerId: string;
+    requesterId: string;
+    linkedWalletId: string;
+    walletAddress: string;
+    ceilings: readonly WalletCeiling[];
+    recipients: readonly string[];
+    expectedRevision: string;
+}
+/**
+ * The answers to a send the wallet's limits do not allow. Each is 403 and
+ * nothing is sent; the 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 in the last 24 hours, the send would pass the daily
+ *   ceiling. It is judged when the send is executed.
+ * - RECIPIENT_NOT_ALLOWED: the wallet has a recipient list and the recipient
+ *   is not in it.
+ * The first and the last are answered when the send is created and again
+ * when it is executed, against the limits as they are then; a repeated
+ * create with the same key answers the send it created. A speed-up is
+ * judged by them too and adds nothing to the day, but is refused when the
+ * day already holds more than the daily ceiling; a cancel by none.
+ */
+export declare const WalletLimitRefusals: readonly ['LIMIT_PER_TRANSFER_EXCEEDED', 'LIMIT_DAILY_EXCEEDED', 'RECIPIENT_NOT_ALLOWED'];
+export type WalletLimitRefusal = (typeof WalletLimitRefusals)[number];
+export declare const isWalletLimitRefusal: (code: unknown) => code is WalletLimitRefusal;
+/** The closed body of POST /v1/operations that asks to replace a linked wallet's limits. */
+export declare function walletLimitsCreate(ownerId: string, linkedWalletId: string, input: WalletLimitsInput): Record<string, unknown>;
+/** The answer of GET /v1/linked-wallets/{id}/limits for walletId. */
+export declare function parseWalletLimits(payload: unknown, walletId: string): WalletLimits;
+/** The display of a wallet_limits.set operation. */
+export declare function parseWalletLimitsDisplay(value: unknown): WalletLimitsDisplay;

package/dist/walletLimits.js

@@ -0,0 +1,102 @@
+// The limits of a linked wallet (owner decision of 14 October 2026). The
+// account's session reads them; changing them, removing them included, is the
+// wallet_limits.set operation the owner confirms with a passkey on the
+// provider's page, which says the new limits in words; and every send from
+// the wallet obeys them. Amounts are in each asset's minimal units on its own
+// network: a token's decimals differ between networks (USDT has 6 on Ethereum
+// and 18 on BNB Smart Chain), so a ceiling names its network.
+import { ClientFlowError, canonicalDecimal, integer, opaqueId, record } from './auth.js';
+import { fault, network, uuid } from './linkedChecks.js';
+/** At most this many network and asset pairs, and this many recipients. */
+export const MaxLimitCeilings = 24;
+export const MaxLimitRecipients = 100;
+/**
+ * The answers to a send the wallet's limits do not allow. Each is 403 and
+ * nothing is sent; the 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 in the last 24 hours, the send would pass the daily
+ *   ceiling. It is judged when the send is executed.
+ * - RECIPIENT_NOT_ALLOWED: the wallet has a recipient list and the recipient
+ *   is not in it.
+ * The first and the last are answered when the send is created and again
+ * when it is executed, against the limits as they are then; a repeated
+ * create with the same key answers the send it created. A speed-up is
+ * judged by them too and adds nothing to the day, but is refused when the
+ * day already holds more than the daily ceiling; a cancel by none.
+ */
+export const WalletLimitRefusals = ['LIMIT_PER_TRANSFER_EXCEEDED', 'LIMIT_DAILY_EXCEEDED', 'RECIPIENT_NOT_ALLOWED'];
+export const isWalletLimitRefusal = (code) => WalletLimitRefusals.includes(code);
+/** The closed body of POST /v1/operations that asks to replace a linked wallet's limits. */
+export function walletLimitsCreate(ownerId, linkedWalletId, input) {
+    const invalid = () => { throw new ClientFlowError('invalid_operation_create'); };
+    const closed = (value, required, optional = []) => { try {
+        return record(value, required, optional);
+    }
+    catch {
+        return invalid();
+    } };
+    const declared = closed(input, ['ceilings', 'recipients', 'revision']);
+    if (!opaqueId(ownerId) || !uuid(linkedWalletId) || !Array.isArray(declared.ceilings) || declared.ceilings.length > MaxLimitCeilings || !recipients(declared.recipients) || !revision(declared.revision))
+        invalid();
+    const pairs = new Set();
+    const ceilings = declared.ceilings.map((value) => {
+        const c = closed(value, ['network', 'asset'], ['perTransferRaw', 'perDayRaw']);
+        const pair = `${c.network} ${c.asset}`;
+        if (!network(c.network) || !asset(c.asset) || pairs.has(pair) || (c.perTransferRaw === undefined && c.perDayRaw === undefined) ||
+            (c.perTransferRaw !== undefined && !amount(c.perTransferRaw)) || (c.perDayRaw !== undefined && !amount(c.perDayRaw)))
+            invalid();
+        pairs.add(pair);
+        const out = { network: c.network, asset: c.asset };
+        if (c.perTransferRaw !== undefined)
+            out.per_transfer_raw = c.perTransferRaw;
+        if (c.perDayRaw !== undefined)
+            out.per_day_raw = c.perDayRaw;
+        return out;
+    });
+    return { kind: 'wallet_limits.set', owner_type: 'account', owner_id: ownerId, linked_wallet_id: linkedWalletId, payload: { ceilings, recipients: [...declared.recipients], expected_revision: declared.revision } };
+}
+/** The answer of GET /v1/linked-wallets/{id}/limits for walletId. */
+export function parseWalletLimits(payload, walletId) {
+    const root = record(payload, ['request_id', 'limits']);
+    const l = record(root.limits, ['ceilings', 'recipients', 'revision', 'wallet_id']);
+    if (!opaqueId(root.request_id) || l.wallet_id !== walletId || !canonicalDecimal(l.revision) || !recipients(l.recipients))
+        fault();
+    return Object.freeze({ requestId: root.request_id, walletId, revision: l.revision, ceilings: parseCeilings(l.ceilings), recipients: Object.freeze([...l.recipients]) });
+}
+/** The display of a wallet_limits.set operation. */
+export function parseWalletLimitsDisplay(value) {
+    const d = record(value, ['kind', 'owner_id', 'requester_id', 'linked_wallet_id', 'wallet_address', 'ceilings', 'recipients', 'expected_revision']);
+    if (d.kind !== 'wallet_limits.set' || !opaqueId(d.owner_id) || !opaqueId(d.requester_id) || !uuid(d.linked_wallet_id) || typeof d.wallet_address !== 'string' ||
+        d.wallet_address.length < 1 || d.wallet_address.length > 256 || !recipients(d.recipients) || !revision(d.expected_revision))
+        fault();
+    return Object.freeze({ kind: 'wallet_limits.set', ownerId: d.owner_id, requesterId: d.requester_id, linkedWalletId: d.linked_wallet_id, walletAddress: d.wallet_address,
+        ceilings: parseCeilings(d.ceilings), recipients: Object.freeze([...d.recipients]), expectedRevision: d.expected_revision });
+}
+function parseCeilings(value) {
+    if (!Array.isArray(value) || value.length > MaxLimitCeilings)
+        fault();
+    const pairs = new Set();
+    return Object.freeze(value.map((item) => {
+        const c = record(item, ['network', 'asset'], ['per_transfer_raw', 'per_day_raw', 'decimals']);
+        const pair = `${c.network} ${c.asset}`;
+        if (!network(c.network) || !asset(c.asset) || pairs.has(pair) || (c.per_transfer_raw === undefined && c.per_day_raw === undefined) ||
+            (c.per_transfer_raw !== undefined && !amount(c.per_transfer_raw)) || (c.per_day_raw !== undefined && !amount(c.per_day_raw)) ||
+            (c.decimals !== undefined && (!integer(c.decimals) || c.decimals < 0 || c.decimals > 30)))
+            fault();
+        pairs.add(pair);
+        const out = { network: c.network, asset: c.asset };
+        if (c.per_transfer_raw !== undefined)
+            out.perTransferRaw = c.per_transfer_raw;
+        if (c.per_day_raw !== undefined)
+            out.perDayRaw = c.per_day_raw;
+        return Object.freeze(out);
+    }));
+}
+function asset(v) { return v === 'native' || v === 'usdt' || v === 'usdc'; }
+function amount(v) { return canonicalDecimal(v) && v.length <= 78; }
+function revision(v) { return canonicalDecimal(v) && v.length <= 20; }
+function recipients(v) {
+    return Array.isArray(v) && v.length <= MaxLimitRecipients && new Set(v).size === v.length && v.every((r) => typeof r === 'string' && /^[\x21-\x7e]{1,128}$/.test(r));
+}

package/dist/walletOperations.d.ts

@@ -0,0 +1,192 @@
+import { type NextAction } from "./auth.ts";
+import type { ResultRecipient } from "./slice4.ts";
+import { type DisplayCommon } from "./walletDisplayParts.ts";
+import { type LinkedSendDisplay, type LinkedWalletIdentity } from "./linkedSendDisplay.ts";
+import { type MediatedDisplay, type MediatedPurgedDisplay } from "./mediatedOperation.ts";
+export { LinkedSendAssets, MaxTransferCommentBytes, ReplaceActions, linkedSendAsset, replaceAction, transferComment } from "./linkedSendDisplay.ts";
+export type { LinkedSendAsset, LinkedSendDisplay, LinkedWalletIdentity, ReplaceAction } from "./linkedSendDisplay.ts";
+export type { MediatedDisplay, MediatedLinkedSendDisplay, MediatedPurgedDisplay, MediatedSendDisplay } from "./mediatedOperation.ts";
+export type UserWalletOperationKind = "wallet.create" | "wallet.sign" | "wallet.send" | "wallet.export" | "wallet.recover";
+export type WalletResultKind = "signature" | "transfer_receipt" | "wallet_created";
+export type UserWalletState = "awaiting_confirmation" | "authorized" | "dispatching" | "outcome_unknown" | "succeeded" | "failed" | "denied" | "canceled" | "expired";
+export type UserWalletEffectState = "no_effect" | "possible" | "known";
+/**
+ * session_authorized: the account's live session authorized the operation
+ * with no passkey. A send from a linked wallet, plain or a replacement, is
+ * authorized so (owner decision, 14 October 2026), as is the registration of
+ * a linked wallet for tracking; every other wallet operation is confirmed
+ * with a passkey (user_confirmed). user_request_signed: a service forwarded
+ * the send on the person's signed request (Mode C); its display is a
+ * MediatedDisplay, with no result recipient.
+ */
+export type UserWalletAuthorizationBasis = "" | "user_confirmed" | "session_authorized" | "user_request_signed";
+type UserWalletCommon = {
+    owner_type: "account";
+    owner_id: string;
+    result_recipient?: ResultRecipient;
+};
+/**
+ * UserWalletOperationCreate is the closed request body of source §2.2: the
+ * top-level wallet ID is required for every kind except wallet.create, and
+ * each payload carries exactly its kind's fields.
+ */
+export type UserWalletOperationCreate = (UserWalletCommon & {
+    kind: "wallet.create";
+    payload: {
+        network: string;
+        recipient_public_key: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.sign";
+    wallet_id: string;
+    payload: {
+        network: string;
+        message_base64url: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.send";
+    wallet_id: string;
+    payload: {
+        network: string;
+        asset: "native";
+        recipient: string;
+        amount_raw: string;
+        max_fee_raw: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.export";
+    wallet_id: string;
+    payload: {
+        recipient_public_key: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.recover";
+    wallet_id: string;
+    payload: {
+        expected_generation: string;
+        recipient_public_key: string;
+    };
+});
+/** UserWalletPurgedDisplay is the safe identity left after material retention expires. */
+export type UserWalletPurgedDisplay = DisplayCommon & {
+    kind: UserWalletOperationKind;
+    materialPurged: true;
+};
+/**
+ * UserWalletDisplay is the safe display of the frozen material. A purged
+ * record keeps its identity and reports materialPurged instead of inventing
+ * material; it never carries signing output or custody material. Narrow with
+ * `walletMaterialPurged` before reading any per-kind material field.
+ */
+export type UserWalletDisplay = UserWalletPurgedDisplay | (DisplayCommon & {
+    kind: "wallet.create";
+    network: string;
+    recipientPublicKey: string;
+    preparedSummary?: string;
+}) | (DisplayCommon & {
+    kind: "wallet.sign";
+    network: string;
+    messageBase64url: string;
+    preparedSummary?: string;
+}) | (DisplayCommon & {
+    kind: "wallet.send";
+    network: string;
+    asset: string;
+    recipient: string;
+    amountRaw: string;
+    maxFeeRaw: string;
+    preparedSummary?: string;
+}) | LinkedSendDisplay | (DisplayCommon & {
+    kind: "wallet.export";
+    recipientPublicKey: string;
+    preparedSummary?: string;
+}) | (DisplayCommon & {
+    kind: "wallet.recover";
+    recipientPublicKey: string;
+    expectedGeneration: string;
+    preparedSummary?: string;
+}) | MediatedDisplay;
+/** walletMaterialPurged separates the purged display from every material display. */
+export declare function walletMaterialPurged(display: UserWalletDisplay): display is UserWalletPurgedDisplay | MediatedPurgedDisplay;
+export interface UserWalletOperation {
+    id: string;
+    version: string;
+    kind: UserWalletOperationKind;
+    state: UserWalletState;
+    effectState: UserWalletEffectState;
+    authorizationBasis: UserWalletAuthorizationBasis;
+    ownerType: "account";
+    ownerId: string;
+    requesterId: string;
+    walletId?: string;
+    /** Present exactly when the operation names a linked wallet instead of walletId. */
+    linkedWallet?: LinkedWalletIdentity;
+    requestFingerprint: string;
+    operationFingerprint: string;
+    display: UserWalletDisplay;
+    /** UTC RFC 3339 date-time string (source §2.2), not NumericDate seconds. */
+    createdAt: string;
+    /** UTC RFC 3339 date-time string (source §2.2), not NumericDate seconds. */
+    expiresAt: string;
+    confirmationLocation?: string;
+    resultKind?: WalletResultKind;
+    nextAction: NextAction;
+}
+/** CreatedWallet is the public identity of a wallet the own-wallet system created. */
+export interface CreatedWallet {
+    walletId: string;
+    keyId: string;
+    network: string;
+    address: string;
+    algorithm: string;
+    publicKey: string;
+}
+/**
+ * DeviceSharePackage is the device share exactly as the own-wallet system
+ * sealed it to the recipient key frozen in the operation. The provider never
+ * opens it; only the holder of the matching device private key can. Every
+ * binary member is lowercase hexadecimal.
+ */
+export interface DeviceSharePackage {
+    ciphertext: string;
+    nonce: string;
+    ephemeralPublicKey: string;
+    encryptionAlgorithm: string;
+    encryptionContext: string;
+}
+export interface WalletResult {
+    requestId: string;
+    result: {
+        operationId: string;
+        kind: WalletResultKind;
+        receiptId: string;
+        outputBase64url?: string;
+        /** Present exactly for a wallet_created result. */
+        wallet?: CreatedWallet;
+        /** Present exactly for a wallet_created result. */
+        deviceShare?: DeviceSharePackage;
+    };
+}
+/** MaxWalletMessageBytes is the decoded wallet.sign payload bound of source §2.8. */
+export declare const MaxWalletMessageBytes = 4096;
+/**
+ * validateUserWalletCreate rejects every locally detectable fault before any
+ * request leaves the client: a foreign owner, a wallet ID present or absent
+ * against its kind, a non-compressed recipient key, a noncanonical or
+ * out-of-range quantity, a non-native asset, and a sign message outside
+ * 1..4096 decoded bytes. It returns the exact value it was given so the
+ * caller sends the same closed body it validated.
+ */
+export declare function validateUserWalletCreate(value: UserWalletOperationCreate, expectedOwnerId: string): UserWalletOperationCreate;
+export declare function parseUserWalletOperationEnvelope(payload: unknown): {
+    requestId: string;
+    operation: UserWalletOperation;
+};
+export declare function parseUserWalletOperation(payload: unknown): UserWalletOperation;
+/**
+ * parseWalletResult accepts the protected wallet output of source §2.2:
+ * output_base64url is present for a signature and forbidden for a transfer
+ * receipt. A wallet_created result is its own closed shape: the created
+ * wallet and its sealed device share, with no output member.
+ */
+export declare function parseWalletResult(payload: unknown, expectedOperationId: string): WalletResult;