@fased/fased 0.1.62 → 0.1.64

package/dist/wallet/external-submission-ledger.js

@@ -0,0 +1,376 @@
+import { resolveProcessScopedMap } from "../shared/process-scoped-map.js";
+import { acquireFileLock, withFileLock } from "../plugin-sdk/file-lock.js";
+import "../infra/file-lock.js";
+import { ensureWalletStateDir } from "./wallet-runtime-config.js";
+import syncFs from "node:fs";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+
+//#region src/wallet/external-submission-ledger.ts
+const STATES = new Set([
+	"reserved",
+	"prepared",
+	"signed",
+	"submitting",
+	"unknown",
+	"confirmed",
+	"failed"
+]);
+const KINDS = new Set([
+	"jupiter-swap",
+	"jupiter-trigger-auth",
+	"jupiter-trigger-create",
+	"jupiter-trigger-cancel"
+]);
+const TRANSITIONS = {
+	reserved: new Set([
+		"reserved",
+		"prepared",
+		"submitting",
+		"failed"
+	]),
+	prepared: new Set([
+		"prepared",
+		"signed",
+		"unknown",
+		"confirmed",
+		"failed"
+	]),
+	signed: new Set([
+		"signed",
+		"submitting",
+		"unknown"
+	]),
+	submitting: new Set([
+		"submitting",
+		"prepared",
+		"unknown",
+		"confirmed",
+		"failed"
+	]),
+	unknown: new Set([
+		"unknown",
+		"confirmed",
+		"failed"
+	]),
+	confirmed: new Set(["confirmed"]),
+	failed: new Set(["failed"])
+};
+const LEDGER_LOCK_OPTIONS = {
+	retries: {
+		retries: 100,
+		factor: 1.15,
+		minTimeout: 10,
+		maxTimeout: 200,
+		randomize: true
+	},
+	stale: 3e4
+};
+const EXECUTION_LOCK_OPTIONS = {
+	retries: {
+		retries: 1,
+		factor: 1,
+		minTimeout: 10,
+		maxTimeout: 10,
+		randomize: false
+	},
+	stale: 3e4
+};
+const ACTIVE_EXECUTIONS = resolveProcessScopedMap(Symbol.for("fased.wallet.externalSubmission.activeExecutions"));
+const LEDGER_MUTATION_QUEUES = resolveProcessScopedMap(Symbol.for("fased.wallet.externalSubmission.mutationQueues"));
+async function claimExternalSubmissionExecution(keyRaw, env = process.env) {
+	const key = keyRaw.trim();
+	if (!key || containsControlCharacter(key)) {
+		throw new Error("external submission execution key is invalid");
+	}
+	const executionKey = `${ledgerPath(env)}\0${key}`;
+	if (ACTIVE_EXECUTIONS.has(executionKey)) {
+		throw new Error(`external submission ${key} is already executing; wait for its durable result instead of retrying`);
+	}
+	ACTIVE_EXECUTIONS.set(executionKey, true);
+	const claimTarget = path.join(path.dirname(ledgerPath(env)), ".external-submission-executions", createHash("sha256").update(key).digest("hex"));
+	let lock;
+	try {
+		lock = await acquireFileLock(claimTarget, EXECUTION_LOCK_OPTIONS);
+	} catch (error) {
+		ACTIVE_EXECUTIONS.delete(executionKey);
+		throw new Error(`external submission ${key} is already executing; wait for its durable result instead of retrying`, { cause: error });
+	}
+	let released = false;
+	return async () => {
+		if (!released) {
+			ACTIVE_EXECUTIONS.delete(executionKey);
+			released = true;
+			await lock.release();
+		}
+	};
+}
+function canonicalJson(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") {
+		return JSON.stringify(value);
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error("external submission intent contains a non-finite number");
+		}
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+	}
+	if (value && typeof value === "object") {
+		const record = value;
+		const entries = Object.keys(record).filter((key) => record[key] !== undefined).toSorted().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+		return `{${entries.join(",")}}`;
+	}
+	throw new Error("external submission intent contains an unsupported value");
+}
+function containsControlCharacter(value) {
+	for (let index = 0; index < value.length; index += 1) {
+		if (value.charCodeAt(index) <= 31) {
+			return true;
+		}
+	}
+	return false;
+}
+function externalSubmissionIntentDigest(intent) {
+	return `sha256:${createHash("sha256").update(canonicalJson(intent)).digest("hex")}`;
+}
+function createExternalSubmissionKey(params) {
+	const walletId = params.walletId.trim();
+	if (!walletId) {
+		throw new Error("external submission walletId is required");
+	}
+	const explicitIntentId = params.explicitIntentId?.trim() || undefined;
+	if (explicitIntentId && (explicitIntentId.length > 160 || containsControlCharacter(explicitIntentId))) {
+		throw new Error("external submission intentId is invalid");
+	}
+	const intentDigest = externalSubmissionIntentDigest(params.intent);
+	const keyDigest = createHash("sha256").update(`${params.kind}\0${walletId}\0${intentDigest}\0${explicitIntentId ?? "default"}`).digest("hex");
+	return {
+		key: `${params.kind}:${keyDigest}`,
+		intentDigest,
+		...explicitIntentId ? { explicitIntentId } : {}
+	};
+}
+function ledgerPath(env) {
+	return path.join(ensureWalletStateDir(env).rootDir, "external-submissions.json");
+}
+async function withLedgerMutationLock(env, task) {
+	const filePath = ledgerPath(env);
+	const previous = LEDGER_MUTATION_QUEUES.get(filePath) ?? Promise.resolve();
+	let releaseQueue;
+	const turn = new Promise((resolve) => {
+		releaseQueue = resolve;
+	});
+	const queued = previous.then(() => turn, () => turn);
+	LEDGER_MUTATION_QUEUES.set(filePath, queued);
+	await previous.catch(() => undefined);
+	try {
+		return await withFileLock(filePath, LEDGER_LOCK_OPTIONS, async () => await task());
+	} finally {
+		releaseQueue();
+		if (LEDGER_MUTATION_QUEUES.get(filePath) === queued) {
+			LEDGER_MUTATION_QUEUES.delete(filePath);
+		}
+	}
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateEntry(value) {
+	if (!isRecord(value)) {
+		throw new Error("external submission ledger contains an invalid entry");
+	}
+	const state = value.state;
+	if (typeof value.key !== "string" || typeof value.kind !== "string" || !KINDS.has(value.kind) || typeof value.walletId !== "string" || typeof value.intentDigest !== "string" || typeof value.createdAt !== "string" || typeof value.updatedAt !== "string" || typeof state !== "string" || !STATES.has(state)) {
+		throw new Error("external submission ledger contains an invalid entry");
+	}
+	if (!value.intentDigest.match(/^sha256:[0-9a-f]{64}$/)) {
+		throw new Error("external submission ledger contains an invalid intent digest");
+	}
+	for (const field of [
+		"explicitIntentId",
+		"signerRequestId",
+		"signerIntentDigest",
+		"signerSignature",
+		"externalRequestId",
+		"transactionDigest",
+		"reason"
+	]) {
+		if (value[field] !== undefined && typeof value[field] !== "string") {
+			throw new Error(`external submission ledger contains an invalid ${field}`);
+		}
+	}
+	if (value.details !== undefined && !isRecord(value.details)) {
+		throw new Error("external submission ledger contains invalid details");
+	}
+	if (value.result !== undefined && !isRecord(value.result)) {
+		throw new Error("external submission ledger contains an invalid result");
+	}
+	return value;
+}
+function loadLedger(env) {
+	const filePath = ledgerPath(env);
+	if (!syncFs.existsSync(filePath)) {
+		return {
+			version: 1,
+			entries: []
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(syncFs.readFileSync(filePath, "utf8"));
+	} catch (error) {
+		throw new Error("external submission ledger is unreadable; refusing a potentially duplicate transaction", { cause: error });
+	}
+	if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.entries)) {
+		throw new Error("external submission ledger has an unsupported format");
+	}
+	const entries = parsed.entries.map(validateEntry);
+	if (new Set(entries.map((entry) => entry.key)).size !== entries.length) {
+		throw new Error("external submission ledger contains duplicate idempotency keys");
+	}
+	return {
+		version: 1,
+		entries
+	};
+}
+function saveLedger(file, env) {
+	const filePath = ledgerPath(env);
+	const temporary = `${filePath}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+	let descriptor;
+	try {
+		descriptor = syncFs.openSync(temporary, "wx", 384);
+		syncFs.writeFileSync(descriptor, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+		syncFs.fsyncSync(descriptor);
+		syncFs.closeSync(descriptor);
+		descriptor = undefined;
+		syncFs.renameSync(temporary, filePath);
+		syncFs.chmodSync(filePath, 384);
+		try {
+			const directory = syncFs.openSync(path.dirname(filePath), "r");
+			try {
+				syncFs.fsyncSync(directory);
+			} finally {
+				syncFs.closeSync(directory);
+			}
+		} catch (error) {
+			const code = error.code;
+			if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR") {
+				throw error;
+			}
+		}
+	} finally {
+		if (descriptor !== undefined) {
+			syncFs.closeSync(descriptor);
+		}
+		try {
+			syncFs.unlinkSync(temporary);
+		} catch {}
+	}
+}
+function getExternalSubmission(params) {
+	const file = loadLedger(params.env ?? process.env);
+	return file.entries.find((entry) => entry.key === params.key.trim());
+}
+function getExternalSubmissionByExplicitIntent(params) {
+	const kind = params.kind;
+	const walletId = params.walletId.trim();
+	const explicitIntentId = params.explicitIntentId.trim();
+	if (!walletId || !explicitIntentId || containsControlCharacter(explicitIntentId)) {
+		throw new Error("external submission explicit intent lookup is invalid");
+	}
+	const file = loadLedger(params.env ?? process.env);
+	return file.entries.find((entry) => entry.kind === kind && entry.walletId === walletId && entry.explicitIntentId === explicitIntentId);
+}
+async function beginExternalSubmission(params) {
+	const env = params.env ?? process.env;
+	return await withLedgerMutationLock(env, () => {
+		const file = loadLedger(env);
+		const key = params.key.trim();
+		const walletId = params.walletId.trim();
+		const existing = file.entries.find((entry) => entry.key === key);
+		if (existing) {
+			if (existing.kind !== params.kind || existing.walletId !== walletId || existing.intentDigest !== params.intentDigest || (existing.explicitIntentId ?? undefined) !== (params.explicitIntentId?.trim() || undefined)) {
+				throw new Error("external submission idempotency key collides with a different intent");
+			}
+			return {
+				entry: existing,
+				created: false
+			};
+		}
+		const explicitIntentId = params.explicitIntentId?.trim() || undefined;
+		const conflictingExplicitIntent = explicitIntentId ? file.entries.find((entry) => entry.kind === params.kind && entry.walletId === walletId && entry.explicitIntentId === explicitIntentId) : undefined;
+		if (conflictingExplicitIntent) {
+			throw new Error("external submission intentId is already bound to a different immutable intent");
+		}
+		const now = new Date().toISOString();
+		const entry = {
+			key,
+			kind: params.kind,
+			walletId,
+			intentDigest: params.intentDigest,
+			...explicitIntentId ? { explicitIntentId } : {},
+			state: "reserved",
+			...params.details ? { details: params.details } : {},
+			createdAt: now,
+			updatedAt: now
+		};
+		file.entries.push(entry);
+		saveLedger(file, env);
+		return {
+			entry,
+			created: true
+		};
+	});
+}
+async function updateExternalSubmission(params) {
+	const env = params.env ?? process.env;
+	return await withLedgerMutationLock(env, () => {
+		const file = loadLedger(env);
+		const entry = file.entries.find((candidate) => candidate.key === params.key.trim());
+		if (!entry) {
+			throw new Error("external submission ledger entry not found");
+		}
+		if (!params.expectedStates.includes(entry.state)) {
+			throw new Error(`external submission ${entry.key} is ${entry.state}; expected ${params.expectedStates.join(" or ")}`);
+		}
+		if (!TRANSITIONS[entry.state].has(params.state)) {
+			throw new Error(`external submission cannot transition from ${entry.state} to ${params.state}`);
+		}
+		Object.assign(entry, params.patch ?? {});
+		entry.state = params.state;
+		entry.updatedAt = new Date().toISOString();
+		saveLedger(file, env);
+		return entry;
+	});
+}
+async function renewConfirmedExternalSubmission(params) {
+	const env = params.env ?? process.env;
+	return await withLedgerMutationLock(env, () => {
+		const file = loadLedger(env);
+		const entry = file.entries.find((candidate) => candidate.key === params.key.trim());
+		if (!entry || entry.state !== "confirmed") {
+			throw new Error("only a confirmed external submission can be renewed");
+		}
+		const now = new Date().toISOString();
+		const renewed = {
+			key: entry.key,
+			kind: entry.kind,
+			walletId: entry.walletId,
+			intentDigest: entry.intentDigest,
+			...entry.explicitIntentId ? { explicitIntentId: entry.explicitIntentId } : {},
+			state: "reserved",
+			...params.details ? { details: params.details } : {},
+			createdAt: now,
+			updatedAt: now
+		};
+		file.entries[file.entries.indexOf(entry)] = renewed;
+		saveLedger(file, env);
+		return renewed;
+	});
+}
+
+//#endregion
+export { beginExternalSubmission, claimExternalSubmissionExecution, createExternalSubmissionKey, externalSubmissionIntentDigest, getExternalSubmission, getExternalSubmissionByExplicitIntent, updateExternalSubmission };

package/dist/wallet/legacy-embedded-keystore.js

@@ -0,0 +1,40 @@
+//#region src/wallet/legacy-embedded-keystore.ts
+const LEGACY_EMBEDDED_KEYSTORE_PROVIDER_ID = "embedded-keystore";
+const LEGACY_EMBEDDED_KEYSTORE_MIGRATION_MESSAGE = "embedded-keystore was retired so normal production Fased code no longer reads wallet private keys in Node or the Gateway. " + "On Local, the signer and Gateway share an OS account, so this code-path separation is not a hard compromise boundary; Hosting uses a separate signer account for OS isolation. " + "Migrate one way with the verified native fased-signerd through its signer-only control socket. " + "For a legacy encrypted keystore, run `fased-signerd admin wallet import-legacy --control-socket <absolute-control.sock> --wallet-id <wallet-id> --locked-role <agent|mining|vault> --keystore-path <absolute-0600-keystore> --passphrase-path <absolute-0600-passphrase-file>`. " + "For a Solana CLI keypair, run `fased-signerd admin wallet import --control-socket <absolute-control.sock> --wallet-id <wallet-id> --locked-role <agent|mining|vault> < /absolute/path/to/solana-keypair.json`. " + "After the native import succeeds, run `fased wallet finalize-legacy-migration --wallet-id <wallet-id>`; it verifies the protocol-v2 signer public key before replacing legacy config/registry references without reading the old key files. " + "Run the native command as the signer/control-socket owner; do not pass a private key or passphrase to Fased CLI, Gateway, UI, argv, or environment variables.";
+var LegacyEmbeddedKeystoreMigrationRequiredError = class extends Error {
+	constructor(context) {
+		super(context?.trim() ? `${context.trim()}: ${LEGACY_EMBEDDED_KEYSTORE_MIGRATION_MESSAGE}` : LEGACY_EMBEDDED_KEYSTORE_MIGRATION_MESSAGE);
+		this.code = "wallet_legacy_embedded_keystore_migration_required";
+		this.name = "LegacyEmbeddedKeystoreMigrationRequiredError";
+	}
+};
+function throwLegacyEmbeddedKeystoreMigrationRequired(context) {
+	throw new LegacyEmbeddedKeystoreMigrationRequiredError(context);
+}
+function hasLegacyEmbeddedKeystoreConfig(cfg, env) {
+	if (cfg.wallet?.provider?.id === LEGACY_EMBEDDED_KEYSTORE_PROVIDER_ID) {
+		return true;
+	}
+	const legacyKeystore = cfg.wallet?.keystore;
+	if (legacyKeystore && (legacyKeystore.enabled !== undefined || Boolean(legacyKeystore.path?.trim()) || Boolean(legacyKeystore.chainSupport?.length) || legacyKeystore.autoLockSeconds !== undefined || legacyKeystore.requirePasskeyForUnlock !== undefined)) {
+		return true;
+	}
+	if (String(env.FASED_WALLET_PROVIDER ?? "").trim() === LEGACY_EMBEDDED_KEYSTORE_PROVIDER_ID) {
+		return true;
+	}
+	return false;
+}
+function hasLegacyEmbeddedKeystoreMaterialHint(env) {
+	for (const [key, rawValue] of Object.entries(env)) {
+		if (typeof rawValue !== "string" || !rawValue.trim()) {
+			continue;
+		}
+		if (key === "FASED_WALLET_KEYSTORE_PATH" || key === "FASED_WALLET_PASSPHRASE" || key === "FASED_WALLET_PASSPHRASE_FILE" || key === "FASED_WALLET_PRIVATE_KEY" || key === "FASED_WALLET_SOLANA_KEYSTORE_PATH" || key.startsWith("FASED_WALLET_SOLANA_KEYSTORE_PATH__")) {
+			return true;
+		}
+	}
+	return false;
+}
+
+//#endregion
+export { LEGACY_EMBEDDED_KEYSTORE_MIGRATION_MESSAGE, LegacyEmbeddedKeystoreMigrationRequiredError, hasLegacyEmbeddedKeystoreConfig, hasLegacyEmbeddedKeystoreMaterialHint, throwLegacyEmbeddedKeystoreMigrationRequired };

package/dist/wallet/local-socket-signer-archive.js

@@ -0,0 +1,30 @@
+import { LocalSocketSignerAdapter } from "./providers/local-socket-signer-adapter.js";
+import { resolveNativeSignerWalletId } from "./native-signer-wallet-id.js";
+
+//#region src/wallet/local-socket-signer-archive.ts
+async function lockSignerOwnedWalletForArchive(params) {
+	const signerWalletId = resolveNativeSignerWalletId(params.wallet);
+	const signer = params.signer ?? new LocalSocketSignerAdapter(params.socketPath);
+	const current = await signer.getSignerPolicy(signerWalletId);
+	if (current.walletId !== signerWalletId) {
+		throw new Error("native signer returned policy state for a different wallet");
+	}
+	const acknowledged = await signer.tightenSignerPolicy({
+		walletId: signerWalletId,
+		expectedVersion: current.version,
+		policy: {
+			walletId: signerWalletId,
+			role: current.role,
+			operations: [],
+			programs: [],
+			assets: []
+		}
+	});
+	if (acknowledged.operations.length !== 0 || acknowledged.programs.length !== 0 || acknowledged.assets.length !== 0) {
+		throw new Error("native signer did not durably acknowledge the exact deny-all archive policy");
+	}
+	return acknowledged;
+}
+
+//#endregion
+export { lockSignerOwnedWalletForArchive };

package/dist/wallet/local-socket-signer-lifecycle.js

@@ -0,0 +1,97 @@
+import { LOCAL_SIGNER_NATIVE_FEE_RESERVATION_LAMPORTS_V2 } from "./local-socket-signer-protocol.js";
+import { callLocalSocketSigner } from "./providers/local-socket-signer-adapter.js";
+
+//#region src/wallet/local-socket-signer-lifecycle.ts
+function lockedLocalSignerPolicy(role) {
+	return {
+		role,
+		operations: [],
+		programs: [],
+		assets: []
+	};
+}
+async function requireSignerOwnedProtocolV2(socketPath) {
+	const result = await callLocalSocketSigner(socketPath, { op: "v2.capabilities" });
+	const capabilities = result.capabilities;
+	const required = [
+		"failClosedPolicies",
+		"policyHashes",
+		"signerOwnedKeys",
+		"atomicMultiAssetCaps",
+		"signerControlledNativeFeeCaps"
+	];
+	const missing = required.filter((feature) => !capabilities?.features.includes(feature));
+	if (result.ready !== true || capabilities?.protocol.current !== 2 || capabilities.protocol.min > 2 || capabilities.protocol.max < 2 || capabilities.nativeFeeReservationLamports !== LOCAL_SIGNER_NATIVE_FEE_RESERVATION_LAMPORTS_V2 || missing.length > 0) {
+		throw new Error(`fased-signerd does not provide the required signer-owned protocol-v2 capabilities${missing.length > 0 ? `: ${missing.join(", ")}` : ""}`);
+	}
+}
+async function readSignerOwnedWallet(params) {
+	const [wallet, policy] = await Promise.all([callLocalSocketSigner(params.socketPath, {
+		op: "v2.wallet.get",
+		walletId: params.walletId
+	}), callLocalSocketSigner(params.socketPath, {
+		op: "v2.policy.get",
+		walletId: params.walletId
+	})]);
+	return {
+		wallet,
+		policy
+	};
+}
+/**
+* Create a signer-owned key without returning its secret to normal Fased Node code. Local runs the
+* signer under the same OS account, so this code-path separation is not a hard compromise boundary.
+*
+* The application socket may create only this explicit empty/deny-all policy. Policy expansion is
+* a separate signer-admin action, so a compromised Gateway cannot turn key creation into spending.
+*/
+async function createLockedSignerOwnedWallet(params) {
+	const walletId = params.walletId.trim();
+	if (!/^[a-zA-Z0-9_-]+$/.test(walletId)) {
+		throw new Error("walletId must contain only letters, numbers, hyphens, or underscores");
+	}
+	await requireSignerOwnedProtocolV2(params.socketPath);
+	try {
+		const existing = await readSignerOwnedWallet({
+			socketPath: params.socketPath,
+			walletId
+		});
+		if (!params.allowExisting) {
+			throw new Error(`signer-owned wallet already exists: ${walletId}`);
+		}
+		if (existing.policy.role !== params.role) {
+			throw new Error(`signer-owned wallet ${walletId} already has role=${existing.policy.role}, not ${params.role}`);
+		}
+		return existing;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.startsWith("signer-owned wallet")) {
+			throw error;
+		}
+	}
+	try {
+		return await callLocalSocketSigner(params.socketPath, {
+			op: "v2.wallet.create",
+			walletId,
+			request: {
+				expectedPolicyVersion: 0,
+				policy: lockedLocalSignerPolicy(params.role)
+			}
+		});
+	} catch (error) {
+		if (!params.allowExisting) {
+			throw error;
+		}
+		const existing = await readSignerOwnedWallet({
+			socketPath: params.socketPath,
+			walletId
+		});
+		if (existing.policy.role !== params.role) {
+			throw new Error(`signer-owned wallet ${walletId} was concurrently created with role=${existing.policy.role}`, { cause: error });
+		}
+		return existing;
+	}
+}
+
+//#endregion
+export { createLockedSignerOwnedWallet };