@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/walletOperations.js

@@ -0,0 +1,308 @@
+// Mode B user wallet operations (AUTH-009-A03, source §1.3). Closed types,
+// client-side validation of the five wallet payloads, and strict parsers for
+// the safe status projection and the protected wallet result. These helpers
+// compose the same /v1 operation routes as the local operations; they add no
+// authority. Local faults raise ClientFlowError; server denials stay
+// AuthorizationError and are produced by the caller's transport.
+import { ClientFlowError, canonicalDecimal, deadlineAfter, isNextAction, opaqueId, record, rfc3339UTC, } from "./auth.js";
+import { bindingRevision, displayCommon, lowerUUID, rawQuantity, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+import { parseLinkedSendDisplay } from "./linkedSendDisplay.js";
+import { parseMediatedOperation } from "./mediatedOperation.js";
+export { LinkedSendAssets, MaxTransferCommentBytes, ReplaceActions, linkedSendAsset, replaceAction, transferComment } from "./linkedSendDisplay.js";
+/** walletMaterialPurged separates the purged display from every material display. */
+export function walletMaterialPurged(display) {
+    return "materialPurged" in display;
+}
+/** MaxWalletMessageBytes is the decoded wallet.sign payload bound of source §2.8. */
+export const MaxWalletMessageBytes = 4096;
+const maxWalletGeneration = (1n << 64n) - 1n;
+const compressedP256Key = /^(02|03)[0-9a-f]{64}$/;
+const walletNetwork = /^[A-Za-z0-9_.-]{1,64}$/;
+const base64urlValue = /^[A-Za-z0-9_-]+$/;
+/**
+ * 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 function validateUserWalletCreate(value, expectedOwnerId) {
+    const common = record(value, ["kind", "owner_type", "owner_id", "payload"], ["wallet_id", "result_recipient"]);
+    if (common.owner_type !== "account" || !opaqueId(common.owner_id) || common.owner_id !== expectedOwnerId) {
+        throw new ClientFlowError("invalid_operation_create");
+    }
+    if (common.result_recipient !== undefined) {
+        const recipient = record(common.result_recipient, ["type", "id"]);
+        if ((recipient.type !== "account" && recipient.type !== "service") || !opaqueId(recipient.id))
+            throw new ClientFlowError("invalid_operation_create");
+    }
+    const walletRequired = common.kind !== "wallet.create";
+    if (walletRequired !== opaqueId(common.wallet_id))
+        throw new ClientFlowError("invalid_operation_create");
+    switch (common.kind) {
+        case "wallet.create": {
+            const payload = record(common.payload, ["network", "recipient_public_key"]);
+            if (!network(payload.network) || !recipientPublicKey(payload.recipient_public_key))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "wallet.sign": {
+            const payload = record(common.payload, ["network", "message_base64url"]);
+            if (!network(payload.network) || !boundedMessage(payload.message_base64url))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "wallet.send": {
+            const payload = record(common.payload, ["network", "asset", "recipient", "amount_raw", "max_fee_raw"]);
+            if (!network(payload.network) || payload.asset !== "native" || typeof payload.recipient !== "string" || !walletRecipient.test(payload.recipient) ||
+                !rawQuantity(payload.amount_raw, true) || !rawQuantity(payload.max_fee_raw, false)) {
+                throw new ClientFlowError("invalid_operation_create");
+            }
+            break;
+        }
+        case "wallet.export": {
+            const payload = record(common.payload, ["recipient_public_key"]);
+            if (!recipientPublicKey(payload.recipient_public_key))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "wallet.recover": {
+            const payload = record(common.payload, ["expected_generation", "recipient_public_key"]);
+            if (!recipientPublicKey(payload.recipient_public_key) || !walletGeneration(payload.expected_generation))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        default:
+            throw new ClientFlowError("invalid_operation_create");
+    }
+    return value;
+}
+export function parseUserWalletOperationEnvelope(payload) {
+    const root = record(payload, ["request_id", "operation"]);
+    if (!opaqueId(root.request_id))
+        throw new ClientFlowError("invalid_server_response");
+    return { requestId: root.request_id, operation: parseUserWalletOperation(root.operation) };
+}
+export function parseUserWalletOperation(payload) {
+    // A Mode C send is read in the mediated projection the provider serves for it.
+    if (payload !== null && typeof payload === "object" && payload.authorization_basis === "user_request_signed")
+        return parseMediatedOperation(payload);
+    const root = record(payload, [
+        "id", "version", "kind", "state", "effect_state", "authorization_basis", "owner_type", "owner_id", "requester_id",
+        "request_fingerprint", "operation_fingerprint", "display", "created_at", "expires_at", "next_action",
+    ], ["wallet_id", "confirmation_location", "result_kind", "binding_source", "connection_id", "linked_wallet_id", "binding_revision"]);
+    if (!opaqueId(root.id) || !canonicalDecimal(root.version) || !userWalletKind(root.kind) || !userWalletState(root.state) ||
+        !userWalletEffectState(root.effect_state) || !userWalletBasis(root.authorization_basis) ||
+        root.owner_type !== "account" || !opaqueId(root.owner_id) || !opaqueId(root.requester_id) ||
+        (root.wallet_id !== undefined && !opaqueId(root.wallet_id)) || !lowerHexDigest(root.request_fingerprint) ||
+        !lowerHexDigest(root.operation_fingerprint) || !rfc3339UTC(root.created_at) || !rfc3339UTC(root.expires_at) ||
+        !deadlineAfter(root.created_at, root.expires_at) || (root.confirmation_location !== undefined && !httpsURL(root.confirmation_location)) ||
+        (root.result_kind !== undefined && !walletResultKind(root.result_kind)) || !isNextAction(root.next_action)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    // A linked wallet is named by all three of its members, only for a send,
+    // and never beside an own wallet.
+    const linked = root.binding_source !== undefined;
+    if (linked && (root.binding_source !== "linked_wallet" || root.kind !== "wallet.send" || root.wallet_id !== undefined ||
+        !lowerUUID(root.connection_id) || !lowerUUID(root.linked_wallet_id) || !bindingRevision(root.binding_revision))) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if (!linked && (root.connection_id !== undefined || root.linked_wallet_id !== undefined || root.binding_revision !== undefined || root.authorization_basis === "session_authorized")) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const display = linked && !purgedDisplay(root.display) ? parseLinkedSendDisplay(root.display) : parseUserWalletDisplay(root.display, root.kind);
+    if (display.ownerId !== root.owner_id || display.requesterId !== root.requester_id || display.walletId !== root.wallet_id) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if ("linkedWalletId" in display && (display.linkedWalletId !== root.linked_wallet_id || display.connectionId !== root.connection_id || display.bindingRevision !== root.binding_revision)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const operation = {
+        id: root.id,
+        version: root.version,
+        kind: root.kind,
+        state: root.state,
+        effectState: root.effect_state,
+        authorizationBasis: root.authorization_basis,
+        ownerType: root.owner_type,
+        ownerId: root.owner_id,
+        requesterId: root.requester_id,
+        requestFingerprint: root.request_fingerprint,
+        operationFingerprint: root.operation_fingerprint,
+        display,
+        createdAt: root.created_at,
+        expiresAt: root.expires_at,
+        nextAction: root.next_action,
+    };
+    if (root.wallet_id !== undefined)
+        operation.walletId = root.wallet_id;
+    if (linked)
+        operation.linkedWallet = { connectionId: root.connection_id, linkedWalletId: root.linked_wallet_id, bindingRevision: root.binding_revision };
+    if (root.confirmation_location !== undefined)
+        operation.confirmationLocation = root.confirmation_location;
+    if (root.result_kind !== undefined)
+        operation.resultKind = root.result_kind;
+    return operation;
+}
+/**
+ * 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 function parseWalletResult(payload, expectedOperationId) {
+    const root = record(payload, ["request_id", "result"]);
+    if (root.result !== null && typeof root.result === "object" && root.result.kind === "wallet_created") {
+        return parseCreatedWalletResult(root.request_id, root.result, expectedOperationId);
+    }
+    const result = record(root.result, ["operation_id", "kind", "receipt_id"], ["output_base64url"]);
+    if (!opaqueId(root.request_id) || !opaqueId(result.operation_id) || result.operation_id !== expectedOperationId ||
+        !walletResultKind(result.kind) || result.kind === "wallet_created" || !opaqueId(result.receipt_id)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if (result.kind === "signature") {
+        if (typeof result.output_base64url !== "string" || !base64urlValue.test(result.output_base64url))
+            throw new ClientFlowError("invalid_server_response");
+        return { requestId: root.request_id, result: { operationId: result.operation_id, kind: result.kind, receiptId: result.receipt_id, outputBase64url: result.output_base64url } };
+    }
+    if (result.output_base64url !== undefined)
+        throw new ClientFlowError("invalid_server_response");
+    return { requestId: root.request_id, result: { operationId: result.operation_id, kind: result.kind, receiptId: result.receipt_id } };
+}
+function parseCreatedWalletResult(requestId, value, expectedOperationId) {
+    const result = record(value, ["operation_id", "kind", "receipt_id", "wallet", "device_share"]);
+    const wallet = record(result.wallet, ["wallet_id", "key_id", "network", "address", "algorithm", "public_key"]);
+    const share = record(result.device_share, ["ciphertext", "nonce", "ephemeral_public_key", "encryption_algorithm", "encryption_context"]);
+    // The receipt of a creation is the created wallet ID; a result naming two
+    // different wallets is not one creation.
+    if (!opaqueId(requestId) || result.operation_id !== expectedOperationId || !lowerUUID(wallet.wallet_id) || result.receipt_id !== wallet.wallet_id ||
+        !lowerUUID(wallet.key_id) || typeof wallet.network !== "string" || !/^[a-z0-9_.-]{1,64}$/.test(wallet.network) ||
+        typeof wallet.address !== "string" || !walletRecipient.test(wallet.address) || !algorithmName(wallet.algorithm) || !lowerHexBytes(wallet.public_key) ||
+        !lowerHexBytes(share.ciphertext) || !lowerHexBytes(share.nonce) || !lowerHexBytes(share.ephemeral_public_key) ||
+        !algorithmName(share.encryption_algorithm) || !lowerHexBytes(share.encryption_context)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return {
+        requestId,
+        result: {
+            operationId: expectedOperationId, kind: "wallet_created", receiptId: wallet.wallet_id,
+            wallet: { walletId: wallet.wallet_id, keyId: wallet.key_id, network: wallet.network, address: wallet.address, algorithm: wallet.algorithm, publicKey: wallet.public_key },
+            deviceShare: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeralPublicKey: share.ephemeral_public_key, encryptionAlgorithm: share.encryption_algorithm, encryptionContext: share.encryption_context },
+        },
+    };
+}
+function purgedDisplay(value) {
+    return value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "material_purged");
+}
+function parseUserWalletDisplay(value, kind) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new ClientFlowError("invalid_server_response");
+    if (Object.prototype.hasOwnProperty.call(value, "material_purged")) {
+        const purged = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "material_purged"], ["wallet_id"]);
+        if (purged.kind !== kind || purged.material_purged !== true)
+            throw new ClientFlowError("invalid_server_response");
+        return { ...displayCommon(purged), kind, materialPurged: true };
+    }
+    switch (kind) {
+        case "wallet.create": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "recipient_public_key"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !network(display.network) || !recipientPublicKey(display.recipient_public_key))
+                throw new ClientFlowError("invalid_server_response");
+            return { ...displayCommon(display), kind, network: display.network, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary) };
+        }
+        case "wallet.sign": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "message_base64url"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !network(display.network) || !boundedMessage(display.message_base64url))
+                throw new ClientFlowError("invalid_server_response");
+            return { ...displayCommon(display), kind, network: display.network, messageBase64url: display.message_base64url, ...summaryOf(display.prepared_summary) };
+        }
+        case "wallet.send": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "asset", "recipient", "amount_raw", "max_fee_raw"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !network(display.network) || display.asset !== "native" || typeof display.recipient !== "string" ||
+                !walletRecipient.test(display.recipient) || !rawQuantity(display.amount_raw, true) || !rawQuantity(display.max_fee_raw, false)) {
+                throw new ClientFlowError("invalid_server_response");
+            }
+            return {
+                ...displayCommon(display), kind, network: display.network, asset: display.asset, recipient: display.recipient,
+                amountRaw: display.amount_raw, maxFeeRaw: display.max_fee_raw, ...summaryOf(display.prepared_summary),
+            };
+        }
+        case "wallet.export": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "recipient_public_key"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !recipientPublicKey(display.recipient_public_key))
+                throw new ClientFlowError("invalid_server_response");
+            return { ...displayCommon(display), kind, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary) };
+        }
+        default: {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "recipient_public_key", "expected_generation"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== "wallet.recover" || !recipientPublicKey(display.recipient_public_key) || !walletGeneration(display.expected_generation)) {
+                throw new ClientFlowError("invalid_server_response");
+            }
+            return {
+                ...displayCommon(display), kind: "wallet.recover", recipientPublicKey: display.recipient_public_key,
+                expectedGeneration: display.expected_generation, ...summaryOf(display.prepared_summary),
+            };
+        }
+    }
+}
+function network(value) {
+    return typeof value === "string" && walletNetwork.test(value);
+}
+function recipientPublicKey(value) {
+    return typeof value === "string" && compressedP256Key.test(value);
+}
+/**
+ * boundedMessage accepts unpadded base64url whose decoded length is 1..4096
+ * bytes. A base64url group of exactly one residual character encodes no byte,
+ * so that length is rejected outright.
+ */
+function boundedMessage(value) {
+    if (typeof value !== "string" || !base64urlValue.test(value) || value.length % 4 === 1)
+        return false;
+    const decoded = Math.floor((value.length * 3) / 4);
+    return decoded >= 1 && decoded <= MaxWalletMessageBytes;
+}
+function walletGeneration(value) {
+    if (!canonicalDecimal(value))
+        return false;
+    const generation = BigInt(value);
+    return generation > 0n && generation <= maxWalletGeneration;
+}
+function userWalletKind(value) {
+    return value === "wallet.create" || value === "wallet.sign" || value === "wallet.send" || value === "wallet.export" || value === "wallet.recover";
+}
+function walletResultKind(value) {
+    return value === "signature" || value === "transfer_receipt" || value === "wallet_created";
+}
+/** lowerHexBytes accepts 1..1024 bytes of lowercase hexadecimal. */
+function lowerHexBytes(value) {
+    return typeof value === "string" && value.length >= 2 && value.length <= 2048 && value.length % 2 === 0 && /^[0-9a-f]+$/.test(value);
+}
+function algorithmName(value) {
+    return typeof value === "string" && /^[a-z0-9_-]{1,128}$/.test(value);
+}
+function userWalletState(value) {
+    return value === "awaiting_confirmation" || value === "authorized" || value === "dispatching" || value === "outcome_unknown" ||
+        value === "succeeded" || value === "failed" || value === "denied" || value === "canceled" || value === "expired";
+}
+function userWalletEffectState(value) {
+    return value === "no_effect" || value === "possible" || value === "known";
+}
+function userWalletBasis(value) {
+    return value === "" || value === "user_confirmed" || value === "session_authorized";
+}
+function lowerHexDigest(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+function httpsURL(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "";
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@shuttle.technology/authorization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Streams Authorization and authorized wallet operations.",
+  "homepage": "https://www.npmjs.com/package/@shuttle.technology/authorization",
+  "packageManager": "pnpm@11.19.0",
+  "type": "module",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./mode-c": {
+      "types": "./dist/modeC.d.ts",
+      "import": "./dist/modeC.js"
+    },
+    "./mode-c-linked": {
+      "types": "./dist/modeCLinked.d.ts",
+      "import": "./dist/modeCLinked.js"
+    },
+    "./streams": {
+      "types": "./dist/streams.d.ts",
+      "import": "./dist/streams.js"
+    },
+    "./linked-wallets": {
+      "types": "./dist/linkedWallets.d.ts",
+      "import": "./dist/linkedWallets.js"
+    },
+    "./device-key": {
+      "types": "./dist/deviceKey.d.ts",
+      "import": "./dist/deviceKey.js"
+    },
+    "./device-share": {
+      "types": "./dist/deviceShare.d.ts",
+      "import": "./dist/deviceShare.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "check": "node --experimental-strip-types --check src/auth.ts && node --experimental-strip-types --check src/balances.ts && node --experimental-strip-types --check src/canonicalize.ts && node --experimental-strip-types --check src/client.ts && node --experimental-strip-types --check src/aesGcmSiv.ts && node --experimental-strip-types --check src/deviceKey.ts && node --experimental-strip-types --check src/deviceShare.ts && node --experimental-strip-types --check src/deviceShareEnvelope.ts && node --experimental-strip-types --check src/linkedSendDisplay.ts && node --experimental-strip-types --check src/linkedChecks.ts && node --experimental-strip-types --check src/linkedWallets.ts && node --experimental-strip-types --check src/linkedWalletSignals.ts && node --experimental-strip-types --check src/mediatedOperation.ts && node --experimental-strip-types --check src/pages.ts && node --experimental-strip-types --check src/modeC.ts && node --experimental-strip-types --check src/modeCLinked.ts && node --experimental-strip-types --check src/poll.ts && node --experimental-strip-types --check src/requestGrant.ts && node --experimental-strip-types --check src/sends.ts && node --experimental-strip-types --check src/slice4.ts && node --experimental-strip-types --check src/streams.ts && node --experimental-strip-types --check src/trackedWallets.ts && node --experimental-strip-types --check src/transferStatus.ts && node --experimental-strip-types --check src/walletDisplayParts.ts && node --experimental-strip-types --check src/walletEvents.ts && node --experimental-strip-types --check src/walletLimits.ts && node --experimental-strip-types --check src/walletOperations.ts && node --check test/http-integration.mjs && node --check test/http-integration-slice4.mjs && node --check test/http-integration-slice6.mjs && node --check test/http-integration-slice7.mjs && node --check test/http-integration-contract.mjs && node --check test/http-integration-linked-send.mjs && node --check test/http-integration-limits.mjs && node --check test/http-integration-modec-linked.mjs && node --check test/http-integration-mode-a.mjs && node --check test/http-integration-demo.mjs",
+    "typecheck": "tsc --noEmit",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "package:smoke": "node test/package-smoke.mjs",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "integration:http": "node test/http-integration.mjs",
+    "verify": "pnpm run check && pnpm run typecheck && pnpm run build && pnpm run test"
+  },
+  "engines": {
+    "node": "24.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
+  }
+}