@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/sends.js

@@ -0,0 +1,127 @@
+// The account's history of sends: GET /v1/operations narrowed to wallet.send,
+// newest first. Every row is one send with what a history shows of it: where,
+// what, how much, to whom, its state, its transaction hash and, once the
+// own-wallet system reported it, the final fate of its transfer.
+import { ClientFlowError, opaqueId, record, rfc3339UTC } from './auth.js';
+import { pageEnvelope, pageRequest } from './pages.js';
+import { parseUserWalletOperation, walletMaterialPurged } from './walletOperations.js';
+const hashPattern = /^[A-Za-z0-9_.:-]{1,128}$/;
+/** The path of one page of the send history. */
+export function sendsPath(options) {
+    const { path, signal } = pageRequest('/v1/operations', options);
+    return { path: `${path}${path.includes('?') ? '&' : '?'}kind=wallet.send`, signal };
+}
+/** Parses one closed page of the send history. */
+export function parseSendPage(payload) {
+    const page = pageEnvelope(payload);
+    const items = page.items.map(parseListedSend);
+    // Newest first: a page out of order is not this list.
+    if (items.some((item, index) => index > 0 && Date.parse(items[index - 1].createdAt) < Date.parse(item.createdAt)))
+        fault();
+    const out = { requestId: page.request_id, items: Object.freeze(items), hasMore: page.has_more };
+    return Object.freeze(page.has_more ? { ...out, nextCursor: page.next_cursor } : out);
+}
+function parseListedSend(payload) {
+    const item = record(payload, ['operation'], ['transaction_hash', 'transfer']);
+    const raw = item.operation;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw) || raw.kind !== 'wallet.send')
+        fault();
+    const send = listedSend(item.operation);
+    if (item.transaction_hash !== undefined) {
+        if (typeof item.transaction_hash !== 'string' || !hashPattern.test(item.transaction_hash) || send.linkedWalletId === undefined)
+            fault();
+        send.transactionHash = item.transaction_hash;
+    }
+    if (item.transfer !== undefined) {
+        if (send.linkedWalletId === undefined)
+            fault();
+        send.transfer = parseTransferOutcome(item.transfer);
+        if (send.transfer.replacedByOperationId === send.operationId)
+            fault();
+    }
+    return Object.freeze(send);
+}
+/**
+ * One send of the account: from a linked wallet authorized by its session,
+ * confirmed with its passkey, or forwarded by a service on the person's signed
+ * request (Mode C, from a bound or a linked wallet), each read with the parser
+ * of the projection the provider serves for it.
+ */
+function listedSend(payload) {
+    const operation = parseUserWalletOperation(payload);
+    const send = {
+        operationId: operation.id, state: operation.state, effectState: operation.effectState, authorizationBasis: operation.authorizationBasis,
+        createdAt: operation.createdAt, expiresAt: operation.expiresAt, materialPurged: walletMaterialPurged(operation.display),
+    };
+    if (operation.linkedWallet)
+        send.linkedWalletId = operation.linkedWallet.linkedWalletId;
+    if (operation.walletId !== undefined)
+        send.walletId = operation.walletId;
+    const display = operation.display;
+    if (!walletMaterialPurged(display) && display.kind === 'wallet.send') {
+        send.network = display.network;
+        send.asset = display.asset;
+        send.recipient = display.recipient;
+        send.amountRaw = display.amountRaw;
+        if ('address' in display && display.address !== undefined)
+            send.address = display.address;
+        if ('comment' in display && display.comment !== undefined)
+            send.comment = display.comment;
+        if ('replacesOperationId' in display && display.replacesOperationId !== undefined) {
+            send.replacesOperationId = display.replacesOperationId;
+            send.replaceAction = display.replaceAction;
+        }
+    }
+    return send;
+}
+function parseTransferOutcome(payload) {
+    const t = record(payload, ['observed_at', 'state'], ['transaction_hash', 'failure_reason', 'replaced_by_operation_id']);
+    const hash = t.transaction_hash, reason = t.failure_reason, replacedBy = t.replaced_by_operation_id;
+    if (!['confirmed', 'failed', 'expired'].includes(t.state) || !rfc3339UTC(t.observed_at) ||
+        (hash !== undefined && (typeof hash !== 'string' || !hashPattern.test(hash))) || (t.state === 'confirmed' && hash === undefined) ||
+        (reason !== undefined && (t.state !== 'failed' || typeof reason !== 'string' || reason.length === 0 || new TextEncoder().encode(reason).length > 1024 || /[\x00-\x1f\x7f-\x9f]/.test(reason))) ||
+        (replacedBy !== undefined && (reason !== 'nonce_used' || !opaqueId(replacedBy))))
+        fault();
+    const out = { state: t.state, observedAt: t.observed_at };
+    if (hash !== undefined)
+        out.transactionHash = hash;
+    if (replacedBy !== undefined)
+        out.replacedByOperationId = replacedBy;
+    if (reason !== undefined)
+        out.failureReason = reason;
+    return Object.freeze(out);
+}
+/**
+ * Says whether a wallet event is the network's record of the transaction with
+ * this hash on this network: true or false where an event's sourceReference
+ * is the transaction hash, and undefined on every other network, where
+ * nothing ties an event to a hash yet. On the EVM networks and TRON the two
+ * are one hexadecimal hash and differ at most in a 0x prefix and letter case.
+ * On Solana both are the transaction's signature in base58, where case is
+ * part of the value. On TON the event names the transaction the network made
+ * and the own-wallet system names the message it sent; the two hashes differ.
+ */
+export function eventOfTransaction(event, networkId, transactionHash) {
+    const family = networkId.split(':', 1)[0];
+    if (family === 'solana')
+        return event.networkId === networkId && /^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(transactionHash) && event.sourceReference === transactionHash;
+    if (family !== 'eip155' && family !== 'tron')
+        return undefined;
+    const bare = (value) => value.toLowerCase().replace(/^0x/, '');
+    return event.networkId === networkId && /^(0x)?[0-9a-fA-F]{64}$/.test(transactionHash) && bare(event.sourceReference) === bare(transactionHash);
+}
+/**
+ * The wallet events that record one listed send on its network: the
+ * withdrawal from the sending wallet and any activity of the same
+ * transaction. It returns undefined where events cannot be tied to the send
+ * (no hash yet, details purged, or a network without that tie), and an empty
+ * list where they can and none of the given events is of this send.
+ */
+export function sendEvents(send, events) {
+    if (send.network === undefined || send.transactionHash === undefined)
+        return undefined;
+    if (eventOfTransaction({ networkId: send.network, sourceReference: '' }, send.network, send.transactionHash) === undefined)
+        return undefined;
+    return events.filter((event) => eventOfTransaction(event, send.network, send.transactionHash) === true);
+}
+function fault() { throw new ClientFlowError('invalid_server_response'); }

package/dist/serviceGrants.d.ts

@@ -0,0 +1,52 @@
+import type { LocalOperationCreate, ServiceReadScope } from "./slice4.ts";
+/** What a grant gives, or changes a grant to; `enabled: false` withdraws it. */
+export interface ServiceGrantInput {
+    walletId: string;
+    servicePrincipalId: string;
+    enabled: boolean;
+    scopes: ServiceReadScope[];
+    /** The service's own reference for its user, returned only to that service; it proves nothing. */
+    externalRef?: string;
+}
+/** The one grant to withdraw: the wallet and the service it names. */
+export interface ServiceGrantTarget {
+    walletId: string;
+    servicePrincipalId: string;
+}
+/**
+ * pending_source: a first streams:read grant waits until Streams opens the
+ * wallet's events to the service. active: the service reads under it now.
+ * revoked: withdrawn with `enabled: false`. stale: the wallet or the service
+ * changed since the grant was set, and the service reads nothing under it
+ * until it is set again.
+ */
+export type ServiceGrantState = "pending_source" | "active" | "revoked" | "stale";
+/**
+ * One grant the account gave. walletKind names the wallet as me() does: "wallet" for a wallet Authorization
+ * created for the account, "linked_wallet" for one of its linked wallets. network and address are empty for a
+ * wallet that is no longer the one granted.
+ */
+export interface AccountServiceGrant {
+    servicePrincipalId: string;
+    walletId: string;
+    walletKind: "wallet" | "linked_wallet";
+    network: string;
+    address: string;
+    scopes: ServiceReadScope[];
+    state: ServiceGrantState;
+    /** UTC RFC 3339 date-time of the last change. */
+    grantedAt: string;
+    externalRef?: string;
+}
+export interface ServiceGrantPage {
+    requestId: string;
+    items: AccountServiceGrant[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+/** serviceGrantCreate is the closed `service_grant.set` body of the account. */
+export declare function serviceGrantCreate(ownerId: string, input: ServiceGrantInput): LocalOperationCreate;
+/** serviceGrantRevocation withdraws the grant of one service on one wallet: enabled false, no scopes. */
+export declare function serviceGrantRevocation(ownerId: string, target: ServiceGrantTarget): LocalOperationCreate;
+/** parseServiceGrantPage reads exactly one `GET /v1/service-grants` page. */
+export declare function parseServiceGrantPage(payload: unknown): ServiceGrantPage;

package/dist/serviceGrants.js

@@ -0,0 +1,46 @@
+/**
+ * The grants an account gives services on its wallets. `service_grant.set`
+ * gives one service read access to one wallet the account owns, changes it or
+ * withdraws it (`enabled: false`); the person confirms every change with a
+ * passkey. `GET /v1/service-grants` lists the grants the account gave, in every
+ * state, so the application can show them and offer to withdraw one.
+ */
+import { ClientFlowError, opaqueId, record, rfc3339UTC } from "./auth.js";
+import { pageEnvelope, pageProjection } from "./pages.js";
+const readScopes = ["wallet:read", "operation:read", "streams:read"];
+/** serviceGrantCreate is the closed `service_grant.set` body of the account. */
+export function serviceGrantCreate(ownerId, input) {
+    const payload = { service_principal_id: input.servicePrincipalId, enabled: input.enabled, scopes: [...input.scopes] };
+    if (input.externalRef !== undefined)
+        payload.external_ref = input.externalRef;
+    return { kind: "service_grant.set", owner_type: "account", owner_id: ownerId, wallet_id: input.walletId, payload };
+}
+/** serviceGrantRevocation withdraws the grant of one service on one wallet: enabled false, no scopes. */
+export function serviceGrantRevocation(ownerId, target) {
+    if (target === null || typeof target !== "object")
+        throw new ClientFlowError("invalid_operation_create");
+    return serviceGrantCreate(ownerId, { walletId: target.walletId, servicePrincipalId: target.servicePrincipalId, enabled: false, scopes: [] });
+}
+/** parseServiceGrantPage reads exactly one `GET /v1/service-grants` page. */
+export function parseServiceGrantPage(payload) {
+    const root = pageEnvelope(payload);
+    const items = root.items.map((value) => {
+        const item = record(value, ["address", "granted_at", "network", "scopes", "service_principal_id", "state", "wallet_id", "wallet_kind"], ["external_ref"]);
+        const scopes = item.scopes;
+        if (!opaqueId(item.service_principal_id) || !opaqueId(item.wallet_id) || (item.wallet_kind !== "wallet" && item.wallet_kind !== "linked_wallet") ||
+            typeof item.network !== "string" || item.network.length > 64 || typeof item.address !== "string" || item.address.length > 256 ||
+            !Array.isArray(scopes) || scopes.length > readScopes.length || new Set(scopes).size !== scopes.length || !scopes.every((scope) => readScopes.includes(scope)) ||
+            (item.state !== "pending_source" && item.state !== "active" && item.state !== "revoked" && item.state !== "stale") || !rfc3339UTC(item.granted_at) ||
+            (item.external_ref !== undefined && (typeof item.external_ref !== "string" || !/^[\x20-\x7E]{1,128}$/.test(item.external_ref)))) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        const grant = {
+            servicePrincipalId: item.service_principal_id, walletId: item.wallet_id, walletKind: item.wallet_kind, network: item.network, address: item.address,
+            scopes: [...scopes], state: item.state, grantedAt: item.granted_at,
+        };
+        if (item.external_ref !== undefined)
+            grant.externalRef = item.external_ref;
+        return grant;
+    });
+    return pageProjection(root.request_id, items, root.has_more, root.next_cursor);
+}

package/dist/slice4.d.ts

@@ -0,0 +1,187 @@
+import { type IdentityMethod, type NextAction } from "./auth.ts";
+import { type WalletLimitsDisplay } from "./walletLimits.ts";
+import { type DebitPermissionDisplay, type DebitPermissionRevokeDisplay } from "./debitPermissionWire.ts";
+import { type ConsentDebitOutcome, type DebitTerms } from "./consentDebit.ts";
+import { type LinkedEnrollmentDisplay, type LinkedRequestGrantEnrollmentCreate, type LinkedRequestGrantResult } from "./modeCLinked.ts";
+export interface HostedIdentityFlow {
+    requestId: string;
+    flowId: string;
+    launchUrl: string;
+    expiresAt: number;
+}
+export interface PasskeyBootstrapResult {
+    requestId: string;
+    credentialId: string;
+    version: string;
+    state: "active";
+}
+export interface VerifiedIdentityResult {
+    requestId: string;
+    verifiedIdentityHandle: string;
+    expiresAt: number;
+}
+export type IdentityVerificationMethod = IdentityMethod;
+/**
+ * AccountIdentity is one active sign-in method of the account. A passkey
+ * carries credentialId: the credential to name when a confirmation is asked
+ * for, also in a browser that did not create that passkey.
+ */
+export interface AccountIdentity {
+    identityId: string;
+    method: IdentityMethod;
+    credentialId?: string;
+    createdAt: string;
+}
+/** parseIdentityList accepts the closed answer of GET /v1/identities. */
+export declare function parseIdentityList(payload: unknown): AccountIdentity[];
+/**
+ * wallet_limits.set changes a linked wallet's limits (LinkedWallets.setLimits); its result kind is wallet_limits.
+ * session.authorize_requests enrolls a Mode C request key on a linked wallet (modeCLinked.ts); its result kind is
+ * request_grant, with the grant. debit_permission.create and debit_permission.revoke give and end a service's
+ * permission to debit a linked wallet without the device (debitPermissions.ts); their result kind is debit_permission.
+ */
+export type LocalOperationKind = "identity.link" | "identity.unlink" | "session.revoke" | "service_grant.set" | "wallet_limits.set" | "session.authorize_requests" | "debit_permission.create" | "debit_permission.revoke";
+export type LocalResultKind = "identity" | "session" | "service_grant" | "wallet_limits" | "request_grant" | "debit_permission";
+export type LocalResultState = "active" | "revoked";
+export type ServiceReadScope = "wallet:read" | "operation:read" | "streams:read";
+export type ResultRecipient = {
+    type: "account" | "service";
+    id: string;
+};
+type LocalOperationCommon = {
+    owner_type: "account";
+    owner_id: string;
+    result_recipient?: ResultRecipient;
+};
+export type LocalOperationCreate = (LocalOperationCommon & {
+    kind: "identity.link";
+    payload: {
+        verified_identity_handle: string;
+    };
+}) | (LocalOperationCommon & {
+    kind: "identity.unlink";
+    payload: {
+        identity_id: string;
+    };
+}) | (LocalOperationCommon & {
+    kind: "session.revoke";
+    payload: {
+        session_id: string;
+    };
+}) | (LocalOperationCommon & {
+    kind: "service_grant.set";
+    wallet_id: string;
+    payload: {
+        service_principal_id: string;
+        enabled: boolean;
+        scopes: ServiceReadScope[];
+        external_ref?: string;
+    };
+}) | LinkedRequestGrantEnrollmentCreate;
+export type OperationDisplay = {
+    kind: "identity.link";
+    ownerId: string;
+    requesterId: string;
+    method: IdentityMethod;
+} | {
+    kind: "identity.unlink";
+    ownerId: string;
+    requesterId: string;
+    identityId: string;
+} | {
+    kind: "session.revoke";
+    ownerId: string;
+    requesterId: string;
+    sessionId: string;
+} | {
+    kind: "service_grant.set";
+    ownerId: string;
+    requesterId: string;
+    walletId: string;
+    servicePrincipalId: string;
+    enabled: boolean;
+    scopes: ServiceReadScope[];
+    externalRef?: string;
+    debit?: DebitTerms;
+} | WalletLimitsDisplay | LinkedEnrollmentDisplay | DebitPermissionDisplay | DebitPermissionRevokeDisplay;
+export interface LocalOperation {
+    id: string;
+    version: string;
+    kind: LocalOperationKind;
+    state: "awaiting_confirmation" | "authorized" | "pending_target_fence" | "succeeded" | "failed" | "denied" | "canceled" | "expired";
+    effectState: "no_effect" | "known";
+    authorizationBasis: "" | "user_confirmed";
+    ownerType: "account";
+    ownerId: string;
+    requesterId: string;
+    walletId?: string;
+    requestFingerprint: string;
+    operationFingerprint: string;
+    display: OperationDisplay;
+    /** 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?: LocalResultKind;
+    nextAction: NextAction;
+}
+export interface ConfirmationChallenge {
+    requestId: string;
+    challengeId: string;
+    publicKey: {
+        challenge: string;
+        rpId: string;
+        timeoutMs: number;
+        allowCredentials: [{
+            type: "public-key";
+            id: string;
+        }];
+        userVerification: "required";
+    };
+    confirmationLocation: string;
+    /** UTC RFC 3339 date-time string (source §2.2), not NumericDate seconds. */
+    expiresAt: string;
+    /** The registered redirect the host's launcher answered once the page came back, when it answered one; complete…Confirmation() takes it. */
+    callbackUri?: string;
+}
+export interface LocalOperationResult {
+    requestId: string;
+    /**
+     * grant is present for the request_grant kind of a linked wallet's enrollment; debit for a service_grant whose service
+     * holds wallet:debit:user: the debit permission the grant's passkey also created (consentDebit.ts).
+     */
+    result: {
+        kind: LocalResultKind;
+        targetId: string;
+        newVersion: string;
+        state: LocalResultState;
+        grant?: LinkedRequestGrantResult;
+        debit?: ConsentDebitOutcome;
+    };
+}
+export declare function parseHostedIdentityFlow(payload: unknown, now: number): HostedIdentityFlow;
+export declare function parsePasskeyBootstrapResult(payload: unknown): PasskeyBootstrapResult;
+export declare function parseVerifiedIdentityResult(payload: unknown, now: number): VerifiedIdentityResult;
+export declare function parseIdentityFlowCallback(value: string, expectedRedirect: string): {
+    flowId: string;
+    state: string;
+    code: string;
+};
+export declare function validateLocalOperationCreate(value: LocalOperationCreate, expectedOwnerId: string): LocalOperationCreate;
+export declare function parseOperationEnvelope(payload: unknown): {
+    requestId: string;
+    operation: LocalOperation;
+};
+export declare function parseOperation(payload: unknown): LocalOperation;
+export declare function parseConfirmationChallenge(payload: unknown, now: number): ConfirmationChallenge;
+export declare function parseOperationConfirmationCallback(value: string, expectedRedirect: string): {
+    state: string;
+    operationId: string;
+};
+export declare function parseLocalOperationResult(payload: unknown): LocalOperationResult;
+/** serviceScopes accepts the read scopes of a service grant: at most the three, each once (none: a withdrawal). */
+export declare function serviceScopes(value: unknown): value is ServiceReadScope[];
+/** printableReference accepts a grant's external_ref: 1 to 128 printable ASCII characters. */
+export declare function printableReference(value: unknown): value is string;
+export {};