@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/credentials.js

@@ -0,0 +1,315 @@
+/**
+ * The session's credentials and every change to them, in one place.
+ *
+ * Every attempt takes a generation when it starts, before anything is
+ * awaited: a sign-in (code exchange), a renewal or restore, a logout. A
+ * session's lineage is the generation of the sign-in (or first restore) it
+ * comes from; its renewals carry it on, and one lineage is installed at a
+ * time. A sign-in installs while no newer sign-in or logout began. A renewal
+ * installs while the installed lineage did not change since it began (an
+ * epoch counts every change, to none included; a rotation within the lineage
+ * is no change) and it answers the same session of the same account: on the
+ * web the cookie is shared by every tab, and a sign-in in another tab puts its
+ * own session there. A renewal or restore of an installed session that
+ * answers another one installs nothing and ends the installed session
+ * (session_replaced); a client with no session takes up what the cookie holds.
+ * A definitive refusal ends the lineage of the token it refused, also after a
+ * rotation, and nothing else. A logout ends everything older.
+ *
+ * Every change of memory and of secure storage runs in one queue, one after
+ * another, failure cleanup included, and installs only while its attempt is
+ * current at that moment. A renewal reads the stored refresh token only in
+ * the queue and is checked again after the read and before it asks the
+ * provider. A superseded attempt undoes its own storage write and nothing
+ * else. A stored token whose cleanup failed stays marked ended, so no restore
+ * takes it up again. On the web nothing is stored: the refresh credential is
+ * the provider's cookie, and a web renewal or restore is checked against its
+ * attempt under the tabs' lock (webRenewal.ts).
+ */
+import { ClientFlowError, integer, isAuthorizationError, opaqueId, record } from "./auth.js";
+/** A renewal that changed hands before it asked the provider anything. */
+export class Superseded extends Error {
+    constructor() { super("superseded"); this.name = "Superseded"; }
+}
+/** The lineage of a stored token of unknown or failed provenance: it is ended and never taken up. */
+const unclaimed = -1;
+export class Credentials {
+    #channel;
+    #storage;
+    #key;
+    #clock = 0;
+    #latestSignIn = 0;
+    #cut = 0;
+    /** The lineage installed now (0 for none), and the epoch that counts its changes. */
+    #lineage = 0;
+    #epoch = 0;
+    #ended = new Set([unclaimed]);
+    /** Every token of the installed lineage handed out, with its refusal by a read, so a refusal reaches its lineage also after a rotation. */
+    #issued = new Map();
+    #held;
+    #storedLineage;
+    #queue = Promise.resolve();
+    constructor(channel, storage, key) {
+        this.#channel = channel;
+        this.#storage = storage;
+        this.#key = key;
+    }
+    /** current is the credentials held, while their lineage is the one installed. */
+    current() {
+        const held = this.#held;
+        return held && held.lineage === this.#lineage && !this.#ended.has(held.lineage) ? held : undefined;
+    }
+    get hasSession() { return this.current() !== undefined; }
+    /** usable is the token to send now: none while there is no session or a read was refused with it. */
+    usable() {
+        const held = this.current();
+        if (!held || this.#refusedRead(held.token))
+            throw new ClientFlowError("session_unavailable");
+        return held.token;
+    }
+    /** dispatchable says a request may still go out with token: of the lineage installed, and not refused by a read. */
+    dispatchable(token) {
+        const issued = this.#issued.get(token);
+        return issued !== undefined && issued.lineage === this.#lineage && !this.#ended.has(issued.lineage) && !issued.refused;
+    }
+    #refusedRead(token) { return this.#issued.get(token)?.refused === true; }
+    /** due says the token is to be renewed first: it lives less than marginSeconds more, or a read was refused with it. */
+    due(nowSeconds, marginSeconds) {
+        const held = this.current();
+        return held !== undefined && (nowSeconds >= held.session.accessExpiresAt - marginSeconds || this.#refusedRead(held.token));
+    }
+    /**
+     * markRefused marks a token a read was refused with, held now or rotated
+     * away, so no call waiting with it sends it; it says whether it is the
+     * token held now, which only a renewal replaces.
+     */
+    markRefused(token) {
+        const issued = this.#issued.get(token);
+        if (!issued)
+            return false;
+        issued.refused = true;
+        return this.current()?.token === token;
+    }
+    /** signIn starts a sign-in: no older sign-in installs after it. */
+    signIn() {
+        const generation = ++this.#clock;
+        this.#latestSignIn = generation;
+        return { generation, kind: "sign_in", epoch: this.#epoch, founds: true, lineage: generation };
+    }
+    /** renewal starts a renewal of the lineage installed now, or a restore that founds one when none is. */
+    renewal() {
+        const generation = ++this.#clock;
+        const held = this.#held?.lineage === this.#lineage ? this.#held : undefined;
+        const renews = this.#lineage !== 0 && held ? { sessionId: held.session.sessionId, accountId: held.session.accountId } : undefined;
+        return { generation, kind: "renewal", epoch: this.#epoch, founds: this.#lineage === 0, lineage: this.#lineage || generation, renews };
+    }
+    #valid(attempt) {
+        if (attempt.generation <= this.#cut || this.#ended.has(attempt.lineage))
+            return false;
+        return attempt.kind === "sign_in" ? this.#latestSignIn === attempt.generation : this.#epoch === attempt.epoch;
+    }
+    /** #install makes lineage the installed one; a change of lineage starts a new epoch and drops the older lineages' tokens. */
+    #setLineage(lineage) {
+        if (lineage === this.#lineage)
+            return;
+        this.#lineage = lineage;
+        this.#epoch++;
+        for (const [token, issued] of this.#issued)
+            if (issued.lineage !== lineage)
+                this.#issued.delete(token);
+    }
+    /** check throws Superseded once the renewal is no longer current, right before it asks the provider. */
+    check(attempt) {
+        if (!this.#valid(attempt))
+            throw new Superseded();
+    }
+    /** superseded answers for an overtaken renewal: the session held now, or none. */
+    superseded() {
+        const held = this.current();
+        if (held && !this.#refusedRead(held.token))
+            return { ...held.session };
+        throw new ClientFlowError("session_unavailable");
+    }
+    #overtaken(attempt) {
+        if (attempt.kind === "renewal")
+            return this.superseded();
+        throw new ClientFlowError("session_unavailable");
+    }
+    /** refreshToken reads the stored refresh token for a mobile renewal, in the queue, and checks the renewal again after the read. */
+    refreshToken(attempt) {
+        return this.#serial(async () => {
+            this.check(attempt);
+            const storage = this.#storage;
+            const token = await storage.get(this.#key);
+            if (this.#storedLineage !== undefined && this.#ended.has(this.#storedLineage)) {
+                await this.#remove(this.#storedLineage);
+                throw new ClientFlowError("mobile_refresh_unavailable");
+            }
+            if (this.#storedLineage !== undefined) {
+                // A founding restore takes up the stored token's lineage; a renewal renews only its own.
+                if (attempt.founds)
+                    attempt.lineage = this.#storedLineage;
+                else if (this.#storedLineage !== attempt.lineage)
+                    throw new Superseded();
+            }
+            this.check(attempt);
+            if (!token)
+                throw new ClientFlowError("mobile_refresh_unavailable");
+            // A first restore owns the token it took up, so a refusal of it clears it.
+            if (this.#storedLineage === undefined)
+                this.#storedLineage = attempt.lineage;
+            return token;
+        });
+    }
+    /**
+     * install keeps what an exchange or a renewal answered, in the queue, only
+     * while its attempt is current: in secure storage first on mobile, then in
+     * memory. A current attempt whose write fails ends its lineage and clears
+     * the held and stored credentials; an attempt overtaken during its write
+     * puts back what was stored before and installs nothing.
+     */
+    install(attempt, payload, exchange) {
+        const grant = this.#parse(payload, exchange);
+        return this.#serial(async () => {
+            if (!this.#valid(attempt))
+                return this.#overtaken(attempt);
+            if (attempt.renews && (grant.session.sessionId !== attempt.renews.sessionId || grant.session.accountId !== attempt.renews.accountId)) {
+                // Another sign-in's session is in the cookie: the one installed can no longer be renewed, and the other is not taken up unasked.
+                this.#fail(attempt.lineage);
+                if (this.#held?.lineage === attempt.lineage)
+                    this.#held = undefined;
+                await this.#remove(attempt.lineage);
+                throw new ClientFlowError("session_replaced");
+            }
+            if (this.#storage) {
+                const storage = this.#storage;
+                let previous;
+                try {
+                    previous = { value: await storage.get(this.#key), lineage: this.#storedLineage };
+                    await storage.set(this.#key, grant.refresh);
+                    this.#storedLineage = attempt.lineage;
+                }
+                catch {
+                    if (this.#valid(attempt)) {
+                        // Fail closed: this lineage and the one installed end, and what may have been written goes.
+                        this.#fail(attempt.lineage);
+                        this.#fail(this.#lineage);
+                        this.#held = undefined;
+                        this.#storedLineage = attempt.lineage;
+                        await this.#remove(attempt.lineage);
+                    }
+                    else if (previous) {
+                        await this.#putBack(previous);
+                    }
+                    throw new ClientFlowError("secure_storage_unavailable");
+                }
+                if (!this.#valid(attempt)) {
+                    await this.#putBack(previous);
+                    return this.#overtaken(attempt);
+                }
+            }
+            const session = { ...grant.session, setupRequired: exchange ? grant.setupRequired : this.#held?.session.setupRequired };
+            if (session.setupRequired === undefined)
+                delete session.setupRequired;
+            this.#held = { token: grant.token, csrf: grant.csrf, session, lineage: attempt.lineage };
+            this.#setLineage(attempt.lineage);
+            // A token a read refused stays refused, also when a renewal answers its bytes again.
+            this.#issued.set(grant.token, { lineage: attempt.lineage, refused: this.#refusedRead(grant.token) });
+            return { ...session };
+        });
+    }
+    /** refuse ends the lineage of a token the provider refused for good, whichever of its tokens it was. */
+    refuse(token) {
+        const issued = this.#issued.get(token);
+        if (issued !== undefined)
+            this.end(issued.lineage);
+    }
+    /** renewalFailed answers for a failed renewal: overtaken, it is the session now; refused for good, its lineage ends. */
+    renewalFailed(attempt, error) {
+        if (error instanceof Superseded)
+            return this.superseded();
+        if (isAuthorizationError(error, "UNAUTHORIZED"))
+            this.end(attempt.lineage);
+        throw error;
+    }
+    /** end ends one lineage at once, and clears its held and stored credentials in the queue. */
+    end(lineage) {
+        this.#fail(lineage);
+        void this.#serial(async () => {
+            if (this.#held?.lineage === lineage)
+                this.#held = undefined;
+            await this.#remove(lineage);
+        });
+    }
+    /** logout ends the session held at once and every older attempt, clears memory and storage in the queue, and answers what it ended. */
+    logout() {
+        const held = this.current();
+        this.#cut = ++this.#clock;
+        this.#fail(this.#lineage);
+        const cleared = this.#serial(async () => {
+            this.#held = undefined;
+            if (!this.#storage)
+                return;
+            // Whatever is stored ends with the logout, of known lineage or not, and stays ended if the deletion fails.
+            if (this.#storedLineage === undefined)
+                this.#storedLineage = unclaimed;
+            this.#ended.add(this.#storedLineage);
+            await this.#storage.delete(this.#key);
+            this.#storedLineage = undefined;
+        });
+        return { token: held?.token, csrf: held?.csrf, sessionId: held?.session.sessionId, cleared };
+    }
+    /** #fail ends a lineage in memory: nothing of it installs or goes out any more. */
+    #fail(lineage) {
+        if (lineage === 0)
+            return;
+        this.#ended.add(lineage);
+        if (this.#lineage === lineage)
+            this.#setLineage(0);
+    }
+    /** #remove deletes the stored token of an ended lineage; when the deletion fails it stays marked ended. */
+    async #remove(lineage) {
+        if (!this.#storage || this.#storedLineage !== lineage)
+            return;
+        try {
+            await this.#storage.delete(this.#key);
+            this.#storedLineage = undefined;
+        }
+        catch { /* stays stored and ended: no restore takes it up */ }
+    }
+    /** #putBack restores what was stored before an overtaken attempt wrote. */
+    async #putBack(previous) {
+        const storage = this.#storage;
+        try {
+            if (previous.value === null)
+                await storage.delete(this.#key);
+            else
+                await storage.set(this.#key, previous.value);
+            this.#storedLineage = previous.lineage;
+        }
+        catch {
+            // What is stored now is the overtaken attempt's: it stays marked ended.
+            this.#storedLineage = unclaimed;
+        }
+    }
+    #serial(work) {
+        const run = this.#queue.then(work);
+        this.#queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    #parse(payload, exchange) {
+        const channelField = this.#channel === "web" ? "csrf_token" : "refresh_token";
+        const required = ["request_id", "access_token", "expires_at", "account_id", "session_id", channelField];
+        if (exchange)
+            required.push("setup_required");
+        const root = record(payload, required);
+        if (!opaqueId(root.request_id) || typeof root.access_token !== "string" || root.access_token.length === 0 || !integer(root.expires_at) || !opaqueId(root.account_id) || !opaqueId(root.session_id) || (exchange && typeof root.setup_required !== "boolean") || typeof root[channelField] !== "string" || root[channelField].length === 0) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        return {
+            token: root.access_token, csrf: this.#channel === "web" ? root.csrf_token : undefined, refresh: this.#channel === "mobile" ? root.refresh_token : undefined,
+            setupRequired: exchange ? root.setup_required : undefined,
+            session: { requestId: root.request_id, accessExpiresAt: root.expires_at, accountId: root.account_id, sessionId: root.session_id },
+        };
+    }
+}

package/dist/debitPermissionWire.d.ts

@@ -0,0 +1,90 @@
+import type { DeviceSharePackage } from './walletOperations.ts';
+export type DebitAsset = 'native' | 'usdt' | 'usdc';
+/** At most this many assets, and this many recipients, in one permission. */
+export declare const MaxDebitAssets = 3;
+export declare const MaxDebitRecipients = 10;
+/** The bounds of one asset, in its minimal units on the wallet's network: one debit, and 24 hours of debits. */
+export interface DebitAssetBound {
+    asset: DebitAsset;
+    perDebitRaw: string;
+    perDayRaw: string;
+}
+/**
+ * What the person grants. walletId is the linked wallet; the permission is on that wallet's own network.
+ * recipients absent or empty: any recipient. expiresAt (UTC RFC 3339, in the future) absent: until revoked.
+ */
+export interface DebitPermissionInput {
+    walletId: string;
+    servicePrincipalId: string;
+    assets: readonly DebitAssetBound[];
+    recipients?: readonly string[];
+    expiresAt?: string;
+}
+/**
+ * What the person confirms. recipients are in the form the network compares them by. shareKeeperPublicKey is
+ * present when the keeper does not hold this wallet's device share yet: the execute then hands it over.
+ */
+export interface DebitPermissionDisplay {
+    kind: 'debit_permission.create';
+    ownerId: string;
+    requesterId: string;
+    linkedWalletId: string;
+    servicePrincipalId: string;
+    network: string;
+    address: string;
+    assets: readonly DebitAssetBound[];
+    recipients: readonly string[];
+    expiresAt?: string;
+    shareKeeperPublicKey?: string;
+}
+/** What the person confirms to end one permission. */
+export interface DebitPermissionRevokeDisplay {
+    kind: 'debit_permission.revoke';
+    ownerId: string;
+    requesterId: string;
+    debitPermissionId: string;
+    servicePrincipalId: string;
+    linkedWalletId: string;
+    network: string;
+    address: string;
+}
+/** expired: past its end. A revoked permission names revokedAt. */
+export type DebitPermissionState = 'active' | 'revoked' | 'expired';
+/** One permission the account gave. serviceName is absent when the service has no display name. */
+export interface DebitPermission {
+    id: string;
+    servicePrincipalId: string;
+    serviceName?: string;
+    linkedWalletId: string;
+    network: string;
+    address: string;
+    assets: readonly DebitAssetBound[];
+    recipients: readonly string[];
+    expiresAt?: string;
+    state: DebitPermissionState;
+    version: string;
+    createdAt: string;
+    revokedAt?: string;
+}
+/** The account's permissions, newest first, at most 100. */
+export interface DebitPermissionList {
+    requestId: string;
+    items: readonly DebitPermission[];
+}
+/** The device key and the wallet's device share as stored on the device, still sealed to that key. */
+export interface DebitShareKeys {
+    devicePrivateKey: CryptoKey;
+    deviceShare: DeviceSharePackage;
+}
+/** The closed body of POST /v1/operations that asks for a new permission. */
+export declare function debitPermissionCreate(ownerId: string, input: DebitPermissionInput): Record<string, unknown>;
+/** The closed body of POST /v1/operations that asks to end one permission. */
+export declare function debitPermissionRevocation(ownerId: string, debitPermissionId: string): Record<string, unknown>;
+/** The display of a debit_permission.create operation. */
+export declare function parseDebitPermissionDisplay(value: unknown): DebitPermissionDisplay;
+/** The display of a debit_permission.revoke operation. */
+export declare function parseDebitPermissionRevokeDisplay(value: unknown): DebitPermissionRevokeDisplay;
+/** The answer of GET /v1/debit-permissions. */
+export declare function parseDebitPermissionList(payload: unknown): DebitPermissionList;
+export declare function wireBounds(value: unknown): readonly DebitAssetBound[];
+export declare function recipients(v: unknown): v is string[];

package/dist/debitPermissionWire.js

@@ -0,0 +1,118 @@
+// The wire of card-like debits (owner decision of 28 October 2026). A person
+// lets one service debit one of their linked wallets without their device:
+// for one to three assets the most one debit and the most 24 hours of debits
+// may move, the recipients a debit may go to (none: any) and an optional end.
+// The person confirms it with a passkey on the provider's page, and its
+// execute hands the wallet's device share to the platform share keeper,
+// sealed to a key the keeper made for that operation; Authorization never
+// opens it. The person keeps their own copy. This module builds the closed
+// request bodies and reads the closed answers; debitPermissions.ts sends them.
+import { ClientFlowError, opaqueId, record, rfc3339UTC } from './auth.js';
+import { fault, network, safeRevision, text, uuid } from './linkedChecks.js';
+/** At most this many assets, and this many recipients, in one permission. */
+export const MaxDebitAssets = 3;
+export const MaxDebitRecipients = 10;
+const invalid = () => { throw new ClientFlowError('invalid_operation_create'); };
+/** The closed body of POST /v1/operations that asks for a new permission. */
+export function debitPermissionCreate(ownerId, input) {
+    let declared;
+    try {
+        declared = record(input, ['walletId', 'servicePrincipalId', 'assets'], ['recipients', 'expiresAt']);
+    }
+    catch {
+        return invalid();
+    }
+    if (!opaqueId(ownerId) || !uuid(declared.walletId) || !opaqueId(declared.servicePrincipalId) ||
+        (declared.recipients !== undefined && !recipients(declared.recipients)) || (declared.expiresAt !== undefined && !rfc3339UTC(declared.expiresAt)))
+        invalid();
+    const assets = parseBounds(declared.assets, ['asset', 'perDebitRaw', 'perDayRaw'], invalid).map((a) => ({ asset: a.asset, per_debit_raw: a.perDebitRaw, per_day_raw: a.perDayRaw }));
+    const payload = { service_principal_id: declared.servicePrincipalId, assets };
+    if (declared.recipients !== undefined)
+        payload.recipients = [...declared.recipients];
+    if (declared.expiresAt !== undefined)
+        payload.expires_at = declared.expiresAt;
+    return { kind: 'debit_permission.create', owner_type: 'account', owner_id: ownerId, linked_wallet_id: declared.walletId, payload };
+}
+/** The closed body of POST /v1/operations that asks to end one permission. */
+export function debitPermissionRevocation(ownerId, debitPermissionId) {
+    if (!opaqueId(ownerId) || !uuid(debitPermissionId))
+        invalid();
+    return { kind: 'debit_permission.revoke', owner_type: 'account', owner_id: ownerId, payload: { debit_permission_id: debitPermissionId } };
+}
+/** The display of a debit_permission.create operation. */
+export function parseDebitPermissionDisplay(value) {
+    const d = record(value, ['kind', 'owner_id', 'requester_id', 'linked_wallet_id', 'service_principal_id', 'network', 'address', 'assets', 'recipients'], ['expires_at', 'share_keeper_public_key']);
+    if (d.kind !== 'debit_permission.create' || !opaqueId(d.owner_id) || !opaqueId(d.requester_id) || !uuid(d.linked_wallet_id) || !opaqueId(d.service_principal_id) ||
+        !network(d.network) || !text(d.address, 256) || !recipients(d.recipients) || (d.expires_at !== undefined && !rfc3339UTC(d.expires_at)) ||
+        (d.share_keeper_public_key !== undefined && (typeof d.share_keeper_public_key !== 'string' || !/^0[23][0-9a-f]{64}$/.test(d.share_keeper_public_key))))
+        fault();
+    const display = { kind: 'debit_permission.create', ownerId: d.owner_id, requesterId: d.requester_id, linkedWalletId: d.linked_wallet_id, servicePrincipalId: d.service_principal_id,
+        network: d.network, address: d.address, assets: wireBounds(d.assets), recipients: Object.freeze([...d.recipients]) };
+    if (d.expires_at !== undefined)
+        display.expiresAt = d.expires_at;
+    if (d.share_keeper_public_key !== undefined)
+        display.shareKeeperPublicKey = d.share_keeper_public_key;
+    return Object.freeze(display);
+}
+/** The display of a debit_permission.revoke operation. */
+export function parseDebitPermissionRevokeDisplay(value) {
+    const d = record(value, ['kind', 'owner_id', 'requester_id', 'debit_permission_id', 'service_principal_id', 'linked_wallet_id', 'network', 'address']);
+    if (d.kind !== 'debit_permission.revoke' || !opaqueId(d.owner_id) || !opaqueId(d.requester_id) || !uuid(d.debit_permission_id) || !opaqueId(d.service_principal_id) ||
+        !uuid(d.linked_wallet_id) || !network(d.network) || !text(d.address, 256))
+        fault();
+    return Object.freeze({ kind: 'debit_permission.revoke', ownerId: d.owner_id, requesterId: d.requester_id, debitPermissionId: d.debit_permission_id,
+        servicePrincipalId: d.service_principal_id, linkedWalletId: d.linked_wallet_id, network: d.network, address: d.address });
+}
+/** The answer of GET /v1/debit-permissions. */
+export function parseDebitPermissionList(payload) {
+    const root = record(payload, ['items', 'request_id']);
+    if (!opaqueId(root.request_id) || !Array.isArray(root.items) || root.items.length > 100)
+        fault();
+    const items = root.items.map((value) => {
+        const p = record(value, ['id', 'service_principal_id', 'linked_wallet_id', 'network', 'address', 'assets', 'recipients', 'state', 'version', 'created_at'], ['service_name', 'expires_at', 'revoked_at']);
+        if (!uuid(p.id) || !opaqueId(p.service_principal_id) || !uuid(p.linked_wallet_id) || !network(p.network) || !text(p.address, 256) || !recipients(p.recipients) ||
+            (p.state !== 'active' && p.state !== 'revoked' && p.state !== 'expired') || !safeRevision(p.version) || !rfc3339UTC(p.created_at) ||
+            (p.service_name !== undefined && !serviceName(p.service_name)) || (p.expires_at !== undefined && !rfc3339UTC(p.expires_at)) ||
+            (p.revoked_at !== undefined && !rfc3339UTC(p.revoked_at)) || (p.state === 'revoked') !== (p.revoked_at !== undefined) || (p.state === 'expired' && p.expires_at === undefined))
+            fault();
+        const item = { id: p.id, servicePrincipalId: p.service_principal_id, linkedWalletId: p.linked_wallet_id, network: p.network, address: p.address,
+            assets: wireBounds(p.assets), recipients: Object.freeze([...p.recipients]), state: p.state, version: p.version, createdAt: p.created_at };
+        if (p.service_name !== undefined)
+            item.serviceName = p.service_name;
+        if (p.expires_at !== undefined)
+            item.expiresAt = p.expires_at;
+        if (p.revoked_at !== undefined)
+            item.revokedAt = p.revoked_at;
+        return Object.freeze(item);
+    });
+    if (new Set(items.map((item) => item.id)).size !== items.length)
+        fault();
+    return Object.freeze({ requestId: root.request_id, items: Object.freeze(items) });
+}
+export function wireBounds(value) {
+    return Object.freeze(parseBounds(value, ['asset', 'per_debit_raw', 'per_day_raw'], fault).map((a) => Object.freeze(a)));
+}
+// parseBounds reads one to three assets, each named once, both amounts canonical and above zero, the one debit no more than the day.
+function parseBounds(value, members, refuse) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > MaxDebitAssets)
+        refuse();
+    const seen = new Set();
+    return value.map((item) => {
+        let a;
+        try {
+            a = record(item, members);
+        }
+        catch {
+            return refuse();
+        }
+        const [perDebit, perDay] = [a[members[1]], a[members[2]]];
+        if (!asset(a.asset) || seen.has(a.asset) || !amount(perDebit) || !amount(perDay) || BigInt(perDebit) > BigInt(perDay))
+            refuse();
+        seen.add(a.asset);
+        return { asset: a.asset, perDebitRaw: perDebit, perDayRaw: perDay };
+    });
+}
+function asset(v) { return v === 'native' || v === 'usdt' || v === 'usdc'; }
+function amount(v) { return typeof v === 'string' && /^[1-9][0-9]{0,77}$/.test(v); }
+export function recipients(v) { return Array.isArray(v) && v.length <= MaxDebitRecipients && v.every((r) => typeof r === 'string' && /^[\x21-\x7e]{1,128}$/.test(r)); }
+function serviceName(v) { return typeof v === 'string' && v.length > 0 && new TextEncoder().encode(v).length <= 128 && !/[\x00-\x1f\x7f-\x9f]/.test(v); }

package/dist/debitPermissions.d.ts

@@ -0,0 +1,39 @@
+import { type DebitPermissionInput, type DebitPermissionList, type DebitShareKeys } from './debitPermissionWire.ts';
+import type { LinkedWalletTransport } from './linkedWallets.ts';
+import { type LocalOperation } from './slice4.ts';
+import type { DeviceSharePackage } from './walletOperations.ts';
+/** The device share the SDK keeps for a linked wallet, resealed to one public key (LinkedWallets); with recover false it never recovers one. */
+export type KeptShareSealer = (linkedWalletId: string, publicKey: string, signal?: AbortSignal, recover?: boolean) => Promise<DeviceSharePackage>;
+export { MaxDebitAssets, MaxDebitRecipients, debitPermissionCreate, debitPermissionRevocation, parseDebitPermissionDisplay, parseDebitPermissionList, parseDebitPermissionRevokeDisplay } from './debitPermissionWire.ts';
+export type { DebitAsset, DebitAssetBound, DebitPermission, DebitPermissionDisplay, DebitPermissionInput, DebitPermissionList, DebitPermissionRevokeDisplay, DebitPermissionState, DebitShareKeys } from './debitPermissionWire.ts';
+export declare class DebitPermissions {
+    #private;
+    constructor(transport: LinkedWalletTransport, kept?: KeptShareSealer);
+    /**
+     * Asks to let one service debit one linked wallet within the bounds given. The operation comes back
+     * awaiting the person's passkey; its display says the bounds as the provider keeps them and, when the
+     * keeper does not hold the wallet's device share yet, the key the execute seals it to.
+     */
+    createDebitPermission(input: DebitPermissionInput, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /**
+     * Applies a confirmed permission. It reads the operation first: when it is confirmed (authorized, at the
+     * version given) and its display names the share keeper's key, the device share is resealed to that key and sent: without keys the
+     * share the SDK keeps for the wallet (recovered first with one passkey confirmation when this browser holds none), with keys the
+     * app's own (resealDeviceShare). The plaintext share exists only inside that call. Without that key the keeper holds the share already
+     * and nothing is sent. The person's own copy stays where it is, and their sends with it go on as before.
+     */
+    executeDebitPermission(operationId: string, version: string, idempotencyKey: string, keys?: DebitShareKeys, signal?: AbortSignal): Promise<LocalOperation>;
+    /**
+     * executeConsentDebitPermission is executeDebitPermission() with the share the SDK keeps, for the permission a
+     * grant's consent created (consentDebit.ts): it never recovers a share, so reading a result never asks for a
+     * passkey; without a current share kept here it refuses with device_share_unavailable and sends nothing.
+     */
+    executeConsentDebitPermission(operationId: string, version: string, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /** The account's permissions in every state, newest first. */
+    listDebitPermissions(signal?: AbortSignal): Promise<DebitPermissionList>;
+    /**
+     * Asks to end one permission. The operation awaits the person's passkey; executeOperation() applies it,
+     * without a body. A debit not yet executed is refused from then on.
+     */
+    revokeDebitPermission(debitPermissionId: string, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+}