@pleri/olam-cli 0.1.195 → 0.1.198

package/dist/lib/auth-backend.d.ts

@@ -0,0 +1,168 @@
+/**
+ * auth-backend — shared backend resolver for `olam auth` subcommands.
+ *
+ * Phase B (cloud-only-vault) flips the default credential backend across the
+ * full CLI auth surface from local (`auth-service` container at 127.0.0.1:9999)
+ * to remote (cloud auth-worker, e.g. auth-worker.kaluga.co). This helper is the
+ * single seam every auth subcommand calls to determine which backend its
+ * action should target.
+ *
+ * Resolution order (mirrors docs/architecture/cloud-only-vault.md §2 for
+ * `withCredential`, adapted to the CLI's --local / --remote flag surface):
+ *
+ *   1. `--local` AND `--remote` (any form) both passed → throw
+ *      `ConflictingBackendFlags` (exit 1 in the action handler).
+ *   2. `--local` alone → backend='local', emitDeprecationWarning=true
+ *      (operator explicitly opted out of the new default; warn so they know
+ *      the flag will eventually be removed).
+ *   3. `--remote` (boolean) alone → backend='remote', no warning.
+ *   4. `--remote <url>` (string form, back-compat) → backend='remote',
+ *      explicitRemoteUrl=<url>. No warning. Pre-Phase-B operators were
+ *      already opting in by typing the URL.
+ *   5. `OLAM_CREDENTIAL_BACKEND=local` env → backend='local', NO warning
+ *      (env-set is the operator's host-wide preference; pestering them on
+ *      every command is noise).
+ *   6. `OLAM_CREDENTIAL_BACKEND=remote` env → backend='remote', no warning.
+ *   7. Default → backend='remote' (the Phase B flip).
+ *
+ * The Phase A `withCredential` selector at
+ * `packages/auth-client/src/backends/selector.ts` honours the same env var
+ * for the agent runtime; this helper keeps the CLI surface symmetric.
+ *
+ * ─── Subcommand audit (current backend coupling, pre-Phase-B) ───
+ *
+ * Every existing `olam auth` subcommand and the code path it currently uses
+ * to reach a credential backend. Each is a future caller of `requireBackend`
+ * once B2 / B4 land. References are `packages/cli/src/commands/auth.ts` line
+ * numbers at HEAD = 3a74bb62 (Phase A complete).
+ *
+ *   login            (auth.ts:170-306) — `--remote <url>` already wired to
+ *                    auth-remote.ts `remoteOAuthStart` (auth.ts:178-238).
+ *                    Local path (auth.ts:240-305) uses `AuthClient` against
+ *                    127.0.0.1:9999. B2 flips the default + adds the
+ *                    interactive confirm prompt + deprecation warning.
+ *
+ *   list             (auth.ts:416-509) — `--remote <url>` wired to
+ *                    `remoteListAccounts` + `remoteListServiceTokens`
+ *                    (auth.ts:423-464). Local path (auth.ts:466-508) uses
+ *                    `AuthClient.status()`. B4 flips default + adds 30s TTL
+ *                    cache + `--no-cache`.
+ *
+ *   refresh          (auth.ts:323-361) — LOCAL ONLY today. Reads config to
+ *                    detect k8s substrate, then calls `AuthClient.refreshAccount`.
+ *                    No --remote path exists yet. B4 adds a default-remote
+ *                    branch (token-refresh via cloud DO) + `--local` opt-out.
+ *
+ *   disable          (auth.ts:124-137) — LOCAL ONLY (AuthClient.disableAccount).
+ *                    B4 adds default-remote branch.
+ *
+ *   enable           (auth.ts:139-152) — LOCAL ONLY (AuthClient.enableAccount).
+ *                    B4 adds default-remote branch.
+ *
+ *   status           (auth.ts:116-122 — deprecated alias for `olam services
+ *                    status`) AND auth-status.ts:runAuthStatus (the real
+ *                    status implementation invoked by other code paths).
+ *                    LOCAL ONLY (AuthClient.status). B7 doctor sweep covers
+ *                    the cross-backend health view.
+ *
+ *   list-json        (auth-list-json.ts) — pure serialiser invoked from
+ *                    `list --json` (auth.ts:481-484). Operates on already-
+ *                    fetched local data. B4 keeps it local-only for now
+ *                    (the JSON wire shape is a local-vault contract).
+ *
+ *   logout           (auth.ts:308-321) — LOCAL ONLY (AuthClient.deleteAccount).
+ *                    Out of Phase B scope; tracked for a follow-up plan.
+ *
+ *   remove           (auth.ts:154-167) — LOCAL ONLY (AuthClient.deleteAccount).
+ *                    Out of Phase B scope.
+ *
+ *   bind-service-token    (auth.ts:363-413) — remote-only by design (CF
+ *                    Access service-token binding). No `requireBackend` needed.
+ *
+ *   migrate-to-remote      (auth.ts:511-543) — bridging command from e6; B3
+ *                    replaces this with `olam auth migrate`.
+ *
+ *   rotate-service-token   (auth.ts:545-572) — remote-only. No change.
+ *
+ *   doctor                  (auth.ts:574-614) — remote-only probe today; B7
+ *                    extends to dual-backend health.
+ *
+ *   issue-anthropic-token  (auth.ts:616-684) — remote-only. No change.
+ *
+ *   list-anthropic-tokens  (auth.ts:686-740) — remote-only. No change.
+ *
+ *   revoke-anthropic-token (auth.ts:742-773) — remote-only. No change.
+ *
+ *   upgrade                 (registered via registerAuthUpgrade(auth) at
+ *                    auth.ts:775) — separate file; out of Phase B scope.
+ *
+ * Subcommands flagged "LOCAL ONLY" today are the ones B4 will refactor to
+ * route through `requireBackend`. The "remote-only by design" subcommands
+ * (bind-service-token, doctor, issue/list/revoke anthropic tokens) keep
+ * their `--remote` required flag — they have no local equivalent.
+ */
+/** Discriminant for the resolved credential backend. */
+export type Backend = 'local' | 'remote';
+/**
+ * Parsed CLI flags relevant to backend selection. Commander.js gives us
+ * `--remote` as boolean OR string depending on the option definition; we
+ * support both forms so subcommands can choose:
+ *
+ *   .option('--remote',         '...')  // boolean
+ *   .option('--remote <url>',   '...')  // string (back-compat)
+ *
+ * Mixed-cardinality subcommands (login, list) historically used the string
+ * form; future cleanup may collapse to boolean once the artifact-based
+ * default URL discovery (Phase A `~/.olam/cloud-bearer.json`) covers all
+ * call sites.
+ */
+export interface BackendResolutionArgs {
+    readonly local?: boolean;
+    readonly remote?: boolean | string;
+}
+export interface BackendResolution {
+    readonly backend: Backend;
+    /**
+     * When backend='remote' and the operator passed `--remote <url>` (string
+     * form), the explicit URL. Subcommands prefer this over auto-discovered
+     * defaults (env / artifact / hard-coded fallback).
+     */
+    readonly explicitRemoteUrl?: string;
+    /**
+     * True when the operator passed `--local` on the CLI. Used by callers to
+     * emit a single deprecation-warning line to stderr before proceeding.
+     * False for `OLAM_CREDENTIAL_BACKEND=local` — that's a host-wide opt-out
+     * the operator already understands, no need to nag every command.
+     */
+    readonly emitDeprecationWarning: boolean;
+}
+/**
+ * Thrown when the operator passes `--local` AND `--remote` to the same
+ * subcommand. Both flags express intent — there's no sane way to choose
+ * one silently. Action handlers should `printError(err.message); exit 1`.
+ */
+export declare class ConflictingBackendFlags extends Error {
+    constructor();
+}
+/**
+ * Resolve which credential backend a subcommand should target.
+ *
+ * See the resolution-order comment at the top of this file for the seven
+ * branches. Pure function — no I/O, no side effects, no caching. Cheap
+ * enough to call once per subcommand action.
+ *
+ * Reads `process.env.OLAM_CREDENTIAL_BACKEND` directly so callers don't
+ * have to thread it through.
+ */
+export declare function requireBackend(args: BackendResolutionArgs): BackendResolution;
+/**
+ * Emit a single deprecation-warning line to the supplied stream. Centralised
+ * so the wording stays consistent across every `olam auth` subcommand that
+ * accepts `--local`. Returns void; callers may ignore the return.
+ *
+ * Callers should only invoke this when
+ * `resolution.emitDeprecationWarning === true` — gating belongs to the
+ * caller so test scaffolding can introspect the resolution without IO.
+ */
+export declare function emitDeprecationWarning(stderr: NodeJS.WritableStream): void;
+//# sourceMappingURL=auth-backend.d.ts.map

package/dist/lib/auth-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-backend.d.ts","sourceRoot":"","sources":["../../src/lib/auth-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,wDAAwD;AACxD,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAwC7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAK1E"}

package/dist/lib/auth-backend.js

@@ -0,0 +1,172 @@
+/**
+ * auth-backend — shared backend resolver for `olam auth` subcommands.
+ *
+ * Phase B (cloud-only-vault) flips the default credential backend across the
+ * full CLI auth surface from local (`auth-service` container at 127.0.0.1:9999)
+ * to remote (cloud auth-worker, e.g. auth-worker.kaluga.co). This helper is the
+ * single seam every auth subcommand calls to determine which backend its
+ * action should target.
+ *
+ * Resolution order (mirrors docs/architecture/cloud-only-vault.md §2 for
+ * `withCredential`, adapted to the CLI's --local / --remote flag surface):
+ *
+ *   1. `--local` AND `--remote` (any form) both passed → throw
+ *      `ConflictingBackendFlags` (exit 1 in the action handler).
+ *   2. `--local` alone → backend='local', emitDeprecationWarning=true
+ *      (operator explicitly opted out of the new default; warn so they know
+ *      the flag will eventually be removed).
+ *   3. `--remote` (boolean) alone → backend='remote', no warning.
+ *   4. `--remote <url>` (string form, back-compat) → backend='remote',
+ *      explicitRemoteUrl=<url>. No warning. Pre-Phase-B operators were
+ *      already opting in by typing the URL.
+ *   5. `OLAM_CREDENTIAL_BACKEND=local` env → backend='local', NO warning
+ *      (env-set is the operator's host-wide preference; pestering them on
+ *      every command is noise).
+ *   6. `OLAM_CREDENTIAL_BACKEND=remote` env → backend='remote', no warning.
+ *   7. Default → backend='remote' (the Phase B flip).
+ *
+ * The Phase A `withCredential` selector at
+ * `packages/auth-client/src/backends/selector.ts` honours the same env var
+ * for the agent runtime; this helper keeps the CLI surface symmetric.
+ *
+ * ─── Subcommand audit (current backend coupling, pre-Phase-B) ───
+ *
+ * Every existing `olam auth` subcommand and the code path it currently uses
+ * to reach a credential backend. Each is a future caller of `requireBackend`
+ * once B2 / B4 land. References are `packages/cli/src/commands/auth.ts` line
+ * numbers at HEAD = 3a74bb62 (Phase A complete).
+ *
+ *   login            (auth.ts:170-306) — `--remote <url>` already wired to
+ *                    auth-remote.ts `remoteOAuthStart` (auth.ts:178-238).
+ *                    Local path (auth.ts:240-305) uses `AuthClient` against
+ *                    127.0.0.1:9999. B2 flips the default + adds the
+ *                    interactive confirm prompt + deprecation warning.
+ *
+ *   list             (auth.ts:416-509) — `--remote <url>` wired to
+ *                    `remoteListAccounts` + `remoteListServiceTokens`
+ *                    (auth.ts:423-464). Local path (auth.ts:466-508) uses
+ *                    `AuthClient.status()`. B4 flips default + adds 30s TTL
+ *                    cache + `--no-cache`.
+ *
+ *   refresh          (auth.ts:323-361) — LOCAL ONLY today. Reads config to
+ *                    detect k8s substrate, then calls `AuthClient.refreshAccount`.
+ *                    No --remote path exists yet. B4 adds a default-remote
+ *                    branch (token-refresh via cloud DO) + `--local` opt-out.
+ *
+ *   disable          (auth.ts:124-137) — LOCAL ONLY (AuthClient.disableAccount).
+ *                    B4 adds default-remote branch.
+ *
+ *   enable           (auth.ts:139-152) — LOCAL ONLY (AuthClient.enableAccount).
+ *                    B4 adds default-remote branch.
+ *
+ *   status           (auth.ts:116-122 — deprecated alias for `olam services
+ *                    status`) AND auth-status.ts:runAuthStatus (the real
+ *                    status implementation invoked by other code paths).
+ *                    LOCAL ONLY (AuthClient.status). B7 doctor sweep covers
+ *                    the cross-backend health view.
+ *
+ *   list-json        (auth-list-json.ts) — pure serialiser invoked from
+ *                    `list --json` (auth.ts:481-484). Operates on already-
+ *                    fetched local data. B4 keeps it local-only for now
+ *                    (the JSON wire shape is a local-vault contract).
+ *
+ *   logout           (auth.ts:308-321) — LOCAL ONLY (AuthClient.deleteAccount).
+ *                    Out of Phase B scope; tracked for a follow-up plan.
+ *
+ *   remove           (auth.ts:154-167) — LOCAL ONLY (AuthClient.deleteAccount).
+ *                    Out of Phase B scope.
+ *
+ *   bind-service-token    (auth.ts:363-413) — remote-only by design (CF
+ *                    Access service-token binding). No `requireBackend` needed.
+ *
+ *   migrate-to-remote      (auth.ts:511-543) — bridging command from e6; B3
+ *                    replaces this with `olam auth migrate`.
+ *
+ *   rotate-service-token   (auth.ts:545-572) — remote-only. No change.
+ *
+ *   doctor                  (auth.ts:574-614) — remote-only probe today; B7
+ *                    extends to dual-backend health.
+ *
+ *   issue-anthropic-token  (auth.ts:616-684) — remote-only. No change.
+ *
+ *   list-anthropic-tokens  (auth.ts:686-740) — remote-only. No change.
+ *
+ *   revoke-anthropic-token (auth.ts:742-773) — remote-only. No change.
+ *
+ *   upgrade                 (registered via registerAuthUpgrade(auth) at
+ *                    auth.ts:775) — separate file; out of Phase B scope.
+ *
+ * Subcommands flagged "LOCAL ONLY" today are the ones B4 will refactor to
+ * route through `requireBackend`. The "remote-only by design" subcommands
+ * (bind-service-token, doctor, issue/list/revoke anthropic tokens) keep
+ * their `--remote` required flag — they have no local equivalent.
+ */
+/**
+ * Thrown when the operator passes `--local` AND `--remote` to the same
+ * subcommand. Both flags express intent — there's no sane way to choose
+ * one silently. Action handlers should `printError(err.message); exit 1`.
+ */
+export class ConflictingBackendFlags extends Error {
+    constructor() {
+        super('Cannot specify both --local and --remote. Pick one.');
+        this.name = 'ConflictingBackendFlags';
+    }
+}
+/**
+ * Resolve which credential backend a subcommand should target.
+ *
+ * See the resolution-order comment at the top of this file for the seven
+ * branches. Pure function — no I/O, no side effects, no caching. Cheap
+ * enough to call once per subcommand action.
+ *
+ * Reads `process.env.OLAM_CREDENTIAL_BACKEND` directly so callers don't
+ * have to thread it through.
+ */
+export function requireBackend(args) {
+    const localFlag = args.local === true;
+    const remoteFlag = args.remote === true || (typeof args.remote === 'string' && args.remote.length > 0);
+    // (1) Conflict — both flags explicit.
+    if (localFlag && remoteFlag) {
+        throw new ConflictingBackendFlags();
+    }
+    // (2) Explicit --local opt-out.
+    if (localFlag) {
+        return { backend: 'local', emitDeprecationWarning: true };
+    }
+    // (3) Explicit --remote (boolean).
+    if (args.remote === true) {
+        return { backend: 'remote', emitDeprecationWarning: false };
+    }
+    // (4) Explicit --remote <url> (string).
+    if (typeof args.remote === 'string' && args.remote.length > 0) {
+        return {
+            backend: 'remote',
+            explicitRemoteUrl: args.remote,
+            emitDeprecationWarning: false,
+        };
+    }
+    // (5) + (6) Env-set override.
+    const env = process.env['OLAM_CREDENTIAL_BACKEND'];
+    if (env === 'local') {
+        return { backend: 'local', emitDeprecationWarning: false };
+    }
+    if (env === 'remote') {
+        return { backend: 'remote', emitDeprecationWarning: false };
+    }
+    // (7) Default — Phase B flip: remote.
+    return { backend: 'remote', emitDeprecationWarning: false };
+}
+/**
+ * Emit a single deprecation-warning line to the supplied stream. Centralised
+ * so the wording stays consistent across every `olam auth` subcommand that
+ * accepts `--local`. Returns void; callers may ignore the return.
+ *
+ * Callers should only invoke this when
+ * `resolution.emitDeprecationWarning === true` — gating belongs to the
+ * caller so test scaffolding can introspect the resolution without IO.
+ */
+export function emitDeprecationWarning(stderr) {
+    stderr.write('warning: --local flag is deprecated. Cloud auth-worker is now the default. ' +
+        'See docs/plans/cloud-only-vault/.\n');
+}
+//# sourceMappingURL=auth-backend.js.map

package/dist/lib/auth-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-backend.js","sourceRoot":"","sources":["../../src/lib/auth-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAwCH;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CAAC,qDAAqD,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAA2B;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC;IACtC,MAAM,UAAU,GACd,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEtF,sCAAsC;IACtC,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,uBAAuB,EAAE,CAAC;IACtC,CAAC;IAED,gCAAgC;IAChC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,IAAI,EAAE,CAAC;IAC5D,CAAC;IAED,mCAAmC;IACnC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IAED,wCAAwC;IACxC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,OAAO;YACL,OAAO,EAAE,QAAQ;YACjB,iBAAiB,EAAE,IAAI,CAAC,MAAM;YAC9B,sBAAsB,EAAE,KAAK;SAC9B,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACnD,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC;IAC7D,CAAC;IACD,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IAED,sCAAsC;IACtC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA6B;IAClE,MAAM,CAAC,KAAK,CACV,6EAA6E;QAC3E,qCAAqC,CACxC,CAAC;AACJ,CAAC"}

package/dist/lib/auth-list-cache.d.ts

@@ -0,0 +1,67 @@
+/**
+ * auth-list-cache — in-process TTL cache for `olam auth list --remote` results.
+ *
+ * Phase B (cloud-only-vault) Decision D5 caches remote `auth list` results for
+ * 30 seconds in-memory (NOT persisted to disk). The cache keeps interactive
+ * runs cheap and lets driver scripts (e.g. `olam doctor` probes that fan out
+ * to `auth list` for credential health) avoid hammering the cloud DO.
+ *
+ * Two-tier read model: `getCachedAuthList` returns a FRESH entry (within TTL),
+ * `getStaleAuthList` returns the most recent entry regardless of age — the
+ * latter is the offline fallback used when a fresh fetch fails. The command
+ * action surfaces staleness to the operator via a `(stale)` annotation +
+ * footer warning.
+ *
+ * Key shape: callers compose a key from (baseUrl, identityHint). A single
+ * Map keyed by that string keeps multiple auth-worker targets isolated (an
+ * operator running `auth list --remote A` then `--remote B` shouldn't see
+ * A's results for B).
+ *
+ * Not persisted: this cache lives only as long as the CLI process. Phase D
+ * may extend to a file-based cache if operator runs frequent short-lived
+ * `olam auth list` invocations and pays a real RTT cost — but the in-process
+ * model is simpler + correct for the most common cases (interactive use,
+ * tight-loop script invocations within a single CLI process).
+ *
+ * Concurrency: single-threaded JS; no locking needed. Read returns the
+ * snapshot at-call-time.
+ */
+/** TTL in milliseconds — 30 seconds per Decision D5. */
+export declare const AUTH_LIST_CACHE_TTL_MS = 30000;
+/**
+ * Return the cached entry for `key` when it's within the TTL window.
+ * Returns `null` when the entry is missing OR stale. `now` is injectable
+ * for deterministic tests; production callers omit it.
+ */
+export declare function getCachedAuthList<T>(key: string, now?: number): {
+    result: T;
+    fetchedAt: number;
+} | null;
+/**
+ * Return the cached entry for `key` regardless of age. Used as the
+ * offline fallback when a fresh fetch fails. Returns `null` when the
+ * cache has never seen this key.
+ */
+export declare function getStaleAuthList<T>(key: string): {
+    result: T;
+    fetchedAt: number;
+} | null;
+/**
+ * Insert / replace the cached entry for `key`. `now` is injectable for tests.
+ */
+export declare function setCachedAuthList<T>(key: string, result: T, now?: number): void;
+/**
+ * Invalidate the entry for `key`. When `key` is omitted, clear the entire
+ * cache. Callers use this after a mutation that the next `list` MUST reflect
+ * (e.g. an explicit `auth login` succeeded against the same baseUrl) — though
+ * for B4 (narrowed) such mutations live on the local backend so callers will
+ * mostly leave the cache to expire naturally.
+ */
+export declare function invalidateAuthListCache(key?: string): void;
+/**
+ * Test-only: wipes the module-level cache. Production code MUST NOT call
+ * this. Tests that share the module across describe blocks call it in a
+ * `beforeEach` to keep the cache deterministic.
+ */
+export declare function _resetAuthListCacheForTests(): void;
+//# sourceMappingURL=auth-list-cache.d.ts.map

package/dist/lib/auth-list-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-list-cache.d.ts","sourceRoot":"","sources":["../../src/lib/auth-list-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAS7C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAmB,GACvB;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,GACV;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAIzC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,EACT,GAAG,GAAE,MAAmB,GACvB,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/lib/auth-list-cache.js

@@ -0,0 +1,84 @@
+/**
+ * auth-list-cache — in-process TTL cache for `olam auth list --remote` results.
+ *
+ * Phase B (cloud-only-vault) Decision D5 caches remote `auth list` results for
+ * 30 seconds in-memory (NOT persisted to disk). The cache keeps interactive
+ * runs cheap and lets driver scripts (e.g. `olam doctor` probes that fan out
+ * to `auth list` for credential health) avoid hammering the cloud DO.
+ *
+ * Two-tier read model: `getCachedAuthList` returns a FRESH entry (within TTL),
+ * `getStaleAuthList` returns the most recent entry regardless of age — the
+ * latter is the offline fallback used when a fresh fetch fails. The command
+ * action surfaces staleness to the operator via a `(stale)` annotation +
+ * footer warning.
+ *
+ * Key shape: callers compose a key from (baseUrl, identityHint). A single
+ * Map keyed by that string keeps multiple auth-worker targets isolated (an
+ * operator running `auth list --remote A` then `--remote B` shouldn't see
+ * A's results for B).
+ *
+ * Not persisted: this cache lives only as long as the CLI process. Phase D
+ * may extend to a file-based cache if operator runs frequent short-lived
+ * `olam auth list` invocations and pays a real RTT cost — but the in-process
+ * model is simpler + correct for the most common cases (interactive use,
+ * tight-loop script invocations within a single CLI process).
+ *
+ * Concurrency: single-threaded JS; no locking needed. Read returns the
+ * snapshot at-call-time.
+ */
+/** TTL in milliseconds — 30 seconds per Decision D5. */
+export const AUTH_LIST_CACHE_TTL_MS = 30_000;
+const cache = new Map();
+/**
+ * Return the cached entry for `key` when it's within the TTL window.
+ * Returns `null` when the entry is missing OR stale. `now` is injectable
+ * for deterministic tests; production callers omit it.
+ */
+export function getCachedAuthList(key, now = Date.now()) {
+    const entry = cache.get(key);
+    if (!entry)
+        return null;
+    if (now - entry.fetchedAt > AUTH_LIST_CACHE_TTL_MS)
+        return null;
+    return { result: entry.result, fetchedAt: entry.fetchedAt };
+}
+/**
+ * Return the cached entry for `key` regardless of age. Used as the
+ * offline fallback when a fresh fetch fails. Returns `null` when the
+ * cache has never seen this key.
+ */
+export function getStaleAuthList(key) {
+    const entry = cache.get(key);
+    if (!entry)
+        return null;
+    return { result: entry.result, fetchedAt: entry.fetchedAt };
+}
+/**
+ * Insert / replace the cached entry for `key`. `now` is injectable for tests.
+ */
+export function setCachedAuthList(key, result, now = Date.now()) {
+    cache.set(key, { result, fetchedAt: now });
+}
+/**
+ * Invalidate the entry for `key`. When `key` is omitted, clear the entire
+ * cache. Callers use this after a mutation that the next `list` MUST reflect
+ * (e.g. an explicit `auth login` succeeded against the same baseUrl) — though
+ * for B4 (narrowed) such mutations live on the local backend so callers will
+ * mostly leave the cache to expire naturally.
+ */
+export function invalidateAuthListCache(key) {
+    if (key === undefined) {
+        cache.clear();
+        return;
+    }
+    cache.delete(key);
+}
+/**
+ * Test-only: wipes the module-level cache. Production code MUST NOT call
+ * this. Tests that share the module across describe blocks call it in a
+ * `beforeEach` to keep the cache deterministic.
+ */
+export function _resetAuthListCacheForTests() {
+    cache.clear();
+}
+//# sourceMappingURL=auth-list-cache.js.map

package/dist/lib/auth-list-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-list-cache.js","sourceRoot":"","sources":["../../src/lib/auth-list-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAO7C,MAAM,KAAK,GAA4B,IAAI,GAAG,EAAE,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,sBAAsB;QAAE,OAAO,IAAI,CAAC;IAChE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAW,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW;IAEX,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAW,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,MAAS,EACT,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B;IACzC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}

package/dist/lib/auth-list.d.ts

@@ -0,0 +1,107 @@
+/**
+ * auth-list — testable orchestration for `olam auth list` and `auth list --json`.
+ *
+ * Phase B (cloud-only-vault) Decision D5: `olam auth list` defaults to the
+ * cloud auth-worker (cf. B1 / B2). This module:
+ *
+ *   1. Resolves the backend via B1's `requireBackend`.
+ *   2. Resolves the remote URL via the same precedence used by `auth login`
+ *      (explicit `--remote <url>` > env > file > hard-coded fallback).
+ *   3. Consults the in-process TTL cache (30 s per D5) when backend='remote'
+ *      and `--no-cache` was NOT passed.
+ *   4. Falls back to the stale cache when a fresh fetch fails (offline UX).
+ *   5. Routes to `AuthClient.status()` on the local backend.
+ *
+ * The Commander.js action handler in `packages/cli/src/commands/auth.ts`
+ * binds the IO touchpoints (cache helpers, fetch, AuthClient) via the
+ * `AuthListDeps` struct and consumes the structured `AuthListResult` to
+ * render the table or JSON output.
+ *
+ * Coupling note: the result object holds the raw remote payload (when
+ * backend='remote') OR the AuthAccountSummary[] (when backend='local'). The
+ * caller picks the right renderer (`renderAuthListJson` for local-JSON,
+ * `renderRemoteAuthListJson` for remote-JSON, or a text table for either).
+ * This keeps the IO + presentation concerns out of this module while still
+ * giving the action a single decision-tree entrypoint.
+ */
+import { AUTH_LIST_CACHE_TTL_MS } from './auth-list-cache.js';
+import type { AccountEntry } from './auth-remote.js';
+import type { AuthAccountSummary } from '@olam/core/src/auth/types.js';
+/** Options parsed from Commander for `olam auth list` and `auth list --json`. */
+export interface AuthListOptions {
+    readonly local?: boolean;
+    readonly remote?: boolean | string;
+    /** When true, bypass the 30 s TTL cache and force a fresh fetch. */
+    readonly noCache?: boolean;
+    /** Renders the result as JSON instead of the text table. */
+    readonly json?: boolean;
+    /** CF_Authorization cookie value (manual paste from DevTools). */
+    readonly cookie?: string;
+}
+/**
+ * Outcome of the remote path: the raw `AccountEntry[]` (post-`remoteListAccounts`
+ * normalisation) along with staleness metadata.
+ */
+export interface RemoteListResult {
+    readonly mode: 'remote';
+    readonly baseUrl: string;
+    readonly accounts: ReadonlyArray<AccountEntry>;
+    /**
+     * True iff the result came from the stale-cache fallback path (a fresh
+     * fetch was attempted AND failed). The caller surfaces a `(stale)`
+     * annotation + warning footer in this case.
+     */
+    readonly stale: boolean;
+    /**
+     * Epoch ms when the payload was originally fetched. Equal to "now" on a
+     * fresh fetch / cache hit; older when stale.
+     */
+    readonly fetchedAt: number;
+    /** Optional error message from the failed fresh fetch (stale path only). */
+    readonly fetchError?: string;
+}
+export interface LocalListResult {
+    readonly mode: 'local';
+    readonly reachable: boolean;
+    readonly accounts: ReadonlyArray<AuthAccountSummary>;
+}
+export interface AuthListError {
+    readonly mode: 'error';
+    readonly exitCode: 1;
+    readonly message: string;
+}
+export type AuthListResult = RemoteListResult | LocalListResult | AuthListError;
+/**
+ * Injection seam — every IO touchpoint is funnelled through this struct so
+ * unit tests assert on orchestration without real HTTP, filesystem reads,
+ * or AuthClient round-trips.
+ */
+export interface AuthListDeps {
+    readonly readEnv?: (key: string) => string | undefined;
+    readonly readAuthWorkerUrlFile?: () => string | null;
+    /** Fresh fetch against the remote. Returns the `AccountEntry[]`. */
+    readonly fetchRemoteAccounts: (baseUrl: string, cookie?: string) => Promise<ReadonlyArray<AccountEntry>>;
+    /** Local backend status — usually `() => new AuthClient().status()`. */
+    readonly fetchLocalStatus: () => Promise<{
+        reachable: boolean;
+        accounts: readonly AuthAccountSummary[];
+    }>;
+    readonly stderr?: NodeJS.WritableStream;
+    /** Test injection for cache TTL semantics; defaults to Date.now(). */
+    readonly now?: () => number;
+}
+/**
+ * Compose the cache key for a (baseUrl, cookie) pair. The cookie value is
+ * included because two operators on the same host (sharing the CLI process,
+ * unlikely but possible in CI) may target the same baseUrl with different
+ * identities — caching across that boundary would leak one operator's
+ * accounts to the other.
+ */
+export declare function authListCacheKey(baseUrl: string, cookie?: string): string;
+/**
+ * Run the `olam auth list` decision tree. Tests inject `fetchRemoteAccounts`
+ * and `fetchLocalStatus` to capture orchestration.
+ */
+export declare function runAuthList(opts: AuthListOptions, deps: AuthListDeps): Promise<AuthListResult>;
+export { AUTH_LIST_CACHE_TTL_MS };
+//# sourceMappingURL=auth-list.d.ts.map

package/dist/lib/auth-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-list.d.ts","sourceRoot":"","sources":["../../src/lib/auth-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,OAAO,EAIL,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,eAAe,GAAG,aAAa,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACrD,oEAAoE;IACpE,QAAQ,CAAC,mBAAmB,EAAE,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,KACZ,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;IAC1C,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,OAAO,CAAC;QACvC,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;KACzC,CAAC,CAAC;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,CA6EzB;AAID,OAAO,EAAE,sBAAsB,EAAE,CAAC"}