@supercuts-walrus/backend 0.0.0-stage → 0.1.0

package/dist/backend.d.ts

@@ -0,0 +1,27 @@
+import { DeploymentConfig } from "./config.js";
+import { PoolEvent, PoolIndex } from "./indexer.js";
+import { RelayAdmission, RelayRequest } from "./relayer.js";
+import { RoleStore } from "./store.js";
+import { MessageEnvelope } from "./transcript.js";
+import { EvidenceReader, PrivateWallet, SettlementExpectation } from "./wallet.js";
+/**
+ * Role-local façade. Network processes inject transport/proof adapters; this
+ * class keeps security-sensitive lifecycle decisions in one reusable backend.
+ */
+export declare class SupercutsBackend {
+    readonly store: RoleStore;
+    readonly poolIndex: PoolIndex;
+    readonly relay: RelayAdmission;
+    readonly wallet: PrivateWallet;
+    private readonly pin;
+    constructor(config: DeploymentConfig, store: RoleStore);
+    applyObservedEvents(events: PoolEvent[], poolState: {
+        root: string;
+        nextLeaf: bigint;
+    }): void;
+    verifyTranscript(messages: MessageEnvelope[]): Promise<string>;
+    preparePrivateTransfer(operationId: string, payloadHash: string, inputCommitment: string, expected: SettlementExpectation, proof: Uint8Array): void;
+    markBroadcast(operationId: string, digest: string): void;
+    reconcilePrivateTransfer(operationId: string, read: EvidenceReader): Promise<import("./store.js").StoredOperation>;
+    admitRelay(request: RelayRequest, verifyProof: (statement: Uint8Array, proof: Uint8Array) => Promise<boolean>): Promise<void>;
+}

package/dist/backend.js

@@ -0,0 +1,62 @@
+import { isValidPersonalMessageSignature } from "@mysten/sui/verify";
+import { applyPoolEvent, assertPoolState, createPoolIndex } from "./indexer.js";
+import { RelayAdmission } from "./relayer.js";
+import { validateTranscript } from "./transcript.js";
+import { PrivateWallet } from "./wallet.js";
+/**
+ * Role-local façade. Network processes inject transport/proof adapters; this
+ * class keeps security-sensitive lifecycle decisions in one reusable backend.
+ */
+export class SupercutsBackend {
+    store;
+    poolIndex;
+    relay;
+    wallet;
+    pin;
+    constructor(config, store) {
+        this.store = store;
+        this.poolIndex = createPoolIndex(config.initialRoot.replace(/^0x/, ""), config.deploymentCheckpoint);
+        this.pin = { packageId: config.packageId, poolId: config.poolId, coinType: config.coinType, verifierVersion: config.verifierVersion };
+        this.relay = new RelayAdmission(store, this.pin, (address, bytes, signature) => isValidPersonalMessageSignature(bytes, signature, { address }), 
+        // The caller must inject the pinned Groth16 verifier before admitting a
+        // live relay request. A missing verifier fails closed.
+        async () => false);
+        this.wallet = new PrivateWallet(store);
+    }
+    applyObservedEvents(events, poolState) {
+        const candidate = {
+            root: this.poolIndex.root, nextLeaf: this.poolIndex.nextLeaf, checkpoint: this.poolIndex.checkpoint,
+            spent: new Set(this.poolIndex.spent), deals: new Set(this.poolIndex.deals), acceptedRoots: new Set(this.poolIndex.acceptedRoots),
+            ...(this.poolIndex.lastPosition ? { lastPosition: { ...this.poolIndex.lastPosition } } : {}),
+        };
+        for (const event of [...events].sort((a, b) => {
+            if (a.checkpoint !== b.checkpoint)
+                return a.checkpoint < b.checkpoint ? -1 : 1;
+            if (a.transactionIndex !== b.transactionIndex)
+                return a.transactionIndex < b.transactionIndex ? -1 : 1;
+            return a.eventIndex - b.eventIndex;
+        }))
+            applyPoolEvent(candidate, event);
+        assertPoolState(candidate, poolState);
+        this.poolIndex.root = candidate.root;
+        this.poolIndex.nextLeaf = candidate.nextLeaf;
+        this.poolIndex.checkpoint = candidate.checkpoint;
+        this.poolIndex.spent = candidate.spent;
+        this.poolIndex.deals = candidate.deals;
+        this.poolIndex.acceptedRoots = candidate.acceptedRoots;
+        if (candidate.lastPosition)
+            this.poolIndex.lastPosition = candidate.lastPosition;
+    }
+    async verifyTranscript(messages) {
+        return validateTranscript(messages, (address, bytes, signature) => isValidPersonalMessageSignature(bytes, signature, { address }));
+    }
+    preparePrivateTransfer(operationId, payloadHash, inputCommitment, expected, proof) {
+        this.wallet.prepare(operationId, payloadHash, inputCommitment, expected, proof);
+    }
+    markBroadcast(operationId, digest) { this.wallet.recordBroadcast(operationId, digest); }
+    reconcilePrivateTransfer(operationId, read) { return this.wallet.reconcile(operationId, read); }
+    async admitRelay(request, verifyProof) {
+        const admission = new RelayAdmission(this.store, this.pin, (address, bytes, signature) => isValidPersonalMessageSignature(bytes, signature, { address }), verifyProof);
+        return admission.admit(request);
+    }
+}

package/dist/buyer-setup.d.ts

@@ -0,0 +1,6 @@
+export declare function setupBuyer(home: string, configPath: string): Record<string, unknown>;
+export declare function promptBuyerSetup(home: string): Promise<Record<string, unknown>>;
+export declare function createBuyerSession(home: string): Record<string, unknown>;
+export declare function renewBuyer(home: string, configPath: string): Record<string, unknown>;
+export declare function approveBuyerSeller(home: string, capabilityId: string): Promise<Record<string, unknown>>;
+export declare function addBuyerPrivacyRule(home: string, capabilityId: string): Promise<Record<string, unknown>>;

package/dist/buyer-setup.js

@@ -0,0 +1,241 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { fail } from "./errors.js";
+import { Phase3App, initialize } from "./phase3.js";
+import { loadMandate } from "./mandate.js";
+import { LiveDealPorts } from "./live-deal-ports.js";
+import { verifySignedCapability } from "./capability.js";
+import { WalrusDealBlobs } from "./deal-wire.js";
+import { canonicalJson } from "./settlement.js";
+import { validateDirectoryOrigin } from "./seller-directory.js";
+function ownerFile(path) {
+    if ((statSync(path).mode & 0o077) !== 0)
+        fail("SETUP_PERMISSIONS", `${path} must be owner-only`);
+}
+function amount(value, name) {
+    if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value))
+        fail("SETUP_INVALID", `${name} must be a positive base-unit string`);
+    return value;
+}
+function origins(values) {
+    if (!Array.isArray(values) || !values.length || values.length > 32)
+        fail("SETUP_INVALID", "sellerOrigins requires 1..32 origins");
+    return values.map((value) => {
+        const url = new URL(String(value));
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(url.hostname)) || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+            fail("SETUP_INVALID", "seller origin must be HTTPS or loopback HTTP without path or credentials");
+        return url.origin;
+    });
+}
+function validateConfig(config) {
+    amount(config.perDealCeiling, "perDealCeiling");
+    amount(config.totalBudget, "totalBudget");
+    if (BigInt(config.totalBudget) < BigInt(config.perDealCeiling))
+        fail("SETUP_INVALID", "totalBudget must cover one permitted deal");
+    if (!Number.isSafeInteger(config.expiresAt) || config.expiresAt <= Date.now())
+        fail("SETUP_INVALID", "expiresAt must be a future Unix millisecond timestamp");
+    if (!Array.isArray(config.allowedCounterparties ?? []) || (config.allowedCounterparties ?? []).some((item) => typeof item !== "string" || !/^0x[0-9a-f]{64}$/i.test(item)))
+        fail("SETUP_INVALID", "allowedCounterparties requires seller Sui addresses");
+    if (config.sellerOrigins?.length)
+        origins(config.sellerOrigins);
+    if (!config.sellerOrigins?.length && !config.directoryUrl)
+        fail("SETUP_INVALID", "configure a directoryUrl or sellerOrigins");
+    if (config.directoryUrl)
+        origins([config.directoryUrl]);
+    for (const key of ["deploymentConfig", "tatumKeyFile", "writeGrpc", "tatumGrpc", "walrusPublisher", "walrusAggregator", "memoryConfigFile"])
+        if (typeof config[key] !== "string" || !config[key])
+            fail("SETUP_INVALID", `${key} is required`);
+    for (const path of [config.tatumKeyFile, config.memoryConfigFile, ...(config.suiKeyFile ? [config.suiKeyFile] : [])])
+        ownerFile(resolve(path));
+    const deployment = JSON.parse(readFileSync(resolve(config.deploymentConfig), "utf8"));
+    if (deployment.network !== "testnet" || deployment.verifierVersion !== 2)
+        fail("SETUP_INVALID", "buyer setup requires the pinned v2 Testnet deployment");
+    if (config.allowPublicX402 !== undefined && typeof config.allowPublicX402 !== "boolean")
+        fail("SETUP_INVALID", "allowPublicX402 must be boolean");
+    for (const list of [config.allowedCapabilityIds, config.allowedCapabilityClasses])
+        if (list !== undefined && (!Array.isArray(list) || list.some((item) => typeof item !== "string" || !item)))
+            fail("SETUP_INVALID", "capability allowlists must contain nonempty strings");
+    return config;
+}
+function readConfig(path) { ownerFile(path); return validateConfig(JSON.parse(readFileSync(path, "utf8"))); }
+function writePolicy(home, config) {
+    const path = join(home, "mandate.json"), mandate = loadMandate(home);
+    const base = { ...mandate };
+    delete base.allowedCapabilityIds;
+    delete base.allowedCapabilityClasses;
+    const next = { ...base, version: "supercuts.mandate.v2", allowedCommands: [...new Set([...mandate.allowedCommands, "deal.execute", "deal.get", "deal.resume", "deal.evidence", "deal.delivery", "deal.catalog", "deal.policy", "settlement.plan", "memory.inventory"])], allowedCounterparties: config.allowedCounterparties ?? [], perDealCeiling: config.perDealCeiling, totalRunBudget: config.totalBudget, expiresAt: config.expiresAt, requiredPrivacy: "any", requireSettlementPlan: true, allowedRails: config.allowPublicX402 === true ? ["shielded", "x402"] : ["shielded"], allowPublicX402: config.allowPublicX402 === true, ...(config.allowedCapabilityIds ? { allowedCapabilityIds: config.allowedCapabilityIds } : {}), ...(config.allowedCapabilityClasses ? { allowedCapabilityClasses: config.allowedCapabilityClasses } : {}) };
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    writeFileSync(join(home, "deal-sellers.json"), `${JSON.stringify(config.directoryUrl ? { directoryUrl: origins([config.directoryUrl])[0], origins: config.sellerOrigins?.length ? origins(config.sellerOrigins) : [] } : origins(config.sellerOrigins ?? []), null, 2)}\n`, { mode: 0o600 });
+    const profilePath = join(home, "profile.json"), profile = JSON.parse(readFileSync(profilePath, "utf8"));
+    profile.policy.allowedCounterparties = [...next.allowedCounterparties];
+    profile.policy.maxAmount = config.perDealCeiling;
+    profile.policy.expiresAt = config.expiresAt;
+    writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(profilePath, 0o600);
+}
+export function setupBuyer(home, configPath) { return setupBuyerConfig(home, readConfig(resolve(configPath))); }
+export async function promptBuyerSetup(home) {
+    if (!process.stdin.isTTY)
+        fail("SETUP_INPUT_REQUIRED", "interactive setup requires a terminal; use --config with an owner-only JSON file");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const ask = async (label) => (await rl.question(`${label}: `)).trim();
+        const days = Number(await ask("Policy duration in days"));
+        if (!Number.isSafeInteger(days) || days < 1 || days > 365)
+            fail("SETUP_INVALID", "policy duration must be 1..365 days");
+        const config = {
+            deploymentConfig: await ask("Pinned Testnet deployment config path"), tatumKeyFile: await ask("Tatum key file path"),
+            writeGrpc: await ask("Sui write gRPC URL"), tatumGrpc: await ask("Tatum read gRPC URL"),
+            walrusPublisher: await ask("Walrus publisher URL"), walrusAggregator: await ask("Walrus aggregator URL"),
+            memoryConfigFile: await ask("Owner-only Walrus Memory config path"),
+            directoryUrl: await ask("Shared directory origin (blank for direct sellers)"),
+            sellerOrigins: (await ask("Additional seller HTTPS origins, comma separated (or blank)")).split(",").map((item) => item.trim()).filter(Boolean),
+            allowedCounterparties: (await ask("Initially approved seller Sui addresses, comma separated (or blank)")).split(",").map((item) => item.trim()).filter(Boolean),
+            perDealCeiling: await ask("Maximum per deal in MIST"), totalBudget: await ask("Lifetime cumulative budget in MIST"),
+            expiresAt: Date.now() + days * 24 * 60 * 60 * 1000, allowPublicX402: (await ask("Allow public x402 when requested? yes/no")).toLowerCase() === "yes",
+        };
+        if (!config.directoryUrl)
+            delete config.directoryUrl;
+        return setupBuyerConfig(home, validateConfig(config));
+    }
+    finally {
+        rl.close();
+    }
+}
+function setupBuyerConfig(home, config) {
+    if (existsSync(join(home, "profile.json")))
+        fail("PROFILE_EXISTS", "buyer home already exists; use setup renew for a standing policy update");
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    chmodSync(home, 0o700);
+    const keyPath = config.suiKeyFile ? resolve(config.suiKeyFile) : join(home, "buyer.sui.key");
+    if (!config.suiKeyFile)
+        writeFileSync(keyPath, Ed25519Keypair.generate().getSecretKey(), { mode: 0o600, flag: "wx" });
+    ownerFile(keyPath);
+    initialize(home, { role: "buyer", "deployment-config": resolve(config.deploymentConfig), "sui-key-file": keyPath, "tatum-key-file": resolve(config.tatumKeyFile), "write-grpc": config.writeGrpc, "tatum-grpc": config.tatumGrpc, "walrus-publisher": config.walrusPublisher, "walrus-aggregator": config.walrusAggregator, "memory-config-file": resolve(config.memoryConfigFile), "allow-counterparty": (config.allowedCounterparties ?? []).join(","), "max-amount": config.perDealCeiling, ...(config.rapidsnark ? { rapidsnark: resolve(config.rapidsnark) } : {}) });
+    writePolicy(home, config);
+    const session = createBuyerSession(home);
+    const decoded = decodeSuiPrivateKey(readFileSync(keyPath, "utf8").trim());
+    if (decoded.scheme !== "ED25519")
+        fail("SETUP_INVALID", "buyer key must use ED25519");
+    return { home, address: Ed25519Keypair.fromSecretKey(decoded.secretKey).toSuiAddress(), ...session, policy: "configured" };
+}
+export function createBuyerSession(home) {
+    if (!existsSync(join(home, "profile.json")))
+        fail("SETUP_REQUIRED", "initialize the buyer before creating a Codex session");
+    const runId = randomUUID(), eventPath = join(home, `events-${runId}.jsonl`), mcpScript = join(dirname(fileURLToPath(import.meta.url)), "mcp-bootstrap.js");
+    const mcp = `[mcp_servers.supercuts-buyer]\ncommand = ${JSON.stringify(process.execPath)}\nargs = ${JSON.stringify([mcpScript])}\n[mcp_servers.supercuts-buyer.env]\nSUPERCUTS_HOME = ${JSON.stringify(home)}\nSUPERCUTS_RUN_ID = ${JSON.stringify(runId)}\nSUPERCUTS_EVENT_PATH = ${JSON.stringify(eventPath)}\n`;
+    const mcpConfig = join(home, "buyer-codex.toml");
+    writeFileSync(mcpConfig, mcp, { mode: 0o600 });
+    chmodSync(mcpConfig, 0o600);
+    return { runId, eventPath, mcpConfig };
+}
+export function renewBuyer(home, configPath) {
+    const config = readConfig(resolve(configPath));
+    const prior = loadMandate(home);
+    if (prior.role !== "buyer" || prior.version !== "supercuts.mandate.v2")
+        fail("SETUP_INVALID", "renewal requires an initialized v2 buyer home");
+    config.allowedCounterparties ??= [...prior.allowedCounterparties];
+    if (config.allowedCapabilityIds === undefined && prior.allowedCapabilityIds)
+        config.allowedCapabilityIds = [...prior.allowedCapabilityIds];
+    if (config.allowedCapabilityClasses === undefined && prior.allowedCapabilityClasses)
+        config.allowedCapabilityClasses = [...prior.allowedCapabilityClasses];
+    const spent = (readReserved(home));
+    if (BigInt(config.totalBudget) < spent)
+        fail("SETUP_INVALID", "renewed lifetime budget is below already reserved spend");
+    writePolicy(home, config);
+    return { home, policy: "renewed", reservedMist: spent.toString(), remainingMist: (BigInt(config.totalBudget) - spent).toString() };
+}
+export async function approveBuyerSeller(home, capabilityId) {
+    if (!capabilityId)
+        fail("ARGUMENT_REQUIRED", "--capability-id is required");
+    const mandate = loadMandate(home);
+    if (mandate.role !== "buyer" || mandate.version !== "supercuts.mandate.v2")
+        fail("SETUP_INVALID", "seller approval requires a v2 buyer home");
+    const sourcePath = join(home, "deal-sellers.json");
+    ownerFile(sourcePath);
+    const source = JSON.parse(readFileSync(sourcePath, "utf8"));
+    if (!source.directoryUrl)
+        fail("SELLER_DIRECTORY_UNAVAILABLE", "buyer has no configured shared directory");
+    const matches = [];
+    for (let offset = 0; offset <= 100_000;) {
+        const response = await fetch(new URL(`/v2/directory/catalog?offset=${offset}`, source.directoryUrl), { redirect: "error", signal: AbortSignal.timeout(30_000) });
+        if (!response.ok)
+            fail("SELLER_DIRECTORY_UNAVAILABLE", `directory returned HTTP ${response.status}`);
+        const catalog = await response.json();
+        if (!Array.isArray(catalog.capabilities) || catalog.capabilities.length > 100)
+            fail("SELLER_DIRECTORY_INVALID", "directory catalog is invalid");
+        matches.push(...(catalog.capabilities ?? []).filter((item) => item.manifest?.capabilityId === capabilityId));
+        if (catalog.nextOffset === undefined)
+            break;
+        if (catalog.nextOffset !== offset + 100 || catalog.capabilities?.length !== 100)
+            fail("SELLER_DIRECTORY_INVALID", "directory pagination is invalid");
+        offset = catalog.nextOffset;
+    }
+    if (matches.length !== 1)
+        fail("SELLER_DIRECTORY_INVALID", "capability must resolve to exactly one live registration");
+    const registration = matches[0];
+    await verifySignedCapability(registration);
+    const endpoint = await validateDirectoryOrigin(registration.manifest.endpoint);
+    const sellerResponse = await fetch(new URL("/v2/catalog", endpoint.origin), { redirect: "error", signal: AbortSignal.timeout(15_000) });
+    if (!sellerResponse.ok)
+        fail("SELLER_CATALOG_INVALID", "seller endpoint is unavailable");
+    const served = await sellerResponse.json();
+    if (!Array.isArray(served.capabilities) || !served.capabilities.some((item) => canonicalJson(item) === canonicalJson(registration)))
+        fail("SELLER_CATALOG_INVALID", "seller no longer serves this signed capability");
+    const app = new Phase3App(home);
+    try {
+        const readback = await new WalrusDealBlobs(app).read(registration.manifestBlobId);
+        if (canonicalJson(JSON.parse(Buffer.from(readback).toString())) !== canonicalJson(registration.manifest))
+            fail("CAPABILITY_BLOB_MISMATCH", "directory manifest differs from Walrus");
+    }
+    finally {
+        app.close();
+    }
+    const path = join(home, "mandate.json"), profilePath = join(home, "profile.json");
+    const updated = { ...mandate, allowedCounterparties: [...new Set([...mandate.allowedCounterparties, registration.manifest.sellerId])] };
+    if (updated.allowedCapabilityIds)
+        updated.allowedCapabilityIds = [...new Set([...updated.allowedCapabilityIds, capabilityId])];
+    const profile = JSON.parse(readFileSync(profilePath, "utf8"));
+    profile.policy.allowedCounterparties = updated.allowedCounterparties;
+    writeFileSync(path, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+    writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
+    return { capabilityId, sellerId: registration.manifest.sellerId, approved: true };
+}
+export async function addBuyerPrivacyRule(home, capabilityId) {
+    const app = new Phase3App(home);
+    try {
+        if (app.profile.role !== "buyer" || app.profile.mock)
+            fail("LIVE_PROFILE_REQUIRED", "privacy rules require a live buyer home");
+        const mandate = loadMandate(home);
+        const matches = (await new LiveDealPorts(app, mandate).catalog()).filter(({ registration }) => registration.manifest.capabilityId === capabilityId);
+        if (matches.length !== 1)
+            fail("POLICY_CAPABILITY_INVALID", "privacy rule requires one signed seller capability");
+        const manifest = matches[0].registration.manifest;
+        const memory = { version: "supercuts.settlement-memory.v1", kind: "privacy_rule", scope: { capabilityId: manifest.capabilityId, counterparty: manifest.sellerId, network: "sui:testnet", asset: manifest.asset }, createdAt: Date.now(), signal: { requiresShielded: true } };
+        const args = { "operation-id": `owner-privacy-${manifest.manifestHash}`, memory: Buffer.from(JSON.stringify(memory)).toString("base64url") };
+        const approval = app.approve(app.preview("memory.policy", args).challengeId);
+        const result = (await app.execute("memory.policy", { ...args, "approval-token": approval.token })).data;
+        return { capabilityId, sellerId: manifest.sellerId, blobId: result.blobId, kind: result.kind, provenance: result.provenance };
+    }
+    finally {
+        app.close();
+    }
+}
+function readReserved(home) {
+    const app = new Phase3App(home);
+    try {
+        if (!app.store.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='mandate_operations'").get())
+            return 0n;
+        return app.store.db.prepare("SELECT amount FROM mandate_operations").all().reduce((sum, row) => sum + BigInt(row.amount), 0n);
+    }
+    finally {
+        app.close();
+    }
+}

package/dist/capability.d.ts

@@ -0,0 +1,32 @@
+export type CapabilityRail = "x402" | "shielded";
+export type JsonSchema = Readonly<Record<string, unknown>>;
+export declare function validateCapabilityPayload(manifest: CapabilityManifest, direction: "input" | "output", value: unknown): void;
+export interface SignedCapabilityRegistration {
+    manifest: CapabilityManifest;
+    manifestBlobId: string;
+    transportPublicKey: string;
+    sellerSignature: string;
+}
+export declare function verifySignedCapability(registration: SignedCapabilityRegistration): Promise<void>;
+/** Framework-neutral service advertisement. This is not an A2A protocol claim. */
+export interface CapabilityManifest {
+    protocol: "supercuts.capability.v1";
+    capabilityId: string;
+    sellerId: string;
+    capability: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    supportedRails: CapabilityRail[];
+    priceBand: {
+        minimum: string;
+        maximum: string;
+    };
+    asset: string;
+    endpoint: string;
+    expiresAt: number;
+    manifestHash: string;
+}
+export declare function capabilityManifestHash(manifest: Omit<CapabilityManifest, "manifestHash">): string;
+export declare function createCapabilityManifest(input: Omit<CapabilityManifest, "protocol" | "manifestHash">): CapabilityManifest;
+export declare function validateCapabilityManifest(value: unknown, now?: number): asserts value is CapabilityManifest;

package/dist/capability.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { isValidPersonalMessageSignature } from "@mysten/sui/verify";
+import { Ajv } from "ajv";
+import { fail } from "./errors.js";
+const schemaCompiler = new Ajv({ strict: true, allErrors: false });
+const compiledSchemas = new Map();
+export function validateCapabilityPayload(manifest, direction, value) {
+    validateCapabilityManifest(manifest);
+    let compiled = compiledSchemas.get(manifest.manifestHash);
+    if (!compiled) {
+        try {
+            compiled = { input: schemaCompiler.compile(manifest.inputSchema), output: schemaCompiler.compile(manifest.outputSchema) };
+        }
+        catch (error) {
+            return fail("CAPABILITY_SCHEMA_INVALID", "signed capability contains an invalid JSON Schema", error);
+        }
+        compiledSchemas.set(manifest.manifestHash, compiled);
+    }
+    if (!compiled[direction](value))
+        fail("CAPABILITY_PAYLOAD_INVALID", `${direction} does not match the signed capability schema`);
+}
+export async function verifySignedCapability(registration) {
+    validateCapabilityManifest(registration.manifest);
+    if (typeof registration.manifestBlobId !== "string" || !registration.manifestBlobId || typeof registration.transportPublicKey !== "string" || !registration.transportPublicKey || typeof registration.sellerSignature !== "string" || !registration.sellerSignature)
+        fail("SELLER_SIGNATURE_INVALID", "signed capability registration is incomplete");
+    const signed = Buffer.from(`${registration.manifest.manifestHash}:${registration.transportPublicKey}`);
+    if (!(await isValidPersonalMessageSignature(signed, registration.sellerSignature, { address: registration.manifest.sellerId })))
+        fail("SELLER_SIGNATURE_INVALID", "seller did not sign the capability and transport key");
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        fail("CAPABILITY_INVALID", "capability manifests must be JSON-compatible");
+    return encoded;
+}
+export function capabilityManifestHash(manifest) {
+    return createHash("sha256").update(canonical({ domain: "supercuts-capability-v1", ...manifest })).digest("hex");
+}
+export function createCapabilityManifest(input) {
+    const unsigned = { protocol: "supercuts.capability.v1", ...input };
+    const manifest = { ...unsigned, manifestHash: capabilityManifestHash(unsigned) };
+    validateCapabilityManifest(manifest);
+    return manifest;
+}
+export function validateCapabilityManifest(value, now = Date.now()) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("CAPABILITY_INVALID", "capability manifest must be an object");
+    const manifest = value;
+    const allowed = new Set(["protocol", "capabilityId", "sellerId", "capability", "description", "inputSchema", "outputSchema", "supportedRails", "priceBand", "asset", "endpoint", "expiresAt", "manifestHash"]);
+    if (Object.keys(manifest).some((key) => !allowed.has(key)))
+        fail("CAPABILITY_INVALID", "capability manifest contains unknown fields");
+    if (manifest.protocol !== "supercuts.capability.v1")
+        fail("CAPABILITY_VERSION_UNSUPPORTED", "capability protocol must be supercuts.capability.v1");
+    for (const field of ["capabilityId", "sellerId", "capability", "description", "asset", "endpoint", "manifestHash"]) {
+        const item = manifest[field];
+        if (typeof item !== "string" || !item || item.length > (field === "description" ? 4096 : 1024))
+            fail("CAPABILITY_INVALID", `${field} is missing or too long`);
+    }
+    if (!manifest.inputSchema || typeof manifest.inputSchema !== "object" || Array.isArray(manifest.inputSchema) || !manifest.outputSchema || typeof manifest.outputSchema !== "object" || Array.isArray(manifest.outputSchema))
+        fail("CAPABILITY_SCHEMA_INVALID", "inputSchema and outputSchema must be JSON Schema objects");
+    if (Buffer.byteLength(canonical(manifest.inputSchema)) + Buffer.byteLength(canonical(manifest.outputSchema)) > 64 * 1024)
+        fail("CAPABILITY_SCHEMA_INVALID", "capability schemas exceed 64 KiB");
+    if (!Array.isArray(manifest.supportedRails) || !manifest.supportedRails.length || new Set(manifest.supportedRails).size !== manifest.supportedRails.length || manifest.supportedRails.some((rail) => rail !== "x402" && rail !== "shielded"))
+        fail("CAPABILITY_RAIL_INVALID", "supportedRails must contain unique supported rails");
+    if (!manifest.priceBand || !/^(?:0|[1-9][0-9]*)$/.test(manifest.priceBand.minimum) || !/^(?:0|[1-9][0-9]*)$/.test(manifest.priceBand.maximum) || BigInt(manifest.priceBand.minimum) > BigInt(manifest.priceBand.maximum))
+        fail("CAPABILITY_PRICE_INVALID", "priceBand must contain ordered unsigned integer strings");
+    if (!Number.isSafeInteger(manifest.expiresAt) || manifest.expiresAt <= now)
+        fail("CAPABILITY_EXPIRED", "capability manifest is expired");
+    let endpoint;
+    try {
+        endpoint = new URL(manifest.endpoint);
+    }
+    catch (error) {
+        return fail("CAPABILITY_ENDPOINT_INVALID", "capability endpoint must be an absolute URL", error);
+    }
+    if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && ["127.0.0.1", "localhost", "::1"].includes(endpoint.hostname)))
+        fail("CAPABILITY_ENDPOINT_INVALID", "capability endpoint must use HTTPS except on loopback");
+    if (endpoint.username || endpoint.password)
+        fail("CAPABILITY_ENDPOINT_INVALID", "capability endpoint cannot contain credentials");
+    const { manifestHash, ...unsigned } = manifest;
+    if (!/^[0-9a-f]{64}$/.test(manifestHash) || capabilityManifestHash(unsigned) !== manifestHash)
+        fail("CAPABILITY_HASH_MISMATCH", "capability manifest hash does not match its canonical contents");
+}

package/dist/claude.d.ts

@@ -0,0 +1,44 @@
+export interface ClaudeUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface ClaudeDecision<T extends Record<string, unknown>> {
+    action: T;
+    model: string;
+    usage: ClaudeUsage;
+    sanitizedRationale: string;
+}
+export interface ClaudeActionSchema {
+    name: string;
+    description: string;
+    properties: Record<string, Record<string, unknown>>;
+    required: string[];
+}
+export interface BoundedClaudeOptions {
+    apiKey?: string;
+    model?: string;
+    maxTurns?: number;
+    maxTokens?: number;
+    retries?: number;
+    fetch?: typeof globalThis.fetch;
+    onDecision?: (entry: {
+        model: string;
+        usage: ClaudeUsage;
+        action: string;
+        rationale: string;
+    }) => void;
+}
+export declare function sanitizeRationale(value: string): string;
+/** Bounded reasoning only. Callers must supply policy-approved choices and own all amounts and success claims. */
+export declare class BoundedClaude {
+    #private;
+    private readonly options;
+    readonly model: string;
+    constructor(options?: BoundedClaudeOptions);
+    decide<T extends Record<string, unknown>>(input: {
+        system: string;
+        task: string;
+        candidates: unknown[];
+        schema: ClaudeActionSchema;
+    }): Promise<ClaudeDecision<T>>;
+}

package/dist/claude.js

@@ -0,0 +1,98 @@
+import { fail } from "./errors.js";
+const secret = /(?:suiprivkey|sk-ant-|-----BEGIN [A-Z ]*PRIVATE KEY-----|seed phrase|note opening|approval token)/gi;
+export function sanitizeRationale(value) { return value.replace(secret, "[REDACTED]").replace(/\s+/g, " ").trim().slice(0, 512); }
+function validateAction(schema, input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        fail("CLAUDE_OUTPUT_INVALID", "Claude tool input must be an object");
+    const value = input;
+    for (const key of Object.keys(value))
+        if (!(key in schema.properties))
+            fail("CLAUDE_OUTPUT_INVALID", `Claude returned unknown field ${key}`);
+    for (const key of schema.required)
+        if (!(key in value))
+            fail("CLAUDE_OUTPUT_INVALID", `Claude omitted required field ${key}`);
+    for (const [key, item] of Object.entries(value)) {
+        const field = schema.properties[key];
+        if (field.type === "string" && typeof item !== "string")
+            fail("CLAUDE_OUTPUT_INVALID", `${key} must be a string`);
+        if (field.type === "boolean" && typeof item !== "boolean")
+            fail("CLAUDE_OUTPUT_INVALID", `${key} must be a boolean`);
+        if (field.type === "array" && !Array.isArray(item))
+            fail("CLAUDE_OUTPUT_INVALID", `${key} must be an array`);
+        if (Array.isArray(field.enum) && !field.enum.includes(item))
+            fail("CLAUDE_OUTPUT_INVALID", `${key} is not an allowed action value`);
+        if (typeof item === "string" && typeof field.maxLength === "number" && item.length > field.maxLength)
+            fail("CLAUDE_OUTPUT_INVALID", `${key} is too long`);
+    }
+}
+/** Bounded reasoning only. Callers must supply policy-approved choices and own all amounts and success claims. */
+export class BoundedClaude {
+    options;
+    model;
+    #apiKey;
+    #maxTurns;
+    #maxTokens;
+    #retries;
+    #fetch;
+    constructor(options = {}) {
+        this.options = options;
+        this.#apiKey = options.apiKey ?? process.env.CLAUDE_API_KEY ?? "";
+        if (!this.#apiKey)
+            fail("CLAUDE_CREDENTIAL_MISSING", "CLAUDE_API_KEY is required for live agent reasoning");
+        this.model = options.model ?? process.env.CLAUDE_MODEL ?? "claude-haiku-5-5";
+        this.#maxTurns = options.maxTurns ?? 3;
+        this.#maxTokens = options.maxTokens ?? 700;
+        this.#retries = options.retries ?? 2;
+        this.#fetch = options.fetch ?? fetch;
+        if (!Number.isSafeInteger(this.#maxTurns) || this.#maxTurns < 1 || this.#maxTurns > 6 || !Number.isSafeInteger(this.#maxTokens) || this.#maxTokens < 32 || this.#maxTokens > 2048 || !Number.isSafeInteger(this.#retries) || this.#retries < 0 || this.#retries > 3)
+            fail("CLAUDE_LIMIT_INVALID", "Claude bounds exceed the allowed demo limits");
+    }
+    async decide(input) {
+        if (!input.task || input.task.length > 16_000 || input.system.length > 8_000 || input.candidates.length > 100)
+            fail("CLAUDE_INPUT_INVALID", "Claude input exceeds bounded limits");
+        const tool = { name: input.schema.name, description: input.schema.description, input_schema: { type: "object", properties: input.schema.properties, required: input.schema.required, additionalProperties: false } };
+        let last;
+        for (let turn = 0; turn < this.#maxTurns; turn++) {
+            for (let attempt = 0; attempt <= this.#retries; attempt++) {
+                let response;
+                try {
+                    response = await this.#fetch("https://api.anthropic.com/v1/messages", { method: "POST", headers: { "content-type": "application/json", "anthropic-version": "2023-06-01", "x-api-key": this.#apiKey }, body: JSON.stringify({ model: this.model, max_tokens: this.#maxTokens, system: input.system, messages: [{ role: "user", content: JSON.stringify({ task: input.task, policyApprovedCandidates: input.candidates }) }], tools: [tool], tool_choice: { type: "tool", name: input.schema.name } }), signal: AbortSignal.timeout(30_000) });
+                }
+                catch (error) {
+                    last = error;
+                    if (attempt < this.#retries)
+                        continue;
+                    return fail("CLAUDE_UNAVAILABLE", "Claude request failed closed", error);
+                }
+                if (!response.ok) {
+                    last = new Error(`Anthropic status ${response.status}`);
+                    if (attempt < this.#retries && (response.status === 429 || response.status >= 500)) {
+                        await response.arrayBuffer();
+                        continue;
+                    }
+                    return fail("CLAUDE_UNAVAILABLE", `Claude returned status ${response.status}`);
+                }
+                let body;
+                try {
+                    body = await response.json();
+                }
+                catch (error) {
+                    return fail("CLAUDE_OUTPUT_INVALID", "Claude returned invalid JSON", error);
+                }
+                const blocks = Array.isArray(body.content) ? body.content : [], selected = blocks.find((block) => block?.type === "tool_use" && block.name === input.schema.name);
+                if (!selected) {
+                    last = new Error("required tool call missing");
+                    break;
+                }
+                validateAction(input.schema, selected.input);
+                const rationaleBlock = blocks.find((block) => block?.type === "text" && typeof block.text === "string");
+                const rationale = sanitizeRationale(String(selected.input.rationale ?? rationaleBlock?.text ?? "bounded selection"));
+                const usage = { inputTokens: Number(body.usage?.input_tokens ?? 0), outputTokens: Number(body.usage?.output_tokens ?? 0) };
+                const actionName = String(selected.input.action ?? selected.input.choice ?? input.schema.name);
+                this.options.onDecision?.({ model: this.model, usage, action: actionName, rationale });
+                return { action: selected.input, model: this.model, usage, sanitizedRationale: rationale };
+            }
+        }
+        return fail("CLAUDE_OUTPUT_INVALID", "Claude did not produce a schema-valid bounded action", last);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { Phase3App, errorOutput, homePath, initialize, parseArgs } from "./phase3.js";
+import { addBuyerPrivacyRule, approveBuyerSeller, createBuyerSession, promptBuyerSetup, renewBuyer, setupBuyer } from "./buyer-setup.js";
+import { onboardingDoctor } from "./onboarding-doctor.js";
+const words = process.argv.slice(2);
+let command = words.shift() ?? "";
+if (["wallet", "offer", "pay", "resource", "memory", "audit", "capability", "settlement", "setup", "policy", "onboarding"].includes(command))
+    command += `.${words.shift() ?? ""}`;
+try {
+    if (!command || command === "help" || command === "--help" || command === "setup.") {
+        process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.help.v1", ok: true, commands: ["setup buyer", "setup renew", "setup session", "init", "doctor", "status", "wallet", "offer", "pay", "memory", "capability", "audit"], setup: "Run supercuts setup buyer --home <private-directory> for guided live Testnet setup. Run supercuts init --role <buyer|seller|auditor> --mock --home <private-directory> for a local non-funded profile. Keep each role in a separate owner-only home.", live: "Supply the pinned Testnet deployment config, owner-only credential files, Sui and Tatum RPC endpoints, Walrus endpoints, local proving artifacts, and RapidSnark. Fund only the buyer address printed by supercuts-demo setup." })}\n`);
+        process.exit(0);
+    }
+    const args = parseArgs(words);
+    const home = homePath(args);
+    const result = command === "init" ? initialize(home, args) : command === "setup.buyer" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: typeof args.config === "string" ? setupBuyer(home, args.config) : await promptBuyerSetup(home) } : command === "setup.renew" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: renewBuyer(home, String(args.config ?? "")) } : command === "setup.session" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: createBuyerSession(home) } : command === "policy.add" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await addBuyerPrivacyRule(home, String(args["capability-id"] ?? "")) } : command === "policy.approve-seller" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await approveBuyerSeller(home, String(args["capability-id"] ?? "")) } : command === "onboarding.doctor" ? { schemaVersion: "supercuts.onboarding.v1", ok: true, command, data: await onboardingDoctor(home, typeof args.config === "string" ? args.config : undefined) } : await (async () => { const app = new Phase3App(home); try {
+        return await app.execute(command, args);
+    }
+    finally {
+        app.close();
+    } })();
+    if (args.authorize === true)
+        result.warnings = ["--authorize is a deprecated compatibility path; SDK integrations must use bound approval tokens"];
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+catch (error) {
+    process.stdout.write(`${JSON.stringify(errorOutput(error))}\n`);
+    process.exitCode = 1;
+}