@axtary/cli 0.1.0 → 0.2.0

package/dist/codex-hook.js

@@ -0,0 +1,259 @@
+import { parseNormalizedAction, } from "@axtary/actionpass";
+import { authorizeRank, DENY_RANK, DEFAULT_HOOK_TIMEOUT_MS, DEFAULT_PROXY_URL, errorReason, postAuthorize, workspaceRelativePath, } from "./claude-code-hook.js";
+import { classifyMcpFilesystemTool } from "./mcp-fs-normalize.js";
+import { classifyShellFileOps, } from "./shell-file-normalize.js";
+export { classifyShellCommand, classifyShellFileOps } from "./shell-file-normalize.js";
+// Codex CLI runtime-hook adapter (mega-plan M8.4). Codex calls a configured
+// `PreToolUse` hook before it runs a tool; the hook reads a JSON payload on
+// stdin and returns a decision. Codex's hook contract is Claude-Code-shaped —
+// it emits the same `hookSpecificOutput.permissionDecision` object — so the
+// output side mirrors the Claude hook exactly. Verified against the official
+// Codex hooks docs (2026-06-26).
+//
+// What differs from Claude/Cursor: Codex's reliable hook surface is the SHELL
+// (`Bash`) tool, whose `tool_input.command` is a shell command string — not a
+// file path. So the core work here is mapping a file-touching shell command
+// (and, best-effort, `apply_patch` edits and MCP filesystem tools) onto the
+// same `github.contents.read/write` actions, so the existing secret/path policy
+// applies. Codex docs note hooks fire reliably for shell, less so for
+// apply_patch / most MCP tools — hence those are best-effort.
+//
+// Fail-closed: a step-up renders as a BLOCK on Codex (its PreToolUse contract
+// documents only allow/deny; we do not rely on an unverified "ask"), and any
+// error (bad payload / unreachable proxy) is an explicit deny.
+export const CODEX_HOOK_SCHEMA_VERSION = "axtary.codex_hook.v0";
+export function parseCodexHookPayload(payloadText) {
+    let raw;
+    try {
+        raw = JSON.parse(payloadText);
+    }
+    catch {
+        throw new Error("codex_hook_payload_invalid_json");
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("codex_hook_payload_not_object");
+    }
+    const record = raw;
+    const toolName = record.tool_name;
+    if (typeof toolName !== "string" || toolName.length === 0) {
+        throw new Error("codex_hook_tool_name_required");
+    }
+    const toolInput = record.tool_input &&
+        typeof record.tool_input === "object" &&
+        !Array.isArray(record.tool_input)
+        ? record.tool_input
+        : {};
+    return {
+        hookEventName: typeof record.hook_event_name === "string" ? record.hook_event_name : null,
+        sessionId: typeof record.session_id === "string" ? record.session_id : null,
+        cwd: typeof record.cwd === "string" ? record.cwd : null,
+        toolName,
+        toolInput,
+    };
+}
+const SHELL_TOOLS = new Set(["Bash", "shell", "local_shell"]);
+// Codex apply_patch envelope headers name the files touched.
+const APPLY_PATCH_FILE_RE = /^\*\*\*\s+(?:Add|Update|Delete)\s+File:\s+(.+?)\s*$/gm;
+function applyPatchPaths(command) {
+    const paths = [];
+    let match;
+    APPLY_PATCH_FILE_RE.lastIndex = 0;
+    while ((match = APPLY_PATCH_FILE_RE.exec(command))) {
+        paths.push(match[1]);
+    }
+    return paths;
+}
+function buildContentAction(op, payload, options, sourceTool) {
+    const path = workspaceRelativePath(op.path, payload.cwd);
+    const repoResource = options.repoResource ?? "repo:local/workspace";
+    const taskId = payload.sessionId
+        ? `codex:${payload.sessionId.slice(0, 12)}`
+        : "codex:session";
+    const base = {
+        actor: {
+            agentId: "agent:codex",
+            humanOwner: options.humanOwner ?? "user:local-developer",
+            runtime: "codex",
+        },
+        intent: {
+            taskId,
+            declaredGoal: `Codex ${payload.toolName} tool call`,
+        },
+    };
+    if (op.kind === "read") {
+        return parseNormalizedAction({
+            ...base,
+            capability: {
+                tool: "github.contents.read",
+                resource: repoResource,
+                payload: { path, source: "codex-hook", codexTool: sourceTool },
+            },
+        });
+    }
+    return parseNormalizedAction({
+        ...base,
+        capability: {
+            tool: "github.contents.write",
+            resource: repoResource,
+            payload: {
+                path,
+                branch: options.branch ?? "workspace",
+                source: "codex-hook",
+                codexTool: sourceTool,
+            },
+        },
+    });
+}
+export function normalizeCodexToolCall(payload, options = {}) {
+    // Shell (the reliable Codex surface): map every file op a command performs,
+    // so `cp secret dest` governs the source read AND the destination write.
+    if (SHELL_TOOLS.has(payload.toolName)) {
+        const command = typeof payload.toolInput.command === "string"
+            ? payload.toolInput.command
+            : "";
+        const ops = command ? classifyShellFileOps(command) : [];
+        if (ops.length === 0) {
+            return { mapped: false, reason: `codex_shell_no_file_op:${payload.toolName}` };
+        }
+        return mappedActions(ops.map((op) => buildContentAction(op, payload, options, payload.toolName)));
+    }
+    // apply_patch (best-effort): the envelope names every file it edits; govern
+    // all of them (the run loop denies if any is denied).
+    if (payload.toolName === "apply_patch") {
+        const command = typeof payload.toolInput.command === "string"
+            ? payload.toolInput.command
+            : "";
+        const paths = command ? applyPatchPaths(command) : [];
+        if (paths.length === 0) {
+            return { mapped: false, reason: "codex_apply_patch_no_files" };
+        }
+        return mappedActions(paths.map((path) => buildContentAction({ kind: "write", path }, payload, options, payload.toolName)));
+    }
+    // MCP filesystem tools (best-effort; Codex MCP hooks fire less reliably).
+    const classified = classifyMcpFilesystemTool(payload.toolName);
+    if (classified) {
+        const rawPath = payload.toolInput[classified.pathField];
+        if (typeof rawPath === "string" && rawPath.length > 0) {
+            return mappedActions([
+                buildContentAction({ kind: classified.kind, path: rawPath }, payload, options, payload.toolName),
+            ]);
+        }
+    }
+    return { mapped: false, reason: `codex_tool_unmapped:${payload.toolName}` };
+}
+function mappedActions(actions) {
+    return { mapped: true, action: actions[0], actions };
+}
+export async function runCodexHook(input) {
+    let payload;
+    try {
+        payload = parseCodexHookPayload(input.payloadText);
+    }
+    catch (error) {
+        return decisionResult(null, null, "deny", [
+            `Axtary blocked this tool call: hook payload could not be parsed (${errorReason(error)}). Protected actions fail closed.`,
+        ]);
+    }
+    const normalization = normalizeCodexToolCall(payload, {
+        repoResource: input.repoResource,
+        humanOwner: input.humanOwner,
+        branch: input.branch,
+    });
+    if (!normalization.mapped) {
+        return {
+            schemaVersion: CODEX_HOOK_SCHEMA_VERSION,
+            status: "no_opinion",
+            tool: payload.toolName,
+            normalizedTool: null,
+            reason: normalization.reason,
+            output: null,
+            exitCode: 0,
+        };
+    }
+    const proxyUrl = (input.proxyUrl ?? DEFAULT_PROXY_URL).replace(/\/$/, "");
+    const fetchImpl = input.fetch ?? globalThis.fetch;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+    // Authorize every governed op; the most restrictive decision wins
+    // (deny > step_up > allow) and a hard deny short-circuits. Fail-closed.
+    let best = null;
+    for (const action of normalization.actions) {
+        let response;
+        try {
+            response = await postAuthorize(fetchImpl, `${proxyUrl}/authorize`, action, timeoutMs);
+        }
+        catch (error) {
+            return decisionResult(payload.toolName, action.capability.tool, "deny", [
+                `Axtary blocked ${action.capability.tool}: local proxy unreachable at ${proxyUrl} (${errorReason(error)}).`,
+                "Start it with: axtary proxy --config axtary.yml",
+            ]);
+        }
+        const rank = authorizeRank(response.status);
+        if (!best || rank > best.rank) {
+            best = { action, response, rank };
+        }
+        if (rank === DENY_RANK)
+            break;
+    }
+    const response = best.response;
+    const normalizedTool = best.action.capability.tool;
+    const reasons = response.decision?.reasons ?? [];
+    const hints = response.hints ?? [];
+    const summary = response.explanation?.summary ?? reasons.join(", ");
+    const ledgerLine = typeof response.ledger?.lineNumber === "number"
+        ? ` Ledger line ${response.ledger.lineNumber}.`
+        : "";
+    if (response.status === "authorized") {
+        // Live-verified against Codex CLI v0.142.3: emitting
+        // `permissionDecision:"allow"` errors the hook ("unsupported
+        // permissionDecision:allow") and Codex then fails open. For an allow we emit
+        // NO decision so Codex proceeds normally; the decision is already recorded by
+        // the /authorize call above (only `deny` is honored on PreToolUse).
+        return {
+            schemaVersion: CODEX_HOOK_SCHEMA_VERSION,
+            status: "allow",
+            tool: payload.toolName,
+            normalizedTool,
+            reason: `Axtary authorized ${normalizedTool}: ${summary}${ledgerLine}`,
+            output: null,
+            exitCode: 0,
+        };
+    }
+    if (response.status === "step_up") {
+        // Codex PreToolUse honors only `deny`; we block step-up (fail closed) rather
+        // than rely on an unverified interactive "ask", and point to the
+        // payload-bound approval path.
+        return decisionResult(payload.toolName, normalizedTool, "step_up", [
+            `Axtary blocked ${normalizedTool} pending human step-up approval: ${summary}`,
+            ...hints,
+            "Approve the exact payload via the Axtary dashboard / proxy approval path before re-running.",
+            ledgerLine.trim(),
+        ]);
+    }
+    return decisionResult(payload.toolName, normalizedTool, "deny", [
+        `Axtary blocked ${normalizedTool}: ${summary}`,
+        ...hints,
+        ledgerLine.trim(),
+    ]);
+}
+// Codex PreToolUse honors only `permissionDecision:"deny"` (allow/ask are
+// rejected as unsupported, v0.142.3), so every blocking decision — an explicit
+// deny, a fail-closed step-up, or an error — renders as a deny.
+function decisionResult(tool, normalizedTool, status, reasonParts) {
+    const reason = reasonParts.filter((part) => part.length > 0).join(" ");
+    return {
+        schemaVersion: CODEX_HOOK_SCHEMA_VERSION,
+        status,
+        tool,
+        normalizedTool,
+        reason,
+        output: JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: reason,
+            },
+        }),
+        exitCode: 0,
+    };
+}
+//# sourceMappingURL=codex-hook.js.map

package/dist/codex-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-hook.js","sourceRoot":"","sources":["../src/codex-hook.ts"],"names":[],"mappings":"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"}

package/dist/credentials.d.ts

@@ -0,0 +1,101 @@
+import { spawnSync } from "node:child_process";
+export declare const CREDENTIALS_SCHEMA_VERSION = "axtary.credentials.v0";
+export type CredentialSecretBackendName = "keychain" | "file";
+/** Non-secret record of a connected provider. Safe to print / show in a UI. */
+export type CredentialMetadata = {
+    provider: string;
+    type: "oauth" | "token";
+    source: "oauth" | "manual";
+    scopes: string[];
+    obtainedAt: string;
+    expiresAt: string | null;
+    /** A non-secret label like a Slack team id or workspace name. */
+    account: string | null;
+    /** Non-secret provider routing data, for example Jira cloudId and siteUrl. */
+    context?: Record<string, string>;
+    secretBackend: CredentialSecretBackendName;
+};
+/** Full credential including the secret material. Never logged or serialized to status output. */
+export type StoredCredential = CredentialMetadata & {
+    accessToken: string;
+    refreshToken: string | null;
+};
+export type CredentialSecret = {
+    accessToken: string;
+    refreshToken: string | null;
+};
+/** Pluggable secret storage so the keychain can be swapped for a file (or an in-memory fake in tests). */
+export type CredentialSecretBackend = {
+    readonly name: CredentialSecretBackendName;
+    get(provider: string): Promise<CredentialSecret | null>;
+    set(provider: string, secret: CredentialSecret): Promise<void>;
+    delete(provider: string): Promise<void>;
+};
+/** True when the macOS `security` keychain CLI is usable. */
+export declare function macKeychainAvailable(platform?: NodeJS.Platform, run?: typeof spawnSync): boolean;
+/** macOS keychain-backed secret store (generic passwords under a per-provider service). */
+export declare function createMacKeychainSecretBackend(run?: typeof spawnSync): CredentialSecretBackend;
+export type CredentialStoreOptions = {
+    baseDir?: string;
+    secretBackend?: CredentialSecretBackend;
+    platform?: NodeJS.Platform;
+    run?: typeof spawnSync;
+};
+export declare class CredentialStore {
+    private readonly baseDir;
+    private readonly filePath;
+    private readonly secretBackend;
+    constructor(options?: CredentialStoreOptions);
+    /** The backend chosen for new writes (so callers can report where secrets land). */
+    secretBackendName(): CredentialSecretBackendName;
+    get(provider: string): Promise<StoredCredential | null>;
+    set(input: {
+        provider: string;
+        type: CredentialMetadata["type"];
+        source: CredentialMetadata["source"];
+        accessToken: string;
+        refreshToken?: string | null;
+        scopes?: string[];
+        expiresAt?: string | null;
+        account?: string | null;
+        context?: Record<string, string>;
+    }): Promise<CredentialMetadata>;
+    /**
+     * Write the secret to the preferred backend, then read it back and confirm it
+     * round-trips. If the keychain write did not actually persist a readable
+     * secret — e.g. macOS `security add-generic-password -w` reads the password
+     * from the controlling TTY rather than our piped stdin, storing garbage — fall
+     * back to the portable 0600 file backend instead of silently storing an
+     * unreadable credential. The secret value is never placed on a process argv.
+     */
+    private writeSecretVerified;
+    delete(provider: string): Promise<boolean>;
+    /** Metadata only — never returns secret material. */
+    list(): Promise<CredentialMetadata[]>;
+    private fileSecretBackend;
+    private read;
+    private write;
+}
+/** True once an OAuth credential has lapsed (with a small safety skew). */
+export declare function credentialExpired(credential: Pick<StoredCredential, "expiresAt">, now?: number, skewMs?: number): boolean;
+/**
+ * Resolve a provider token with the broker taking precedence over a raw env
+ * var. A connected, non-expired stored credential wins; otherwise we fall back
+ * to `env[tokenEnv]` (which itself may be populated by a secret manager — see
+ * https://docs.axtary.com/credentials). Returns the token and where it came from.
+ */
+export declare function resolveProviderToken(input: {
+    provider: string;
+    tokenEnv: string;
+    env: Record<string, string | undefined>;
+    store: CredentialStore | null;
+    now?: number;
+}): Promise<{
+    token: string | undefined;
+    source: "broker" | "env" | "missing";
+}>;
+export declare function loadCredentialStore(options?: CredentialStoreOptions): CredentialStore;
+export declare function credentialsBaseDir(): string;
+export declare function credentialsLocation(baseDir?: string): string;
+export declare function removeCredentialsFile(baseDir: string): Promise<void>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}

package/dist/credentials.js

@@ -0,0 +1,277 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// Axtary local credential broker.
+//
+// PRD §10.1: the credential broker runs locally so provider secrets stay on the
+// customer's machine and never reach the hosted control plane. This module is
+// that broker's storage layer: it keeps a 0600 metadata file (which providers
+// are connected, scopes, expiry — never the secret) and stores the actual access
+// tokens in the OS keychain when available, falling back to the same 0600 file.
+//
+// The metadata/secret split means `axtary connections` (status) is secret-safe
+// by construction: it only ever reads metadata, never a token.
+export const CREDENTIALS_SCHEMA_VERSION = "axtary.credentials.v0";
+const KEYCHAIN_SERVICE_PREFIX = "axtary:credential:";
+const KEYCHAIN_ACCOUNT = "axtary";
+function defaultBaseDir() {
+    return process.env.AXTARY_HOME ?? join(homedir(), ".axtary");
+}
+function credentialsFilePath(baseDir) {
+    return join(baseDir, "credentials.json");
+}
+/** True when the macOS `security` keychain CLI is usable. */
+export function macKeychainAvailable(platform = process.platform, run = spawnSync) {
+    if (platform !== "darwin")
+        return false;
+    const probe = run("security", ["help"], { stdio: "ignore" });
+    return probe.status === 0 || probe.status === 1; // `security help` exits non-zero but exists
+}
+/** macOS keychain-backed secret store (generic passwords under a per-provider service). */
+export function createMacKeychainSecretBackend(run = spawnSync) {
+    const service = (provider) => `${KEYCHAIN_SERVICE_PREFIX}${provider}`;
+    return {
+        name: "keychain",
+        async get(provider) {
+            const result = run("security", ["find-generic-password", "-a", KEYCHAIN_ACCOUNT, "-s", service(provider), "-w"], { encoding: "utf8" });
+            if (result.status !== 0 || typeof result.stdout !== "string")
+                return null;
+            try {
+                return JSON.parse(result.stdout.trim());
+            }
+            catch {
+                return null;
+            }
+        },
+        async set(provider, secret) {
+            // Pass the secret on stdin, never on argv. `-w` with no value makes
+            // `security` read the password from the prompt (here, stdin), which
+            // prompts twice ("password" + "retype"), so the payload is written twice.
+            // This keeps the token off the `security` process command line, where
+            // `ps` would otherwise expose it to any same-user process. `-U` updates an
+            // existing item.
+            const payload = JSON.stringify(secret);
+            const result = run("security", [
+                "add-generic-password",
+                "-U",
+                "-a",
+                KEYCHAIN_ACCOUNT,
+                "-s",
+                service(provider),
+                "-w",
+            ], { input: `${payload}\n${payload}\n`, stdio: ["pipe", "ignore", "ignore"] });
+            if (result.status !== 0) {
+                throw new Error("credential_keychain_write_failed");
+            }
+        },
+        async delete(provider) {
+            run("security", ["delete-generic-password", "-a", KEYCHAIN_ACCOUNT, "-s", service(provider)], { stdio: "ignore" });
+        },
+    };
+}
+/**
+ * Resolve the secret backend: explicit override wins; otherwise keychain on
+ * macOS when available, else the 0600 file. `AXTARY_CREDENTIAL_BACKEND=file`
+ * forces the portable file backend (useful in CI / containers).
+ */
+function resolveSecretBackend(options, fileBackend) {
+    if (options.secretBackend)
+        return options.secretBackend;
+    if (process.env.AXTARY_CREDENTIAL_BACKEND === "file")
+        return fileBackend;
+    if (macKeychainAvailable(options.platform, options.run)) {
+        return createMacKeychainSecretBackend(options.run);
+    }
+    return fileBackend;
+}
+export class CredentialStore {
+    baseDir;
+    filePath;
+    secretBackend;
+    constructor(options = {}) {
+        this.baseDir = options.baseDir ?? defaultBaseDir();
+        this.filePath = credentialsFilePath(this.baseDir);
+        this.secretBackend = resolveSecretBackend(options, this.fileSecretBackend());
+    }
+    /** The backend chosen for new writes (so callers can report where secrets land). */
+    secretBackendName() {
+        return this.secretBackend.name;
+    }
+    async get(provider) {
+        const file = await this.read();
+        const metadata = file.credentials[provider];
+        if (!metadata)
+            return null;
+        const backend = metadata.secretBackend === this.secretBackend.name
+            ? this.secretBackend
+            : metadata.secretBackend === "file"
+                ? this.fileSecretBackend()
+                : createMacKeychainSecretBackend();
+        const secret = await backend.get(provider);
+        if (!secret)
+            return null;
+        return { ...metadata, accessToken: secret.accessToken, refreshToken: secret.refreshToken };
+    }
+    async set(input) {
+        const usedBackend = await this.writeSecretVerified(input.provider, {
+            accessToken: input.accessToken,
+            refreshToken: input.refreshToken ?? null,
+        });
+        const metadata = {
+            provider: input.provider,
+            type: input.type,
+            source: input.source,
+            scopes: input.scopes ?? [],
+            obtainedAt: new Date().toISOString(),
+            expiresAt: input.expiresAt ?? null,
+            account: input.account ?? null,
+            context: input.context,
+            secretBackend: usedBackend.name,
+        };
+        const file = await this.read();
+        file.credentials[input.provider] = metadata;
+        if (usedBackend.name !== "file" && file.secrets) {
+            delete file.secrets[input.provider];
+        }
+        await this.write(file);
+        return metadata;
+    }
+    /**
+     * Write the secret to the preferred backend, then read it back and confirm it
+     * round-trips. If the keychain write did not actually persist a readable
+     * secret — e.g. macOS `security add-generic-password -w` reads the password
+     * from the controlling TTY rather than our piped stdin, storing garbage — fall
+     * back to the portable 0600 file backend instead of silently storing an
+     * unreadable credential. The secret value is never placed on a process argv.
+     */
+    async writeSecretVerified(provider, secret) {
+        const primary = this.secretBackend;
+        try {
+            await primary.set(provider, secret);
+            const readBack = await primary.get(provider);
+            if (readBack &&
+                readBack.accessToken === secret.accessToken &&
+                (readBack.refreshToken ?? null) === (secret.refreshToken ?? null)) {
+                return primary;
+            }
+        }
+        catch {
+            // Fall through to the file backend below.
+        }
+        if (primary.name === "file") {
+            throw new Error("credential_secret_write_failed");
+        }
+        // The preferred backend did not round-trip. Remove any partial item it left,
+        // then store the secret in the verifiable 0600 file backend.
+        try {
+            await primary.delete(provider);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        const fileBackend = this.fileSecretBackend();
+        await fileBackend.set(provider, secret);
+        return fileBackend;
+    }
+    async delete(provider) {
+        const file = await this.read();
+        const metadata = file.credentials[provider];
+        if (!metadata)
+            return false;
+        const backend = metadata.secretBackend === "file" ? this.fileSecretBackend() : createMacKeychainSecretBackend();
+        await backend.delete(provider);
+        delete file.credentials[provider];
+        if (file.secrets)
+            delete file.secrets[provider];
+        await this.write(file);
+        return true;
+    }
+    /** Metadata only — never returns secret material. */
+    async list() {
+        const file = await this.read();
+        return Object.values(file.credentials).sort((a, b) => a.provider.localeCompare(b.provider));
+    }
+    fileSecretBackend() {
+        return {
+            name: "file",
+            get: async (provider) => {
+                const file = await this.read();
+                return file.secrets?.[provider] ?? null;
+            },
+            set: async (provider, secret) => {
+                const file = await this.read();
+                file.secrets = file.secrets ?? {};
+                file.secrets[provider] = secret;
+                await this.write(file);
+            },
+            delete: async (provider) => {
+                const file = await this.read();
+                if (file.secrets) {
+                    delete file.secrets[provider];
+                    await this.write(file);
+                }
+            },
+        };
+    }
+    async read() {
+        try {
+            const raw = await readFile(this.filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            return {
+                version: parsed.version ?? CREDENTIALS_SCHEMA_VERSION,
+                credentials: parsed.credentials ?? {},
+                secrets: parsed.secrets,
+            };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return { version: CREDENTIALS_SCHEMA_VERSION, credentials: {} };
+            }
+            throw error;
+        }
+    }
+    async write(file) {
+        await mkdir(this.baseDir, { recursive: true, mode: 0o700 });
+        await writeFile(this.filePath, `${JSON.stringify({ ...file, version: CREDENTIALS_SCHEMA_VERSION }, null, 2)}\n`, { mode: 0o600 });
+    }
+}
+/** True once an OAuth credential has lapsed (with a small safety skew). */
+export function credentialExpired(credential, now = Date.now(), skewMs = 30_000) {
+    if (!credential.expiresAt)
+        return false;
+    return new Date(credential.expiresAt).getTime() - skewMs <= now;
+}
+/**
+ * Resolve a provider token with the broker taking precedence over a raw env
+ * var. A connected, non-expired stored credential wins; otherwise we fall back
+ * to `env[tokenEnv]` (which itself may be populated by a secret manager — see
+ * https://docs.axtary.com/credentials). Returns the token and where it came from.
+ */
+export async function resolveProviderToken(input) {
+    if (input.store) {
+        const credential = await input.store.get(input.provider);
+        if (credential && !credentialExpired(credential, input.now)) {
+            return { token: credential.accessToken, source: "broker" };
+        }
+    }
+    const envToken = input.env[input.tokenEnv];
+    if (envToken)
+        return { token: envToken, source: "env" };
+    return { token: undefined, source: "missing" };
+}
+export function loadCredentialStore(options = {}) {
+    return new CredentialStore(options);
+}
+export function credentialsBaseDir() {
+    return defaultBaseDir();
+}
+export function credentialsLocation(baseDir = defaultBaseDir()) {
+    return credentialsFilePath(baseDir);
+}
+// Re-exported for callers that need to clean up a base dir in tests.
+export async function removeCredentialsFile(baseDir) {
+    await rm(credentialsFilePath(baseDir), { force: true });
+    await rm(dirname(credentialsFilePath(baseDir)), { force: true, recursive: true });
+}
+//# sourceMappingURL=credentials.js.map