@shuttle.technology/authorization 0.1.0 → 0.2.0

package/dist/redirects.d.ts

@@ -0,0 +1,45 @@
+import { type AuthIntent } from "./auth.ts";
+import type { Session } from "./client.ts";
+/**
+ * HostedSignIn is a sign-in started on the provider's hosted page. The person
+ * picks the method there. On the web the state and the S256 verifier stay in
+ * this client's memory until `exchangeHandoff` receives the redirect back; on
+ * mobile the system browser hands the redirect back to the same call, which
+ * exchanges it and answers the session.
+ */
+export interface HostedSignIn {
+    intent: AuthIntent;
+    launchUrl: string;
+    session?: Session;
+}
+/** hostedSignInUrl is the provider's sign-in page for one client, intent, state and S256 challenge. */
+export declare function hostedSignInUrl(authorizationOrigin: string, input: {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    challenge: string;
+    intent: AuthIntent;
+}): string;
+/**
+ * handoffCallback reads the redirect back from a sign-in at the exact
+ * registered redirect. A sign-in begun on the hosted page returns the code and
+ * the state alone; one begun through the attempt API also names its attempt.
+ */
+export declare function handoffCallback(value: string, expected: string): {
+    attemptId?: string;
+    state: string;
+    code: string;
+};
+/** restoreCallback reads the redirect back from a web restore at the exact registered redirect. */
+export declare function restoreCallback(value: string, expected: string): {
+    restoreId: string;
+    state: string;
+    code: string;
+};
+/** The app's own exact origin: https on any host, or http on a loopback host. */
+export declare function exactAppOrigin(value: string): boolean;
+/** A redirect back to the app: https on any host, or http on a loopback host; no credentials, query or fragment. */
+export declare function exactAppRedirect(value: string): boolean;
+export declare function exactHttpsOrigin(value: string): boolean;
+export declare function exactHttpsRedirect(value: string): boolean;
+export declare function httpsURL(value: unknown): value is string;

package/dist/redirects.js

@@ -0,0 +1,108 @@
+// The provider's top-level sign-in page, the redirects that come back to the
+// application from a sign-in or a restore, and the exact HTTPS shapes the
+// configuration and the provider's answers are checked against.
+import { ClientFlowError, opaqueId } from "./auth.js";
+/** hostedSignInUrl is the provider's sign-in page for one client, intent, state and S256 challenge. */
+export function hostedSignInUrl(authorizationOrigin, input) {
+    const start = new URL("/v1/auth/start", authorizationOrigin);
+    start.searchParams.set("client_id", input.clientId);
+    start.searchParams.set("redirect_uri", input.redirectUri);
+    start.searchParams.set("state", input.state);
+    start.searchParams.set("code_challenge", input.challenge);
+    start.searchParams.set("code_challenge_method", "S256");
+    start.searchParams.set("intent", input.intent);
+    return start.toString();
+}
+/**
+ * handoffCallback reads the redirect back from a sign-in at the exact
+ * registered redirect. A sign-in begun on the hosted page returns the code and
+ * the state alone; one begun through the attempt API also names its attempt.
+ */
+export function handoffCallback(value, expected) {
+    const callback = exactRedirect(value, expected);
+    const code = callback.searchParams.getAll("code");
+    const state = callback.searchParams.getAll("state");
+    const attemptId = callback.searchParams.getAll("attempt_id");
+    const size = callback.searchParams.size;
+    if (code.length !== 1 || state.length !== 1 || code[0] === "" || state[0] === "" || !((size === 2 && attemptId.length === 0) || (size === 3 && attemptId.length === 1 && opaqueId(attemptId[0])))) {
+        throw new ClientFlowError("invalid_callback");
+    }
+    return attemptId.length === 1 ? { code: code[0], state: state[0], attemptId: attemptId[0] } : { code: code[0], state: state[0] };
+}
+/** restoreCallback reads the redirect back from a web restore at the exact registered redirect. */
+export function restoreCallback(value, expected) {
+    const callback = exactRedirect(value, expected);
+    const code = callback.searchParams.getAll("code");
+    const state = callback.searchParams.getAll("state");
+    const restoreId = callback.searchParams.getAll("restore_id");
+    if (callback.searchParams.size !== 3 || code.length !== 1 || state.length !== 1 || restoreId.length !== 1 || code[0] === "" || state[0] === "" || !opaqueId(restoreId[0]))
+        throw new ClientFlowError("invalid_callback");
+    return { code: code[0], state: state[0], restoreId: restoreId[0] };
+}
+function exactRedirect(value, expected) {
+    let callback;
+    try {
+        callback = new URL(value);
+    }
+    catch {
+        throw new ClientFlowError("invalid_callback");
+    }
+    const target = new URL(expected);
+    if (`${callback.origin}${callback.pathname}` !== `${target.origin}${target.pathname}` || callback.hash !== "")
+        throw new ClientFlowError("invalid_callback");
+    return callback;
+}
+/** A loopback host a browser treats as a secure context over plain http (local development). */
+function loopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** The app's own exact origin: https on any host, or http on a loopback host. */
+export function exactAppOrigin(value) {
+    try {
+        const parsed = new URL(value);
+        const secure = parsed.protocol === "https:" || (parsed.protocol === "http:" && loopbackHost(parsed.hostname));
+        return secure && parsed.username === "" && parsed.password === "" && parsed.pathname === "/" && parsed.search === "" && parsed.hash === "" && parsed.origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+/** A redirect back to the app: https on any host, or http on a loopback host; no credentials, query or fragment. */
+export function exactAppRedirect(value) {
+    try {
+        const parsed = new URL(value);
+        const secure = parsed.protocol === "https:" || (parsed.protocol === "http:" && loopbackHost(parsed.hostname));
+        return secure && parsed.username === "" && parsed.password === "" && parsed.search === "" && parsed.hash === "";
+    }
+    catch {
+        return false;
+    }
+}
+export function exactHttpsOrigin(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "" && parsed.pathname === "/" && parsed.search === "" && parsed.hash === "" && parsed.origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+export function exactHttpsRedirect(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "" && parsed.search === "" && parsed.hash === "";
+    }
+    catch {
+        return false;
+    }
+}
+export function httpsURL(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return new URL(value).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -1,5 +1,7 @@
 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;
@@ -35,10 +37,11 @@ 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.
+ * 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";
-export type LocalResultKind = "identity" | "session" | "service_grant" | "wallet_limits" | "request_grant";
+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 = {
@@ -99,12 +102,13 @@ export type OperationDisplay = {
     enabled: boolean;
     scopes: ServiceReadScope[];
     externalRef?: string;
-} | WalletLimitsDisplay | LinkedEnrollmentDisplay;
+    debit?: DebitTerms;
+} | WalletLimitsDisplay | LinkedEnrollmentDisplay | DebitPermissionDisplay | DebitPermissionRevokeDisplay;
 export interface LocalOperation {
     id: string;
     version: string;
     kind: LocalOperationKind;
-    state: "awaiting_confirmation" | "authorized" | "succeeded" | "denied" | "canceled" | "expired";
+    state: "awaiting_confirmation" | "authorized" | "pending_target_fence" | "succeeded" | "failed" | "denied" | "canceled" | "expired";
     effectState: "no_effect" | "known";
     authorizationBasis: "" | "user_confirmed";
     ownerType: "account";
@@ -138,16 +142,22 @@ export interface ConfirmationChallenge {
     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. */
+    /**
+     * 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;
@@ -170,4 +180,8 @@ export declare function parseOperationConfirmationCallback(value: string, expect
     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 {};

package/dist/slice4.js

@@ -1,5 +1,7 @@
 import { ClientFlowError, canonicalDecimal, deadlineAfter, identityMethods, integer, isNextAction, opaqueId, record, rfc3339UTC, unexpiredRFC3339, } from "./auth.js";
 import { parseWalletLimitsDisplay } from "./walletLimits.js";
+import { parseDebitPermissionDisplay, parseDebitPermissionRevokeDisplay } from "./debitPermissionWire.js";
+import { parseConsentDebitOutcome, parseDebitTerms } from "./consentDebit.js";
 import { parseLinkedEnrollmentDisplay, parseLinkedRequestGrantResult, validateLinkedEnrollmentCreate, } from "./modeCLinked.js";
 /** parseIdentityList accepts the closed answer of GET /v1/identities. */
 export function parseIdentityList(payload) {
@@ -202,9 +204,9 @@ export function parseOperationConfirmationCallback(value, expectedRedirect) {
 }
 export function parseLocalOperationResult(payload) {
     const root = record(payload, ["request_id", "result"]);
-    const result = record(root.result, ["kind", "target_id", "new_version", "state"], ["grant"]);
+    const result = record(root.result, ["kind", "target_id", "new_version", "state"], ["grant", "debit"]);
     if (!opaqueId(root.request_id) || !localResultKind(result.kind) || !opaqueId(result.target_id) || !canonicalDecimal(result.new_version) || (result.state !== "active" && result.state !== "revoked") ||
-        (result.grant !== undefined) !== (result.kind === "request_grant")) {
+        (result.grant !== undefined) !== (result.kind === "request_grant") || (result.debit !== undefined && result.kind !== "service_grant")) {
         throw new ClientFlowError("invalid_server_response");
     }
     const parsed = { kind: result.kind, targetId: result.target_id, newVersion: result.new_version, state: result.state };
@@ -213,6 +215,8 @@ export function parseLocalOperationResult(payload) {
         if (parsed.grant.requestGrantId !== result.target_id)
             throw new ClientFlowError("invalid_server_response");
     }
+    if (result.debit !== undefined)
+        parsed.debit = parseConsentDebitOutcome(result.debit);
     return { requestId: root.request_id, result: parsed };
 }
 function parseDisplay(value, kind) {
@@ -232,28 +236,36 @@ function parseDisplay(value, kind) {
         return parseWalletLimitsDisplay(value);
     if (kind === "session.authorize_requests")
         return parseLinkedEnrollmentDisplay(value);
+    if (kind === "debit_permission.create")
+        return parseDebitPermissionDisplay(value);
+    if (kind === "debit_permission.revoke")
+        return parseDebitPermissionRevokeDisplay(value);
     if (kind === "session.revoke") {
         const display = record(value, ["kind", "owner_id", "requester_id", "session_id"]);
         if (display.kind !== kind || !opaqueId(display.owner_id) || !opaqueId(display.requester_id) || !opaqueId(display.session_id))
             throw new ClientFlowError("invalid_server_response");
         return { kind, ownerId: display.owner_id, requesterId: display.requester_id, sessionId: display.session_id };
     }
-    const display = record(value, ["kind", "owner_id", "requester_id", "wallet_id", "service_principal_id", "enabled", "scopes"], ["external_ref"]);
+    const display = record(value, ["kind", "owner_id", "requester_id", "wallet_id", "service_principal_id", "enabled", "scopes"], ["external_ref", "debit"]);
     if (display.kind !== kind || !opaqueId(display.owner_id) || !opaqueId(display.requester_id) || !opaqueId(display.wallet_id) || !opaqueId(display.service_principal_id) || typeof display.enabled !== "boolean" || !serviceScopes(display.scopes) || (display.external_ref !== undefined && !printableReference(display.external_ref)))
         throw new ClientFlowError("invalid_server_response");
     const result = { kind, ownerId: display.owner_id, requesterId: display.requester_id, walletId: display.wallet_id, servicePrincipalId: display.service_principal_id, enabled: display.enabled, scopes: display.scopes };
     if (display.external_ref !== undefined)
         result.externalRef = display.external_ref;
+    if (display.debit !== undefined)
+        result.debit = parseDebitTerms(display.debit);
     return result;
 }
 function localOperationKind(value) {
-    return value === "identity.link" || value === "identity.unlink" || value === "session.revoke" || value === "service_grant.set" || value === "wallet_limits.set" || value === "session.authorize_requests";
+    return value === "identity.link" || value === "identity.unlink" || value === "session.revoke" || value === "service_grant.set" || value === "wallet_limits.set" || value === "session.authorize_requests" ||
+        value === "debit_permission.create" || value === "debit_permission.revoke";
 }
 function localResultKind(value) {
-    return value === "identity" || value === "session" || value === "service_grant" || value === "wallet_limits" || value === "request_grant";
+    return value === "identity" || value === "session" || value === "service_grant" || value === "wallet_limits" || value === "request_grant" || value === "debit_permission";
 }
 function operationState(value) {
-    return value === "awaiting_confirmation" || value === "authorized" || value === "succeeded" || value === "denied" || value === "canceled" || value === "expired";
+    return value === "awaiting_confirmation" || value === "authorized" || value === "pending_target_fence" || value === "succeeded" || value === "failed" ||
+        value === "denied" || value === "canceled" || value === "expired";
 }
 function effectState(value) {
     return value === "no_effect" || value === "known";
@@ -264,12 +276,14 @@ function lowerHexDigest(value) {
 function base64url(value) {
     return typeof value === "string" && /^[A-Za-z0-9_-]+$/.test(value);
 }
-function serviceScopes(value) {
+/** serviceScopes accepts the read scopes of a service grant: at most the three, each once (none: a withdrawal). */
+export function serviceScopes(value) {
     if (!Array.isArray(value) || value.length > 3 || new Set(value).size !== value.length)
         return false;
     return value.every((scope) => scope === "wallet:read" || scope === "operation:read" || scope === "streams:read");
 }
-function printableReference(value) {
+/** printableReference accepts a grant's external_ref: 1 to 128 printable ASCII characters. */
+export function printableReference(value) {
     return typeof value === "string" && /^[\x20-\x7E]{1,128}$/.test(value);
 }
 function httpsURL(value) {

package/dist/streams.js

@@ -1,7 +1,7 @@
 // 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
+// (`@streams/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,

package/dist/walletCreateGrant.d.ts

@@ -0,0 +1,62 @@
+import { type AuthorizationErrorCode } from "./errors.ts";
+import { type ServiceReadScope } from "./slice4.ts";
+import type { UserWalletOperation } from "./walletOperations.ts";
+/** The grant a creation asks for: the service, one to three read scopes, and the service's optional reference for its user. */
+export interface WalletCreateGrant {
+    servicePrincipalId: string;
+    scopes: ServiceReadScope[];
+    externalRef?: string;
+}
+/** What createWallet() takes: the network, the app's own device key if it keeps the share itself, and the optional grant. */
+export interface WalletCreateInput {
+    network: string;
+    recipientPublicKey?: string;
+    /**
+     * Opens the new wallet to a service in the same passkey confirmation. When that service holds wallet:debit:user,
+     * the same confirmation also creates its debit permission on the wallet with the ceilings the platform set for the
+     * service (display.debit names them, the provider's page says them); there is nothing to pass for it, and
+     * walletOperationResult() reports it in result.debit. That needs the share the SDK keeps (no recipientPublicKey).
+     */
+    grant?: WalletCreateGrant;
+}
+/**
+ * What became of the grant once the wallet exists. succeeded: the service
+ * reads the wallet. pending_target_fence: a first streams:read grant waits
+ * for Streams; read client.operation(operationId) until it ends. not_set: the
+ * grant was not set, for the reason code says; DEPENDENCY_UNAVAILABLE passes,
+ * and reading the result again repeats the step, any other code asks for the
+ * grant alone. linkedWalletId is the created wallet among the linked wallets.
+ */
+export interface WalletCreateGrantOutcome {
+    state: "succeeded" | "pending_target_fence" | "not_set";
+    operationId?: string;
+    linkedWalletId?: string;
+    code?: AuthorizationErrorCode;
+}
+/** The grant's wire member, the scopes in the provider's order. */
+export type WalletCreateGrantWire = {
+    service_principal_id: string;
+    scopes: ServiceReadScope[];
+    external_ref?: string;
+};
+/** validWalletCreateGrant reads the wire member as the provider takes it: one of its services, one to three scopes, an optional printable reference. */
+export declare function validWalletCreateGrant(value: unknown): value is WalletCreateGrantWire;
+/** walletCreateBody is the closed wallet.create body of createWallet(): the device key the creation seals the share to, and the grant when one is asked for. */
+export declare function walletCreateBody(ownerId: string, input: WalletCreateInput, sdkKey: string | undefined): {
+    kind: "wallet.create";
+    owner_type: "account";
+    owner_id: string;
+    payload: {
+        network: string;
+        recipient_public_key: string;
+    };
+    grant?: WalletCreateGrantWire;
+};
+/** createdAsAsked refuses an admitted creation whose display names another grant than the one asked for, or one where none was. */
+export declare function createdAsAsked(operation: UserWalletOperation, create: {
+    grant?: WalletCreateGrantWire;
+}): UserWalletOperation;
+/** parseWalletCreateGrant reads the grant a creation's display names. */
+export declare function parseWalletCreateGrant(value: unknown): WalletCreateGrant;
+/** parseWalletCreateGrantOutcome reads the grant member of a creation's result: a code exactly for not_set, an operation for every grant that was set. */
+export declare function parseWalletCreateGrantOutcome(value: unknown): WalletCreateGrantOutcome;

package/dist/walletCreateGrant.js

@@ -0,0 +1,89 @@
+// A wallet's creation that opens the wallet to a service in the same passkey
+// confirmation (owner decision of 28 October 2026): the read grant
+// service_grant.set would give, named beside the wallet. The person confirms
+// once, on a page that names the service and what it may see; the provider
+// sets the grant when the creation's result is read. A grant that cannot be
+// set leaves the wallet as it is, and the result says why: the app then asks
+// for the grant alone (createServiceGrant), with its own passkey confirmation.
+import { ClientFlowError, opaqueId, record } from "./auth.js";
+import { isAuthorizationErrorCode } from "./errors.js";
+import { printableReference, serviceScopes } from "./slice4.js";
+import { lowerUUID } from "./walletDisplayParts.js";
+const order = ["wallet:read", "operation:read", "streams:read"];
+/** validWalletCreateGrant reads the wire member as the provider takes it: one of its services, one to three scopes, an optional printable reference. */
+export function validWalletCreateGrant(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const grant = value;
+    const members = Object.keys(grant);
+    return members.every((member) => member === "service_principal_id" || member === "scopes" || member === "external_ref") &&
+        opaqueId(grant.service_principal_id) && serviceScopes(grant.scopes) && grant.scopes.length >= 1 && (grant.external_ref === undefined || printableReference(grant.external_ref));
+}
+function grantWire(input) {
+    let declared;
+    try {
+        declared = record(input, ["servicePrincipalId", "scopes"], ["externalRef"]);
+    }
+    catch {
+        throw new ClientFlowError("invalid_operation_create");
+    }
+    // The scopes go in the provider's order, so a repeat of the request is the same request.
+    const raw = declared.scopes;
+    const scopes = serviceScopes(raw) ? order.filter((scope) => raw.includes(scope)) : raw;
+    const wire = { service_principal_id: declared.servicePrincipalId, scopes: scopes };
+    if (declared.externalRef !== undefined)
+        wire.external_ref = declared.externalRef;
+    if (!validWalletCreateGrant(wire))
+        throw new ClientFlowError("invalid_operation_create");
+    return wire;
+}
+/** walletCreateBody is the closed wallet.create body of createWallet(): the device key the creation seals the share to, and the grant when one is asked for. */
+export function walletCreateBody(ownerId, input, sdkKey) {
+    if (input === null || typeof input !== "object")
+        throw new ClientFlowError("invalid_operation_create");
+    const create = { kind: "wallet.create", owner_type: "account", owner_id: ownerId, payload: { network: input.network, recipient_public_key: sdkKey ?? input.recipientPublicKey } };
+    if (input.grant !== undefined)
+        create.grant = grantWire(input.grant);
+    return create;
+}
+function sameGrant(shown, asked) {
+    if (shown === undefined || asked === undefined)
+        return shown === asked;
+    return shown.servicePrincipalId === asked.service_principal_id && shown.scopes.join(" ") === asked.scopes.join(" ") && shown.externalRef === asked.external_ref;
+}
+/** createdAsAsked refuses an admitted creation whose display names another grant than the one asked for, or one where none was. */
+export function createdAsAsked(operation, create) {
+    const display = operation.display;
+    if (operation.kind !== "wallet.create" || display.kind !== "wallet.create")
+        throw new ClientFlowError("invalid_server_response");
+    if (!("materialPurged" in display) && !sameGrant(display.grant, create.grant))
+        throw new ClientFlowError("invalid_server_response");
+    return operation;
+}
+/** parseWalletCreateGrant reads the grant a creation's display names. */
+export function parseWalletCreateGrant(value) {
+    if (!validWalletCreateGrant(value) || order.filter((scope) => value.scopes.includes(scope)).join(" ") !== value.scopes.join(" "))
+        throw new ClientFlowError("invalid_server_response");
+    const grant = { servicePrincipalId: value.service_principal_id, scopes: [...value.scopes] };
+    if (value.external_ref !== undefined)
+        grant.externalRef = value.external_ref;
+    return grant;
+}
+/** parseWalletCreateGrantOutcome reads the grant member of a creation's result: a code exactly for not_set, an operation for every grant that was set. */
+export function parseWalletCreateGrantOutcome(value) {
+    const outcome = record(value, ["state"], ["operation_id", "linked_wallet_id", "code"]);
+    const state = outcome.state;
+    if ((state !== "succeeded" && state !== "pending_target_fence" && state !== "not_set") || (outcome.operation_id !== undefined && !lowerUUID(outcome.operation_id)) ||
+        (outcome.linked_wallet_id !== undefined && !lowerUUID(outcome.linked_wallet_id)) || (state === "not_set") !== (outcome.code !== undefined) ||
+        (outcome.code !== undefined && !isAuthorizationErrorCode(outcome.code)) || (state !== "not_set" && outcome.operation_id === undefined)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const parsed = { state };
+    if (outcome.operation_id !== undefined)
+        parsed.operationId = outcome.operation_id;
+    if (outcome.linked_wallet_id !== undefined)
+        parsed.linkedWalletId = outcome.linked_wallet_id;
+    if (outcome.code !== undefined)
+        parsed.code = outcome.code;
+    return parsed;
+}

package/dist/walletDisplayParts.d.ts

@@ -13,3 +13,5 @@ export declare function summaryOf(value: unknown): {
 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;
+/** lowerHexBytes accepts 1..1024 bytes of lowercase hexadecimal. */
+export declare function lowerHexBytes(value: unknown): value is string;

package/dist/walletDisplayParts.js

@@ -41,3 +41,7 @@ export function bindingRevision(value) {
 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);
 }
+/** lowerHexBytes accepts 1..1024 bytes of lowercase hexadecimal. */
+export function lowerHexBytes(value) {
+    return typeof value === "string" && value.length >= 2 && value.length <= 2048 && value.length % 2 === 0 && /^[0-9a-f]+$/.test(value);
+}