@askalf/dario 3.31.5 → 3.31.11

package/dist/cc-authorize-probe.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Live probe of Anthropic's /oauth/authorize endpoint.
+ *
+ * Lifted from scripts/_authorize-probe-classifier.mjs and
+ * scripts/check-cc-authorize-probe.mjs so `dario doctor --probe` can
+ * reuse the same logic without re-importing from scripts. The .mjs
+ * files re-export from this module for the CI drift watcher.
+ *
+ * Motivating pattern: Anthropic's policy engine flips scope
+ * acceptability without changing what CC ships in its binary, so the
+ * binary-scan drift watcher can't see the flip. The live probe fills
+ * that gap — but from GitHub Actions IPs it hits Cloudflare's bot
+ * challenge and comes back "inconclusive" most of the time. Running
+ * the same probe from a user's own machine (via `dario doctor
+ * --probe`) is the workaround: CF doesn't challenge residential IPs
+ * the same way. See dario #42 / #71 for the incidents this prevents.
+ */
+/**
+ * The specific string Anthropic's authorize endpoint returns for a
+ * scope set its policy engine rejects. Observed across multiple
+ * incidents (dario #22, #42, #71) — stable across the policy flips.
+ */
+export declare const REJECT_MARKER = "Invalid request format";
+/**
+ * The minimal response shape the classifier needs. `fetch` results can
+ * be mapped to this in one call (see `probeAuthorize` below).
+ */
+export interface AuthorizeResponse {
+    status: number;
+    location: string | null;
+    body: string;
+    error: string | null;
+}
+export type ProbeVerdict = 'accepted' | 'rejected' | 'inconclusive';
+export interface ClassifiedVerdict {
+    verdict: ProbeVerdict;
+    reason: string;
+}
+/**
+ * Classify a single authorize-endpoint response.
+ *
+ *   accepted     — 3xx redirect to login/consent, OR 2xx without the
+ *                  reject marker. The scope set passed validation.
+ *   rejected     — body contains the specific "Invalid request format"
+ *                  marker. The scope set was refused.
+ *   inconclusive — fetch error, Cloudflare challenge, or any other
+ *                  response shape we can't categorize. Not drift; try
+ *                  again.
+ */
+export declare function classifyAuthorizeResponse({ status, location, body, error }: AuthorizeResponse): ClassifiedVerdict;
+export interface DriftItem {
+    probe: 'A' | 'B';
+    severity: 'high' | 'medium' | 'info';
+    message: string;
+}
+export interface CombinedVerdict {
+    outcome: 'clean' | 'drift' | 'inconclusive';
+    drift: boolean;
+    items: DriftItem[];
+}
+/**
+ * Combine the verdicts for probe A (pinned 6-scope) and probe B
+ * (5-scope, org:create_api_key removed) into a single watcher result.
+ * See scripts/check-cc-authorize-probe.mjs for the full rationale.
+ */
+export declare function combineVerdicts(a: ClassifiedVerdict, b: ClassifiedVerdict): CombinedVerdict;
+export interface ProbeConfig {
+    clientId: string;
+    authorizeUrl: string;
+    scopes: string;
+}
+export interface ProbeOptions {
+    timeoutMs?: number;
+    /** Test hook. Default: `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export interface ProbeResult extends ClassifiedVerdict {
+    /** The exact URL sent — useful for the user to paste into a browser if the verdict is rejected. */
+    probedUrl: string;
+    /** Scope count from `scopes`, for quick human read-out. */
+    scopeCount: number;
+}
+export declare function buildProbeAuthorizeUrl(cfg: ProbeConfig): string;
+/**
+ * Probe the authorize endpoint with the given config. Follows exactly
+ * one redirect hop if the Location points at a trusted Anthropic host
+ * (claude.ai / claude.com / *.anthropic.com) — the legacy
+ * `claude.com/cai/oauth/authorize` edge 307s to claude.ai and the
+ * destination is where the validation happens. Stopping at the edge
+ * would silently treat every scope set as accepted.
+ */
+export declare function runAuthorizeProbe(cfg: ProbeConfig, opts?: ProbeOptions): Promise<ProbeResult>;

package/dist/cc-authorize-probe.js

@@ -0,0 +1,186 @@
+/**
+ * Live probe of Anthropic's /oauth/authorize endpoint.
+ *
+ * Lifted from scripts/_authorize-probe-classifier.mjs and
+ * scripts/check-cc-authorize-probe.mjs so `dario doctor --probe` can
+ * reuse the same logic without re-importing from scripts. The .mjs
+ * files re-export from this module for the CI drift watcher.
+ *
+ * Motivating pattern: Anthropic's policy engine flips scope
+ * acceptability without changing what CC ships in its binary, so the
+ * binary-scan drift watcher can't see the flip. The live probe fills
+ * that gap — but from GitHub Actions IPs it hits Cloudflare's bot
+ * challenge and comes back "inconclusive" most of the time. Running
+ * the same probe from a user's own machine (via `dario doctor
+ * --probe`) is the workaround: CF doesn't challenge residential IPs
+ * the same way. See dario #42 / #71 for the incidents this prevents.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * The specific string Anthropic's authorize endpoint returns for a
+ * scope set its policy engine rejects. Observed across multiple
+ * incidents (dario #22, #42, #71) — stable across the policy flips.
+ */
+export const REJECT_MARKER = 'Invalid request format';
+/** Not a real callback — the probe only needs the initial response. */
+const PROBE_REDIRECT_URI = 'http://localhost:12345/callback';
+const PROBE_TIMEOUT_MS = 15_000;
+/** Cloudflare fronts claude.ai and challenges unrecognized clients. */
+function isCloudflareChallenge({ status, body }) {
+    const bodyText = typeof body === 'string' ? body : '';
+    if (bodyText.includes('Just a moment...') || bodyText.includes('/cdn-cgi/challenge-platform/')) {
+        return true;
+    }
+    if (status === 403 && bodyText.includes('cdn-cgi')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Classify a single authorize-endpoint response.
+ *
+ *   accepted     — 3xx redirect to login/consent, OR 2xx without the
+ *                  reject marker. The scope set passed validation.
+ *   rejected     — body contains the specific "Invalid request format"
+ *                  marker. The scope set was refused.
+ *   inconclusive — fetch error, Cloudflare challenge, or any other
+ *                  response shape we can't categorize. Not drift; try
+ *                  again.
+ */
+export function classifyAuthorizeResponse({ status, location, body, error }) {
+    if (error) {
+        return { verdict: 'inconclusive', reason: `fetch error: ${error}` };
+    }
+    if (isCloudflareChallenge({ status, body })) {
+        return {
+            verdict: 'inconclusive',
+            reason: `blocked by Cloudflare bot challenge (status=${status}). ` +
+                `The live probe is unreliable from CI IPs — rely on the scope-literal ` +
+                `scan in check-cc-drift.mjs, or run this probe from a trusted network.`,
+        };
+    }
+    const bodyText = typeof body === 'string' ? body : '';
+    if (bodyText.includes(REJECT_MARKER)) {
+        return { verdict: 'rejected', reason: `body contains "${REJECT_MARKER}"` };
+    }
+    if (status >= 300 && status < 400 && typeof location === 'string' && location.length > 0) {
+        return { verdict: 'accepted', reason: `${status} redirect to ${location}` };
+    }
+    if (status >= 200 && status < 300) {
+        return { verdict: 'accepted', reason: `${status} body rendered, no reject marker` };
+    }
+    return {
+        verdict: 'inconclusive',
+        reason: `unexpected response: status=${status}, location=${location ?? 'none'}, body_len=${bodyText.length}`,
+    };
+}
+/**
+ * Combine the verdicts for probe A (pinned 6-scope) and probe B
+ * (5-scope, org:create_api_key removed) into a single watcher result.
+ * See scripts/check-cc-authorize-probe.mjs for the full rationale.
+ */
+export function combineVerdicts(a, b) {
+    if (a.verdict === 'inconclusive' || b.verdict === 'inconclusive') {
+        const items = [];
+        if (a.verdict === 'inconclusive')
+            items.push({ probe: 'A', severity: 'info', message: `probe A inconclusive: ${a.reason}` });
+        if (b.verdict === 'inconclusive')
+            items.push({ probe: 'B', severity: 'info', message: `probe B inconclusive: ${b.reason}` });
+        return { outcome: 'inconclusive', drift: false, items };
+    }
+    const items = [];
+    if (a.verdict !== 'accepted') {
+        items.push({
+            probe: 'A',
+            severity: 'high',
+            message: `Pinned FALLBACK.scopes (6-scope) no longer accepted by authorize endpoint (${a.reason}). ` +
+                `This is the dario #42 / #71 failure mode: users will hit "Invalid request format" on fresh login. ` +
+                `Investigate which scope the server now rejects and update FALLBACK.scopes in src/cc-oauth-detect.ts; ` +
+                `bump the cache suffix (CACHE_PATH) so existing users regenerate.`,
+        });
+    }
+    if (b.verdict === 'accepted') {
+        items.push({
+            probe: 'B',
+            severity: 'info',
+            message: `5-scope form (org:create_api_key removed) is ALSO accepted. Anthropic's authorize ` +
+                `endpoint appears permissive for this client_id — both the 6-scope form our users send ` +
+                `and the 5-scope form are accepted. Nothing to fix; recorded so we notice when it flips.`,
+        });
+    }
+    const hasDrift = items.some((i) => i.severity === 'high');
+    return {
+        outcome: hasDrift ? 'drift' : 'clean',
+        drift: hasDrift,
+        items,
+    };
+}
+function base64url(buf) {
+    return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function pkceChallenge() {
+    const verifier = base64url(randomBytes(32));
+    return base64url(createHash('sha256').update(verifier).digest());
+}
+export function buildProbeAuthorizeUrl(cfg) {
+    const params = new URLSearchParams({
+        code: 'true',
+        client_id: cfg.clientId,
+        response_type: 'code',
+        redirect_uri: PROBE_REDIRECT_URI,
+        scope: cfg.scopes,
+        code_challenge: pkceChallenge(),
+        code_challenge_method: 'S256',
+        state: base64url(randomBytes(16)),
+    });
+    return `${cfg.authorizeUrl}?${params.toString()}`;
+}
+const PROBE_HEADERS = {
+    'User-Agent': 'dario-cc-authorize-probe/1 (+https://github.com/askalf/dario)',
+    Accept: 'text/html,application/xhtml+xml;q=0.9,*/*;q=0.8',
+};
+async function fetchOnce(url, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? PROBE_TIMEOUT_MS;
+    try {
+        const res = await fetchImpl(url, {
+            method: 'GET',
+            redirect: 'manual',
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: PROBE_HEADERS,
+        });
+        const location = res.headers.get('location');
+        let body = '';
+        try {
+            body = await res.text();
+        }
+        catch (err) {
+            return { status: res.status, location, body: '', error: `read body failed: ${err?.message ?? String(err)}` };
+        }
+        return { status: res.status, location, body, error: null };
+    }
+    catch (err) {
+        return { status: 0, location: null, body: '', error: err?.message ?? String(err) };
+    }
+}
+/**
+ * Probe the authorize endpoint with the given config. Follows exactly
+ * one redirect hop if the Location points at a trusted Anthropic host
+ * (claude.ai / claude.com / *.anthropic.com) — the legacy
+ * `claude.com/cai/oauth/authorize` edge 307s to claude.ai and the
+ * destination is where the validation happens. Stopping at the edge
+ * would silently treat every scope set as accepted.
+ */
+export async function runAuthorizeProbe(cfg, opts = {}) {
+    const url = buildProbeAuthorizeUrl(cfg);
+    const first = await fetchOnce(url, opts);
+    const trustedRedirect = first.status >= 300 && first.status < 400 &&
+        typeof first.location === 'string' &&
+        /^https:\/\/(claude\.ai|claude\.com|[\w-]+\.anthropic\.com)\//.test(first.location);
+    const response = trustedRedirect && first.location !== null
+        ? await fetchOnce(first.location, opts)
+        : first;
+    const classified = classifyAuthorizeResponse(response);
+    const scopeCount = cfg.scopes.split(/\s+/).filter(Boolean).length;
+    return { ...classified, probedUrl: url, scopeCount };
+}

package/dist/cc-oauth-detect.d.ts

@@ -75,6 +75,16 @@ export declare const FALLBACK_FOR_DRIFT_CHECK: Readonly<DetectedOAuthConfig>;
  * window after it.
  */
 export declare function scanBinaryForOAuthConfig(buf: Buffer): Omit<DetectedOAuthConfig, 'source' | 'ccPath' | 'ccHash'> | null;
+/**
+ * Given CC's binary and a list of scope literals we expect to find,
+ * return the subset that actually appear as quoted-string literals in
+ * the binary. Scoping the match to `"<scope>"` (with surrounding
+ * double quotes) avoids false matches on partial substrings. Pure
+ * over its inputs — safe to unit-test without a real CC binary.
+ *
+ * Exported for unit tests.
+ */
+export declare function filterScopesByBinaryPresence(buf: Buffer, expected: readonly string[]): string[];
 /**
  * Get the OAuth config for dario to use. Scans the installed CC binary
  * on first call, caches to disk, and memoizes in-process for subsequent

package/dist/cc-oauth-detect.js

@@ -273,22 +273,51 @@ export function scanBinaryForOAuthConfig(buf) {
     const tokenMatch = /TOKEN_URL\s*:\s*"(https:\/\/[^"]*\/oauth\/token[^"]*)"/.exec(prodBlock);
     if (tokenMatch && tokenMatch[1])
         tokenUrl = tokenMatch[1];
-    // Scopes are NOT detected from the binary. Previous versions of this
-    // scanner anchored on `"user:profile ` and regex-captured the first
-    // contiguous quoted run of scopes, but that anchor matches an error/help
-    // message string literal (used by `claude setup-token` error output) that
-    // contains only 4 of the 6 actual scopes. The real scope array is stored
-    // as a constant-reference array — `dY8 = [B9H, TI, "user:sessions:...", ...]`
-    // — where the first two elements are minified variable references, not
-    // literal strings, so no regex can reliably extract the full list. And the
-    // runtime-computed union `n36` only exists after `Array.from(new Set(...))`
-    // executes, which we can't evaluate from a static scan.
+    // Scopes can't be EXTRACTED from the binary — the real scope array is
+    // stored as a constant-reference array (`dY8 = [B9H, TI, "user:sessions:
+    // ...", ...]`) where the first elements are minified variable references,
+    // not literal strings, so no regex resolves the full list statically.
     //
-    // Given that scopes rarely change across CC releases (Anthropic adds or
-    // removes maybe one per major version), hardcoding them in FALLBACK is
-    // more reliable than scanning. If Anthropic changes the scope list, the
-    // fix is a one-line FALLBACK update in a dario release.
-    return { clientId, authorizeUrl, tokenUrl, scopes: FALLBACK.scopes };
+    // But we CAN verify them: every scope CC uses does appear as a quoted
+    // literal string somewhere in the binary (either in the scope array
+    // itself when not minified to a variable ref, or in help-text /
+    // error-message references that name scopes by literal). Scan for each
+    // FALLBACK scope's quoted literal; if any go missing, drop those
+    // scopes from the returned config and log a warning.
+    //
+    // This catches one class of drift the hardcoded FALLBACK doesn't: a
+    // future CC release that REMOVES a scope from the active set — Anthropic
+    // deprecates `user:file_upload` in CC v2.2.0, say — would leave dario
+    // sending a stale scope that the server now rejects, same failure mode
+    // as #42 / #71. Binary verification catches it at startup without
+    // waiting for a user to hit the "Invalid request format" page.
+    //
+    // It does NOT catch the opposite direction (Anthropic starts accepting
+    // a new scope CC didn't previously use) — those still require a FALLBACK
+    // bump. The probe in scripts/check-cc-authorize-probe.mjs + `dario
+    // doctor --probe` covers that direction.
+    const expected = FALLBACK.scopes.split(/\s+/).filter(Boolean);
+    const verified = filterScopesByBinaryPresence(buf, expected);
+    const scopes = verified.length > 0 ? verified.join(' ') : FALLBACK.scopes;
+    return { clientId, authorizeUrl, tokenUrl, scopes };
+}
+/**
+ * Given CC's binary and a list of scope literals we expect to find,
+ * return the subset that actually appear as quoted-string literals in
+ * the binary. Scoping the match to `"<scope>"` (with surrounding
+ * double quotes) avoids false matches on partial substrings. Pure
+ * over its inputs — safe to unit-test without a real CC binary.
+ *
+ * Exported for unit tests.
+ */
+export function filterScopesByBinaryPresence(buf, expected) {
+    const out = [];
+    for (const scope of expected) {
+        const needle = Buffer.from(`"${scope}"`);
+        if (buf.includes(needle))
+            out.push(scope);
+    }
+    return out;
 }
 async function loadCache() {
     try {

package/dist/cli.js

@@ -643,6 +643,30 @@ async function help() {
                              CLI. (v3.27)
     dario doctor             Print a health report: dario / Node / CC /
                              template / drift / OAuth / pool / backends
+    dario doctor --probe     Also hit Anthropic's authorize endpoint with
+                             dario's effective OAuth config and surface
+                             the server's verdict — the single reliable
+                             signal for scope-policy drift (dario#42/#71
+                             class). One GET to claude.ai; no PII.
+    dario doctor --json      Emit the check report as structured JSON
+                             for machine consumption (claude-bridge
+                             /status, CI scripts, etc.) instead of the
+                             human-readable table.
+    dario doctor --auth-check
+                             One-shot listener on an ephemeral loopback
+                             port. Send ONE request from your client
+                             (OpenClaw, Hermes, curl, etc.) and dario
+                             classifies the auth headers it sees against
+                             DARIO_API_KEY — with redacted previews and
+                             a targeted diagnosis (dario#97 class). Use
+                             --timeout-ms=N to adjust the 30s default.
+    dario config             Print the effective configuration (port,
+                             host, DARIO_API_KEY state, OAuth status,
+                             pool, backends, paths) with credentials
+                             redacted. Safe to paste into bug reports.
+                             --json for structured output.
+    dario upgrade            npm install -g @askalf/dario@latest with a
+                             pre-flight current-vs-latest check.
 
   Proxy options:
     --model=MODEL            Force a model for all requests
@@ -942,17 +966,65 @@ async function mcp() {
     }
 }
 async function doctor() {
-    const { runChecks, formatChecks, exitCodeFor } = await import('./doctor.js');
+    const { runChecks, formatChecks, formatChecksJson, exitCodeFor, runAuthCheck } = await import('./doctor.js');
+    const probe = args.includes('--probe');
+    const asJson = args.includes('--json');
+    const authCheck = args.includes('--auth-check');
+    if (authCheck) {
+        console.log('');
+        console.log('  dario — Auth Check');
+        console.log('  ──────────────────');
+        console.log('');
+        const timeoutArg = args.find((a) => a.startsWith('--timeout-ms='));
+        const timeoutMs = timeoutArg ? Math.max(1000, parseInt(timeoutArg.split('=')[1], 10)) : 30_000;
+        const result = await runAuthCheck({
+            timeoutMs,
+            onListening: (port) => {
+                console.log(`  Listening on http://127.0.0.1:${port}/`);
+                console.log(`  Waiting up to ${Math.round(timeoutMs / 1000)}s for ONE request from your client.`);
+                console.log('  Any path and method are fine — dario only inspects the auth headers.');
+                console.log('');
+            },
+        });
+        console.log(`  Verdict:   ${result.verdict}`);
+        console.log(`  Expected:  ${result.expected === '<unset>' ? '(unset)' : 'Bearer <key>  (DARIO_API_KEY matches)'}`);
+        if (result.received) {
+            const seen = [];
+            if (result.authorization?.present)
+                seen.push(`Authorization: ${result.authorization.redacted}${result.authorization.bearerPrefix === false ? ' (no Bearer prefix)' : ''}`);
+            if (result.xApiKey?.present)
+                seen.push(`x-api-key: ${result.xApiKey.redacted}`);
+            console.log(`  Received:  ${seen.length > 0 ? seen.join(', ') : 'no auth headers'}`);
+        }
+        else {
+            console.log(`  Received:  (no request within ${Math.round(timeoutMs / 1000)}s)`);
+        }
+        console.log('');
+        console.log('  ' + result.diagnosis);
+        console.log('');
+        process.exit(result.verdict === 'match' ? 0 : 1);
+    }
+    const checks = await runChecks({ probe });
+    if (asJson) {
+        // JSON mode is meant for machine consumption (claude-bridge /status,
+        // deepdive health checks, CI scripts) — no decorative header, no
+        // trailing prose, stable shape. Exit code is also surfaced in the
+        // JSON envelope for callers that can't read process exit codes.
+        process.stdout.write(formatChecksJson(checks) + '\n');
+        process.exit(exitCodeFor(checks));
+    }
     console.log('');
     console.log('  dario — Doctor');
     console.log('  ─────────────');
     console.log('');
-    const checks = await runChecks();
     console.log(formatChecks(checks));
     console.log('');
     const code = exitCodeFor(checks);
     if (code !== 0) {
         console.log('  One or more checks failed. Address the [FAIL] rows and re-run `dario doctor`.');
+        if (!probe) {
+            console.log('  For a live check against Anthropic\'s authorize endpoint, re-run with `--probe`.');
+        }
         console.log('');
     }
     process.exit(code);
@@ -969,6 +1041,86 @@ async function version() {
         console.log('unknown');
     }
 }
+async function config() {
+    const { collectEffectiveConfig, formatEffectiveConfig, formatEffectiveConfigJson } = await import('./config-report.js');
+    const asJson = args.includes('--json');
+    const report = await collectEffectiveConfig();
+    if (asJson) {
+        process.stdout.write(formatEffectiveConfigJson(report) + '\n');
+        return;
+    }
+    console.log('');
+    console.log('  dario — Config');
+    console.log('  ─────────────');
+    console.log('');
+    console.log(formatEffectiveConfig(report));
+}
+async function upgrade() {
+    // Thin wrapper over `npm install -g @askalf/dario@latest`. The value
+    // isn't in saving the user typing — it's in the pre-flight (print
+    // current vs. latest version, refuse to run if already on latest,
+    // fail with a clear hint if npm is missing).
+    const { spawnSync } = await import('node:child_process');
+    const { fileURLToPath } = await import('node:url');
+    const { readFile: rf } = await import('node:fs/promises');
+    const dir = join(fileURLToPath(import.meta.url), '..', '..');
+    let currentVersion = 'unknown';
+    try {
+        const pkg = JSON.parse(await rf(join(dir, 'package.json'), 'utf-8'));
+        currentVersion = pkg.version ?? 'unknown';
+    }
+    catch { /* noop */ }
+    console.log('');
+    console.log('  dario — Upgrade');
+    console.log('  ──────────────');
+    console.log('');
+    console.log(`  Current: v${currentVersion}`);
+    // Probe npm for the latest version first — avoids a long npm install if
+    // the user's already on @latest. 3s timeout keeps the pre-flight short.
+    let latestVersion = null;
+    try {
+        const res = spawnSync('npm', ['view', '@askalf/dario', 'version'], {
+            encoding: 'utf8',
+            timeout: 3000,
+            shell: process.platform === 'win32',
+        });
+        if (res.status === 0) {
+            const m = /(\d+\.\d+\.\d+(?:[.\-][\w.\-]+)?)/.exec(res.stdout);
+            latestVersion = m ? m[1] : null;
+        }
+    }
+    catch { /* noop */ }
+    if (!latestVersion) {
+        console.log('  Latest: (npm view failed — is npm on PATH? Continuing anyway.)');
+    }
+    else {
+        console.log(`  Latest:  v${latestVersion}`);
+        if (latestVersion === currentVersion) {
+            console.log('');
+            console.log('  Already on the latest release. Nothing to do.');
+            console.log('');
+            return;
+        }
+    }
+    console.log('');
+    console.log('  Running: npm install -g @askalf/dario@latest');
+    console.log('');
+    const install = spawnSync('npm', ['install', '-g', '@askalf/dario@latest'], {
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+    });
+    if (install.status !== 0) {
+        console.error('');
+        console.error('  npm install failed. If this is a permissions issue, try:');
+        console.error('    sudo npm install -g @askalf/dario@latest     # POSIX');
+        console.error('    npm install -g @askalf/dario@latest          # Windows (may need admin)');
+        console.error('');
+        process.exit(install.status ?? 1);
+    }
+    console.log('');
+    console.log('  Upgrade complete. Run `dario --version` to confirm.');
+    console.log('');
+}
 // Main
 const commands = {
     login,
@@ -982,6 +1134,8 @@ const commands = {
     subagent,
     mcp,
     doctor,
+    config,
+    upgrade,
     help,
     version,
     '--help': help,

package/dist/config-report.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `dario config` — print effective configuration with credentials redacted.
+ *
+ * Different from `dario doctor`: doctor is "is it working?", config is
+ * "what IS it?". The overlap is intentional — config shows *settings*
+ * (port, host, DARIO_API_KEY state, model defaults) that operators
+ * need to confirm when debugging a client misconfiguration. Doctor
+ * shows *health* (OAuth expiry, template drift, TLS fingerprint
+ * match) that operators need to confirm when debugging a routing
+ * failure.
+ *
+ * Every output row is already safe to paste into a bug report:
+ * credentials are replaced with `set`/`unset` state tags, paths are
+ * left untouched because they're operationally useful, tokens never
+ * appear.
+ */
+export interface ConfigSection {
+    title: string;
+    rows: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+export interface ConfigReport {
+    generatedAt: string;
+    version: string;
+    sections: ConfigSection[];
+}
+/**
+ * Collect the effective dario configuration the proxy would run with.
+ * Reads env vars, filesystem state (credentials, override files, caches),
+ * account pool, and configured backends. Never reads the actual
+ * credential VALUES — only their presence/absence/path.
+ */
+export declare function collectEffectiveConfig(): Promise<ConfigReport>;
+export declare function formatAge(ms: number): string;
+/**
+ * Pretty-print a ConfigReport as aligned ASCII. Same approach as
+ * doctor's formatChecks — plain text, no colors, pasteable.
+ */
+export declare function formatEffectiveConfig(report: ConfigReport): string;
+/** Structured envelope for `dario config --json`. */
+export declare function formatEffectiveConfigJson(report: ConfigReport): string;

package/dist/config-report.js

@@ -0,0 +1,187 @@
+/**
+ * `dario config` — print effective configuration with credentials redacted.
+ *
+ * Different from `dario doctor`: doctor is "is it working?", config is
+ * "what IS it?". The overlap is intentional — config shows *settings*
+ * (port, host, DARIO_API_KEY state, model defaults) that operators
+ * need to confirm when debugging a client misconfiguration. Doctor
+ * shows *health* (OAuth expiry, template drift, TLS fingerprint
+ * match) that operators need to confirm when debugging a routing
+ * failure.
+ *
+ * Every output row is already safe to paste into a bug report:
+ * credentials are replaced with `set`/`unset` state tags, paths are
+ * left untouched because they're operationally useful, tokens never
+ * appear.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Collect the effective dario configuration the proxy would run with.
+ * Reads env vars, filesystem state (credentials, override files, caches),
+ * account pool, and configured backends. Never reads the actual
+ * credential VALUES — only their presence/absence/path.
+ */
+export async function collectEffectiveConfig() {
+    const sections = [];
+    const home = join(homedir(), '.dario');
+    // ── Identity
+    let version = 'unknown';
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+        version = pkg.version ?? 'unknown';
+    }
+    catch { /* noop */ }
+    sections.push({
+        title: 'Identity',
+        rows: [
+            { label: 'version', value: `v${version}` },
+            { label: 'runtime', value: `node ${process.version} on ${process.platform} ${process.arch}` },
+        ],
+    });
+    // ── Proxy bind
+    sections.push({
+        title: 'Proxy (on `dario proxy`)',
+        rows: [
+            { label: 'port', value: envOrDefault('DARIO_PORT', '3456') },
+            { label: 'host', value: envOrDefault('DARIO_HOST', '127.0.0.1') },
+            { label: 'model', value: envOrDefault('DARIO_MODEL', '(passthrough — client picks)') },
+            { label: 'effort', value: envOrDefault('DARIO_EFFORT', '(CC default)') },
+        ],
+    });
+    // ── Auth gate
+    sections.push({
+        title: 'Auth gate',
+        rows: [
+            {
+                label: 'DARIO_API_KEY',
+                value: process.env.DARIO_API_KEY
+                    ? `set (length ${process.env.DARIO_API_KEY.length}) — x-api-key / Authorization Bearer required`
+                    : 'unset — auth not enforced on loopback',
+            },
+            {
+                label: 'DARIO_STRICT_TLS',
+                value: process.env.DARIO_STRICT_TLS === '1' ? 'on' : 'off',
+            },
+        ],
+    });
+    // ── OAuth (Claude subscription credentials)
+    const credsPath = join(home, 'credentials.json');
+    const credsInfo = describeCreds(credsPath);
+    sections.push({
+        title: 'OAuth',
+        rows: [
+            { label: 'credentials', value: credsInfo },
+            { label: 'path', value: credsPath },
+        ],
+    });
+    // ── Pool
+    try {
+        const { listAccountAliases } = await import('./accounts.js');
+        const aliases = await listAccountAliases();
+        sections.push({
+            title: 'Account pool',
+            rows: [
+                { label: 'mode', value: aliases.length === 0 ? 'single-account (no pool)' : `pool of ${aliases.length}` },
+                ...(aliases.length > 0 ? [{ label: 'aliases', value: aliases.join(', ') }] : []),
+            ],
+        });
+    }
+    catch {
+        sections.push({
+            title: 'Account pool',
+            rows: [{ label: 'mode', value: '(check failed)' }],
+        });
+    }
+    // ── Backends
+    try {
+        const { listBackends } = await import('./openai-backend.js');
+        const backends = await listBackends();
+        sections.push({
+            title: 'OpenAI-compat backends',
+            rows: [
+                { label: 'count', value: String(backends.length) },
+                ...(backends.length > 0
+                    ? [{ label: 'names', value: backends.map((b) => b.name).join(', ') }]
+                    : []),
+            ],
+        });
+    }
+    catch {
+        sections.push({
+            title: 'OpenAI-compat backends',
+            rows: [{ label: 'count', value: '(check failed)' }],
+        });
+    }
+    // ── Paths (everything dario reads/writes on disk)
+    sections.push({
+        title: 'Paths',
+        rows: [
+            { label: 'home', value: home },
+            { label: 'credentials', value: credsPath },
+            { label: 'accounts', value: join(home, 'accounts') },
+            { label: 'oauth cache', value: join(home, 'cc-oauth-cache-v6.json') },
+            { label: 'oauth override', value: join(home, 'oauth-config.override.json') },
+            { label: 'template cache', value: join(home, 'template-cache.json') },
+        ],
+    });
+    return {
+        generatedAt: new Date().toISOString(),
+        version,
+        sections,
+    };
+}
+function envOrDefault(name, dflt) {
+    return process.env[name] ? `${process.env[name]}  (from ${name})` : dflt;
+}
+function describeCreds(path) {
+    if (!existsSync(path))
+        return 'not authenticated (run `dario login`)';
+    try {
+        const s = statSync(path);
+        const mode = (s.mode & 0o777).toString(8);
+        const age = formatAge(Date.now() - s.mtimeMs);
+        return `present (mode ${mode}, last updated ${age} ago)`;
+    }
+    catch {
+        return 'present (stat failed)';
+    }
+}
+// Exported for unit tests.
+export function formatAge(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.round(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    const d = Math.round(h / 24);
+    return `${d}d`;
+}
+/**
+ * Pretty-print a ConfigReport as aligned ASCII. Same approach as
+ * doctor's formatChecks — plain text, no colors, pasteable.
+ */
+export function formatEffectiveConfig(report) {
+    const lines = [];
+    for (const section of report.sections) {
+        lines.push(`  ${section.title}`);
+        lines.push(`  ${'─'.repeat(section.title.length)}`);
+        const labelWidth = section.rows.reduce((n, r) => Math.max(n, r.label.length), 0);
+        for (const r of section.rows) {
+            lines.push(`    ${r.label.padEnd(labelWidth)}  ${r.value}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Structured envelope for `dario config --json`. */
+export function formatEffectiveConfigJson(report) {
+    return JSON.stringify(report, null, 2);
+}

package/dist/doctor.d.ts

@@ -31,6 +31,26 @@ export declare function formatChecks(checks: Check[]): string;
  * a user's machine just because they're on an untested CC version.
  */
 export declare function exitCodeFor(checks: Check[]): number;
+/**
+ * Serialize a check report as structured JSON. Lets other tools
+ * (claude-bridge's /status command, deepdive, CI scripts) consume
+ * dario's health programmatically instead of scraping the formatted
+ * text. Emitted by `dario doctor --json`.
+ */
+export declare function formatChecksJson(checks: Check[]): string;
+export declare function probeNpmLatestCC(): string | null;
+export interface RunChecksOptions {
+    /**
+     * Opt-in: hit Anthropic's authorize endpoint with the scope set dario
+     * would use on `accounts add`, and surface the server's verdict as a
+     * check row. Default off — `dario doctor` without `--probe` is a
+     * read-only local scan, no outbound traffic beyond what the other
+     * checks already make (OAuth token refresh, CC binary version probe,
+     * npm drift check). Enable with `dario doctor --probe`; costs one
+     * GET to `claude.ai` and runs in parallel with the other checks.
+     */
+    probe?: boolean;
+}
 /**
  * Run every available health check. Never throws — each check is
  * individually try/caught so a broken subsystem (e.g. unreadable accounts
@@ -40,4 +60,49 @@ export declare function exitCodeFor(checks: Check[]): number;
  * version, platform) so a reader scanning the output top-down sees
  * the environment before the subsystems.
  */
-export declare function runChecks(): Promise<Check[]>;
+export declare function runChecks(opts?: RunChecksOptions): Promise<Check[]>;
+export interface SeenHeader {
+    present: boolean;
+    /** Redacted preview: `"abcd...wxyz"` — first 4 + last 4 chars, or length tag if the value is too short to excerpt safely. */
+    redacted?: string;
+    length?: number;
+    /** For Authorization: whether the value started with "Bearer " (case-insensitive). */
+    bearerPrefix?: boolean;
+    /** Did this header's value (after any `Bearer ` strip) match DARIO_API_KEY? */
+    matches?: boolean;
+}
+export type AuthCheckVerdict = 'match' | 'mismatch' | 'no-auth-header' | 'timeout' | 'no-enforcement';
+export interface AuthCheckResult {
+    received: boolean;
+    port?: number;
+    expected: string;
+    xApiKey?: SeenHeader;
+    authorization?: SeenHeader;
+    verdict: AuthCheckVerdict;
+    diagnosis: string;
+}
+export interface AuthCheckOptions {
+    /** Milliseconds to wait for an inbound request. Default 30,000. */
+    timeoutMs?: number;
+    /** Override the expected key. Default: `process.env.DARIO_API_KEY`. */
+    expectedKey?: string;
+    /** Test hook: called when the server is listening, with the port. */
+    onListening?: (port: number) => void;
+}
+export declare function redactSecret(value: string): string;
+export declare function classifyAuthHeaders(headers: {
+    'x-api-key'?: string | string[];
+    authorization?: string | string[];
+}, expected: string): {
+    xApiKey: SeenHeader;
+    authorization: SeenHeader;
+    verdict: AuthCheckVerdict;
+};
+/**
+ * Listen for one inbound request on a random loopback port, classify
+ * whatever auth headers it carries against `DARIO_API_KEY`, return a
+ * structured result. Sends 200 / 401 to the inbound request so the
+ * client doesn't hang, then closes. This is a probe — it does not
+ * proxy, does not log, does not persist.
+ */
+export declare function runAuthCheck(opts?: AuthCheckOptions): Promise<AuthCheckResult>;

package/dist/doctor.js

@@ -14,8 +14,12 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, platform, arch, release } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:http';
 import { CC_TEMPLATE, } from './cc-template.js';
-import { describeTemplate, detectDrift, checkCCCompat, findInstalledCC, SUPPORTED_CC_RANGE, CURRENT_SCHEMA_VERSION, } from './live-fingerprint.js';
+import { describeTemplate, detectDrift, checkCCCompat, findInstalledCC, SUPPORTED_CC_RANGE, CURRENT_SCHEMA_VERSION, compareVersions, } from './live-fingerprint.js';
+import { detectCCOAuthConfig } from './cc-oauth-detect.js';
+import { runAuthorizeProbe } from './cc-authorize-probe.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Pretty-print a list of Check results as aligned ASCII. No color codes —
@@ -41,6 +45,63 @@ export function formatChecks(checks) {
 export function exitCodeFor(checks) {
     return checks.some((c) => c.status === 'fail') ? 1 : 0;
 }
+/**
+ * Serialize a check report as structured JSON. Lets other tools
+ * (claude-bridge's /status command, deepdive, CI scripts) consume
+ * dario's health programmatically instead of scraping the formatted
+ * text. Emitted by `dario doctor --json`.
+ */
+export function formatChecksJson(checks) {
+    const summary = {
+        ok: checks.filter((c) => c.status === 'ok').length,
+        warn: checks.filter((c) => c.status === 'warn').length,
+        fail: checks.filter((c) => c.status === 'fail').length,
+        info: checks.filter((c) => c.status === 'info').length,
+    };
+    return JSON.stringify({
+        generatedAt: new Date().toISOString(),
+        exitCode: exitCodeFor(checks),
+        summary,
+        checks,
+    }, null, 2);
+}
+/**
+ * Ask npm for the latest @anthropic-ai/claude-code version. One 3s
+ * timeout; failures return null so doctor silently drops the check.
+ * Result is cached module-scoped so back-to-back doctor invocations
+ * (e.g. from a wrapping script) don't hammer the npm registry.
+ */
+let _npmLatestCache = null;
+const NPM_CACHE_TTL_MS = 60 * 1000;
+export function probeNpmLatestCC() {
+    if (_npmLatestCache && Date.now() - _npmLatestCache.at < NPM_CACHE_TTL_MS) {
+        return _npmLatestCache.value;
+    }
+    let value = null;
+    try {
+        // `npm view <pkg> version` prints the version as a single line.
+        // 3s timeout keeps doctor responsive even with flaky network /
+        // corporate proxies; stdio ignores stderr so "npm notice" banners
+        // don't pollute stdout parsing.
+        const out = execFileSync('npm', ['view', '@anthropic-ai/claude-code', 'version'], {
+            encoding: 'utf-8',
+            timeout: 3_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            // npm ships as .cmd on Windows; execFile can't spawn it directly
+            // without shell:true. `npm` is not user-overridable here so the
+            // command-injection risk is nil.
+            shell: process.platform === 'win32',
+        });
+        const m = /(\d+\.\d+\.\d+(?:[.\-][\w.\-]+)?)/.exec(out);
+        value = m ? m[1] : null;
+    }
+    catch {
+        value = null;
+    }
+    _npmLatestCache = { value, at: Date.now() };
+    return value;
+}
 /**
  * Run every available health check. Never throws — each check is
  * individually try/caught so a broken subsystem (e.g. unreadable accounts
@@ -50,7 +111,7 @@ export function exitCodeFor(checks) {
  * version, platform) so a reader scanning the output top-down sees
  * the environment before the subsystems.
  */
-export async function runChecks() {
+export async function runChecks(opts = {}) {
     const checks = [];
     // ---- dario version
     try {
@@ -105,6 +166,24 @@ export async function runChecks() {
             label: 'CC binary',
             detail: `v${cc.version} at ${cc.path}  (range: v${SUPPORTED_CC_RANGE.min} – v${SUPPORTED_CC_RANGE.maxTested})`,
         });
+        // Stale-upstream probe: compare installed against npm's @latest.
+        // One network hop (3s timeout, 60s in-process cache). Silent on
+        // failure — no check row emitted — since a flaky network
+        // shouldn't turn doctor's output noisy. Only emits when the
+        // installed CC is strictly older than the npm latest.
+        try {
+            const npmLatest = probeNpmLatestCC();
+            if (npmLatest && compareVersions(cc.version, npmLatest) < 0) {
+                checks.push({
+                    status: 'info',
+                    label: 'CC upstream',
+                    detail: `npm latest is v${npmLatest} — installed is v${cc.version}. ` +
+                        `Run \`npm install -g @anthropic-ai/claude-code@latest\` to upgrade; ` +
+                        `dario's template will re-capture automatically on next startup.`,
+                });
+            }
+        }
+        catch { /* silent */ }
     }
     else if (cc.path) {
         checks.push({
@@ -159,6 +238,50 @@ export async function runChecks() {
     catch (err) {
         checks.push({ status: 'warn', label: 'OAuth', detail: `check failed: ${err.message}` });
     }
+    // ---- Authorize-URL probe (opt-in, --probe).
+    // One GET to the authorize endpoint with dario's effective OAuth config.
+    // This is the single reliable signal for the class of bug that broke
+    // #42 / #71 — Anthropic flipping server-side scope policy without
+    // changing the CC binary. The nightly probe in check-cc-authorize-
+    // probe.mjs hits Cloudflare challenges from CI IPs; running from a
+    // user's machine bypasses that. No PII leaves: the probe uses a
+    // fresh PKCE challenge and a dummy redirect_uri, and only reads the
+    // status code / Location header / response body markers.
+    if (opts.probe) {
+        try {
+            const cfg = await detectCCOAuthConfig();
+            const result = await runAuthorizeProbe({
+                clientId: cfg.clientId,
+                authorizeUrl: cfg.authorizeUrl,
+                scopes: cfg.scopes,
+            });
+            const status = result.verdict === 'accepted'
+                ? 'ok'
+                : result.verdict === 'rejected'
+                    ? 'fail'
+                    : 'warn';
+            const label = 'Authorize probe';
+            const summary = `${result.scopeCount}-scope ${result.verdict} — ${result.reason}`;
+            checks.push({ status, label, detail: summary });
+            if (result.verdict !== 'accepted') {
+                // On rejection: the URL is the one `accounts add` would open —
+                // surface it so the user can paste and diff against `claude
+                // /login`'s URL. On inconclusive (often Cloudflare from our
+                // fetch-based probe — CF challenges non-browser clients
+                // regardless of IP): the same URL pasted into the user's
+                // browser bypasses CF since a real browser passes the
+                // challenge. Either way, the URL is the actionable artifact.
+                checks.push({ status: 'info', label: 'Probe URL', detail: result.probedUrl });
+            }
+        }
+        catch (err) {
+            checks.push({
+                status: 'warn',
+                label: 'Authorize probe',
+                detail: `check failed: ${err.message}`,
+            });
+        }
+    }
     // ---- Account pool
     try {
         const { listAccountAliases, loadAllAccounts } = await import('./accounts.js');
@@ -250,3 +373,160 @@ function safely(fn, fallback) {
         return fallback;
     }
 }
+// Exported for unit tests.
+export function redactSecret(value) {
+    if (value.length <= 8)
+        return `<${value.length} chars>`;
+    return `${value.slice(0, 4)}…${value.slice(-4)} (length ${value.length})`;
+}
+// Exported for unit tests. Pure — takes the two headers + the expected
+// key, returns the classification. Separated from the HTTP dance so
+// tests can drive synthetic inputs without binding a socket.
+export function classifyAuthHeaders(headers, expected) {
+    const xRaw = headers['x-api-key'];
+    const aRaw = headers['authorization'];
+    const xVal = Array.isArray(xRaw) ? xRaw[0] : xRaw;
+    const aVal = Array.isArray(aRaw) ? aRaw[0] : aRaw;
+    const xApiKey = { present: xVal !== undefined };
+    if (xVal !== undefined) {
+        xApiKey.length = xVal.length;
+        xApiKey.redacted = redactSecret(xVal);
+        xApiKey.matches = xVal === expected;
+    }
+    const authorization = { present: aVal !== undefined };
+    if (aVal !== undefined) {
+        authorization.length = aVal.length;
+        authorization.bearerPrefix = /^Bearer\s+/i.test(aVal);
+        const stripped = aVal.replace(/^Bearer\s+/i, '');
+        authorization.redacted = redactSecret(stripped);
+        authorization.matches = stripped === expected;
+    }
+    let verdict;
+    if (!xApiKey.present && !authorization.present) {
+        verdict = 'no-auth-header';
+    }
+    else if (xApiKey.matches === true || authorization.matches === true) {
+        verdict = 'match';
+    }
+    else {
+        verdict = 'mismatch';
+    }
+    return { xApiKey, authorization, verdict };
+}
+function diagnoseAuthCheck(result) {
+    switch (result.verdict) {
+        case 'match':
+            return `client auth matches DARIO_API_KEY. A real dario proxy would accept this request.`;
+        case 'mismatch': {
+            const parts = [];
+            if (result.authorization?.present) {
+                const bearer = result.authorization.bearerPrefix ? ' (Bearer prefix present)' : ' (Bearer prefix missing)';
+                parts.push(`Authorization header${bearer}: value ${result.authorization.redacted} — does NOT match expected ${redactSecret(result.expected)}.`);
+            }
+            if (result.xApiKey?.present) {
+                parts.push(`x-api-key header: value ${result.xApiKey.redacted} — does NOT match expected ${redactSecret(result.expected)}.`);
+            }
+            const hint = suggestAuthFix(result);
+            return parts.join(' ') + (hint ? ' ' + hint : '');
+        }
+        case 'no-auth-header':
+            return (`client sent no x-api-key and no Authorization header. ` +
+                `Expected ${redactSecret(result.expected)} in either. ` +
+                `Set ANTHROPIC_API_KEY=${result.expected} in your client's environment, ` +
+                `or use your tool's own "API key" config field if it has one.`);
+        case 'timeout':
+            return (`no request received within the timeout. Did your client target the ` +
+                `port printed above? If the client uses a base URL you configured ` +
+                `elsewhere, point it at the --auth-check listener for this one request.`);
+        case 'no-enforcement':
+            return (`DARIO_API_KEY is not set — dario does not enforce auth on loopback ` +
+                `by default, so any request would be allowed through. To test auth ` +
+                `enforcement, set DARIO_API_KEY=your-secret before running --auth-check.`);
+    }
+}
+/** Pattern-match common failure modes for a sharper hint. */
+function suggestAuthFix(result) {
+    const auth = result.authorization;
+    const exp = result.expected;
+    // Authorization value looks like a real Anthropic key — very common
+    // pattern: client has one stashed from an earlier setup (OpenClaw's
+    // auth-profiles.json, ANTHROPIC_API_KEY env, config file) and it's
+    // shadowing the intended "dario" value. dario#97 exactly.
+    if (auth?.present && auth.redacted?.startsWith('sk-a')) {
+        return (`The value your client sent looks like a real Anthropic API key ` +
+            `(starts with "sk-a…"). Your client has that key configured somewhere ` +
+            `(auth-profiles.json, ANTHROPIC_API_KEY env, client config file) and it's ` +
+            `overriding "${exp}". Either replace it with "${exp}" or bypass auth entirely ` +
+            `by running dario on --host=127.0.0.1 without DARIO_API_KEY set.`);
+    }
+    // Authorization with no "Bearer " prefix: some clients just set the
+    // header value raw.
+    if (auth?.present && auth.bearerPrefix === false) {
+        return (`The Authorization header is missing the "Bearer " prefix. Most ` +
+            `HTTP client libraries want "Bearer <key>" as one value — yours seems ` +
+            `to be setting the key directly. Check your client's auth config.`);
+    }
+    return null;
+}
+/**
+ * Listen for one inbound request on a random loopback port, classify
+ * whatever auth headers it carries against `DARIO_API_KEY`, return a
+ * structured result. Sends 200 / 401 to the inbound request so the
+ * client doesn't hang, then closes. This is a probe — it does not
+ * proxy, does not log, does not persist.
+ */
+export async function runAuthCheck(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const expected = opts.expectedKey ?? process.env.DARIO_API_KEY ?? '';
+    if (!expected) {
+        return {
+            received: false,
+            expected: '<unset>',
+            verdict: 'no-enforcement',
+            diagnosis: diagnoseAuthCheck({ received: false, expected: '<unset>', verdict: 'no-enforcement' }),
+        };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            server.close(() => resolve(result));
+        };
+        const server = createServer((req, res) => {
+            const { xApiKey, authorization, verdict } = classifyAuthHeaders(req.headers, expected);
+            const port = server.address()?.port;
+            const result = {
+                received: true,
+                port,
+                expected,
+                xApiKey,
+                authorization,
+                verdict,
+                diagnosis: '',
+            };
+            result.diagnosis = diagnoseAuthCheck(result);
+            res.writeHead(verdict === 'match' ? 200 : 401, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                message: 'dario auth-check received this request — see the dario CLI output for the diagnostic.',
+                verdict,
+            }));
+            settle(result);
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const port = server.address().port;
+            opts.onListening?.(port);
+        });
+        setTimeout(() => {
+            const port = server.address()?.port;
+            settle({
+                received: false,
+                port,
+                expected,
+                verdict: 'timeout',
+                diagnosis: diagnoseAuthCheck({ received: false, port, expected, verdict: 'timeout' }),
+            });
+        }, timeoutMs);
+    });
+}

package/dist/live-fingerprint.d.ts

@@ -210,6 +210,7 @@ export declare function findInstalledCC(): {
     path: string | null;
     version: string | null;
 };
+export declare function enumerateClaudeCandidates(): string[];
 /**
  * Given a captured /v1/messages request body, pull out the fields that
  * matter for template replay: agent identity, system prompt, tool list,
@@ -281,7 +282,7 @@ export declare function _resetInstalledVersionProbeForTest(): void;
  */
 export declare const SUPPORTED_CC_RANGE: {
     readonly min: "1.0.0";
-    readonly maxTested: "2.1.118";
+    readonly maxTested: "2.1.119";
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/live-fingerprint.js

@@ -449,30 +449,77 @@ function findClaudeBinary() {
     // non-standard installs.
     if (process.env.DARIO_CLAUDE_BIN)
         return process.env.DARIO_CLAUDE_BIN;
-    // Try the obvious name. On Windows spawn resolves `.cmd` shims
-    // automatically when shell:true, but we don't want shell:true for
-    // safety. The `where` / `which` probe handles Windows via PATHEXT.
-    const candidates = process.platform === 'win32'
-        ? ['claude.cmd', 'claude.exe', 'claude']
-        : ['claude'];
-    for (const name of candidates) {
-        if (existsOnPath(name))
-            return name;
+    const candidates = enumerateClaudeCandidates();
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0];
+    // Multiple installs on PATH — common on Windows where an npm-wrapper
+    // (~/AppData/Roaming/npm/claude.cmd) coexists with a native install
+    // (~/.local/bin/claude.exe). Version-probe each and pick the newest.
+    // Falls back to the first candidate if no probe succeeds (e.g. every
+    // spawn fails on a sandboxed runtime).
+    const probed = [];
+    for (const path of candidates) {
+        const version = probeOneVersion(path);
+        if (version)
+            probed.push({ path, version });
     }
-    return null;
+    if (probed.length === 0)
+        return candidates[0];
+    probed.sort((a, b) => compareVersions(b.version, a.version));
+    return probed[0].path;
 }
-function existsOnPath(name) {
+// Exported for unit tests.
+export function enumerateClaudeCandidates() {
     const pathEnv = process.env.PATH ?? '';
     const sep = process.platform === 'win32' ? ';' : ':';
     const dirs = pathEnv.split(sep).filter(Boolean);
+    // `.exe` first on Windows: the native binary beats a `.cmd` wrapper
+    // when both live in the same dir. Across dirs we version-probe anyway
+    // so order here only matters when probes all fail.
+    const names = process.platform === 'win32'
+        ? ['claude.exe', 'claude.cmd', 'claude']
+        : ['claude'];
+    const found = [];
+    const seen = new Set();
     for (const d of dirs) {
-        try {
-            if (existsSync(join(d, name)))
-                return true;
+        for (const name of names) {
+            const full = join(d, name);
+            if (seen.has(full))
+                continue;
+            try {
+                if (existsSync(full)) {
+                    seen.add(full);
+                    found.push(full);
+                }
+            }
+            catch { /* noop */ }
         }
-        catch { /* noop */ }
     }
-    return false;
+    return found;
+}
+// Version-probe one specific binary path. Same safety logic as
+// probeInstalledCCVersionUncached below (reject shell metacharacters in
+// override paths before spawning with shell:true on Windows).
+function probeOneVersion(bin) {
+    try {
+        const useShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(bin);
+        if (useShell && /[&|><^"'%\r\n`$;(){}[\]]/.test(bin))
+            return null;
+        const out = execFileSync(bin, ['--version'], {
+            encoding: 'utf-8',
+            timeout: 2_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            shell: useShell,
+        });
+        const m = /(\d+\.\d+\.\d+(?:[.\-][\w.\-]+)?)/.exec(out);
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Given a captured /v1/messages request body, pull out the fields that
@@ -730,7 +777,7 @@ export function _resetInstalledVersionProbeForTest() {
  */
 export const SUPPORTED_CC_RANGE = {
     min: '1.0.0',
-    maxTested: '2.1.118',
+    maxTested: '2.1.119',
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.31.5",
+  "version": "3.31.11",
   "description": "A local LLM router. One endpoint, every provider — Claude subscriptions, OpenAI, OpenRouter, Groq, local LiteLLM, any OpenAI-compat endpoint — your tools don't need to change.",
   "type": "module",
   "bin": {