@askalf/dario 6.12.30 → 6.13.1

package/README.md

@@ -28,7 +28,7 @@
 
 <p><strong>One local endpoint. Every AI tool you own. The subscriptions you already pay for.</strong></p>
 
-<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~40k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
+<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~41k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
 <sub><a href="#start-in-60-seconds">Start</a> · <a href="#why-people-pick-it">Why dario</a> · <a href="#what-it-does-with-a-request">Routing</a> · <a href="#will-my-account-get-suspended">Risk</a> · <a href="#reference">Reference</a> · <a href="#trust--transparency">Trust</a> · <a href="docs/returning.md">Coming back after a while?</a></sub>
 
@@ -115,7 +115,7 @@ dario runs entirely on your machine, authenticates as you with your own Claude l
 
 | Signal | Status |
 |---|---|
-| Source | **~40k** lines of TypeScript across **78** files, auditable in a weekend. One credential path since v5: the pool. |
+| Source | **~41k** lines of TypeScript across **79** files, auditable in a weekend. One credential path since v5: the pool. |
 | Dependencies | **0 runtime.** Verify: `npm ls --production` |
 | Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore, published with OIDC trusted publishing — no long-lived npm token exists to leak |
 | Scanning | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) on every push to master, every PR and weekly · [ClusterFuzzLite](./.github/workflows/cflite.yml) fuzzes the SSE translator, the rejection parsers and the cch stamper weekly · [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/askalf/dario) and [Best Practices](https://www.bestpractices.dev/projects/13638) badges above are live |

package/dist/cli.js

@@ -19,7 +19,7 @@
 import { unlink, writeFile } from 'node:fs/promises';
 import { formatLedgerSummary, formatLedgerConsumers, formatUsd, renderLedgerCard, readLedgerFile, resolveLedgerPath, summarizeLedger } from './ledger.js';
 import { renderSpendDonuts } from './donuts.js';
-import { KeyStore, createKey, revokeKey, rotateKey, deleteKey, parseExpiry, publicKey, resolveKeysPath, KEY_NAME_RE, setKeyBudget, parseUsdBudget, parseTokenBudget, formatBudget } from './keys.js';
+import { KeyStore, createKey, revokeKey, rotateKey, deleteKey, parseExpiry, publicKey, resolveKeysPath, KEY_NAME_RE, parseKeySocketSpec, setKeyBudget, parseUsdBudget, parseTokenBudget, formatBudget } from './keys.js';
 /**
  * `--budget=$5/day` / `--budget-tokens=2M/day` → a KeyBudget, or undefined when
  * neither flag is present. A flag that does not parse exits 1 with the accepted
@@ -729,6 +729,29 @@ async function proxy() {
         || ['0', 'false', 'no', 'off'].includes((process.env['DARIO_KEYS'] ?? '').toLowerCase()));
     const keysPathArg = args.find(a => a.startsWith('--keys-path='));
     const keysPath = keysPathArg ? keysPathArg.slice('--keys-path='.length) : undefined;
+    // --key-socket=<path>=<key> (repeatable) / DARIO_KEY_SOCKETS (comma-separated)
+    // Each unix socket is bound to one named key; see ProxyOptions.keySockets.
+    const keySocketSpecs = [
+        ...args.filter(a => a.startsWith('--key-socket=')).map(a => a.slice('--key-socket='.length)),
+        ...(process.env['DARIO_KEY_SOCKETS'] ?? '').split(',').map(s => s.trim()).filter(Boolean),
+    ];
+    const keySockets = [];
+    for (const spec of keySocketSpecs) {
+        const ks = parseKeySocketSpec(spec);
+        if (!ks) {
+            console.error(`[dario] --key-socket: "${spec}" is not <absolute socket path>=<key name>`);
+            process.exit(1);
+        }
+        if (keySockets.some(k => k.path === ks.path)) {
+            console.error(`[dario] --key-socket: ${ks.path} is given twice`);
+            process.exit(1);
+        }
+        keySockets.push(ks);
+    }
+    if (keySockets.length > 0 && !keys) {
+        console.error('[dario] --key-socket binds a named key, but named keys are off (--no-keys / DARIO_KEYS=0).');
+        process.exit(1);
+    }
     // --preserve-output-format — carry the client body's `output_config.format`
     // (structured-output JSON schema) through to upstream instead of dropping it
     // during the CC rebuild. See ProxyOptions.preserveOutputFormat for rationale.
@@ -753,7 +776,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, shutdownGraceMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, shutdownGraceMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
 }
 /**
  * `dario keys` — named keys for a shared dario (v6.8, dario#1318). One
@@ -2120,6 +2143,13 @@ async function help() {
                              DARIO_API_KEY authenticates. Env: DARIO_KEYS=0;
                              --keys-path=<file> / DARIO_KEYS_PATH moves the
                              file. See \`dario keys\`. (v6.8)
+    --key-socket=<path>=<key>
+                             Also listen on a unix socket bound to one
+                             named key: every request on it is that
+                             key's, with no secret sent or stored by the
+                             caller. Who may connect is the socket's
+                             directory and group (it is created 0660).
+                             Repeatable. Env: DARIO_KEY_SOCKETS=<spec>,..
     --session-idle-rotate=MS Idle ms before an account's session id
                              rotates (default: 900000 = 15 min).
                              Real CC rotates once per conversation, not

package/dist/keys.d.ts

@@ -207,6 +207,22 @@ export interface KeyPublic {
 export declare function publicKey(k: KeyRecord, now?: number): KeyPublic;
 /** `--expires=30d` / `12h` / `2026-12-31` → epoch ms, or null when unparseable. */
 export declare function parseExpiry(value: string, now?: number): number | null;
+/**
+ * A unix socket bound to one named key: a request that arrives on it IS that
+ * key's, with no secret on the wire and none on the caller's disk. Who may
+ * connect is decided by the filesystem (the socket's directory and mode), so
+ * a caller that must not hold a credential, such as a CI job running code it
+ * did not write, never has one to leak. A header on the socket names no
+ * other key: the socket decides.
+ */
+export interface KeySocket {
+    /** Absolute path of the socket file. */
+    path: string;
+    /** The named key every request on it is. */
+    key: string;
+}
+/** `<absolute path>=<key name>` (`--key-socket`, `DARIO_KEY_SOCKETS`), or null when malformed. */
+export declare function parseKeySocketSpec(spec: string): KeySocket | null;
 /**
  * The proxy's live view of the file. Reloads when the file's mtime moves (a
  * stat per auth — the cost of "no restart"), records last-used with a
@@ -228,6 +244,12 @@ export declare class KeyStore {
     list(now?: number): KeyPublic[];
     /** The record a request's credential names, or null. Reloads first when the file moved. */
     match(provided: string | undefined, now?: number): KeyRecord | null;
+    /**
+     * The usable record named `name`, or null (unknown, revoked or expired).
+     * For a key socket, where the connection names the key and no secret is
+     * presented. Reloads first when the file moved.
+     */
+    byName(name: string, now?: number): KeyRecord | null;
     /** Note a use; written to disk after a quiet moment. */
     touch(k: KeyRecord, now?: number): void;
     /** Apply a mutation to the file on disk (re-read first), then adopt it. */

package/dist/keys.js

@@ -386,6 +386,17 @@ export function parseExpiry(value, now = Date.now()) {
     const abs = Date.parse(v);
     return Number.isNaN(abs) ? null : abs;
 }
+/** `<absolute path>=<key name>` (`--key-socket`, `DARIO_KEY_SOCKETS`), or null when malformed. */
+export function parseKeySocketSpec(spec) {
+    const i = spec.lastIndexOf('=');
+    if (i <= 0)
+        return null;
+    const path = spec.slice(0, i);
+    const key = spec.slice(i + 1);
+    if (!path.startsWith('/') || path.includes('\0') || !KEY_NAME_RE.test(key))
+        return null;
+    return { path, key };
+}
 /**
  * The proxy's live view of the file. Reloads when the file's mtime moves (a
  * stat per auth — the cost of "no restart"), records last-used with a
@@ -435,6 +446,16 @@ export class KeyStore {
             return null;
         return matchKey(this.file, provided, now);
     }
+    /**
+     * The usable record named `name`, or null (unknown, revoked or expired).
+     * For a key socket, where the connection names the key and no secret is
+     * presented. Reloads first when the file moved.
+     */
+    byName(name, now = Date.now()) {
+        this.load();
+        const k = this.file.keys.find((r) => r.name === name);
+        return k && keyIsUsable(k, now) ? k : null;
+    }
     /** Note a use; written to disk after a quiet moment. */
     touch(k, now = Date.now()) {
         const iso = new Date(now).toISOString();

package/dist/live-fingerprint.d.ts

@@ -510,7 +510,7 @@ export declare function detectDrift(t: TemplateData, installedOverride?: string
  */
 export declare const SUPPORTED_CC_RANGE: {
     readonly min: "1.0.0";
-    readonly maxTested: "2.1.291";
+    readonly maxTested: "2.1.292";
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/live-fingerprint.js

@@ -1211,7 +1211,7 @@ export function detectDrift(t, installedOverride) {
  */
 export const SUPPORTED_CC_RANGE = {
     min: '1.0.0',
-    maxTested: '2.1.291',
+    maxTested: '2.1.292',
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/proxy.d.ts

@@ -2,6 +2,7 @@ import { type IncomingMessage } from 'node:http';
 import { type WriteStream } from 'node:fs';
 import { getAccessToken, getStatus } from './oauth.js';
 import { type EffortValue } from './cc-template.js';
+import { type KeySocket } from './keys.js';
 /**
  * Assemble the `x-anthropic-billing-header` system-block text, following
  * Claude Code's format:
@@ -398,6 +399,13 @@ interface ProxyOptions {
      */
     keys?: boolean;
     keysPath?: string;
+    /**
+     * Unix sockets bound to named keys (`--key-socket=<path>=<key>`). Every
+     * request on one is that key's, whatever its headers say, so a caller
+     * reaches dario with no secret at all and the socket's directory and mode
+     * decide who may (keys.ts, KeySocket). Needs named keys on. POSIX only.
+     */
+    keySockets?: KeySocket[];
     sessionIdleRotateMs?: number;
     sessionRotateJitterMs?: number;
     sessionMaxAgeMs?: number;
@@ -761,5 +769,24 @@ export declare function resolveSingleAccountStartupStatus(deps?: {
     getStatus: typeof getStatus;
     getAccessToken: typeof getAccessToken;
 }): Promise<Awaited<ReturnType<typeof getStatus>>>;
+/**
+ * Take `<path>.lock`, held from the stale-socket probe through the bind and
+ * released after either. Two starts that both found the same stale socket
+ * would otherwise both remove it, the second removing the first's fresh
+ * socket. Created with O_EXCL, so one start wins and the other fails. An
+ * existing lock is never removed here, however old: removing one is itself a
+ * race between two starts, so a lock left by a start that crashed while
+ * binding is the operator's to delete. Returns the release.
+ */
+export declare function acquireSocketLock(path: string): () => void;
+/**
+ * Clear a key socket's path for a new bind. Call it holding acquireSocketLock. A socket nothing answers on is
+ * stale (a crashed or killed run) and is removed. One that accepts, or that
+ * neither accepts nor refuses within `timeoutMs`, belongs to a running
+ * listener: removing it would cut that listener off from every new client,
+ * so this throws instead. Any other file is left for the bind to refuse; an
+ * unexpected filesystem error is thrown as is.
+ */
+export declare function clearStaleSocket(path: string, timeoutMs?: number): Promise<void>;
 export declare function startProxy(opts?: ProxyOptions): Promise<void>;
 export {};

package/dist/proxy.js

@@ -1,6 +1,7 @@
 import { createServer } from 'node:http';
 import { randomUUID, randomBytes, timingSafeEqual, createHash } from 'node:crypto';
-import { readFileSync, readdirSync, createWriteStream } from 'node:fs';
+import { readFileSync, readdirSync, createWriteStream, lstatSync, unlinkSync, chmodSync, openSync, writeSync, closeSync } from 'node:fs';
+import { createServer as createNetServer, connect as netConnect } from 'node:net';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { setDefaultResultOrder } from 'node:dns';
@@ -1230,6 +1231,73 @@ export async function resolveSingleAccountStartupStatus(deps = {
     }
     return status;
 }
+/**
+ * Take `<path>.lock`, held from the stale-socket probe through the bind and
+ * released after either. Two starts that both found the same stale socket
+ * would otherwise both remove it, the second removing the first's fresh
+ * socket. Created with O_EXCL, so one start wins and the other fails. An
+ * existing lock is never removed here, however old: removing one is itself a
+ * race between two starts, so a lock left by a start that crashed while
+ * binding is the operator's to delete. Returns the release.
+ */
+export function acquireSocketLock(path) {
+    const lock = `${path}.lock`;
+    let fd;
+    try {
+        fd = openSync(lock, 'wx', 0o600);
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+        throw new Error(`${lock} exists: another start is binding this socket, or one crashed while binding it; if no dario is starting, remove it`);
+    }
+    try {
+        writeSync(fd, `${process.pid}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return () => { try {
+        unlinkSync(lock);
+    }
+    catch { /* already gone */ } };
+}
+/**
+ * Clear a key socket's path for a new bind. Call it holding acquireSocketLock. A socket nothing answers on is
+ * stale (a crashed or killed run) and is removed. One that accepts, or that
+ * neither accepts nor refuses within `timeoutMs`, belongs to a running
+ * listener: removing it would cut that listener off from every new client,
+ * so this throws instead. Any other file is left for the bind to refuse; an
+ * unexpected filesystem error is thrown as is.
+ */
+export async function clearStaleSocket(path, timeoutMs = 1000) {
+    let isSocket;
+    try {
+        isSocket = lstatSync(path).isSocket();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (!isSocket)
+        return;
+    const live = await new Promise((resolve, reject) => {
+        const c = netConnect(path);
+        const timer = setTimeout(() => { c.destroy(); resolve(true); }, timeoutMs);
+        c.once('connect', () => { clearTimeout(timer); c.destroy(); resolve(true); });
+        c.once('error', (err) => {
+            clearTimeout(timer);
+            if (err.code === 'ECONNREFUSED')
+                resolve(false);
+            else
+                reject(err);
+        });
+    });
+    if (live)
+        throw new Error(`${path} is in use by a running listener (another dario?)`);
+    unlinkSync(path);
+}
 export async function startProxy(opts = {}) {
     const port = opts.port ?? DEFAULT_PORT;
     const host = opts.host ?? process.env.DARIO_HOST ?? DEFAULT_HOST;
@@ -2255,6 +2323,8 @@ export async function startProxy(opts = {}) {
     const ERR_UNAUTH = JSON.stringify({ error: 'Unauthorized', message: 'Invalid or missing API key' });
     const ERR_FORBIDDEN = JSON.stringify({ error: 'Forbidden', message: 'Path not allowed. Supported paths: POST /v1/messages, POST /v1/messages/count_tokens, POST /v1/chat/completions, GET /v1/models' });
     const ERR_METHOD = JSON.stringify({ error: 'Method not allowed' });
+    /** The named key each key-socket connection is (opts.keySockets); absent for TCP. */
+    const keySocketOf = new WeakMap();
     /**
      * Who is asking. A named key wins when it matches, and is then the
      * request's consumer; otherwise the root key decides as it always has,
@@ -2262,6 +2332,15 @@ export async function startProxy(opts = {}) {
      * A revoked or expired named key is indistinguishable from a wrong one.
      */
     function resolveRequestAuth(req) {
+        // A key socket names the key; no header can name another, or drop to the root key.
+        const bound = keySocketOf.get(req.socket);
+        if (bound !== undefined) {
+            const key = keyStore ? keyStore.byName(bound) : null;
+            if (!key)
+                return { ok: false, key: null };
+            keyStore.touch(key);
+            return { ok: true, key };
+        }
         const provided = req.headers['x-api-key']
             || req.headers.authorization?.replace(/^Bearer\s+/i, '');
         const key = keyStore ? keyStore.match(provided) : null;
@@ -2483,13 +2562,35 @@ export async function startProxy(opts = {}) {
         // The request's first stamp (src/timing.ts): every split below is
         // measured from here, before any parsing, auth or queueing.
         const arrivedAt = Date.now();
+        // Strip query parameters for endpoint matching
+        const urlPath = req.url?.split('?')[0] ?? '';
+        // A key socket's request is its bound key's or it is refused, on every
+        // route: no header (root key, analytics token, admin token) grants a
+        // socket caller anything its key does not. An unusable bound key is a 401
+        // here, before any route can answer; the admin API and seat pins, which
+        // authenticate by their own token, are not served on a key socket.
+        const socketKey = keySocketOf.get(req.socket);
+        if (socketKey !== undefined) {
+            if (!keyStore?.byName(socketKey)) {
+                if (verbose)
+                    console.error(`[dario] 401 rejected (key socket: named key "${socketKey}" unknown, revoked or expired): ${req.method} ${urlPath}`);
+                res.writeHead(401, JSON_HEADERS);
+                res.end(ERR_UNAUTH);
+                return;
+            }
+            if (urlPath.startsWith('/admin/') || req.headers[SEAT_PIN_HEADER] !== undefined) {
+                res.writeHead(403, JSON_HEADERS);
+                res.end(JSON.stringify({ type: 'error', error: { type: 'permission_error', message: 'the admin API and seat pins are not served on a key socket' } }));
+                return;
+            }
+        }
+        // CORS preflight, after the key-socket gate so a socket's unusable key
+        // refuses it like any other request.
         if (req.method === 'OPTIONS') {
             res.writeHead(204, CORS_HEADERS);
             res.end();
             return;
         }
-        // Strip query parameters for endpoint matching
-        const urlPath = req.url?.split('?')[0] ?? '';
         // Liveness probe — always 200 while the HTTP server is accepting requests,
         // deliberately decoupled from OAuth state. Docker's healthcheck (and the
         // autoheal watchdog that keys on it) points HERE, not /health: a broken or
@@ -2518,7 +2619,8 @@ export async function startProxy(opts = {}) {
             // view. Now: authenticated, OR bare loopback that did not arrive via CF.
             const viaCfRay = req.headers['cf-ray'] !== undefined;
             const includeInternal = shouldDiscloseHealthInternals({
-                authenticated: authenticateRequest(req.headers, apiKeyBuf),
+                // On a key socket the caller is its named key, never the root key.
+                authenticated: socketKey === undefined && authenticateRequest(req.headers, apiKeyBuf),
                 // Without this, `authenticated` is vacuously true on an unkeyed proxy
                 // and the tunnel check below is never reached — see the gate's docs.
                 keyConfigured: apiKeyBuf !== null,
@@ -2699,10 +2801,12 @@ export async function startProxy(opts = {}) {
             res.end(ANALYTICS_UI_SHELL);
             return;
         }
-        // Read-only analytics token: accepted on the read-only surfaces only.
-        // Anything else falls through to the normal request auth below.
+        // Read-only analytics token: accepted on the read-only surfaces only, and
+        // only over TCP: on a key socket the bound key decides, so no header can
+        // stand in for one that is unusable. Anything else falls through to the
+        // normal request auth below.
         const analyticsRead = isAnalyticsReadPath(urlPath) && req.method === 'GET';
-        const requestAuth = (analyticsRead && analyticsTokenBuf && authenticateRequest(req.headers, analyticsTokenBuf))
+        const requestAuth = (analyticsRead && analyticsTokenBuf && !keySocketOf.has(req.socket) && authenticateRequest(req.headers, analyticsTokenBuf))
             ? { ok: true, key: null }
             : resolveRequestAuth(req);
         if (!requestAuth.ok) {
@@ -2713,7 +2817,10 @@ export async function startProxy(opts = {}) {
                 // `dk_` value that did not match is a named key that is unknown,
                 // revoked or expired — the three are one case on purpose.
                 const provided = req.headers['x-api-key'] || req.headers.authorization?.replace(/^Bearer\s+/i, '');
-                console.error(`[dario] #${requestCount} 401 rejected (${looksLikeNamedKey(provided) ? 'named key unknown, revoked or expired' : 'DARIO_API_KEY mismatch'}): ${describeAuthReject(req.headers)}`);
+                const boundKey = keySocketOf.get(req.socket);
+                console.error(boundKey !== undefined
+                    ? `[dario] #${requestCount} 401 rejected (key socket: named key "${boundKey}" unknown, revoked or expired)`
+                    : `[dario] #${requestCount} 401 rejected (${looksLikeNamedKey(provided) ? 'named key unknown, revoked or expired' : 'DARIO_API_KEY mismatch'}): ${describeAuthReject(req.headers)}`);
             }
             writeLogLine(logFileStream, {
                 ts: new Date().toISOString(), req: requestCount,
@@ -5980,6 +6087,58 @@ export async function startProxy(opts = {}) {
     else {
         console.log('[dario] --no-live-capture: background live fingerprint refresh skipped; using bundled template.');
     }
+    // Key sockets: each connection is handed to the same HTTP server, tagged with
+    // its key, so routing, limits, timeouts and the shutdown drain are the TCP
+    // listener's own. A stale socket file from a crashed run is replaced; a
+    // live one, or any other file at the path, is left alone and the start fails.
+    const keySocketServers = [];
+    for (const ks of opts.keySockets ?? []) {
+        if (process.platform === 'win32')
+            throw new Error('--key-socket needs a POSIX host (a unix socket)');
+        if (!keyStore)
+            throw new Error(`--key-socket ${ks.path}: named keys are off (--no-keys / DARIO_KEYS=0), so no key can be bound`);
+        const store = keyStore;
+        const ns = createNetServer((sock) => { keySocketOf.set(sock, ks.key); server.emit('connection', sock); });
+        // Probe, removal and bind under one lock, so a concurrent start cannot
+        // remove the socket this one just bound.
+        let release = null;
+        try {
+            release = acquireSocketLock(ks.path);
+            await clearStaleSocket(ks.path);
+            await new Promise((resolve, reject) => {
+                ns.once('error', reject);
+                // Born 0660 (umask around the synchronous bind), not chmod'd after: no
+                // moment where the socket is wider than it ends up.
+                const umask = process.umask(0o117);
+                try {
+                    ns.listen(ks.path, () => { ns.off('error', reject); resolve(); });
+                }
+                finally {
+                    process.umask(umask);
+                }
+            });
+        }
+        catch (err) {
+            ns.close();
+            throw new Error(`--key-socket ${ks.path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            release?.();
+        }
+        ns.on('error', (err) => {
+            console.error(`[dario] key socket ${ks.path}: ${err.code ?? err.message}`);
+        });
+        // Owner and group read/write, nobody else: with the directory's own mode, the filesystem is the credential.
+        // Kept for a platform that ignores umask on bind.
+        try {
+            chmodSync(ks.path, 0o660);
+        }
+        catch (err) {
+            console.error(`[dario] key socket ${ks.path}: chmod failed (${err instanceof Error ? err.message : err})`);
+        }
+        console.log(`[dario] key socket: ${ks.path} → named key "${ks.key}"${store.byName(ks.key) ? '' : ' (no usable key of that name yet; its requests are refused until one exists)'}`);
+        keySocketServers.push(ns);
+    }
     server.listen(port, host, () => {
         const modeLine = passthrough
             ? 'Mode: passthrough (OAuth swap only, no injection)'
@@ -6114,6 +6273,8 @@ export async function startProxy(opts = {}) {
         // force-exit guard sits past the grace so a stream that never ends cannot
         // wedge shutdown, and a hung fsync cannot either.
         server.close();
+        for (const ns of keySocketServers)
+            ns.close();
         const { graceMs, forceExitMs } = shutdownTimers(opts.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS);
         void drainThenClose(() => waitForIdle(() => queue.snapshot().active, { graceMs }), {
             before: [flushPoolTokens, () => ledger?.flush()],

package/docs/commands.md

@@ -39,6 +39,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
 | `--verbose` / `-v` | Log every request (one line per request — method + path + billing bucket) | off |
 | `--verbose=2` / `-vv` / `DARIO_LOG_BODIES=1` | Also dump the outbound request body (redacted: bearer tokens, `sk-ant-*` keys, JWTs stripped; capped at 8KB). For wire-level client-compat debugging. | off |
+| `--key-socket=<path>=<key>` / `DARIO_KEY_SOCKETS` | Also listen on a unix socket bound to one named key: every request on it is that key's, with no secret sent or stored by the caller; the socket's directory and group decide who may connect. Repeatable. See [Key sockets](./keys.md#a-key-with-no-secret-key-sockets). | none |
 | `--no-keys` / `DARIO_KEYS=0`; `--keys-path=<file>` / `DARIO_KEYS_PATH` | Ignore named keys (`~/.dario/keys.json`) so only `DARIO_API_KEY` authenticates; or move the file. See [Named keys](./keys.md). (v6.8) | on, `~/.dario/keys.json` |
 | `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
 | `--pool-fallback=<models>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), serve the request as `<model>` from whichever provider can, instead of surfacing the 429/503. Accepts a **chain** — `gpt-5.6-sol,claude-sonnet-5` — read left to right, each provider taking the first entry it can serve. A Codex/ChatGPT subscription that lists the model is preferred (no per-token cost) and works on **both** wire shapes; otherwise a configured openai-compat backend, which is still OpenAI-path only (no Messages translation on that route). A chain also makes failover **symmetric**: a rate-limited or failing subscription hands the request back to the Claude pool. Only a 429/5xx fails over — a 400 surfaces, since a bad request would just reproduce itself elsewhere. Every substituted response carries `x-dario-pool-fallback: <model>` — never silent. Needs a Codex account (`dario add altman`) or a backend (`dario backend add …`); `dario doctor` reports it as INERT with neither. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |

package/docs/configuration.md

@@ -49,6 +49,7 @@ Halts the proxy when an upstream response reports `representative-claim: overage
 |---|---|---|---|
 | `DARIO_KEYS` | `--no-keys` | on | `0` ignores `~/.dario/keys.json`: only `DARIO_API_KEY` authenticates. See [Named keys](./keys.md) |
 | `DARIO_KEYS_PATH` | `--keys-path=<file>` | `~/.dario/keys.json` | where the key hashes live; `dario keys` and the running proxy read the same file |
+| `DARIO_KEY_SOCKETS` | `--key-socket=<path>=<key>` (repeatable) | none | unix sockets bound to one named key each: every request on one is that key's, with no secret sent. See [Key sockets](./keys.md#a-key-with-no-secret-key-sockets) |
 
 ## ChatGPT seats
 

package/docs/keys.md

@@ -146,6 +146,39 @@ For a deployment where only named keys should get in, set `DARIO_API_KEY` to
 a long random value nobody is given — the non-loopback bind requires one
 anyway — and hand out named keys.
 
+## A key with no secret: key sockets
+
+A caller that must not hold any credential (a CI job running code it did not
+write, a sandboxed agent) can still be a named key. `--key-socket=<path>=<key>`
+also listens on a unix socket, and every request on it is that key's: no
+header is needed, and none can name another key or the root key. The key's
+models, budgets, seat, expiry and revoke apply as on TCP; a socket whose key is
+unknown, revoked or expired answers `401` on every route, `/health` and
+`/livez` included. No header grants a socket caller more than its key: the
+analytics token does not apply there, `/health` gives the public view, and the
+admin API and seat pins are refused with `403`.
+
+```bash
+dario keys create ci --models=claude-sonnet-5 --budget=20
+sudo install -d -o dario -g ci-exec -m 2750 /run/dario   # setgid: the socket's group is ci-exec
+dario proxy --key-socket=/run/dario/ci.sock=ci
+curl -s --unix-socket /run/dario/ci.sock http://dario/v1/messages -H 'content-type: application/json' -d '…'
+```
+
+Who may connect is the filesystem's call: the socket is created `0660`, so its
+owner and its group can connect and nobody else can. Put it in a directory
+owned by the dario account, grouped to the accounts that may spend the key,
+mode `2750`: the setgid bit gives the socket that group (without it the group
+is dario's own, and the callers cannot connect), and the directory keeps every
+other account from reaching the socket at all. Repeat the flag for more sockets, or list them in
+`DARIO_KEY_SOCKETS=<path>=<key>,…`. A stale socket file at the path is
+replaced; one a running listener still answers on, or any other file there,
+stops the start, as do named keys being off and
+a Windows host. A start holds `<path>.lock` while it checks and binds the
+socket, so two starts at once cannot remove each other's. dario never removes
+an existing lock: one left by a start that crashed while binding stops the
+next start until it is deleted. POSIX only.
+
 ## Compared with a gateway
 
 A LiteLLM-style gateway in front of dario does this with a database, a UI and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.12.30",
+  "version": "6.13.1",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
   "type": "module",
   "bin": {