@alphafox/cli 0.1.0

package/dist/config/profiles.d.ts

@@ -0,0 +1,29 @@
+export type ProfileName = "production" | "staging" | "local";
+export interface ProfileConfig {
+    readonly name: ProfileName;
+    readonly apiBaseUrl: string;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly clientId: string;
+    readonly contractVersion?: string;
+    /** Only for local / unsafe custom. */
+    readonly localOrigin?: string;
+}
+export interface CliConfigFile {
+    readonly activeProfile: ProfileName;
+    readonly profiles: Partial<Record<ProfileName, Partial<ProfileConfig>>>;
+    readonly unsafeCustomEndpoint?: string;
+    /**
+     * Tokens MUST NOT be stored here. Key is reserved to detect accidental writes.
+     * @deprecated never use
+     */
+    readonly __tokensForbidden?: never;
+}
+export declare function defaultConfigDir(env?: NodeJS.ProcessEnv): string;
+export declare function configFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function loadConfigFile(env?: NodeJS.ProcessEnv): CliConfigFile;
+export declare function saveConfigFile(config: CliConfigFile, env?: NodeJS.ProcessEnv): void;
+export declare function resolveProfile(name?: ProfileName | string, env?: NodeJS.ProcessEnv, options?: {
+    readonly unsafeCustomEndpoint?: string;
+}): ProfileConfig;
+export declare function assertNoTokenFields(config: unknown): void;

package/dist/config/profiles.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfigDir = defaultConfigDir;
+exports.configFilePath = configFilePath;
+exports.loadConfigFile = loadConfigFile;
+exports.saveConfigFile = saveConfigFile;
+exports.resolveProfile = resolveProfile;
+exports.assertNoTokenFields = assertNoTokenFields;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const DEFAULTS = {
+    production: {
+        name: "production",
+        apiBaseUrl: "https://alphafox.app/api/v1",
+        issuer: "https://alphafox.app/api/auth",
+        audience: "https://alphafox.app/api/v1",
+        clientId: "alphafox-cli-prod",
+        contractVersion: "2026-08-11",
+    },
+    staging: {
+        name: "staging",
+        apiBaseUrl: "https://staging.alphafox.app/api/v1",
+        issuer: "https://staging.alphafox.app/api/auth",
+        audience: "https://staging.alphafox.app/api/v1",
+        clientId: "alphafox-cli-staging",
+        contractVersion: "2026-08-11",
+    },
+    local: {
+        name: "local",
+        apiBaseUrl: "http://127.0.0.1:3000/api/v1",
+        issuer: "http://127.0.0.1:3000/api/auth",
+        audience: "http://127.0.0.1:3000/api/v1",
+        clientId: "alphafox-cli-local",
+        localOrigin: "http://127.0.0.1:3000",
+        contractVersion: "2026-08-11",
+    },
+};
+function defaultConfigDir(env = process.env) {
+    if (env.ALPHAFOX_CONFIG_DIR?.trim()) {
+        return env.ALPHAFOX_CONFIG_DIR.trim();
+    }
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "alphafox");
+}
+function configFilePath(env = process.env) {
+    return (0, node_path_1.join)(defaultConfigDir(env), "config.json");
+}
+function loadConfigFile(env = process.env) {
+    const path = configFilePath(env);
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return { activeProfile: "production", profiles: {} };
+    }
+    const raw = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    // Fail closed if someone stuffed tokens into config.
+    if (raw.tokens != null ||
+        raw.accessToken != null ||
+        raw.refreshToken != null ||
+        raw.secret != null) {
+        throw new Error("Refusing to load config: tokens/secrets must not be stored in config files. Remove them and use the OS keychain.");
+    }
+    return {
+        activeProfile: raw.activeProfile ?? "production",
+        profiles: raw.profiles ?? {},
+        unsafeCustomEndpoint: raw.unsafeCustomEndpoint,
+    };
+}
+function saveConfigFile(config, env = process.env) {
+    // Strip any accidental token fields
+    const safe = {
+        activeProfile: config.activeProfile,
+        profiles: config.profiles,
+        ...(config.unsafeCustomEndpoint
+            ? { unsafeCustomEndpoint: config.unsafeCustomEndpoint }
+            : {}),
+    };
+    const dir = defaultConfigDir(env);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configFilePath(env), `${JSON.stringify(safe, null, 2)}\n`, {
+        mode: 0o600,
+    });
+}
+function resolveProfile(name, env = process.env, options = {}) {
+    const file = loadConfigFile(env);
+    const profileName = (name ||
+        env.ALPHAFOX_PROFILE ||
+        file.activeProfile ||
+        "production");
+    if (!DEFAULTS[profileName]) {
+        throw new Error(`Unknown profile "${profileName}". Use production|staging|local.`);
+    }
+    const base = { ...DEFAULTS[profileName], ...(file.profiles[profileName] ?? {}) };
+    if (profileName === "local" && env.ALPHAFOX_LOCAL_ORIGIN?.trim()) {
+        const origin = env.ALPHAFOX_LOCAL_ORIGIN.trim().replace(/\/$/, "");
+        return {
+            ...base,
+            name: "local",
+            localOrigin: origin,
+            apiBaseUrl: `${origin}/api/v1`,
+            issuer: `${origin}/api/auth`,
+            audience: `${origin}/api/v1`,
+        };
+    }
+    const custom = options.unsafeCustomEndpoint ||
+        env.ALPHAFOX_UNSAFE_CUSTOM_ENDPOINT ||
+        file.unsafeCustomEndpoint;
+    if (custom) {
+        // Custom endpoint never inherits stored prod/staging tokens (caller must not send them).
+        const origin = custom.replace(/\/$/, "").replace(/\/api\/v1$/, "");
+        return {
+            ...base,
+            apiBaseUrl: custom.includes("/api/v1")
+                ? custom
+                : `${origin}/api/v1`,
+            issuer: `${origin}/api/auth`,
+            audience: custom.includes("/api/v1") ? custom : `${origin}/api/v1`,
+        };
+    }
+    return base;
+}
+function assertNoTokenFields(config) {
+    if (!config || typeof config !== "object") {
+        return;
+    }
+    const obj = config;
+    for (const key of Object.keys(obj)) {
+        const lower = key.toLowerCase();
+        if (lower.includes("token") ||
+            lower.includes("secret") ||
+            lower.includes("password") ||
+            lower === "authorization") {
+            throw new Error(`Forbidden config field: ${key}`);
+        }
+    }
+}

package/dist/envelope.d.ts

@@ -0,0 +1,37 @@
+export type ExitCode = 0 | 1 | 2 | 3 | 4 | 10 | 64 | 65 | 66 | 69 | 70 | 75 | 77 | 78;
+export interface SuccessEnvelope<T = unknown> {
+    readonly ok: true;
+    readonly data: T;
+    readonly meta?: Record<string, unknown>;
+    readonly requestId?: string;
+}
+export interface ErrorBody {
+    readonly type: string;
+    readonly subtype?: string;
+    readonly code?: string | number;
+    readonly message: string;
+    readonly hint?: string;
+    readonly status?: number;
+    readonly risk?: string;
+    readonly action?: string;
+    readonly details?: unknown;
+}
+export interface ErrorEnvelope {
+    readonly ok: false;
+    readonly error: ErrorBody;
+    readonly requestId?: string;
+}
+export declare function newRequestId(): string;
+export declare function successEnvelope<T>(data: T, meta?: Record<string, unknown>, requestId?: string): SuccessEnvelope<T>;
+export declare function errorEnvelope(error: ErrorBody, requestId?: string): ErrorEnvelope;
+export declare function writeSuccess(data: unknown, options?: {
+    readonly meta?: Record<string, unknown>;
+    readonly requestId?: string;
+    readonly format?: "json" | "jsonl" | "text";
+}): void;
+export declare function writeError(error: ErrorBody, options?: {
+    readonly requestId?: string;
+    readonly exitCode?: number;
+}): never;
+export declare function mapErrorToExitCode(error: ErrorBody): number;
+export declare function parseJsonEnvelope(text: string): SuccessEnvelope | ErrorEnvelope;

package/dist/envelope.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newRequestId = newRequestId;
+exports.successEnvelope = successEnvelope;
+exports.errorEnvelope = errorEnvelope;
+exports.writeSuccess = writeSuccess;
+exports.writeError = writeError;
+exports.mapErrorToExitCode = mapErrorToExitCode;
+exports.parseJsonEnvelope = parseJsonEnvelope;
+const node_crypto_1 = require("node:crypto");
+function newRequestId() {
+    return (0, node_crypto_1.randomUUID)();
+}
+function successEnvelope(data, meta, requestId) {
+    return {
+        ok: true,
+        data,
+        ...(meta ? { meta } : {}),
+        ...(requestId ? { requestId } : {}),
+    };
+}
+function errorEnvelope(error, requestId) {
+    return {
+        ok: false,
+        error,
+        ...(requestId ? { requestId } : {}),
+    };
+}
+function writeSuccess(data, options = {}) {
+    const envelope = successEnvelope(data, options.meta, options.requestId);
+    if (options.format === "text" && data && typeof data === "object") {
+        process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+function writeError(error, options = {}) {
+    const envelope = errorEnvelope(error, options.requestId);
+    process.stderr.write(`${JSON.stringify(envelope)}\n`);
+    process.exit(options.exitCode ?? mapErrorToExitCode(error));
+}
+function mapErrorToExitCode(error) {
+    if (error.type === "confirmation") {
+        return 10;
+    }
+    if (error.status === 401) {
+        return 77;
+    }
+    if (error.status === 403) {
+        return 77;
+    }
+    if (error.status === 404) {
+        return 66;
+    }
+    if (error.status === 409) {
+        return 75;
+    }
+    if (error.status === 422 || error.status === 400) {
+        return 64;
+    }
+    if (error.status === 429) {
+        return 75;
+    }
+    if (error.status && error.status >= 500) {
+        return 69;
+    }
+    if (error.type === "usage") {
+        return 64;
+    }
+    return 1;
+}
+function parseJsonEnvelope(text) {
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || !("ok" in parsed)) {
+        throw new Error("Invalid envelope: missing ok field");
+    }
+    return parsed;
+}

package/dist/http/client.d.ts

@@ -0,0 +1,19 @@
+import type { ProfileConfig } from "../config/profiles";
+export interface ApiRequestOptions {
+    readonly method: string;
+    readonly path: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+    readonly profile: ProfileConfig;
+    readonly requestId?: string;
+    readonly skipAuth?: boolean;
+    readonly idempotencyKey?: string;
+}
+export interface ApiResponse {
+    readonly status: number;
+    readonly headers: Headers;
+    readonly bodyText: string;
+    readonly requestId: string;
+    readonly json: unknown;
+}
+export declare function apiRequest(options: ApiRequestOptions, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Promise<ApiResponse>;

package/dist/http/client.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiRequest = apiRequest;
+const envelope_1 = require("../envelope");
+const store_1 = require("../keychain/store");
+const allowlist_1 = require("../catalog/allowlist");
+async function apiRequest(options, env = process.env, fetchImpl = fetch) {
+    const path = (0, allowlist_1.normalizeApiPath)(options.path);
+    if ((0, allowlist_1.isInternalDisallowedPath)(path)) {
+        throw Object.assign(new Error(`Path is internal and not allowed: ${path}`), {
+            status: 403,
+            type: "authorization",
+            subtype: "internal_path_forbidden",
+        });
+    }
+    // Product raw API: /api/v1 only. Auth AS paths under /api/auth/oauth are allowed.
+    const isOAuthAsPath = path.startsWith("/api/auth/oauth");
+    if (!isOAuthAsPath &&
+        !(0, allowlist_1.isFacadeAllowlistedPath)(path) &&
+        path.startsWith("/api/") &&
+        !path.startsWith("/api/v1")) {
+        throw Object.assign(new Error(`Path is outside Public API facade: ${path}`), {
+            status: 403,
+            type: "authorization",
+            subtype: "facade_only",
+        });
+    }
+    const requestId = options.requestId ?? (0, envelope_1.newRequestId)();
+    const base = options.profile.apiBaseUrl.replace(/\/$/, "");
+    // path may be full /api/v1/... while base already ends with /api/v1
+    let url;
+    if (path.startsWith("/api/v1")) {
+        const origin = base.replace(/\/api\/v1$/, "");
+        url = `${origin}${path}`;
+    }
+    else if (path.startsWith("/api/auth")) {
+        const origin = base.replace(/\/api\/v1$/, "");
+        url = `${origin}${path}`;
+    }
+    else {
+        url = `${base}${path.startsWith("/") ? path : `/${path}`}`;
+    }
+    const headers = {
+        Accept: "application/json",
+        "X-Request-Id": requestId,
+        "X-Alphafox-Client": "alphafox-cli",
+        "X-Alphafox-Client-Version": env.ALPHAFOX_CLI_VERSION ?? "0.1.0",
+        ...(options.headers ?? {}),
+    };
+    if (!options.skipAuth) {
+        const tokens = (0, store_1.loadTokens)(options.profile.name, env);
+        if (tokens) {
+            // Never send tokens to a different origin than the profile audience.
+            const tokenAudienceOrigin = originOf(tokens.audience);
+            const targetOrigin = originOf(url);
+            if (tokens.audience &&
+                tokenAudienceOrigin &&
+                targetOrigin &&
+                tokenAudienceOrigin !== targetOrigin) {
+                throw Object.assign(new Error("Refusing to send stored tokens to a different origin than token audience (fail-closed)."), {
+                    status: 403,
+                    type: "authorization",
+                    subtype: "cross_origin_token",
+                });
+            }
+            headers.Authorization = `Bearer ${tokens.accessToken}`;
+        }
+    }
+    if (options.idempotencyKey) {
+        headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    const init = {
+        method: options.method.toUpperCase(),
+        headers,
+    };
+    if (options.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(options.body);
+    }
+    const response = await fetchImpl(url, init);
+    const bodyText = await response.text();
+    let json = null;
+    try {
+        json = bodyText ? JSON.parse(bodyText) : null;
+    }
+    catch {
+        json = { raw: bodyText };
+    }
+    const responseRequestId = response.headers.get("x-request-id") ??
+        response.headers.get("X-Request-Id") ??
+        requestId;
+    return {
+        status: response.status,
+        headers: response.headers,
+        bodyText,
+        requestId: responseRequestId,
+        json,
+    };
+}
+function originOf(value) {
+    try {
+        if (value.startsWith("http://") || value.startsWith("https://")) {
+            return new URL(value).origin;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { runCli, parseGlobalFlags } from "./commands/run";
+export { successEnvelope, errorEnvelope, parseJsonEnvelope, writeSuccess, writeError, } from "./envelope";
+export { resolveProfile, loadConfigFile, saveConfigFile, assertNoTokenFields, } from "./config/profiles";
+export { saveTokens, loadTokens, deleteTokens, tokenFingerprint, } from "./keychain/store";
+export { isFacadeAllowlistedPath, isInternalDisallowedPath, normalizeApiPath, } from "./catalog/allowlist";
+export { assertHighRiskConfirmation } from "./safety/confirmation";
+export { CATALOG_OPERATIONS, findCatalogOperation, buildCapabilityManifest, } from "./catalog/operations";
+export { CLI_VERSION, CLI_PACKAGE, CLI_CONTRACT_VERSION } from "./version";

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_CONTRACT_VERSION = exports.CLI_PACKAGE = exports.CLI_VERSION = exports.buildCapabilityManifest = exports.findCatalogOperation = exports.CATALOG_OPERATIONS = exports.assertHighRiskConfirmation = exports.normalizeApiPath = exports.isInternalDisallowedPath = exports.isFacadeAllowlistedPath = exports.tokenFingerprint = exports.deleteTokens = exports.loadTokens = exports.saveTokens = exports.assertNoTokenFields = exports.saveConfigFile = exports.loadConfigFile = exports.resolveProfile = exports.writeError = exports.writeSuccess = exports.parseJsonEnvelope = exports.errorEnvelope = exports.successEnvelope = exports.parseGlobalFlags = exports.runCli = void 0;
+var run_1 = require("./commands/run");
+Object.defineProperty(exports, "runCli", { enumerable: true, get: function () { return run_1.runCli; } });
+Object.defineProperty(exports, "parseGlobalFlags", { enumerable: true, get: function () { return run_1.parseGlobalFlags; } });
+var envelope_1 = require("./envelope");
+Object.defineProperty(exports, "successEnvelope", { enumerable: true, get: function () { return envelope_1.successEnvelope; } });
+Object.defineProperty(exports, "errorEnvelope", { enumerable: true, get: function () { return envelope_1.errorEnvelope; } });
+Object.defineProperty(exports, "parseJsonEnvelope", { enumerable: true, get: function () { return envelope_1.parseJsonEnvelope; } });
+Object.defineProperty(exports, "writeSuccess", { enumerable: true, get: function () { return envelope_1.writeSuccess; } });
+Object.defineProperty(exports, "writeError", { enumerable: true, get: function () { return envelope_1.writeError; } });
+var profiles_1 = require("./config/profiles");
+Object.defineProperty(exports, "resolveProfile", { enumerable: true, get: function () { return profiles_1.resolveProfile; } });
+Object.defineProperty(exports, "loadConfigFile", { enumerable: true, get: function () { return profiles_1.loadConfigFile; } });
+Object.defineProperty(exports, "saveConfigFile", { enumerable: true, get: function () { return profiles_1.saveConfigFile; } });
+Object.defineProperty(exports, "assertNoTokenFields", { enumerable: true, get: function () { return profiles_1.assertNoTokenFields; } });
+var store_1 = require("./keychain/store");
+Object.defineProperty(exports, "saveTokens", { enumerable: true, get: function () { return store_1.saveTokens; } });
+Object.defineProperty(exports, "loadTokens", { enumerable: true, get: function () { return store_1.loadTokens; } });
+Object.defineProperty(exports, "deleteTokens", { enumerable: true, get: function () { return store_1.deleteTokens; } });
+Object.defineProperty(exports, "tokenFingerprint", { enumerable: true, get: function () { return store_1.tokenFingerprint; } });
+var allowlist_1 = require("./catalog/allowlist");
+Object.defineProperty(exports, "isFacadeAllowlistedPath", { enumerable: true, get: function () { return allowlist_1.isFacadeAllowlistedPath; } });
+Object.defineProperty(exports, "isInternalDisallowedPath", { enumerable: true, get: function () { return allowlist_1.isInternalDisallowedPath; } });
+Object.defineProperty(exports, "normalizeApiPath", { enumerable: true, get: function () { return allowlist_1.normalizeApiPath; } });
+var confirmation_1 = require("./safety/confirmation");
+Object.defineProperty(exports, "assertHighRiskConfirmation", { enumerable: true, get: function () { return confirmation_1.assertHighRiskConfirmation; } });
+var operations_1 = require("./catalog/operations");
+Object.defineProperty(exports, "CATALOG_OPERATIONS", { enumerable: true, get: function () { return operations_1.CATALOG_OPERATIONS; } });
+Object.defineProperty(exports, "findCatalogOperation", { enumerable: true, get: function () { return operations_1.findCatalogOperation; } });
+Object.defineProperty(exports, "buildCapabilityManifest", { enumerable: true, get: function () { return operations_1.buildCapabilityManifest; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "CLI_VERSION", { enumerable: true, get: function () { return version_1.CLI_VERSION; } });
+Object.defineProperty(exports, "CLI_PACKAGE", { enumerable: true, get: function () { return version_1.CLI_PACKAGE; } });
+Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return version_1.CLI_CONTRACT_VERSION; } });

package/dist/keychain/store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OS keychain token storage. Config files never receive tokens.
+ * Test injection: ALPHAFOX_TEST_ACCESS_TOKEN / ALPHAFOX_TEST_REFRESH_TOKEN
+ * (local unit tests only; not a production automation path — ADR 0004).
+ */
+export interface StoredTokens {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresAt: number;
+    readonly environment: string;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly clientId: string;
+    readonly scopes: readonly string[];
+}
+export declare function saveTokens(profile: string, tokens: StoredTokens, env?: NodeJS.ProcessEnv): void;
+export declare function loadTokens(profile: string, env?: NodeJS.ProcessEnv): StoredTokens | null;
+export declare function deleteTokens(profile: string, env?: NodeJS.ProcessEnv): void;
+export declare function tokenFingerprint(token: string): string;

package/dist/keychain/store.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * OS keychain token storage. Config files never receive tokens.
+ * Test injection: ALPHAFOX_TEST_ACCESS_TOKEN / ALPHAFOX_TEST_REFRESH_TOKEN
+ * (local unit tests only; not a production automation path — ADR 0004).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveTokens = saveTokens;
+exports.loadTokens = loadTokens;
+exports.deleteTokens = deleteTokens;
+exports.tokenFingerprint = tokenFingerprint;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+function serviceName(profile) {
+    return `alphafox-cli.${profile}`;
+}
+function accountName() {
+    return "oauth-tokens";
+}
+/** File fallback under secure mode 0600 when OS keychain is unavailable (CI/Linux headless). */
+function fileFallbackPath(profile, env) {
+    const base = env.ALPHAFOX_KEYCHAIN_DIR?.trim() ||
+        (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "alphafox", "keychain");
+    return (0, node_path_1.join)(base, `${profile}.tokens.json`);
+}
+function saveTokens(profile, tokens, env = process.env) {
+    const payload = JSON.stringify(tokens);
+    if (tryKeychainWrite(profile, payload, env)) {
+        return;
+    }
+    const path = fileFallbackPath(profile, env);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(path, ".."), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, payload, { mode: 0o600 });
+}
+function loadTokens(profile, env = process.env) {
+    // Controlled test injection — never document as prod automation.
+    if (env.ALPHAFOX_TEST_ACCESS_TOKEN?.trim()) {
+        return {
+            accessToken: env.ALPHAFOX_TEST_ACCESS_TOKEN.trim(),
+            refreshToken: env.ALPHAFOX_TEST_REFRESH_TOKEN?.trim() ?? "",
+            expiresAt: Date.now() + 3600_000,
+            environment: profile,
+            issuer: env.ALPHAFOX_TEST_ISSUER ?? "",
+            audience: env.ALPHAFOX_TEST_AUDIENCE ?? "",
+            clientId: env.ALPHAFOX_TEST_CLIENT_ID ?? "",
+            scopes: (env.ALPHAFOX_TEST_SCOPES ?? "openid profile").split(/\s+/),
+        };
+    }
+    const fromKc = tryKeychainRead(profile, env);
+    if (fromKc) {
+        return JSON.parse(fromKc);
+    }
+    const path = fileFallbackPath(profile, env);
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return null;
+    }
+    return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+}
+function deleteTokens(profile, env = process.env) {
+    tryKeychainDelete(profile, env);
+    const path = fileFallbackPath(profile, env);
+    if ((0, node_fs_1.existsSync)(path)) {
+        (0, node_fs_1.unlinkSync)(path);
+    }
+}
+function tokenFingerprint(token) {
+    return (0, node_crypto_1.createHash)("sha256").update(token).digest("hex").slice(0, 12);
+}
+function tryKeychainWrite(profile, payload, env) {
+    if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
+        return false;
+    }
+    if (process.platform === "darwin") {
+        try {
+            // delete existing silently
+            try {
+                (0, node_child_process_1.execFileSync)("security", [
+                    "delete-generic-password",
+                    "-s",
+                    serviceName(profile),
+                    "-a",
+                    accountName(),
+                ], { stdio: "ignore" });
+            }
+            catch {
+                // none
+            }
+            (0, node_child_process_1.execFileSync)("security", [
+                "add-generic-password",
+                "-s",
+                serviceName(profile),
+                "-a",
+                accountName(),
+                "-w",
+                payload,
+                "-U",
+            ], { stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function tryKeychainRead(profile, env) {
+    if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
+        return null;
+    }
+    if (process.platform === "darwin") {
+        try {
+            const out = (0, node_child_process_1.execFileSync)("security", [
+                "find-generic-password",
+                "-s",
+                serviceName(profile),
+                "-a",
+                accountName(),
+                "-w",
+            ], { encoding: "utf8" });
+            return out.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function tryKeychainDelete(profile, env) {
+    if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
+        return;
+    }
+    if (process.platform === "darwin") {
+        try {
+            (0, node_child_process_1.execFileSync)("security", [
+                "delete-generic-password",
+                "-s",
+                serviceName(profile),
+                "-a",
+                accountName(),
+            ], { stdio: "ignore" });
+        }
+        catch {
+            // none
+        }
+    }
+}

package/dist/safety/confirmation.d.ts

@@ -0,0 +1,22 @@
+export type RiskLevel = "read" | "write" | "high-risk-write";
+export interface ConfirmationGateResult {
+    readonly allowed: boolean;
+    readonly error?: {
+        readonly type: "confirmation";
+        readonly subtype: "confirmation_required";
+        readonly message: string;
+        readonly hint: string;
+        readonly risk: "high-risk-write";
+        readonly action: string;
+    };
+}
+/**
+ * High-risk writes require explicit --yes (or equivalent confirmation token).
+ * Server still enforces scopes/roles; this is CLI UX only.
+ */
+export declare function assertHighRiskConfirmation(input: {
+    readonly risk: RiskLevel | string;
+    readonly yes: boolean;
+    readonly action: string;
+    readonly dryRun?: boolean;
+}): ConfirmationGateResult;