@sigma-auth/cli 0.0.2 → 0.0.4

package/README.md

@@ -4,6 +4,8 @@ Headless CLI for [Sigma Auth](https://auth.sigmaidentity.com). Create a Bitcoin
 
 The server never sees private keys. Identity is a BAP member key, not an API key.
 
+`identity create` mints a Type42 `rootPk` directly. Existing Type42 `.bep` files keep working; no re-key.
+
 ```bash
 bunx @sigma-auth/cli --help
 ```
@@ -26,14 +28,65 @@ bunx @sigma-auth/cli identity create \
 
 | Command | Job |
 | --- | --- |
-| `sigma identity create` | Create Type42 master + first BAP, encrypt `.bep` |
+| `sigma identity create` | Mint a Type42 `rootPk` + first BAP, encrypt `.bep` |
 | `sigma identity info` | Public fields from a local backup |
 | `sigma backup encrypt` | JSON → `.bep` |
 | `sigma auth sign-in` | Member-key Bitcoin-Auth; cookie jar; register BAP |
 | `sigma backup push` | POST ciphertext only |
 | `sigma oauth register` | Session `/api/oauth-clients` or RFC 7591 DCR |
 | `sigma doctor` | Env, files, RFC 8414, session |
+| `sigma diagnose bap` | Public BAP profile; optional `--pubkey` registered-list check |
+| `sigma diagnose identities` | `GET /api/user/bap-ids` (`--pubkey` or session cookie) |
+| `sigma diagnose last-oauth` | Last selected BAP for `--pubkey` `--client-id` |
+| `sigma diagnose client` | Public OAuth client metadata |
 
 Password sources (exactly one): `--password-file`, `--password-stdin`, or `SIGMA_BACKUP_PASSWORD`. `--password` on argv is rejected.
 
+## Diagnose (no private keys)
+
+Public HTTP lookups against `https://auth.sigmaidentity.com`. Use these when a Sigma login shows the wrong faucet, a profile 404s, or last-selected identity looks stuck.
+
+```bash
+bunx @sigma-auth/cli diagnose bap --bap-id 3QpdyNb9HScYmWEyfqtRQbKzwyf --json
+bunx @sigma-auth/cli diagnose bap --bap-id 33mGVYzkGE9XMbu346XkUaMHyzwV --pubkey 03a42932… --json
+bunx @sigma-auth/cli diagnose identities --pubkey 03a42932… --json
+bunx @sigma-auth/cli diagnose last-oauth --pubkey 03a42932… --client-id droplit --json
+```
+
+`diagnose bap` treats a profile 404 as a successful diagnosis (`found: false`), not a command failure.
+
 Contract: `docs/specs/sigma-cli-v1.md` in [sigma-auth](https://github.com/b-open-io/sigma-auth).
+
+
+### Delegated agent authorization
+
+```sh
+sigma agent capabilities --json
+sigma agent connect --name "My agent" --capability profile.read --capability identity.read --json
+# Complete the returned verificationUri in your browser, using userCode when provided.
+# Save the returned agentId; connect does not wait for approval.
+sigma agent status --agent-id AGENT_ID --json
+sigma agent execute --agent-id AGENT_ID --capability profile.read --args-file arguments.json --json
+sigma agent disconnect --agent-id AGENT_ID --json
+```
+
+Use capability names from discovery and a JSON object in `arguments.json`.
+Repeat `status` after its `nextPollAt` (Unix milliseconds). It makes at most one
+status request, preserves server throttling across restarts, and reports terminal
+approval states. Reuse the agent ID instead of repeating registration. After a
+failed connect request, do not blindly reconnect: the registration may have
+reached the provider. Retain `SIGMA_HOME` for diagnosis.
+
+This uses Better Auth Agent Auth via `@auth/agent` 0.6.2, with delegated human
+approval. It is not WorkOS auth.md, RFC 8628 device authorization, or a BRC100
+wallet signer. The CLI never submits human approval or uses browser session
+cookies. Execution requires an active capability explicitly requested at connect.
+Agent and host keys live separately under `SIGMA_HOME/agent-auth`, with private
+atomic files (0600) and directory (0700). Revocation failures retain credentials
+for a retry. Keep this directory private and use one CLI process per SIGMA_HOME
+at a time; the SDK's index updates are not a multi-process transaction.
+
+`--base-url` or `SIGMA_AUTH_URL` selects the provider. HTTPS is required except
+explicit localhost HTTP testing; discovery and execution URLs must share the
+provider origin. Redirects are rejected. Approval URL query strings and complete
+claim URLs are omitted from output because they may contain bearer artifacts.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sigma-auth/cli",
-	"version": "0.0.2",
-	"description": "Headless Sigma Auth CLI: create a BAP identity locally, sign in with Bitcoin-Auth, push encrypted backups, register OAuth clients",
+	"version": "0.0.4",
+	"description": "Headless Sigma Auth CLI: create a BAP identity locally, sign in with Bitcoin-Auth, diagnose public identities, push encrypted backups, register OAuth clients",
 	"type": "module",
 	"bin": {
 		"sigma": "./src/index.ts"
@@ -35,6 +35,7 @@
 		"bun": ">=1.1.0"
 	},
 	"dependencies": {
+		"@auth/agent": "0.6.2",
 		"@bsv/sdk": "^2.1.6",
 		"bitcoin-auth": "^0.0.8",
 		"bitcoin-backup": "^0.0.13",

package/src/agent-store.ts

@@ -0,0 +1,57 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+	chmodSync,
+	closeSync,
+	fsyncSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { KVStorage } from "@auth/agent";
+import { ensureDir } from "./fsutil.ts";
+
+export function agentStore(home: string) {
+	const directory = join(home, "agent-auth");
+	ensureDir(directory);
+	const path = (key: string) =>
+		join(directory, `${createHash("sha256").update(key).digest("hex")}.json`);
+	const kv = {
+		async get(key: string): Promise<string | null> {
+			try {
+				return readFileSync(path(key), "utf8");
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+				throw error;
+			}
+		},
+		async set(key: string, value: string) {
+			const target = path(key);
+			const temporary = `${target}.${randomUUID()}.tmp`;
+			const fd = openSync(temporary, "wx", 0o600);
+			try {
+				writeFileSync(fd, value);
+				fsyncSync(fd);
+			} finally {
+				closeSync(fd);
+			}
+			try {
+				renameSync(temporary, target);
+				chmodSync(target, 0o600);
+			} finally {
+				rmSync(temporary, { force: true });
+			}
+		},
+		async del(key: string) {
+			try {
+				unlinkSync(path(key));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			}
+		},
+	};
+	return { kv, storage: new KVStorage(kv) };
+}

package/src/agent.ts

@@ -0,0 +1,366 @@
+import {
+	AgentAuthClient,
+	type ApprovalInfo,
+	type ProviderConfig,
+} from "@auth/agent";
+import { agentStore } from "./agent-store.ts";
+import { flag, flagList, type ParsedArgs } from "./args.ts";
+import type { RuntimeConfig } from "./config.ts";
+import { CliError, usage } from "./error.ts";
+import { readText } from "./fsutil.ts";
+import { printHuman, printJson } from "./output.ts";
+
+type State = {
+	agentId: string;
+	provider: string;
+	requestedCapabilities: string[];
+	status: string;
+	verificationUri?: string;
+	userCode?: string;
+	expiresAt?: number;
+	nextPollAt: number;
+	intervalMs: number;
+};
+const pending = Symbol("approval saved");
+const terminal = new Set(["denied", "rejected", "revoked", "expired"]);
+function fail(message: string): never {
+	throw new CliError(1, "agent", message);
+}
+
+export function agentUrl(value: string, origin?: string): URL {
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		return fail("Invalid agent provider URL");
+	}
+	const localhost = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+	if (
+		(url.protocol !== "https:" && !(url.protocol === "http:" && localhost)) ||
+		url.username ||
+		url.password ||
+		url.hash ||
+		(origin && url.origin !== origin)
+	) {
+		fail(
+			"Agent URLs must use HTTPS (HTTP localhost is allowed), have no credentials, and share the provider origin",
+		);
+	}
+	return url;
+}
+
+export function validateAgentProvider(
+	config: ProviderConfig,
+	origin: string,
+): void {
+	agentUrl(config.issuer, origin);
+	if (!config.endpoints || typeof config.endpoints !== "object")
+		fail("Invalid agent discovery endpoints");
+	for (const endpoint of Object.values(config.endpoints)) {
+		if (typeof endpoint !== "string") fail("Invalid agent discovery endpoint");
+		agentUrl(
+			new URL(endpoint, `${config.issuer.replace(/\/+$/, "")}/`).href,
+			origin,
+		);
+	}
+	for (const location of [
+		config.default_location,
+		config.jwks_uri,
+		...(config.capabilities ?? []).map((cap) => cap.location),
+	]) {
+		if (location) agentUrl(location, origin);
+	}
+}
+
+function publicApproval(info: ApprovalInfo, origin: string) {
+	const uri = info.verification_uri
+		? agentUrl(info.verification_uri, origin)
+		: undefined;
+	// Complete URIs and query strings can contain bearer claim artifacts.
+	if (uri) uri.search = "";
+	return { verificationUri: uri?.href, userCode: info.user_code };
+}
+
+function redact(value: unknown, secrets: string[]): unknown {
+	if (typeof value === "string") {
+		let text = value.replace(
+			/Bearer\s+\S+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/gi,
+			"[redacted]",
+		);
+		for (const secret of secrets)
+			if (secret) text = text.replaceAll(secret, "[redacted]");
+		return text;
+	}
+	if (Array.isArray(value)) return value.map((item) => redact(item, secrets));
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value)
+				.filter(
+					([key]) =>
+						!/^(d|privateKey|private_key|agentKeypair|keypair|authorization|headers|cookie|cookies|.*token.*|.*secret.*|.*password.*|verification_uri_complete)$/i.test(
+							key,
+						),
+				)
+				.map(([key, item]) => [key, redact(item, secrets)]),
+		);
+	}
+	return value;
+}
+
+export async function agentCommand(
+	args: ParsedArgs,
+	cfg: RuntimeConfig,
+): Promise<number> {
+	const command = args.positional[1];
+	if (
+		!["capabilities", "connect", "status", "execute", "disconnect"].includes(
+			command ?? "",
+		)
+	)
+		usage(
+			"Expected agent capabilities, connect, status, execute, or disconnect",
+		);
+	const required = (name: string) =>
+		flag(args, name)?.trim() || usage(`--${name} is required`);
+	const requested = [...new Set(flagList(args, "capability"))];
+	const name = command === "connect" ? required("name") : undefined;
+	if (
+		command === "connect" &&
+		(!requested.length || requested.some((cap) => !cap.trim()))
+	)
+		usage("At least one --capability is required");
+	const agentId = ["status", "execute", "disconnect"].includes(command ?? "")
+		? required("agent-id")
+		: undefined;
+	const capability = command === "execute" ? required("capability") : undefined;
+	if (command === "execute" && requested.length !== 1)
+		usage("Execute accepts exactly one --capability");
+	let argumentsValue: Record<string, unknown> | undefined;
+	if (command === "execute") {
+		try {
+			argumentsValue = JSON.parse(readText(required("args-file")));
+		} catch {
+			usage("--args-file must contain a JSON object");
+		}
+		if (
+			!argumentsValue ||
+			Array.isArray(argumentsValue) ||
+			typeof argumentsValue !== "object"
+		)
+			usage("--args-file must contain a JSON object");
+	}
+	const origin = agentUrl(cfg.baseUrl).origin;
+	const { kv, storage } = agentStore(cfg.home);
+	let state: State | undefined;
+	let revokeConfirmed = false;
+	const stateKey = (id: string) => `cli:state:${id}`;
+	const save = async () => {
+		if (state) await kv.set(stateKey(state.agentId), JSON.stringify(state));
+	};
+	if (agentId) {
+		const raw = await kv.get(stateKey(agentId));
+		if (!raw) fail("No saved agent connection; connect first");
+		state = JSON.parse(raw) as State;
+		agentUrl(state.provider, origin);
+	}
+	const originalDelete = storage.deleteAgentConnection.bind(storage);
+	storage.deleteAgentConnection = async (id) => {
+		// SDK 0.6.2 ignores revoke HTTP/network failures. Keep credentials for retry.
+		if (command === "disconnect" && !revokeConfirmed)
+			fail(
+				"Revocation was not confirmed; local credentials retained. Retry disconnect",
+			);
+		await originalDelete(id);
+	};
+	const transport = (async (
+		input: string | URL | Request,
+		init?: RequestInit,
+	) => {
+		const url = agentUrl(
+			typeof input === "string"
+				? input
+				: input instanceof URL
+					? input.href
+					: input.url,
+			origin,
+		);
+		const response = await fetch(input, {
+			...init,
+			redirect: "error",
+			credentials: "omit",
+			signal: AbortSignal.timeout(cfg.timeoutMs),
+		});
+		if (response.url) agentUrl(response.url, origin);
+		if (command === "disconnect") revokeConfirmed = response.ok;
+		if (state && command === "status") {
+			const retry = response.headers.get("retry-after");
+			const seconds = retry === null ? Number.NaN : Number(retry);
+			const until = Number.isFinite(seconds)
+				? Date.now() + Math.max(0, seconds) * 1000
+				: Date.parse(retry ?? "");
+			if (response.status === 429)
+				state.intervalMs = Math.max(state.intervalMs * 2, 5000);
+			state.nextPollAt = Math.max(
+				state.nextPollAt,
+				Date.now() + state.intervalMs,
+				Number.isFinite(until) ? until : 0,
+			);
+			await save();
+			if (response.status === 429)
+				throw new CliError(
+					5,
+					"rate_limit",
+					"Agent status is throttled; retry after nextPollAt",
+					429,
+				);
+		}
+		if (response.ok && url.pathname.endsWith("agent-configuration"))
+			validateAgentProvider(
+				(await response.clone().json()) as ProviderConfig,
+				origin,
+			);
+		return response;
+	}) as typeof fetch;
+	// URL-only mode disables the SDK default public directory. Discovery stays on this provider.
+	const client = new AgentAuthClient({
+		storage,
+		urls: [cfg.baseUrl],
+		fetch: transport,
+		onApprovalRequired: async (info) => {
+			if (!state) fail("Registration state was not saved");
+			Object.assign(state, publicApproval(info, origin), {
+				status: "pending",
+				expiresAt: Date.now() + Math.max(0, info.expires_in) * 1000,
+				intervalMs: Math.max(1, info.interval || 5) * 1000,
+				nextPollAt: Date.now() + Math.max(1, info.interval || 5) * 1000,
+			});
+			await save();
+			throw pending;
+		},
+	});
+	// Hook SDK persistence, which occurs before onApprovalRequired (no polling or duplicate registration).
+	const originalSet = storage.setAgentConnection.bind(storage);
+	storage.setAgentConnection = async (id, connection) => {
+		await originalSet(id, connection);
+		if (command === "connect") {
+			state = {
+				agentId: id,
+				provider: connection.issuer,
+				requestedCapabilities: requested,
+				status: "pending",
+				nextPollAt: Date.now() + 5000,
+				intervalMs: 5000,
+			};
+			await save();
+		}
+	};
+	const output = async (data: unknown) => {
+		const host = await storage.getHostIdentity();
+		const connection = state
+			? await storage.getAgentConnection(state.agentId)
+			: null;
+		const secrets = [
+			host?.keypair.privateKey.d,
+			connection?.agentKeypair.privateKey.d,
+		].filter((value): value is string => typeof value === "string");
+		const safe = redact(data, secrets);
+		if (cfg.json) printJson(true, safe);
+		else printHuman(cfg, JSON.stringify(safe, null, 2));
+		return 0;
+	};
+	try {
+		const provider = agentId
+			? await storage.getProviderConfig(state!.provider)
+			: await client.discoverProvider(cfg.baseUrl);
+		if (!provider)
+			fail(
+				"Saved provider configuration is missing; connection cannot be used",
+			);
+		validateAgentProvider(provider, origin);
+		if (command === "capabilities")
+			return output(
+				await client.listCapabilities({ provider: provider.issuer }),
+			);
+		if (command === "connect") {
+			if (!provider.modes.includes("delegated"))
+				fail("Provider does not support delegated approval");
+			try {
+				const result = await client.connectAgent({
+					provider: provider.issuer,
+					name,
+					capabilities: requested,
+					mode: "delegated",
+				});
+				state!.status = result.status;
+				await save();
+			} catch (error) {
+				if (error !== pending) throw error;
+			}
+			return output(state);
+		}
+		if (command === "status") {
+			// Approval may have completed before expiresAt while this CLI was stopped.
+			// Only the provider can declare the registration expired.
+			if (!terminal.has(state!.status) && Date.now() >= state!.nextPollAt) {
+				state!.nextPollAt = Date.now() + state!.intervalMs;
+				await save();
+				try {
+					const result = await client.agentStatus(agentId!);
+					state!.status = result.status;
+				} catch (error) {
+					if (!(error instanceof CliError && error.status === 429)) throw error;
+				}
+			}
+			await save();
+			const connection = await storage.getAgentConnection(agentId!);
+			return output({
+				...state,
+				grants: connection?.capabilityGrants.map(
+					({ capability, status, constraints }) => ({
+						capability,
+						status,
+						constraints,
+					}),
+				),
+				action: terminal.has(state!.status)
+					? "Connect again to request new approval"
+					: state!.status === "pending"
+						? "Complete approval in your browser, then run status after nextPollAt"
+						: undefined,
+			});
+		}
+		if (command === "disconnect") {
+			await client.disconnectAgent(agentId!);
+			state!.status = "revoked";
+			await save();
+			return output({ agentId, status: "revoked" });
+		}
+		if (state!.status !== "active")
+			fail("Agent is not active; run status after approval");
+		const connection = await storage.getAgentConnection(agentId!);
+		if (
+			!state!.requestedCapabilities.includes(capability!) ||
+			!connection?.capabilityGrants.some(
+				(grant) => grant.capability === capability && grant.status === "active",
+			)
+		)
+			fail("Capability is not an active requested grant");
+		return output(
+			await client.executeCapability({
+				agentId: agentId!,
+				capability: capability!,
+				arguments: argumentsValue,
+			}),
+		);
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		// SDK errors may contain untrusted server response text, URLs, and headers.
+		throw new CliError(
+			1,
+			"agent",
+			"Agent request failed; credentials were retained. Check provider availability and run status before retrying",
+		);
+	} finally {
+		client.destroy();
+	}
+}

package/src/args.ts

@@ -7,12 +7,11 @@ const BOOL_FLAGS = new Set([
 	"help",
 	"signin",
 	"push-backup",
-	"show-mnemonic",
 	"public",
 	"password-stdin",
 ]);
 
-const REPEATABLE = new Set(["redirect-uri", "grant-type"]);
+const REPEATABLE = new Set(["redirect-uri", "grant-type", "capability"]);
 
 export type ParsedArgs = {
 	positional: string[];
@@ -42,7 +41,9 @@ export function parseArgs(argv: string[]): ParsedArgs {
 			break;
 		}
 		if (token === "--password" || token.startsWith("--password=")) {
-			usage("--password is not allowed; use --password-file, --password-stdin, or SIGMA_BACKUP_PASSWORD");
+			usage(
+				"--password is not allowed; use --password-file, --password-stdin, or SIGMA_BACKUP_PASSWORD",
+			);
 		}
 		if (token === "-h") {
 			flags.help = ["true"];

package/src/commands.ts

@@ -20,14 +20,18 @@ import {
 	publicFields,
 	rootPubkey,
 } from "./identity.ts";
-import { printHuman, printJson, printWarn, type OutputMode } from "./output.ts";
+import { type OutputMode, printHuman, printJson, printWarn } from "./output.ts";
 import { resolvePassword } from "./password.ts";
 
 function mode(cfg: RuntimeConfig): OutputMode {
 	return { json: cfg.json, quiet: cfg.quiet };
 }
 
-function succeed(cfg: RuntimeConfig, data: Record<string, unknown>, human: string): number {
+function succeed(
+	cfg: RuntimeConfig,
+	data: Record<string, unknown>,
+	human: string,
+): number {
 	if (cfg.json) {
 		printJson(true, data);
 	} else {
@@ -39,7 +43,7 @@ function succeed(cfg: RuntimeConfig, data: Record<string, unknown>, human: strin
 async function loadBackup(
 	args: ParsedArgs,
 	cfg: RuntimeConfig,
-	password: string
+	password: string,
 ): Promise<{ path: string; backup: BapMasterBackup; ciphertext: string }> {
 	const path = backupPath(args, cfg.home);
 	const ciphertext = readText(path);
@@ -49,7 +53,7 @@ async function loadBackup(
 
 export async function identityCreate(
 	args: ParsedArgs,
-	cfg: RuntimeConfig
+	cfg: RuntimeConfig,
 ): Promise<number> {
 	const label = flag(args, "label");
 	if (!label) {
@@ -63,13 +67,6 @@ export async function identityCreate(
 	const encrypted = await encryptMaster(created.backup, password);
 	const out = flag(args, "out") ?? `${cfg.home}/identity.bep`;
 	writeSecretFile(out, encrypted, cfg.force);
-	if (boolFlag(args, "show-mnemonic")) {
-		process.stderr.write(`${created.mnemonic}\n`);
-	}
-	const mnemonicFile = flag(args, "mnemonic-file");
-	if (mnemonicFile) {
-		writeSecretFile(mnemonicFile, `${created.mnemonic}\n`, cfg.force);
-	}
 
 	let userId: string | undefined;
 	if (boolFlag(args, "signin") || boolFlag(args, "push-backup")) {
@@ -98,13 +95,13 @@ export async function identityCreate(
 			backupPath: out,
 			userId,
 		},
-		`created ${created.bapId}\n${out}`
+		`created ${created.bapId}\n${out}`,
 	);
 }
 
 export async function identityInfo(
 	args: ParsedArgs,
-	cfg: RuntimeConfig
+	cfg: RuntimeConfig,
 ): Promise<number> {
 	const password = await resolvePassword(args, true);
 	if (!password) {
@@ -115,13 +112,13 @@ export async function identityInfo(
 	return succeed(
 		cfg,
 		fields,
-		`${fields.bapId}\n${fields.pubkey}\n${fields.address}`
+		`${fields.bapId}\n${fields.pubkey}\n${fields.address}`,
 	);
 }
 
 export async function backupEncrypt(
 	args: ParsedArgs,
-	cfg: RuntimeConfig
+	cfg: RuntimeConfig,
 ): Promise<number> {
 	const input = flag(args, "in");
 	const out = flag(args, "out");
@@ -148,18 +145,14 @@ export async function backupEncrypt(
 	}
 	const encrypted = await encryptMaster(parsed, password);
 	writeSecretFile(out, encrypted, cfg.force);
-	return succeed(
-		cfg,
-		{ backupPath: out, warning },
-		out
-	);
+	return succeed(cfg, { backupPath: out, warning }, out);
 }
 
 export async function authSignIn(
 	args: ParsedArgs,
 	cfg: RuntimeConfig,
 	emit = true,
-	resolvedPassword?: string
+	resolvedPassword?: string,
 ): Promise<number> {
 	const password = resolvedPassword ?? (await resolvePassword(args, true));
 	if (!password) {
@@ -190,14 +183,13 @@ export async function authSignIn(
 			signed.status,
 			signed.json,
 			signed.text,
-			signed.headers
+			signed.headers,
 		);
 	}
 	const payload = signed.json as {
 		user?: { id?: string; pubkey?: string };
 	};
-	const name =
-		("label" in backup && backup.label) || "Identity 1";
+	const name = ("label" in backup && backup.label) || "Identity 1";
 	const registered = await requestJson(client, "POST", "/api/user/bap-ids", {
 		body: {
 			bapId: member.bapId,
@@ -218,7 +210,7 @@ export async function authSignIn(
 			registered.status,
 			registered.json,
 			registered.text,
-			registered.headers
+			registered.headers,
 		);
 	}
 	if (!emit) {
@@ -232,14 +224,14 @@ export async function authSignIn(
 			bapId: member.bapId,
 			cookieJar: cfg.cookieJar,
 		},
-		`signed in as ${member.bapId}`
+		`signed in as ${member.bapId}`,
 	);
 }
 
 export async function backupPush(
 	args: ParsedArgs,
 	cfg: RuntimeConfig,
-	emit = true
+	emit = true,
 ): Promise<number> {
 	const path = backupPath(args, cfg.home);
 	const ciphertext = readText(path).replace(/\n+$/, "");
@@ -250,7 +242,13 @@ export async function backupPush(
 		withCookies: true,
 	});
 	if (result.status >= 400) {
-		throwHttp("/api/backup", result.status, result.json, result.text, result.headers);
+		throwHttp(
+			"/api/backup",
+			result.status,
+			result.json,
+			result.text,
+			result.headers,
+		);
 	}
 	const payload = result.json as { bapId?: string; message?: string };
 	if (!emit) {
@@ -259,13 +257,13 @@ export async function backupPush(
 	return succeed(
 		cfg,
 		{ bapId: payload.bapId, message: payload.message },
-		payload.message ?? "backup stored"
+		payload.message ?? "backup stored",
 	);
 }
 
 export async function oauthRegister(
 	args: ParsedArgs,
-	cfg: RuntimeConfig
+	cfg: RuntimeConfig,
 ): Promise<number> {
 	const name = flag(args, "name");
 	const redirectUris = flagList(args, "redirect-uri");
@@ -281,7 +279,9 @@ export async function oauthRegister(
 		const ownerBapId = flag(args, "owner-bap-id");
 		const clientId = flag(args, "client-id");
 		if (!ownerBapId || !clientId) {
-			usage("--owner-bap-id and --client-id are required with --signing-pubkey");
+			usage(
+				"--owner-bap-id and --client-id are required with --signing-pubkey",
+			);
 		}
 		const result = await requestJson(client, "POST", "/api/oauth-clients", {
 			body: {
@@ -299,11 +299,15 @@ export async function oauthRegister(
 				result.status,
 				result.json,
 				result.text,
-				result.headers
+				result.headers,
 			);
 		}
 		const payload = result.json as {
-			client?: { clientId?: string; accountPubkey?: string; ownerBapId?: string };
+			client?: {
+				clientId?: string;
+				accountPubkey?: string;
+				ownerBapId?: string;
+			};
 		};
 		return succeed(
 			cfg,
@@ -315,7 +319,7 @@ export async function oauthRegister(
 				public: true,
 				path: "session",
 			},
-			payload.client?.clientId ?? clientId
+			payload.client?.clientId ?? clientId,
 		);
 	}
 
@@ -335,7 +339,7 @@ export async function oauthRegister(
 				response_types: ["code"],
 				token_endpoint_auth_method: "none",
 			},
-		}
+		},
 	);
 	if (result.status >= 400) {
 		throwHttp(
@@ -343,7 +347,7 @@ export async function oauthRegister(
 			result.status,
 			result.json,
 			result.text,
-			result.headers
+			result.headers,
 		);
 	}
 	const payload = result.json as {
@@ -352,7 +356,7 @@ export async function oauthRegister(
 	};
 	printWarn(
 		mode(cfg),
-		"DCR client has no memberPubkey; POST /api/auth/oauth2/token will reject this client. Register with --signing-pubkey after auth sign-in to store the member key."
+		"DCR client has no memberPubkey; POST /api/auth/oauth2/token will reject this client. Register with --signing-pubkey after auth sign-in to store the member key.",
 	);
 	return succeed(
 		cfg,
@@ -362,7 +366,7 @@ export async function oauthRegister(
 			path: "dcr",
 			client_secret: payload.client_secret,
 		},
-		payload.client_id ?? "registered"
+		payload.client_id ?? "registered",
 	);
 }
 
@@ -374,7 +378,10 @@ type Check = {
 	skipped?: boolean;
 };
 
-export async function doctor(args: ParsedArgs, cfg: RuntimeConfig): Promise<number> {
+export async function doctor(
+	args: ParsedArgs,
+	cfg: RuntimeConfig,
+): Promise<number> {
 	const checks: Check[] = [];
 	const add = (check: Check) => {
 		checks.push(check);
@@ -461,7 +468,7 @@ export async function doctor(args: ParsedArgs, cfg: RuntimeConfig): Promise<numb
 		const meta = await requestJson(
 			client,
 			"GET",
-			"/.well-known/oauth-authorization-server"
+			"/.well-known/oauth-authorization-server",
 		);
 		const body = meta.json as {
 			issuer?: string;
@@ -544,7 +551,7 @@ export async function doctor(args: ParsedArgs, cfg: RuntimeConfig): Promise<numb
 		const sessionNameOk = names.some(
 			(name) =>
 				name === "better-auth.session_token" ||
-				name === "__Secure-better-auth.session_token"
+				name === "__Secure-better-auth.session_token",
 		);
 		add({
 			id: "session.cookie",
@@ -553,9 +560,14 @@ export async function doctor(args: ParsedArgs, cfg: RuntimeConfig): Promise<numb
 			detail: names.join(",") || "no cookies",
 		});
 		try {
-			const session = await requestJson(client, "GET", "/api/auth/get-session", {
-				withCookies: true,
-			});
+			const session = await requestJson(
+				client,
+				"GET",
+				"/api/auth/get-session",
+				{
+					withCookies: true,
+				},
+			);
 			const body = session.json as { user?: { id?: string } } | null;
 			add({
 				id: "session.get",
@@ -573,7 +585,9 @@ export async function doctor(args: ParsedArgs, cfg: RuntimeConfig): Promise<numb
 		}
 	}
 
-	const failed = checks.some((check) => check.required && !check.ok && !check.skipped);
+	const failed = checks.some(
+		(check) => check.required && !check.ok && !check.skipped,
+	);
 	if (cfg.json) {
 		printJson(!failed, { baseUrl: cfg.baseUrl, checks });
 	}
@@ -586,6 +600,11 @@ Create a Bitcoin (BAP) identity key locally, sign in with Bitcoin-Auth, push
 encrypted bitcoin-backup ciphertext, and register OAuth clients.
 
 Commands:
+  agent capabilities [--json]
+  agent connect --name NAME --capability NAME [--capability NAME] [--json]
+  agent status --agent-id ID [--json]
+  agent execute --agent-id ID --capability NAME --args-file FILE [--json]
+  agent disconnect --agent-id ID [--json]
   identity create    Create Type42 master + first BAP, encrypt, write .bep
   identity info      Decrypt local backup; print public fields
   backup encrypt     Encrypt a BapMasterBackup JSON file to .bep
@@ -593,6 +612,10 @@ Commands:
   backup push        POST ciphertext with session; never decrypt
   oauth register     Register an OAuth client (session path or DCR)
   doctor             Non-interactive health check
+  diagnose bap       Public BAP profile (+ --pubkey registered-list check)
+  diagnose identities  GET /api/user/bap-ids [--pubkey]
+  diagnose last-oauth  Last selected BAP for --pubkey --client-id
+  diagnose client    Public OAuth client metadata --client-id
 
 Global flags:
   --base-url <url>   SIGMA_AUTH_URL (default https://auth.sigmaidentity.com)

package/src/diagnose.ts

@@ -0,0 +1,191 @@
+import type { ParsedArgs } from "./args.ts";
+import { flag } from "./args.ts";
+import type { RuntimeConfig } from "./config.ts";
+import { usage } from "./error.ts";
+import { createHttp, requestJson, throwHttp } from "./http.ts";
+import { printHuman, printJson, type OutputMode } from "./output.ts";
+
+function mode(cfg: RuntimeConfig): OutputMode {
+	return { json: cfg.json, quiet: cfg.quiet };
+}
+
+function succeed(cfg: RuntimeConfig, data: Record<string, unknown>, human: string): number {
+	if (cfg.json) {
+		printJson(true, data);
+	} else {
+		printHuman(mode(cfg), human);
+	}
+	return 0;
+}
+
+function record(json: unknown): Record<string, unknown> {
+	return json && typeof json === "object" ? (json as Record<string, unknown>) : {};
+}
+
+export async function diagnoseBap(args: ParsedArgs, cfg: RuntimeConfig): Promise<number> {
+	const bapId = flag(args, "bap-id");
+	if (!bapId) {
+		usage("--bap-id is required");
+	}
+	const pubkey = flag(args, "pubkey");
+	const client = createHttp(cfg);
+	const profileRes = await requestJson(
+		client,
+		"GET",
+		`/api/bap/profile?bapId=${encodeURIComponent(bapId)}`
+	);
+	if (profileRes.status >= 500) {
+		throwHttp(
+			"/api/bap/profile",
+			profileRes.status,
+			profileRes.json,
+			profileRes.text,
+			profileRes.headers
+		);
+	}
+	const found = profileRes.status === 200 && record(profileRes.json).status === "OK";
+	const profile = found ? record(profileRes.json).result ?? record(profileRes.json) : null;
+
+	let registeredToPubkey: boolean | null = null;
+	let identities: unknown[] | undefined;
+	if (pubkey) {
+		const listRes = await requestJson(
+			client,
+			"GET",
+			`/api/user/bap-ids?pubkey=${encodeURIComponent(pubkey)}`
+		);
+		if (listRes.status >= 400) {
+			throwHttp(
+				"/api/user/bap-ids",
+				listRes.status,
+				listRes.json,
+				listRes.text,
+				listRes.headers
+			);
+		}
+		const bapIds = record(listRes.json).bapIds;
+		identities = Array.isArray(bapIds) ? bapIds : [];
+		registeredToPubkey = identities.some((row) => {
+			const item = record(row);
+			return item.identity_key === bapId || item.id === bapId || item.bapId === bapId;
+		});
+	}
+
+	let hint: string;
+	if (registeredToPubkey === true && found) {
+		hint = "registered to this pubkey and has a published profile";
+	} else if (registeredToPubkey === true && !found) {
+		hint = "registered to this pubkey but no published BAP profile";
+	} else if (registeredToPubkey === false && found) {
+		hint = "published profile exists but this BAP is not in this pubkey's registered list";
+	} else if (registeredToPubkey === false && !found) {
+		hint = "not in this pubkey's registered list and no published BAP profile (typical leftover HD identity)";
+	} else if (found) {
+		hint = "published BAP profile found";
+	} else {
+		hint = "no published BAP profile (404). Pass --pubkey to also check GET /api/user/bap-ids";
+	}
+
+	const data: Record<string, unknown> = {
+		bapId,
+		found,
+		profile,
+		hint,
+	};
+	if (pubkey) {
+		data.pubkey = pubkey;
+		data.registeredToPubkey = registeredToPubkey;
+		data.registeredCount = identities?.length ?? 0;
+	}
+
+	const lines = [
+		`bapId  ${bapId}`,
+		`found  ${found}`,
+		pubkey ? `registeredToPubkey  ${registeredToPubkey}` : null,
+		hint,
+	].filter((line): line is string => line !== null);
+	return succeed(cfg, data, lines.join("\n"));
+}
+
+export async function diagnoseIdentities(
+	args: ParsedArgs,
+	cfg: RuntimeConfig
+): Promise<number> {
+	const pubkey = flag(args, "pubkey");
+	const client = createHttp(cfg);
+	const path = pubkey
+		? `/api/user/bap-ids?pubkey=${encodeURIComponent(pubkey)}`
+		: "/api/user/bap-ids";
+	const result = await requestJson(client, "GET", path, {
+		withCookies: !pubkey,
+	});
+	if (result.status >= 400) {
+		throwHttp(path, result.status, result.json, result.text, result.headers);
+	}
+	const bapIds = record(result.json).bapIds;
+	const list = Array.isArray(bapIds) ? bapIds : [];
+	const names = list
+		.map((row) => {
+			const item = record(row);
+			const id = String(item.identity_key ?? item.id ?? "");
+			const name = typeof item.name === "string" ? item.name : "";
+			const primary = item.is_primary === true ? " (primary)" : "";
+			return `${id}${name ? `  ${name}` : ""}${primary}`;
+		})
+		.join("\n");
+	return succeed(
+		cfg,
+		{ pubkey: pubkey ?? null, count: list.length, bapIds: list },
+		names || "(none)"
+	);
+}
+
+export async function diagnoseLastOauth(
+	args: ParsedArgs,
+	cfg: RuntimeConfig
+): Promise<number> {
+	const pubkey = flag(args, "pubkey");
+	const clientId = flag(args, "client-id");
+	if (!pubkey || !clientId) {
+		usage("--pubkey and --client-id are required");
+	}
+	const client = createHttp(cfg);
+	const path = `/api/user/last-oauth-identity?pubkey=${encodeURIComponent(pubkey)}&clientId=${encodeURIComponent(clientId)}`;
+	const result = await requestJson(client, "GET", path);
+	if (result.status >= 400) {
+		throwHttp(path, result.status, result.json, result.text, result.headers);
+	}
+	const lastSelectedBapId = record(result.json).lastSelectedBapId ?? null;
+	return succeed(
+		cfg,
+		{ pubkey, clientId, lastSelectedBapId },
+		typeof lastSelectedBapId === "string" ? lastSelectedBapId : "(none)"
+	);
+}
+
+export async function diagnoseClient(
+	args: ParsedArgs,
+	cfg: RuntimeConfig
+): Promise<number> {
+	const clientId = flag(args, "client-id");
+	if (!clientId) {
+		usage("--client-id is required");
+	}
+	const client = createHttp(cfg);
+	const path = `/api/oauth-clients?clientId=${encodeURIComponent(clientId)}`;
+	const result = await requestJson(client, "GET", path);
+	if (result.status >= 400) {
+		throwHttp(path, result.status, result.json, result.text, result.headers);
+	}
+	const payload = record(result.json);
+	const clients = Array.isArray(payload.clients) ? payload.clients : [];
+	const first = clients[0] ? record(clients[0]) : payload;
+	if (!first.clientId && !first.name) {
+		return succeed(cfg, { clientId, client: null }, "(not found)");
+	}
+	return succeed(
+		cfg,
+		{ clientId, client: first },
+		`${String(first.clientId ?? clientId)}  ${String(first.name ?? "")}`
+	);
+}

package/src/identity.ts

@@ -1,4 +1,4 @@
-import { HD, Mnemonic, PrivateKey, Utils } from "@bsv/sdk";
+import { PrivateKey, Utils } from "@bsv/sdk";
 import {
 	type BapMasterBackup,
 	decryptBackup,
@@ -25,19 +25,12 @@ export type PublicIdentity = {
 };
 
 export function createMasterBackup(label: string): {
-	mnemonic: string;
 	backup: BapMasterBackup;
 	bapId: string;
 	pubkey: string;
 	address: string;
 } {
-	const mnemonic = Mnemonic.fromRandom();
-	const hdKey = HD.fromSeed(mnemonic.toSeed());
-	const rootKey = hdKey.derive("m/0'/0");
-	const rootPk = rootKey.privKey?.toWif();
-	if (!rootPk) {
-		cryptoFail("Failed to derive wallet root private key");
-	}
+	const rootPk = PrivateKey.fromRandom().toWif();
 	const bap = new BAP({ rootPk });
 	const first = bap.newId();
 	const backup: BapMasterBackup = {
@@ -48,7 +41,6 @@ export function createMasterBackup(label: string): {
 	};
 	const member = first.getAccountKey();
 	return {
-		mnemonic: mnemonic.toString(),
 		backup,
 		bapId: first.bapId,
 		pubkey: member.toPublicKey().toString(),

package/src/index.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 
+import { agentCommand } from "./agent.ts";
 import { boolFlag, parseArgs } from "./args.ts";
 import {
 	authSignIn,
@@ -12,6 +13,12 @@ import {
 	oauthRegister,
 } from "./commands.ts";
 import { loadConfig } from "./config.ts";
+import {
+	diagnoseBap,
+	diagnoseClient,
+	diagnoseIdentities,
+	diagnoseLastOauth,
+} from "./diagnose.ts";
 import { usage } from "./error.ts";
 import { reportError } from "./output.ts";
 
@@ -26,6 +33,7 @@ export async function run(argv: string[]): Promise<number> {
 			return 0;
 		}
 		const [group, command] = args.positional;
+		if (group === "agent") return await agentCommand(args, cfg);
 		if (group === "identity" && command === "create") {
 			return await identityCreate(args, cfg);
 		}
@@ -47,6 +55,18 @@ export async function run(argv: string[]): Promise<number> {
 		if (group === "doctor") {
 			return await doctor(args, cfg);
 		}
+		if (group === "diagnose" && command === "bap") {
+			return await diagnoseBap(args, cfg);
+		}
+		if (group === "diagnose" && command === "identities") {
+			return await diagnoseIdentities(args, cfg);
+		}
+		if (group === "diagnose" && command === "last-oauth") {
+			return await diagnoseLastOauth(args, cfg);
+		}
+		if (group === "diagnose" && command === "client") {
+			return await diagnoseClient(args, cfg);
+		}
 		if (!group) {
 			process.stdout.write(HELP);
 			return 0;