@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/appliance/rvfa-signing.js

@@ -0,0 +1,347 @@
+/**
+ * RVFA Ed25519 Code Signing -- Digital signatures for RVFA appliance files.
+ *
+ * Provides tamper detection and publisher identity verification using
+ * Ed25519 (RFC 8032) via Node.js native crypto. Zero external dependencies.
+ *
+ * @module @claude-flow/cli/appliance/rvfa-signing
+ */
+import { generateKeyPairSync, createHash, sign, verify, createPublicKey, createPrivateKey, } from 'node:crypto';
+import { readFile, writeFile, stat, chmod, mkdir } from 'node:fs/promises';
+// ── Constants ────────────────────────────────────────────────
+const PREAMBLE_SIZE = 12; // 4B magic + 4B version + 4B header_len
+const SHA256_SIZE = 32;
+const KEY_FILE_MODE = 0o600;
+// ── Key Management ───────────────────────────────────────────
+/** Compute the fingerprint of a public key: first 16 hex chars of its SHA256. */
+function computeFingerprint(publicKeyPem) {
+    return createHash('sha256')
+        .update(publicKeyPem, 'utf-8')
+        .digest('hex')
+        .slice(0, 16);
+}
+/**
+ * Generate a new Ed25519 key pair for RVFA signing.
+ */
+export async function generateKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    const pubBuf = Buffer.from(publicKey, 'utf-8');
+    const privBuf = Buffer.from(privateKey, 'utf-8');
+    const fingerprint = computeFingerprint(publicKey);
+    return { publicKey: pubBuf, privateKey: privBuf, fingerprint };
+}
+/**
+ * Save a key pair to disk as PEM files.
+ *
+ * @param keyPair  The key pair to persist.
+ * @param dir      Directory to write files into.
+ * @param name     Base name for the key files (default: 'rvfa-signing').
+ * @returns Paths to the written public and private key files.
+ */
+export async function saveKeyPair(keyPair, dir, name = 'rvfa-signing') {
+    await mkdir(dir, { recursive: true });
+    const pubPath = `${dir}/${name}.pub`;
+    const privPath = `${dir}/${name}.key`;
+    await writeFile(pubPath, keyPair.publicKey);
+    await writeFile(privPath, keyPair.privateKey, { mode: KEY_FILE_MODE });
+    // Ensure private key has restrictive permissions even on existing files
+    await chmod(privPath, KEY_FILE_MODE);
+    return { publicKeyPath: pubPath, privateKeyPath: privPath };
+}
+/**
+ * Load a key pair from PEM files on disk.
+ *
+ * @param dir   Directory containing the key files.
+ * @param name  Base name for the key files (default: 'rvfa-signing').
+ */
+export async function loadKeyPair(dir, name = 'rvfa-signing') {
+    const pubPath = `${dir}/${name}.pub`;
+    const privPath = `${dir}/${name}.key`;
+    const publicKey = await readFile(pubPath);
+    const privateKey = await readFile(privPath);
+    // Warn if private key permissions are too open
+    const privStat = await stat(privPath);
+    const mode = privStat.mode & 0o777;
+    if (mode & 0o077) {
+        console.warn(`[rvfa-signing] WARNING: Private key ${privPath} has open permissions ` +
+            `(${mode.toString(8)}). Consider running: chmod 600 ${privPath}`);
+    }
+    const fingerprint = computeFingerprint(publicKey.toString('utf-8'));
+    return { publicKey, privateKey, fingerprint };
+}
+/**
+ * Load a public key from a single PEM file.
+ */
+export async function loadPublicKey(path) {
+    return readFile(path);
+}
+// ── Internal Helpers ─────────────────────────────────────────
+/**
+ * Recursively sort object keys for canonical JSON serialization.
+ * Produces deterministic output regardless of insertion order.
+ */
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val) && !Buffer.isBuffer(val)) {
+            const sorted = {};
+            for (const k of Object.keys(val).sort()) {
+                sorted[k] = val[k];
+            }
+            return sorted;
+        }
+        return val;
+    });
+}
+/**
+ * Parse an RVFA binary into its components without full validation.
+ * Returns the header object, header JSON bytes, section data region, and footer.
+ */
+function parseRvfaBinary(buf) {
+    if (buf.length < PREAMBLE_SIZE + SHA256_SIZE) {
+        throw new Error('Buffer too small to be a valid RVFA file');
+    }
+    const magic = buf.subarray(0, 4).toString('ascii');
+    if (magic !== 'RVFA') {
+        throw new Error(`Invalid RVFA magic: expected "RVFA", got "${magic}"`);
+    }
+    const headerLen = buf.readUInt32LE(8);
+    const headerStart = PREAMBLE_SIZE;
+    const headerEnd = headerStart + headerLen;
+    if (headerEnd > buf.length - SHA256_SIZE) {
+        throw new Error('Header length extends beyond buffer');
+    }
+    const headerJson = buf.subarray(headerStart, headerEnd).toString('utf-8');
+    let header;
+    try {
+        header = JSON.parse(headerJson);
+    }
+    catch {
+        throw new Error('Failed to parse RVFA header JSON');
+    }
+    const footer = buf.subarray(buf.length - SHA256_SIZE);
+    const sectionData = buf.subarray(headerEnd, buf.length - SHA256_SIZE);
+    return { header, headerStart, headerEnd, sectionData, footer };
+}
+/**
+ * Compute the signing digest for an RVFA file.
+ *
+ * The digest is SHA256 of: canonical_header_json (without signature field)
+ *                         + section_data_bytes
+ *                         + footer_32_bytes
+ */
+function computeSigningDigest(header, sectionData, footer) {
+    // Strip signature field from header for digest computation
+    const stripped = { ...header };
+    delete stripped.signature;
+    const canonical = Buffer.from(canonicalJson(stripped), 'utf-8');
+    return createHash('sha256')
+        .update(canonical)
+        .update(sectionData)
+        .update(footer)
+        .digest();
+}
+/** Convert a Buffer or PEM string into a KeyObject. */
+function toPrivateKeyObject(key) {
+    const pem = Buffer.isBuffer(key) ? key.toString('utf-8') : key;
+    return createPrivateKey(pem);
+}
+/** Convert a Buffer or PEM string into a KeyObject. */
+function toPublicKeyObject(key) {
+    const pem = Buffer.isBuffer(key) ? key.toString('utf-8') : key;
+    return createPublicKey(pem);
+}
+/**
+ * Rebuild the RVFA binary with an updated header.
+ *
+ * Preserves the original preamble version, recalculates header length,
+ * and keeps section data and footer intact.
+ */
+function rebuildRvfa(originalBuf, newHeader, sectionData, footer) {
+    const headerJson = Buffer.from(JSON.stringify(newHeader), 'utf-8');
+    // Preamble: magic + version + new header length
+    const preamble = Buffer.alloc(PREAMBLE_SIZE);
+    originalBuf.copy(preamble, 0, 0, 8); // magic + version unchanged
+    preamble.writeUInt32LE(headerJson.length, 8);
+    return Buffer.concat([preamble, headerJson, sectionData, footer]);
+}
+// ── RvfaSigner ───────────────────────────────────────────────
+/**
+ * Signs RVFA appliance files and data with Ed25519.
+ */
+export class RvfaSigner {
+    keyObj;
+    fingerprint;
+    constructor(privateKey) {
+        this.keyObj = toPrivateKeyObject(privateKey);
+        // Derive public key to compute fingerprint
+        const pubPem = createPublicKey(this.keyObj)
+            .export({ type: 'spki', format: 'pem' });
+        this.fingerprint = computeFingerprint(pubPem);
+    }
+    /**
+     * Sign an RVFA appliance file in-place.
+     *
+     * Algorithm:
+     *  1. Read and parse the RVFA binary
+     *  2. Strip any existing signature from the header
+     *  3. Compute SHA256 of [canonical_header + section_data + footer]
+     *  4. Sign the digest with Ed25519
+     *  5. Embed signature metadata into the header
+     *  6. Write the updated binary back to the file
+     *
+     * @param rvfaPath   Path to the .rvf appliance file.
+     * @param signedBy   Optional publisher name.
+     * @returns The signature metadata that was embedded.
+     */
+    async signAppliance(rvfaPath, signedBy) {
+        const buf = await readFile(rvfaPath);
+        const { header, sectionData, footer } = parseRvfaBinary(buf);
+        // Compute digest over header (without signature) + sections + footer
+        const digest = computeSigningDigest(header, sectionData, footer);
+        // Ed25519 sign
+        const sig = sign(null, digest, this.keyObj);
+        const metadata = {
+            algorithm: 'ed25519',
+            publicKeyFingerprint: this.fingerprint,
+            signature: sig.toString('hex'),
+            signedAt: new Date().toISOString(),
+            signedBy,
+            scope: 'full',
+        };
+        // Embed signature in header and rebuild
+        header.signature = metadata;
+        const rebuilt = rebuildRvfa(buf, header, sectionData, footer);
+        await writeFile(rvfaPath, rebuilt);
+        return metadata;
+    }
+    /**
+     * Sign a section footer hash (detached signature).
+     *
+     * @param footerHash  The 32-byte SHA256 footer hash from an RVFA file.
+     * @returns Hex-encoded Ed25519 signature.
+     */
+    async signSections(footerHash) {
+        if (footerHash.length !== SHA256_SIZE) {
+            throw new Error(`Footer hash must be ${SHA256_SIZE} bytes, got ${footerHash.length}`);
+        }
+        const sig = sign(null, footerHash, this.keyObj);
+        return sig.toString('hex');
+    }
+    /**
+     * Sign an RVFP patch file (detached signature).
+     *
+     * @param patchData  The raw patch binary data.
+     * @returns Hex-encoded Ed25519 signature.
+     */
+    async signPatch(patchData) {
+        const digest = createHash('sha256').update(patchData).digest();
+        const sig = sign(null, digest, this.keyObj);
+        return sig.toString('hex');
+    }
+}
+// ── RvfaVerifier ─────────────────────────────────────────────
+/**
+ * Verifies Ed25519 signatures on RVFA appliance files and data.
+ */
+export class RvfaVerifier {
+    keyObj;
+    fingerprint;
+    constructor(publicKey) {
+        this.keyObj = toPublicKeyObject(publicKey);
+        const pem = Buffer.isBuffer(publicKey) ? publicKey.toString('utf-8') : publicKey;
+        this.fingerprint = computeFingerprint(pem);
+    }
+    /**
+     * Verify the Ed25519 signature embedded in an RVFA appliance file.
+     *
+     * @param rvfaPath  Path to the .rvf appliance file.
+     * @returns Verification result with details and any errors.
+     */
+    async verifyAppliance(rvfaPath) {
+        const errors = [];
+        let buf;
+        try {
+            buf = await readFile(rvfaPath);
+        }
+        catch (err) {
+            return { valid: false, errors: [`Failed to read file: ${err.message}`] };
+        }
+        let parsed;
+        try {
+            parsed = parseRvfaBinary(buf);
+        }
+        catch (err) {
+            return { valid: false, errors: [`Invalid RVFA file: ${err.message}`] };
+        }
+        const { header, sectionData, footer } = parsed;
+        // Extract signature metadata from header
+        const sigRaw = header.signature;
+        if (!sigRaw || typeof sigRaw !== 'object') {
+            return { valid: false, errors: ['No signature found in RVFA header'] };
+        }
+        const sigMeta = sigRaw;
+        if (sigMeta.algorithm !== 'ed25519') {
+            errors.push(`Unsupported algorithm: ${String(sigMeta.algorithm)}`);
+            return { valid: false, errors };
+        }
+        if (typeof sigMeta.signature !== 'string' || !sigMeta.signature) {
+            errors.push('Signature field is missing or empty');
+            return { valid: false, errors };
+        }
+        // Recompute the digest the same way the signer did
+        const digest = computeSigningDigest(header, sectionData, footer);
+        // Verify
+        let sigBuf;
+        try {
+            sigBuf = Buffer.from(sigMeta.signature, 'hex');
+        }
+        catch {
+            errors.push('Signature is not valid hex');
+            return { valid: false, errors };
+        }
+        let valid;
+        try {
+            valid = verify(null, digest, this.keyObj, sigBuf);
+        }
+        catch (err) {
+            errors.push(`Verification error: ${err.message}`);
+            return { valid: false, errors };
+        }
+        if (!valid) {
+            errors.push('Ed25519 signature verification failed: data may be tampered');
+        }
+        return {
+            valid,
+            signerFingerprint: sigMeta.publicKeyFingerprint,
+            signedAt: sigMeta.signedAt,
+            signedBy: sigMeta.signedBy,
+            errors,
+        };
+    }
+    /**
+     * Verify a detached Ed25519 signature over arbitrary data.
+     *
+     * @param data       The data that was signed.
+     * @param signature  Hex-encoded Ed25519 signature.
+     */
+    async verifyDetached(data, signature) {
+        const digest = createHash('sha256').update(data).digest();
+        const sigBuf = Buffer.from(signature, 'hex');
+        return verify(null, digest, this.keyObj, sigBuf);
+    }
+    /**
+     * Verify an RVFP patch file signature.
+     *
+     * @param patchData  The raw patch binary data.
+     * @param signature  Hex-encoded Ed25519 signature.
+     */
+    async verifyPatch(patchData, signature) {
+        const digest = createHash('sha256').update(patchData).digest();
+        const sigBuf = Buffer.from(signature, 'hex');
+        return verify(null, digest, this.keyObj, sigBuf);
+    }
+}
+//# sourceMappingURL=rvfa-signing.js.map

package/dist/src/auth/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `ruflo auth login` flow orchestration (ADR-306) — composes
+ * `@claude-flow/security`'s ported OAuth primitives (loopback PKCE, OOB
+ * manual-paste, refresh) the same way meta-proxy's `oauth/login.rs`
+ * orchestrates its own Rust primitives. See security-bridge.ts for why the
+ * package is loaded lazily, and oauth/client.ts (in @claude-flow/security)
+ * for why this targets the live `auth.cognitum.one` surface rather than
+ * ADR-308's unconfirmed `/v1/auth/*` spec.
+ *
+ * @module auth/client
+ */
+import { type OAuthTokenResponse } from './security-bridge.js';
+/** Refresh before there is less than one minute left on the access token. */
+export declare const ACCESS_TOKEN_REFRESH_WINDOW_MS = 60000;
+export interface LoginResult {
+    tokens: OAuthTokenResponse;
+    method: 'pkce' | 'device' | 'token-stdin';
+}
+/**
+ * Best-effort headlessness signal — a false negative just means the browser
+ * flow is attempted and a real browser opens fine anyway; a false positive
+ * means the user falls back to the manual OOB flow, which always works
+ * regardless. Mirrors meta-proxy's `login.rs::is_probably_headless()`.
+ */
+export declare function isProbablyHeadless(): boolean;
+/**
+ * Validates the OAuth callback params against the request that started the
+ * flow — the CSRF-critical step, extracted so it's independently testable.
+ * Order matters: an explicit `error` (user denied) and a missing code are
+ * reported as their own reasons; a missing or mismatched `state` is always
+ * a state-mismatch, even when a code is present.
+ */
+export declare function validateCallback(error: string | null, code: string | null, returnedState: string | null, expectedState: string): {
+    ok: true;
+    code: string;
+} | {
+    ok: false;
+    reason: 'denied' | 'state-mismatch';
+    detail?: string;
+};
+export declare class LoginCancelledError extends Error {
+    constructor();
+}
+export declare class LoginDeniedError extends Error {
+    constructor(detail: string);
+}
+export declare class StateMismatchError extends Error {
+    constructor();
+}
+export declare class NotLoggedInError extends Error {
+    constructor(profile: string);
+}
+export declare class SessionOnlyExpiredError extends Error {
+    constructor(profile: string);
+}
+export declare class ScopeConsentMismatchError extends Error {
+    constructor(profile: string, scopes: string[]);
+}
+/** Browser-based loopback PKCE login — the ADR-306 default for an interactive desktop. */
+export declare function browserLogin(print: (line: string) => void): Promise<LoginResult>;
+/** Headless fallback: prints the authorize URL with the OOB redirect, prompts for the pasted code. */
+export declare function manualLogin(print: (line: string) => void, input?: NodeJS.ReadableStream): Promise<LoginResult>;
+/**
+ * `--token-stdin`: reads one JSON object from stdin,
+ * `{access_token, refresh_token?, expires_in, scope}`. Wire format is not
+ * specified by ADR-306 — defined here as typed JSON rather than a bare
+ * token string, so scope/expiry are explicit rather than inferred.
+ */
+export declare function tokenStdinLogin(input?: NodeJS.ReadableStream): Promise<LoginResult>;
+/**
+ * Refreshes an access token. Classifies failure into network-unreachable
+ * vs. a reachable-but-erroring server so callers can print an honest
+ * message instead of collapsing both into "offline" (ADR-308 failure
+ * policy: local ruflo functionality is never affected by auth being
+ * unavailable, but the diagnostic should say WHY it's unavailable).
+ */
+export declare function refreshAccessToken(refreshTokenValue: string): Promise<OAuthTokenResponse>;
+/**
+ * Returns an access token suitable for an authenticated call.
+ *
+ * Fast path: a process-memory token with more than one minute remaining.
+ * Slow path: load the profile's refresh token from the OS keychain, perform
+ * one refresh, persist a rotated refresh token BEFORE exposing the new access
+ * token, then update metadata and the process cache. Refresh is deliberately
+ * demand-driven: offline-safe commands such as plain `auth status` never call
+ * this function and therefore never create background traffic or retry loops.
+ */
+export declare function getValidAccessToken(profileName?: string): Promise<string>;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/auth/client.js

@@ -0,0 +1,242 @@
+/**
+ * `ruflo auth login` flow orchestration (ADR-306) — composes
+ * `@claude-flow/security`'s ported OAuth primitives (loopback PKCE, OOB
+ * manual-paste, refresh) the same way meta-proxy's `oauth/login.rs`
+ * orchestrates its own Rust primitives. See security-bridge.ts for why the
+ * package is loaded lazily, and oauth/client.ts (in @claude-flow/security)
+ * for why this targets the live `auth.cognitum.one` surface rather than
+ * ADR-308's unconfirmed `/v1/auth/*` spec.
+ *
+ * @module auth/client
+ */
+import * as readline from 'node:readline/promises';
+import { existsSync } from 'node:fs';
+import { loadSecurityOAuth } from './security-bridge.js';
+import { KEYCHAIN_SERVICE } from './constants.js';
+import { getProfile, setProfile } from './state.js';
+import { getSessionToken, setSessionToken } from './session.js';
+import { hasConsent } from '../funnel/index.js';
+import { domainForScope } from './scopes.js';
+/** Refresh before there is less than one minute left on the access token. */
+export const ACCESS_TOKEN_REFRESH_WINDOW_MS = 60_000;
+/**
+ * Best-effort headlessness signal — a false negative just means the browser
+ * flow is attempted and a real browser opens fine anyway; a false positive
+ * means the user falls back to the manual OOB flow, which always works
+ * regardless. Mirrors meta-proxy's `login.rs::is_probably_headless()`.
+ */
+export function isProbablyHeadless() {
+    return Boolean(process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.CONTAINER || existsDockerEnv());
+}
+function existsDockerEnv() {
+    try {
+        return existsSync('/.dockerenv');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates the OAuth callback params against the request that started the
+ * flow — the CSRF-critical step, extracted so it's independently testable.
+ * Order matters: an explicit `error` (user denied) and a missing code are
+ * reported as their own reasons; a missing or mismatched `state` is always
+ * a state-mismatch, even when a code is present.
+ */
+export function validateCallback(error, code, returnedState, expectedState) {
+    if (error)
+        return { ok: false, reason: 'denied', detail: error };
+    if (!code)
+        return { ok: false, reason: 'denied', detail: 'no authorization code received' };
+    if (!returnedState || returnedState !== expectedState)
+        return { ok: false, reason: 'state-mismatch' };
+    return { ok: true, code };
+}
+export class LoginCancelledError extends Error {
+    constructor() {
+        super('login cancelled: no code was entered');
+        this.name = 'LoginCancelledError';
+    }
+}
+export class LoginDeniedError extends Error {
+    constructor(detail) {
+        super(`authorization was denied or failed: ${detail}`);
+        this.name = 'LoginDeniedError';
+    }
+}
+export class StateMismatchError extends Error {
+    constructor() {
+        super('state mismatch — the OAuth callback did not match the request this CLI sent');
+        this.name = 'StateMismatchError';
+    }
+}
+export class NotLoggedInError extends Error {
+    constructor(profile) {
+        super(`not logged in for profile "${profile}" — run: ruflo auth login --profile ${profile}`);
+        this.name = 'NotLoggedInError';
+    }
+}
+export class SessionOnlyExpiredError extends Error {
+    constructor(profile) {
+        super(`profile "${profile}" has no persisted refresh token and its in-memory access token is ` +
+            `absent or expiring — run: ruflo auth login --profile ${profile}`);
+        this.name = 'SessionOnlyExpiredError';
+    }
+}
+export class ScopeConsentMismatchError extends Error {
+    constructor(profile, scopes) {
+        super(`profile "${profile}" has scope(s) without matching local consent: ${scopes.join(', ')} — ` +
+            'authenticated capability denied');
+        this.name = 'ScopeConsentMismatchError';
+    }
+}
+/** Browser-based loopback PKCE login — the ADR-306 default for an interactive desktop. */
+export async function browserLogin(print) {
+    const sec = await loadSecurityOAuth();
+    const server = await sec.CallbackServer.bind();
+    const pkce = sec.generatePkce();
+    const url = sec.authorizeUrl(server.redirectUri, pkce.state, pkce.codeChallenge);
+    print('Opening your browser to sign in to Cognitum...');
+    print(`If it doesn't open automatically, visit:\n\n  ${url}\n`);
+    await sec.openBrowser(url).catch(() => { }); // best-effort — the URL above is always the fallback
+    print('Waiting for you to finish signing in...');
+    const result = await server.awaitCallback();
+    const validated = validateCallback(result.error, result.code, result.state, pkce.state);
+    if (!validated.ok) {
+        if (validated.reason === 'state-mismatch')
+            throw new StateMismatchError();
+        throw new LoginDeniedError(validated.detail ?? 'unknown');
+    }
+    const tokens = await sec.exchangeCode(validated.code, pkce.codeVerifier, server.redirectUri);
+    return { tokens, method: 'pkce' };
+}
+/** Headless fallback: prints the authorize URL with the OOB redirect, prompts for the pasted code. */
+export async function manualLogin(print, input = process.stdin) {
+    const sec = await loadSecurityOAuth();
+    print('Browser-based callback unavailable (SSH/container detected, or --no-browser).\n');
+    const pkce = sec.generatePkce();
+    const url = sec.authorizeUrl(sec.OOB_REDIRECT_URI, pkce.state, pkce.codeChallenge);
+    print(`Open this URL in a browser and authorize:\n\n  ${url}\n`);
+    // `rl.question()` resolves on a newline-terminated 'line' event — if `input`
+    // ends without ever emitting one (e.g. stdin closed early, or piped input
+    // with no trailing newline), it hangs forever rather than treating EOF as
+    // a cancellation. Race it against the interface's own 'close' event so an
+    // early EOF resolves to "" (-> LoginCancelledError below) instead of hanging.
+    const rl = readline.createInterface({ input, terminal: false });
+    let code;
+    try {
+        const closed = new Promise((resolve) => rl.once('close', () => resolve('')));
+        code = (await Promise.race([rl.question('Paste the code shown after authorizing: '), closed])).trim();
+    }
+    finally {
+        rl.close();
+    }
+    if (!code)
+        throw new LoginCancelledError();
+    const tokens = await sec.exchangeManualCode(code, pkce.codeVerifier);
+    return { tokens, method: 'device' };
+}
+/**
+ * `--token-stdin`: reads one JSON object from stdin,
+ * `{access_token, refresh_token?, expires_in, scope}`. Wire format is not
+ * specified by ADR-306 — defined here as typed JSON rather than a bare
+ * token string, so scope/expiry are explicit rather than inferred.
+ */
+export async function tokenStdinLogin(input = process.stdin) {
+    const chunks = [];
+    for await (const chunk of input)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    if (!raw)
+        throw new Error('--token-stdin: no input received on stdin');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--token-stdin expects a single JSON object: {"access_token","refresh_token"?,"expires_in","scope"}');
+    }
+    if (!parsed.access_token)
+        throw new Error('--token-stdin: JSON is missing required field "access_token"');
+    const tokens = {
+        access_token: parsed.access_token,
+        token_type: 'Bearer',
+        refresh_token: parsed.refresh_token,
+        expires_in: parsed.expires_in,
+    };
+    return { tokens, method: 'token-stdin' };
+}
+/**
+ * Refreshes an access token. Classifies failure into network-unreachable
+ * vs. a reachable-but-erroring server so callers can print an honest
+ * message instead of collapsing both into "offline" (ADR-308 failure
+ * policy: local ruflo functionality is never affected by auth being
+ * unavailable, but the diagnostic should say WHY it's unavailable).
+ */
+export async function refreshAccessToken(refreshTokenValue) {
+    const sec = await loadSecurityOAuth();
+    try {
+        return await sec.refreshToken(refreshTokenValue);
+    }
+    catch (e) {
+        if (e instanceof sec.OAuthError) {
+            if (e.code === 'network') {
+                throw new Error('Could not reach the Cognitum auth service. ruflo core functionality is unaffected — ' +
+                    'sign-in is not required for local use.');
+            }
+            throw new Error(`Cognitum auth service returned an unexpected response: ${e.message}`);
+        }
+        throw e;
+    }
+}
+/**
+ * Returns an access token suitable for an authenticated call.
+ *
+ * Fast path: a process-memory token with more than one minute remaining.
+ * Slow path: load the profile's refresh token from the OS keychain, perform
+ * one refresh, persist a rotated refresh token BEFORE exposing the new access
+ * token, then update metadata and the process cache. Refresh is deliberately
+ * demand-driven: offline-safe commands such as plain `auth status` never call
+ * this function and therefore never create background traffic or retry loops.
+ */
+export async function getValidAccessToken(profileName = 'default') {
+    const profile = getProfile(profileName);
+    if (!profile)
+        throw new NotLoggedInError(profileName);
+    const scopesWithoutConsent = profile.scopes.filter((scope) => {
+        const domain = domainForScope(scope);
+        return domain !== undefined && !hasConsent(domain);
+    });
+    if (scopesWithoutConsent.length > 0) {
+        throw new ScopeConsentMismatchError(profileName, scopesWithoutConsent);
+    }
+    const cached = getSessionToken(profileName, ACCESS_TOKEN_REFRESH_WINDOW_MS);
+    if (cached)
+        return cached;
+    if (!profile.keychainRef)
+        throw new SessionOnlyExpiredError(profileName);
+    const sec = await loadSecurityOAuth();
+    const keychain = await sec.createKeychainAdapter();
+    const refreshTokenValue = await keychain.getSecret(KEYCHAIN_SERVICE, profile.keychainRef);
+    if (!refreshTokenValue)
+        throw new SessionOnlyExpiredError(profileName);
+    const refreshed = await refreshAccessToken(refreshTokenValue);
+    if (!refreshed.access_token)
+        throw new Error('Cognitum refresh response did not contain an access token');
+    // Cognitum rotates refresh tokens with reuse detection. Commit the rotated
+    // credential first; if this write fails, do not publish/cache the access
+    // token and do not retry the already-spent old refresh token here.
+    if (refreshed.refresh_token) {
+        await keychain.setSecret(KEYCHAIN_SERVICE, profile.keychainRef, refreshed.refresh_token);
+    }
+    const expiresAtMs = Date.now() + Math.max(0, refreshed.expires_in ?? 0) * 1000;
+    setSessionToken(profileName, refreshed.access_token, expiresAtMs);
+    setProfile(profileName, {
+        ...profile,
+        accountId: refreshed.account_email ?? profile.accountId,
+        accessTokenExpiresAt: new Date(expiresAtMs).toISOString(),
+        linkedAt: new Date().toISOString(),
+    });
+    return refreshed.access_token;
+}
+//# sourceMappingURL=client.js.map

package/dist/src/auth/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared ADR-306 constants — split out so `commands/auth.ts` and
+ * `auth/client.ts` reference the same keychain service name rather than two
+ * independently-typed string literals that could silently drift apart.
+ */
+export declare const KEYCHAIN_SERVICE = "ruflo-cognitum-auth";
+//# sourceMappingURL=constants.d.ts.map