@alphafox/cli 0.1.4 → 0.2.0

package/dist/envelope.js

@@ -4,10 +4,12 @@ exports.newRequestId = newRequestId;
 exports.successEnvelope = successEnvelope;
 exports.errorEnvelope = errorEnvelope;
 exports.writeSuccess = writeSuccess;
+exports.applyJqFilter = applyJqFilter;
 exports.writeError = writeError;
 exports.mapErrorToExitCode = mapErrorToExitCode;
 exports.parseJsonEnvelope = parseJsonEnvelope;
 const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
 function newRequestId() {
     return (0, node_crypto_1.randomUUID)();
 }
@@ -28,11 +30,49 @@ function errorEnvelope(error, 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`);
+    const rendered = options.format === "text" && data && typeof data === "object"
+        ? `${JSON.stringify(envelope, null, 2)}\n`
+        : `${JSON.stringify(envelope)}\n`;
+    if (options.jq?.trim()) {
+        const filtered = applyJqFilter(envelope, options.jq.trim());
+        process.stdout.write(filtered.endsWith("\n") ? filtered : `${filtered}\n`);
         return;
     }
-    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+    process.stdout.write(rendered);
+}
+function applyJqFilter(value, filter, spawn = node_child_process_1.spawnSync) {
+    if (!filter.trim()) {
+        throw Object.assign(new Error("--jq filter must be non-empty"), {
+            type: "usage",
+            subtype: "jq_empty",
+            status: 64,
+        });
+    }
+    const result = spawn(process.env.ALPHAFOX_JQ?.trim() || "jq", ["-c", filter], {
+        input: JSON.stringify(value),
+        encoding: "utf8",
+        timeout: 10_000,
+    });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            throw Object.assign(new Error("jq is not installed; --jq requires the jq binary on PATH"), { type: "usage", subtype: "jq_not_installed", status: 64 });
+        }
+        throw Object.assign(new Error(result.error.message), {
+            type: "usage",
+            subtype: "jq_failed",
+            status: 64,
+        });
+    }
+    if (result.status !== 0) {
+        const errText = (result.stderr || "jq filter failed").trim();
+        throw Object.assign(new Error(errText), {
+            type: "usage",
+            subtype: "jq_failed",
+            status: 64,
+        });
+    }
+    return result.stdout;
 }
 function writeError(error, options = {}) {
     const envelope = errorEnvelope(error, options.requestId);

package/dist/http/client.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiRequest = apiRequest;
 const envelope_1 = require("../envelope");
+const version_1 = require("../version");
 const refresh_1 = require("../auth/refresh");
 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);
+    // Keep query string for endpoints like /traders/performance?ids=...
+    const { path, query } = splitPathAndQuery(options.path);
     if ((0, allowlist_1.isInternalDisallowedPath)(path)) {
         throw Object.assign(new Error(`Path is internal and not allowed: ${path}`), {
             status: 403,
@@ -16,15 +18,15 @@ async function apiRequest(options, env = process.env, fetchImpl = fetch) {
     }
     // 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",
-        });
+    if (!isOAuthAsPath && path.startsWith("/api/")) {
+        // Unknown /api/v1/* is denied (finite facility/catalog allowlist).
+        if (!(0, allowlist_1.isFacadeAllowlistedPath)(path)) {
+            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(/\/$/, "");
@@ -32,30 +34,32 @@ async function apiRequest(options, env = process.env, fetchImpl = fetch) {
     let url;
     if (path.startsWith("/api/v1")) {
         const origin = base.replace(/\/api\/v1$/, "");
-        url = `${origin}${path}`;
+        url = `${origin}${path}${query}`;
     }
     else if (path.startsWith("/api/auth")) {
         const origin = base.replace(/\/api\/v1$/, "");
-        url = `${origin}${path}`;
+        url = `${origin}${path}${query}`;
     }
     else {
-        url = `${base}${path.startsWith("/") ? path : `/${path}`}`;
+        url = `${base}${path.startsWith("/") ? path : `/${path}`}${query}`;
     }
     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",
+        "X-Alphafox-Client-Version": env.ALPHAFOX_CLI_VERSION ?? version_1.CLI_VERSION,
         ...(options.headers ?? {}),
     };
     if (!options.skipAuth) {
         let tokens = (0, store_1.loadTokens)(options.profile.name, env);
         // Proactive refresh before the access token expires (or once already expired).
         if (tokens && (0, refresh_1.accessTokenNeedsRefresh)(tokens)) {
-            const renewed = await (0, refresh_1.refreshStoredTokens)(options.profile, env, fetchImpl, { force: true });
-            if (renewed) {
-                tokens = renewed;
+            const outcome = await (0, refresh_1.refreshStoredTokens)(options.profile, env, fetchImpl, { force: true });
+            if (outcome.status === "refreshed" || outcome.status === "unchanged") {
+                tokens = outcome.tokens;
             }
+            // On failed refresh keep prior tokens only for the request; do not treat
+            // failure as a successful renewal.
         }
         if (tokens) {
             // Never send tokens to a different site than the profile audience.
@@ -109,8 +113,8 @@ async function apiRequest(options, env = process.env, fetchImpl = fetch) {
         !isOAuthAsPath) {
         const tokens = (0, store_1.loadTokens)(options.profile.name, env);
         if (tokens?.refreshToken?.trim()) {
-            const renewed = await (0, refresh_1.refreshStoredTokens)(options.profile, env, fetchImpl, { force: true });
-            if (renewed) {
+            const outcome = await (0, refresh_1.refreshStoredTokens)(options.profile, env, fetchImpl, { force: true });
+            if (outcome.status === "refreshed") {
                 return apiRequest({ ...options, requestId, _refreshRetried: true }, env, fetchImpl);
             }
         }
@@ -190,3 +194,15 @@ function sameAuthSite(a, b) {
         return false;
     }
 }
+/** Split raw path so allowlist uses path-only while fetch keeps query. */
+function splitPathAndQuery(raw) {
+    const trimmed = raw.trim();
+    const q = trimmed.indexOf("?");
+    if (q < 0) {
+        return { path: (0, allowlist_1.normalizeApiPath)(trimmed), query: "" };
+    }
+    return {
+        path: (0, allowlist_1.normalizeApiPath)(trimmed.slice(0, q)),
+        query: trimmed.slice(q),
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,15 @@
 export { runCli, parseGlobalFlags } from "./commands/run";
-export { successEnvelope, errorEnvelope, parseJsonEnvelope, writeSuccess, writeError, } from "./envelope";
+export { successEnvelope, errorEnvelope, parseJsonEnvelope, writeSuccess, writeError, applyJqFilter, } 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 { saveTokens, loadTokens, deleteTokens, tokenFingerprint, getLastTokenSaveResult, probeOsKeychain, keychainPlatform, } from "./keychain/store";
+export { linuxSecretServiceArgs, linuxSecretToolBin, } from "./keychain/linux-secret-service";
+export { windowsCredentialTarget, WINDOWS_CRED_MAX_BYTES, } from "./keychain/windows-credential";
+export { isFacadeAllowlistedPath, isInternalDisallowedPath, normalizeApiPath, pathTemplateMatches, } from "./catalog/allowlist";
+export { checkCliCompatibility, type CompatibilityRange, type CompatibilityResult, } from "./catalog/compatibility";
+export { resolveTypedCommand } from "./catalog/command-tree";
+export { assertHighRiskConfirmation, inferRawApiRisk, requiresHighRiskConfirmation, } from "./safety/confirmation";
+export { refreshStoredTokens, refreshStoredTokensOrNull, accessTokenNeedsRefresh, } from "./auth/refresh";
+export { runBrowserPkceLogin } from "./auth/browser-login";
+export { startLoopbackCallbackServer } from "./auth/loopback-callback";
+export { CATALOG_OPERATIONS, CATALOG_SOURCE, CATALOG_VERSION, COMPATIBILITY_RANGE, findCatalogOperation, findCatalogOperationByRoute, getOperationSchemaDocument, buildCapabilityManifest, checkGeneratedCatalogCompatibility, } from "./catalog/operations";
 export { CLI_VERSION, CLI_PACKAGE, CLI_CONTRACT_VERSION } from "./version";

package/dist/index.js

@@ -1,6 +1,6 @@
 "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;
+exports.CLI_CONTRACT_VERSION = exports.CLI_PACKAGE = exports.CLI_VERSION = exports.checkGeneratedCatalogCompatibility = exports.buildCapabilityManifest = exports.getOperationSchemaDocument = exports.findCatalogOperationByRoute = exports.findCatalogOperation = exports.COMPATIBILITY_RANGE = exports.CATALOG_VERSION = exports.CATALOG_SOURCE = exports.CATALOG_OPERATIONS = exports.startLoopbackCallbackServer = exports.runBrowserPkceLogin = exports.accessTokenNeedsRefresh = exports.refreshStoredTokensOrNull = exports.refreshStoredTokens = exports.requiresHighRiskConfirmation = exports.inferRawApiRisk = exports.assertHighRiskConfirmation = exports.resolveTypedCommand = exports.checkCliCompatibility = exports.pathTemplateMatches = exports.normalizeApiPath = exports.isInternalDisallowedPath = exports.isFacadeAllowlistedPath = exports.WINDOWS_CRED_MAX_BYTES = exports.windowsCredentialTarget = exports.linuxSecretToolBin = exports.linuxSecretServiceArgs = exports.keychainPlatform = exports.probeOsKeychain = exports.getLastTokenSaveResult = exports.tokenFingerprint = exports.deleteTokens = exports.loadTokens = exports.saveTokens = exports.assertNoTokenFields = exports.saveConfigFile = exports.loadConfigFile = exports.resolveProfile = exports.applyJqFilter = 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; } });
@@ -10,6 +10,7 @@ Object.defineProperty(exports, "errorEnvelope", { enumerable: true, get: functio
 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; } });
+Object.defineProperty(exports, "applyJqFilter", { enumerable: true, get: function () { return envelope_1.applyJqFilter; } });
 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; } });
@@ -20,16 +21,46 @@ Object.defineProperty(exports, "saveTokens", { enumerable: true, get: function (
 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; } });
+Object.defineProperty(exports, "getLastTokenSaveResult", { enumerable: true, get: function () { return store_1.getLastTokenSaveResult; } });
+Object.defineProperty(exports, "probeOsKeychain", { enumerable: true, get: function () { return store_1.probeOsKeychain; } });
+Object.defineProperty(exports, "keychainPlatform", { enumerable: true, get: function () { return store_1.keychainPlatform; } });
+var linux_secret_service_1 = require("./keychain/linux-secret-service");
+Object.defineProperty(exports, "linuxSecretServiceArgs", { enumerable: true, get: function () { return linux_secret_service_1.linuxSecretServiceArgs; } });
+Object.defineProperty(exports, "linuxSecretToolBin", { enumerable: true, get: function () { return linux_secret_service_1.linuxSecretToolBin; } });
+var windows_credential_1 = require("./keychain/windows-credential");
+Object.defineProperty(exports, "windowsCredentialTarget", { enumerable: true, get: function () { return windows_credential_1.windowsCredentialTarget; } });
+Object.defineProperty(exports, "WINDOWS_CRED_MAX_BYTES", { enumerable: true, get: function () { return windows_credential_1.WINDOWS_CRED_MAX_BYTES; } });
 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; } });
+Object.defineProperty(exports, "pathTemplateMatches", { enumerable: true, get: function () { return allowlist_1.pathTemplateMatches; } });
+var compatibility_1 = require("./catalog/compatibility");
+Object.defineProperty(exports, "checkCliCompatibility", { enumerable: true, get: function () { return compatibility_1.checkCliCompatibility; } });
+var command_tree_1 = require("./catalog/command-tree");
+Object.defineProperty(exports, "resolveTypedCommand", { enumerable: true, get: function () { return command_tree_1.resolveTypedCommand; } });
 var confirmation_1 = require("./safety/confirmation");
 Object.defineProperty(exports, "assertHighRiskConfirmation", { enumerable: true, get: function () { return confirmation_1.assertHighRiskConfirmation; } });
+Object.defineProperty(exports, "inferRawApiRisk", { enumerable: true, get: function () { return confirmation_1.inferRawApiRisk; } });
+Object.defineProperty(exports, "requiresHighRiskConfirmation", { enumerable: true, get: function () { return confirmation_1.requiresHighRiskConfirmation; } });
+var refresh_1 = require("./auth/refresh");
+Object.defineProperty(exports, "refreshStoredTokens", { enumerable: true, get: function () { return refresh_1.refreshStoredTokens; } });
+Object.defineProperty(exports, "refreshStoredTokensOrNull", { enumerable: true, get: function () { return refresh_1.refreshStoredTokensOrNull; } });
+Object.defineProperty(exports, "accessTokenNeedsRefresh", { enumerable: true, get: function () { return refresh_1.accessTokenNeedsRefresh; } });
+var browser_login_1 = require("./auth/browser-login");
+Object.defineProperty(exports, "runBrowserPkceLogin", { enumerable: true, get: function () { return browser_login_1.runBrowserPkceLogin; } });
+var loopback_callback_1 = require("./auth/loopback-callback");
+Object.defineProperty(exports, "startLoopbackCallbackServer", { enumerable: true, get: function () { return loopback_callback_1.startLoopbackCallbackServer; } });
 var operations_1 = require("./catalog/operations");
 Object.defineProperty(exports, "CATALOG_OPERATIONS", { enumerable: true, get: function () { return operations_1.CATALOG_OPERATIONS; } });
+Object.defineProperty(exports, "CATALOG_SOURCE", { enumerable: true, get: function () { return operations_1.CATALOG_SOURCE; } });
+Object.defineProperty(exports, "CATALOG_VERSION", { enumerable: true, get: function () { return operations_1.CATALOG_VERSION; } });
+Object.defineProperty(exports, "COMPATIBILITY_RANGE", { enumerable: true, get: function () { return operations_1.COMPATIBILITY_RANGE; } });
 Object.defineProperty(exports, "findCatalogOperation", { enumerable: true, get: function () { return operations_1.findCatalogOperation; } });
+Object.defineProperty(exports, "findCatalogOperationByRoute", { enumerable: true, get: function () { return operations_1.findCatalogOperationByRoute; } });
+Object.defineProperty(exports, "getOperationSchemaDocument", { enumerable: true, get: function () { return operations_1.getOperationSchemaDocument; } });
 Object.defineProperty(exports, "buildCapabilityManifest", { enumerable: true, get: function () { return operations_1.buildCapabilityManifest; } });
+Object.defineProperty(exports, "checkGeneratedCatalogCompatibility", { enumerable: true, get: function () { return operations_1.checkGeneratedCatalogCompatibility; } });
 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; } });

package/dist/keychain/linux-secret-service.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Linux Secret Service via `secret-tool` (libsecret).
+ * Tokens travel on stdin/stdout, never as argv.
+ */
+export declare const LINUX_SECRET_LABEL_PREFIX = "alphafox-cli";
+export declare function linuxSecretServiceArgs(action: "store" | "lookup" | "clear", service: string, account: string): readonly string[];
+export declare function linuxSecretToolBin(env?: NodeJS.ProcessEnv): string;
+export declare function linuxSecretServiceWrite(service: string, account: string, payload: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function linuxSecretServiceRead(service: string, account: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function linuxSecretServiceDelete(service: string, account: string, env?: NodeJS.ProcessEnv): void;
+export declare function linuxSecretServiceAvailable(env?: NodeJS.ProcessEnv): boolean;

package/dist/keychain/linux-secret-service.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Linux Secret Service via `secret-tool` (libsecret).
+ * Tokens travel on stdin/stdout, never as argv.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINUX_SECRET_LABEL_PREFIX = void 0;
+exports.linuxSecretServiceArgs = linuxSecretServiceArgs;
+exports.linuxSecretToolBin = linuxSecretToolBin;
+exports.linuxSecretServiceWrite = linuxSecretServiceWrite;
+exports.linuxSecretServiceRead = linuxSecretServiceRead;
+exports.linuxSecretServiceDelete = linuxSecretServiceDelete;
+exports.linuxSecretServiceAvailable = linuxSecretServiceAvailable;
+const node_child_process_1 = require("node:child_process");
+exports.LINUX_SECRET_LABEL_PREFIX = "alphafox-cli";
+function linuxSecretServiceArgs(action, service, account) {
+    if (action === "store") {
+        return [
+            "store",
+            "--label",
+            `${exports.LINUX_SECRET_LABEL_PREFIX} ${service}`,
+            "service",
+            service,
+            "account",
+            account,
+        ];
+    }
+    if (action === "lookup") {
+        return ["lookup", "service", service, "account", account];
+    }
+    return ["clear", "service", service, "account", account];
+}
+function linuxSecretToolBin(env = process.env) {
+    return env.ALPHAFOX_SECRET_TOOL?.trim() || "secret-tool";
+}
+function childEnv(env) {
+    return { ...process.env, ...env };
+}
+function linuxSecretServiceWrite(service, account, payload, env = process.env) {
+    try {
+        (0, node_child_process_1.execFileSync)(linuxSecretToolBin(env), [...linuxSecretServiceArgs("store", service, account)], {
+            input: payload,
+            encoding: "utf8",
+            stdio: ["pipe", "ignore", "ignore"],
+            timeout: 10_000,
+            env: childEnv(env),
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function linuxSecretServiceRead(service, account, env = process.env) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)(linuxSecretToolBin(env), [...linuxSecretServiceArgs("lookup", service, account)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+            env: childEnv(env),
+        });
+        const text = out.replace(/\n$/, "");
+        return text.length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+function linuxSecretServiceDelete(service, account, env = process.env) {
+    try {
+        (0, node_child_process_1.execFileSync)(linuxSecretToolBin(env), [...linuxSecretServiceArgs("clear", service, account)], {
+            stdio: "ignore",
+            timeout: 10_000,
+            env: childEnv(env),
+        });
+    }
+    catch {
+        // none
+    }
+}
+function linuxSecretServiceAvailable(env = process.env) {
+    try {
+        (0, node_child_process_1.execFileSync)(linuxSecretToolBin(env), ["--help"], {
+            stdio: "ignore",
+            timeout: 5_000,
+            env: childEnv(env),
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/keychain/store.d.ts

@@ -13,7 +13,26 @@ export interface StoredTokens {
     readonly clientId: string;
     readonly scopes: readonly string[];
 }
-export declare function saveTokens(profile: string, tokens: StoredTokens, env?: NodeJS.ProcessEnv): void;
+export type TokenStorageBackend = "keychain" | "file" | "test-injection";
+export type OsKeychainKind = "macos-security" | "linux-secret-service" | "windows-credential-manager" | "none";
+export interface TokenStorageResult {
+    readonly backend: TokenStorageBackend;
+    readonly kind?: OsKeychainKind;
+    /** Absolute path when backend is file. */
+    readonly path?: string;
+    /** True when OS keychain failed/unavailable and file fallback was used. */
+    readonly degraded: boolean;
+}
+export declare function getLastTokenSaveResult(): TokenStorageResult | null;
+export declare function keychainServiceName(profile: string): string;
+export declare function keychainAccountName(): string;
+/** Test-only override. Production code uses process.platform. */
+export declare function keychainPlatform(env?: NodeJS.ProcessEnv): NodeJS.Platform;
+export declare function probeOsKeychain(env?: NodeJS.ProcessEnv): {
+    readonly kind: OsKeychainKind;
+    readonly available: boolean;
+};
+export declare function saveTokens(profile: string, tokens: StoredTokens, env?: NodeJS.ProcessEnv): TokenStorageResult;
 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

@@ -5,6 +5,11 @@
  * (local unit tests only; not a production automation path — ADR 0004).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLastTokenSaveResult = getLastTokenSaveResult;
+exports.keychainServiceName = keychainServiceName;
+exports.keychainAccountName = keychainAccountName;
+exports.keychainPlatform = keychainPlatform;
+exports.probeOsKeychain = probeOsKeychain;
 exports.saveTokens = saveTokens;
 exports.loadTokens = loadTokens;
 exports.deleteTokens = deleteTokens;
@@ -14,12 +19,52 @@ 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) {
+const linux_secret_service_1 = require("./linux-secret-service");
+const windows_credential_1 = require("./windows-credential");
+/** Last save outcome — callers/tests can observe silent-fallback without stderr parsing. */
+let lastSaveResult = null;
+function getLastTokenSaveResult() {
+    return lastSaveResult;
+}
+function keychainServiceName(profile) {
     return `alphafox-cli.${profile}`;
 }
-function accountName() {
+function keychainAccountName() {
     return "oauth-tokens";
 }
+function serviceName(profile) {
+    return keychainServiceName(profile);
+}
+function accountName() {
+    return keychainAccountName();
+}
+/** Test-only override. Production code uses process.platform. */
+function keychainPlatform(env = process.env) {
+    const raw = env.ALPHAFOX_KEYCHAIN_PLATFORM?.trim();
+    if (raw === "darwin" || raw === "linux" || raw === "win32") {
+        return raw;
+    }
+    return process.platform;
+}
+function probeOsKeychain(env = process.env) {
+    const platform = keychainPlatform(env);
+    if (platform === "darwin") {
+        return { kind: "macos-security", available: true };
+    }
+    if (platform === "linux") {
+        return {
+            kind: "linux-secret-service",
+            available: (0, linux_secret_service_1.linuxSecretServiceAvailable)(env),
+        };
+    }
+    if (platform === "win32") {
+        return {
+            kind: "windows-credential-manager",
+            available: (0, windows_credential_1.windowsCredentialAvailable)(env),
+        };
+    }
+    return { kind: "none", available: false };
+}
 /** 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() ||
@@ -29,11 +74,31 @@ function fileFallbackPath(profile, env) {
 function saveTokens(profile, tokens, env = process.env) {
     const payload = JSON.stringify(tokens);
     if (tryKeychainWrite(profile, payload, env)) {
-        return;
+        lastSaveResult = {
+            backend: "keychain",
+            kind: probeOsKeychain(env).kind,
+            degraded: false,
+        };
+        return lastSaveResult;
     }
     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 });
+    const intentionalFile = env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1";
+    lastSaveResult = {
+        backend: "file",
+        path,
+        // Intentional file mode is not a silent degrade.
+        degraded: !intentionalFile,
+    };
+    // Observable signal when OS keychain failed unexpectedly (not force-file).
+    if (!intentionalFile) {
+        process.emitWarning(`OS keychain unavailable for profile "${profile}"; tokens stored in file ${path} (mode 0600). Set ALPHAFOX_FORCE_FILE_KEYCHAIN=1 when file storage is intentional.`, {
+            code: "ALPHAFOX_KEYCHAIN_FILE_FALLBACK",
+            detail: path,
+        });
+    }
+    return lastSaveResult;
 }
 function loadTokens(profile, env = process.env) {
     // Controlled test injection — never document as prod automation.
@@ -77,7 +142,14 @@ function tryKeychainWrite(profile, payload, env) {
     if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
         return false;
     }
-    if (process.platform === "darwin") {
+    const platform = keychainPlatform(env);
+    if (platform === "linux") {
+        return (0, linux_secret_service_1.linuxSecretServiceWrite)(serviceName(profile), accountName(), payload, env);
+    }
+    if (platform === "win32") {
+        return (0, windows_credential_1.windowsCredentialWrite)(profile, payload, env);
+    }
+    if (platform === "darwin") {
         try {
             // delete existing silently
             try {
@@ -114,7 +186,14 @@ function tryKeychainRead(profile, env) {
     if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
         return null;
     }
-    if (process.platform === "darwin") {
+    const platform = keychainPlatform(env);
+    if (platform === "linux") {
+        return (0, linux_secret_service_1.linuxSecretServiceRead)(serviceName(profile), accountName(), env);
+    }
+    if (platform === "win32") {
+        return (0, windows_credential_1.windowsCredentialRead)(profile, env);
+    }
+    if (platform === "darwin") {
         try {
             const out = (0, node_child_process_1.execFileSync)("security", [
                 "find-generic-password",
@@ -136,7 +215,16 @@ function tryKeychainDelete(profile, env) {
     if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
         return;
     }
-    if (process.platform === "darwin") {
+    const platform = keychainPlatform(env);
+    if (platform === "linux") {
+        (0, linux_secret_service_1.linuxSecretServiceDelete)(serviceName(profile), accountName(), env);
+        return;
+    }
+    if (platform === "win32") {
+        (0, windows_credential_1.windowsCredentialDelete)(profile, env);
+        return;
+    }
+    if (platform === "darwin") {
         try {
             (0, node_child_process_1.execFileSync)("security", [
                 "delete-generic-password",

package/dist/keychain/windows-credential.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Windows Credential Manager via advapi32 CredWrite/CredRead/CredDelete.
+ * Payload is passed on stdin to PowerShell — never as argv.
+ */
+/** CRED_MAX_CREDENTIAL_BLOB_SIZE is 5*512 = 2560. */
+export declare const WINDOWS_CRED_MAX_BYTES = 2560;
+export declare const WINDOWS_CRED_PS1 = "# Alphafox CLI \u2014 Windows Credential Manager helper (t101360)\nparam(\n  [Parameter(Mandatory = $true)][ValidateSet('write','read','delete')][string]$Action,\n  [Parameter(Mandatory = $true)][string]$Target\n)\n$ErrorActionPreference = 'Stop'\nAdd-Type -TypeDefinition @\"\nusing System;\nusing System.Runtime.InteropServices;\nnamespace AlphafoxCred {\n  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]\n  public struct CREDENTIAL {\n    public uint Flags;\n    public uint Type;\n    public string TargetName;\n    public string Comment;\n    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;\n    public uint CredentialBlobSize;\n    public IntPtr CredentialBlob;\n    public uint Persist;\n    public uint AttributeCount;\n    public IntPtr Attributes;\n    public string TargetAlias;\n    public string UserName;\n  }\n  public static class Native {\n    [DllImport(\"advapi32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    public static extern bool CredWrite(ref CREDENTIAL credential, uint flags);\n    [DllImport(\"advapi32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    public static extern bool CredRead(string target, uint type, uint flags, out IntPtr credentialPtr);\n    [DllImport(\"advapi32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    public static extern bool CredDelete(string target, uint type, uint flags);\n    [DllImport(\"advapi32.dll\", SetLastError = true)]\n    public static extern void CredFree(IntPtr credential);\n  }\n}\n\"@\n$CredTypeGeneric = 1\n$PersistLocalMachine = 2\nswitch ($Action) {\n  'write' {\n    $payload = [Console]::In.ReadToEnd()\n    $bytes = [Text.Encoding]::UTF8.GetBytes($payload)\n    if ($bytes.Length -gt 2560) { throw \"credential blob too large\" }\n    $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)\n    try {\n      [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)\n      $cred = New-Object AlphafoxCred.CREDENTIAL\n      $cred.Type = $CredTypeGeneric\n      $cred.TargetName = $Target\n      $cred.UserName = \"alphafox-cli\"\n      $cred.CredentialBlobSize = [uint32]$bytes.Length\n      $cred.CredentialBlob = $blob\n      $cred.Persist = $PersistLocalMachine\n      $ok = [AlphafoxCred.Native]::CredWrite([ref]$cred, 0)\n      if (-not $ok) {\n        throw \"CredWrite failed Win32=$([Runtime.InteropServices.Marshal]::GetLastWin32Error())\"\n      }\n    } finally {\n      [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)\n    }\n  }\n  'read' {\n    $ptr = [IntPtr]::Zero\n    $ok = [AlphafoxCred.Native]::CredRead($Target, $CredTypeGeneric, 0, [ref]$ptr)\n    if (-not $ok) { exit 2 }\n    try {\n      $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][AlphafoxCred.CREDENTIAL])\n      $size = [int]$cred.CredentialBlobSize\n      $bytes = New-Object byte[] $size\n      [Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $size)\n      [Console]::Out.Write([Text.Encoding]::UTF8.GetString($bytes))\n    } finally {\n      [AlphafoxCred.Native]::CredFree($ptr)\n    }\n  }\n  'delete' {\n    [void][AlphafoxCred.Native]::CredDelete($Target, $CredTypeGeneric, 0)\n  }\n}\n";
+export declare function windowsCredentialTarget(profile: string): string;
+export declare function windowsPowershellBin(env?: NodeJS.ProcessEnv): string;
+export declare function windowsCredentialWrite(profile: string, payload: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function windowsCredentialRead(profile: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function windowsCredentialDelete(profile: string, env?: NodeJS.ProcessEnv): void;
+export declare function windowsCredentialAvailable(env?: NodeJS.ProcessEnv): boolean;