devflow-kit 1.8.2 → 2.0.0

package/dist/core/cache.js

@@ -0,0 +1,205 @@
+/**
+ * @file cache.ts
+ *
+ * Generic TTL cache — sync reads, async writes.
+ *
+ * Sync-read / async-write asymmetry:
+ *   Reads use readFileSync: a ~1KB cache entry takes ~0.01ms and sits on
+ *   the TUI startup path where async I/O would complicate the call site.
+ *   Writes use writeFileAtomicExclusive (async): no sync atomic-write variant
+ *   exists in this codebase; cache writes always happen in async contexts.
+ *
+ * Path safety:
+ *   Every composed cache-entry path is verified to resolve inside cacheDir.
+ *   An unvalidated key is an arbitrary-file-overwrite primitive through
+ *   path.join()'s normalization of ".." components. safeEntryPath() enforces
+ *   containment and returns null on violation; all callers treat null as a miss.
+ *
+ * applies ADR-013: core-layer module, no Claude Code adapter concerns.
+ * avoids PF-011: entries written via tmp→rename (writeFileAtomicExclusive).
+ */
+import * as fs from 'node:fs';
+import { promises as fsAsync } from 'node:fs';
+import * as path from 'node:path';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Maximum cache TTL: 7 days.
+ * Clamps inflated or future-timestamped entries that would otherwise be
+ * permanently fresh and never re-fetch. Applied on write; enforced on read.
+ */
+export const MAX_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Path accessors — single source of truth for cache directory layout
+// ---------------------------------------------------------------------------
+//
+// All callers that write or read the model-discovery catalog AND the uninstall
+// removal target derive their directory paths from these functions. Keeping
+// write-site and removal-site in the same module prevents silent orphaning of
+// cache data on future relocations (avoids PF-013).
+//
+// applies ADR-013: path layout owned by the core module, not scattered across
+// callers in src/cli/ or src/hud/.
+/**
+ * Returns the model-discovery cache directory for the given devflowDir.
+ *
+ * This is the single authoritative path for the external-models cache written
+ * by discoverExternalModels and read by getExternalModelsCached. The uninstall
+ * removal target in removeDevFlowInstallArtifacts MUST derive its path from
+ * this function so that write-site and removal-site cannot drift independently.
+ */
+export function modelCacheDir(devflowDir) {
+    return path.join(devflowDir, 'cache', 'models');
+}
+/**
+ * Returns the HUD component cache directory for the given devflowDir.
+ *
+ * Used by version-badge.ts for the npm registry version-check cache.
+ * Separate from modelCacheDir because the version-check and model-discovery
+ * caches live in different subdirectories under devflowDir/cache/.
+ */
+export function hudCacheDir(devflowDir) {
+    return path.join(devflowDir, 'cache');
+}
+// ---------------------------------------------------------------------------
+// Path containment guard
+// ---------------------------------------------------------------------------
+/**
+ * Returns the resolved entry path for (cacheDir, key) if and only if it is
+ * strictly inside cacheDir. Returns null when the key contains path-traversal
+ * components ("..", absolute paths, etc.) that escape the cache directory.
+ *
+ * Uses path.resolve to normalise ".." before comparing, so path.join's
+ * normalisation of ".." cannot be used to escape via a crafted key.
+ */
+function safeEntryPath(cacheDir, key) {
+    const joined = path.join(cacheDir, `${key}.json`);
+    const normalizedEntry = path.resolve(joined);
+    const normalizedDir = path.resolve(cacheDir);
+    // Require strict prefix — the entry must live INSIDE the dir, not at the dir root.
+    if (!normalizedEntry.startsWith(normalizedDir + path.sep)) {
+        return null;
+    }
+    return normalizedEntry;
+}
+// ---------------------------------------------------------------------------
+// Private read helper
+// ---------------------------------------------------------------------------
+function readCacheEntry(cacheDir, key, validate) {
+    const filePath = safeEntryPath(cacheDir, key);
+    if (filePath === null)
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const envelope = parseRawEnvelope(raw);
+        if (envelope === null)
+            return null;
+        // parseRawEnvelope guarantees timestamp is not in the future, so age >= 0.
+        // Clamp TTL so an inflated value does not make the entry perpetually fresh.
+        const age = Date.now() - envelope.timestamp;
+        const clampedTtl = Math.min(Math.abs(envelope.ttl), MAX_TTL_MS);
+        if (age >= clampedTtl)
+            return null;
+        return validate(envelope.data);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read a cached value. Returns null on miss, expiry, or validation failure.
+ *
+ * @param cacheDir - Absolute directory path for cache entries.
+ * @param key - Cache key (becomes `<key>.json` inside cacheDir). Path-traversal
+ *   components cause a null return rather than an error — callers treat missing
+ *   entries and bad keys identically.
+ * @param validate - Called on the raw `data` field from the cache envelope.
+ *   Return a typed value on success, null to treat as a miss. Run on every
+ *   read — no bypass for corrupt or schema-evolved entries.
+ */
+export function readCache(cacheDir, key, validate) {
+    return readCacheEntry(cacheDir, key, validate);
+}
+/**
+ * Parse and validate a raw JSON string as a cache envelope.
+ *
+ * Returns null when:
+ *   - JSON is malformed
+ *   - timestamp is not a finite number
+ *   - timestamp is in the future (poisoned entry)
+ *   - ttl is absent or not a finite number
+ *
+ * The single canonical envelope parser — used by readCacheEntry (which adds
+ * the expiry check on top) and exported for model-discovery.ts (stale-fallback
+ * and prune sorters) so all callers share one parser and cannot drift.
+ *
+ * applies ADR-003: eliminated private parseEnvelope duplicate; one parser, one truth.
+ */
+export function parseRawEnvelope(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    const ts = obj['timestamp'];
+    if (typeof ts !== 'number' || !Number.isFinite(ts))
+        return null;
+    // Reject future timestamps (poisoned entry — matches writer policy).
+    if (ts > Date.now())
+        return null;
+    const rawTtl = obj['ttl'];
+    if (typeof rawTtl !== 'number' || !Number.isFinite(rawTtl))
+        return null;
+    return { data: obj['data'], timestamp: ts, ttl: rawTtl };
+}
+/**
+ * Write a value to cache with a TTL in milliseconds.
+ *
+ * - Creates cacheDir at mode 0700 if absent (owner-only access).
+ * - Writes the entry via atomic tmp→rename (avoids PF-011 delete-then-write window).
+ * - Hardens the entry to 0600 after the write (owner-only read/write for cache data
+ *   that will feed agent frontmatter in later phases).
+ * - TTL is clamped to MAX_TTL_MS before storage.
+ * - Non-fatal on any I/O error — cache write failure is never surfaced to the user.
+ *
+ * @param cacheDir - Absolute directory path for cache entries.
+ * @param key - Cache key. Path-traversal components are silently rejected.
+ * @param data - Value to cache.
+ * @param ttlMs - Time-to-live in milliseconds.
+ */
+export async function writeCache(cacheDir, key, data, ttlMs) {
+    const filePath = safeEntryPath(cacheDir, key);
+    if (filePath === null)
+        return;
+    try {
+        await fsAsync.mkdir(cacheDir, { recursive: true, mode: 0o700 });
+        const envelope = {
+            data,
+            timestamp: Date.now(),
+            ttl: Math.min(Math.abs(ttlMs), MAX_TTL_MS),
+        };
+        await writeFileAtomicExclusive(filePath, JSON.stringify(envelope));
+    }
+    catch {
+        // Cache write failure is non-fatal
+        return;
+    }
+    // Harden entry to 0600 after the atomic write. writeFileAtomicExclusive
+    // preserves the existing mode on re-writes; this chmod bootstraps 0600 on
+    // the first write to a fresh entry. Best-effort, non-fatal (avoids PF-009).
+    try {
+        await fsAsync.chmod(filePath, 0o600);
+    }
+    catch { /* non-fatal */ }
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/codex-auth-inspect.js

@@ -0,0 +1,128 @@
+/**
+ * Codex credential-file inspection for `devflow proxy --status`.
+ *
+ * applies ADR-013: pure core-layer module — no Claude Code adapter concerns and
+ *   no presentation (colour/format lives with the other CLI formatters).
+ *
+ * WHY THIS EXISTS RATHER THAN IMPORTING THE ROUTING RUNTIME
+ * The routing runtime validates this same file and exposes an equivalent
+ * inspector, but it ships no package `exports` map and no `main`, so the only
+ * way to reach it is a deep path into its build output. That would pin us to an
+ * internal layout across an exact-pinned dependency bump. The subset below is
+ * small enough to re-derive, so we own it.
+ *
+ * WHAT AN EXPIRED ACCESS TOKEN MEANS: nothing actionable. The relay refreshes
+ * proactively inside a two-minute margin and reactively on a 401, using the
+ * refresh token in this same file. Expiry is therefore reported as information,
+ * never as a warning — warning on it would fire on a perfectly healthy install.
+ * The genuinely actionable states are `absent` and `unreadable`: the relay
+ * rejects a malformed file outright, so every request 401s while a naive
+ * existence check still reports "present".
+ *
+ * SECURITY: the JWT payload is decoded for display only — never signature-checked
+ * and never trusted for an authorisation decision. No token material is returned
+ * from this module; the account id is truncated to a short suffix so status output
+ * cannot leak a full identifier into a terminal, screenshot, or bug report.
+ */
+/** Number of trailing account-id characters kept for display. */
+const ACCOUNT_SUFFIX_LENGTH = 6;
+/**
+ * Decode a JWT payload without verifying its signature.
+ *
+ * Display-only (see module header). Returns undefined for anything that is not a
+ * three-part token with a base64url-encoded JSON object payload.
+ */
+function decodeJwtPayload(token) {
+    const payload = token.split('.')[1];
+    if (payload === undefined || payload === '')
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extract the `exp` claim as a Date. Undefined when absent or non-numeric. */
+function jwtExpiry(token) {
+    const exp = decodeJwtPayload(token)?.['exp'];
+    return typeof exp === 'number' && Number.isFinite(exp) ? new Date(exp * 1000) : undefined;
+}
+/** Extract the ChatGPT account id from the OpenAI auth claim. Undefined when absent. */
+function jwtAccountId(token) {
+    const claim = decodeJwtPayload(token)?.['https://api.openai.com/auth'];
+    if (typeof claim !== 'object' || claim === null || Array.isArray(claim))
+        return undefined;
+    const accountId = claim['chatgpt_account_id'];
+    return typeof accountId === 'string' && accountId !== '' ? accountId : undefined;
+}
+/**
+ * Classify an I/O error from reading ~/.codex/auth.json into a CodexAuthState.
+ *
+ * applies ADR-013: pure classification logic belongs in src/core/, not in the
+ *   CLI presentation layer that calls it.
+ *
+ * ENOENT is the ordinary "not signed in" case: the file has never been written
+ * by `codex login`. Every other error (EACCES, EISDIR, EMFILE, …) is a real
+ * fault the user must act on — reporting it as `absent` would silently hide it.
+ *
+ * @param err  The caught exception from `fs.readFile(codexAuthPath)`.
+ */
+export function classifyCodexAuthReadError(err) {
+    return err?.code === 'ENOENT'
+        ? { kind: 'absent' }
+        : { kind: 'unreadable', reason: 'cannot read file' };
+}
+/**
+ * Inspect the raw contents of `~/.codex/auth.json`.
+ *
+ * Every failure mode the relay would reject at request time is surfaced here as
+ * `unreadable` with a reason, so status reports the same verdict the relay would
+ * reach rather than merely confirming the file exists.
+ *
+ * @param raw  File contents. Pass the string; callers own the I/O and the
+ *             `absent` case (an unreadable path is not the same as a bad file).
+ */
+export function inspectCodexAuth(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return { kind: 'unreadable', reason: 'not valid JSON' };
+    }
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+        return { kind: 'unreadable', reason: 'unexpected shape' };
+    }
+    const tokens = json['tokens'];
+    if (typeof tokens !== 'object' || tokens === null || Array.isArray(tokens)) {
+        return { kind: 'unreadable', reason: 'unexpected shape' };
+    }
+    const accessToken = tokens['access_token'];
+    if (typeof accessToken !== 'string' || accessToken === '') {
+        return { kind: 'unreadable', reason: 'no access token' };
+    }
+    // Mirrors the relay's resolution order: the explicit field wins, the token claim
+    // is the fallback. Neither present is a hard failure there, so it is one here too.
+    const storedAccountId = tokens['account_id'];
+    const accountId = typeof storedAccountId === 'string' && storedAccountId !== ''
+        ? storedAccountId
+        : jwtAccountId(accessToken);
+    if (accountId === undefined) {
+        return { kind: 'unreadable', reason: 'no account id' };
+    }
+    const rawAuthMode = json['auth_mode'];
+    const authMode = typeof rawAuthMode === 'string' && rawAuthMode !== '' ? rawAuthMode : 'unknown';
+    return {
+        kind: 'present',
+        authMode,
+        accountSuffix: accountId.length > ACCOUNT_SUFFIX_LENGTH
+            ? `…${accountId.slice(-ACCOUNT_SUFFIX_LENGTH)}`
+            : accountId,
+        expiresAt: jwtExpiry(accessToken),
+    };
+}
+//# sourceMappingURL=codex-auth-inspect.js.map