@askalf/dario 6.7.1 → 6.8.0

package/README.md

@@ -27,7 +27,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 · ~36k 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 · ~38k 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="#point-your-tools-at-it">Your tools</a> · <a href="#what-it-does-with-a-request">Routing</a> · <a href="#two-plans-one-endpoint">Two plans</a> · <a href="#many-seats-one-endpoint">Pool</a> · <a href="#it-tracks-a-moving-target">Drift</a> · <a href="#trust--transparency">Trust</a> · <a href="#will-my-account-get-suspended">Risk</a> · <a href="#commands">Commands</a> · <a href="#faq">FAQ</a> · <a href="docs/returning.md">Coming back after a while?</a></sub>
 
@@ -373,6 +373,17 @@ Three things it does that a round-robin doesn't:
 
 `--pool-strategy=fill-first` concentrates new conversations on one seat until it drains, for primary/backup setups. Refresh tokens expire about 28 days after the original grant regardless of rotation, so every seat's grant age is tracked and surfaced in `dario accounts list`, `dario doctor` and `GET /accounts` before it becomes a silent outage. Provision over HTTP with the headless [admin API](./docs/admin-api.md); pin one request to one seat with `dario accounts check <alias>` (admin API required: `DARIO_ADMIN=1` and a `DARIO_ADMIN_TOKEN`). Internals and the live `/accounts` + `/analytics` endpoints: [multi-account-pool.md](./docs/multi-account-pool.md); covered end-to-end by [`test/pool-e2e.mjs`](./test/pool-e2e.mjs).
 
+### One key per developer
+
+A shared dario serves several people through one `DARIO_API_KEY`, and nothing says whose traffic is whose except a header any client can set. Since 6.8 a **named key** ties attribution to the credential:
+
+```bash
+dario keys create alice
+dario keys create bob --seat=bobs-max --models=claude-sonnet-5,claude-haiku*
+```
+
+The secret is printed once and only its hash is kept, in `~/.dario/keys.json`. The request authenticated with alice's key *is* alice's in `/analytics`, in the ledger (`dario usage --by-key`) and on every log line; a key can prefer one pool seat (taken while it has headroom, normal routing otherwise, so a developer's conversations ride their own subscription) and can be held to a model allowlist (`403` before anything goes upstream, in either wire shape). The running proxy picks up a created, rotated or revoked key on its next request; the root `DARIO_API_KEY` keeps working beside them; `/admin/keys` does the same over HTTP. Details: [keys.md](./docs/keys.md).
+
 ### Watch it happen
 
 Type `dario` with no arguments for a full-screen control panel: live request stream, per-model burn rate, rate-limit utilization per seat, billing-bucket breakdown, and an in-place config editor that writes `~/.dario/config.json`. Pure ANSI, zero new runtime deps. <kbd>Tab</kbd> moves between tabs, <kbd>r</kbd> refreshes, <kbd>R</kbd> resumes a halted overage guard, <kbd>q</kbd> quits.
@@ -515,9 +526,10 @@ Longer version, with specifics: [#68](https://github.com/askalf/dario/discussion
 | `dario doctor [--usage] [--probe] [--obedience] [--auth-check] [--bun-bootstrap] [--json]` | One aggregated health report: runtime/TLS, template and drift, OAuth, pool, refresh-grant age, failover readiness, backends |
 | `dario add altman` / `dario add amodei` | Attach a ChatGPT plan / a Claude account, by whose it is |
 | `dario accounts list` / `add` / `remove` / `check <alias>` | Pool management; `check` sends one pinned request per model through the running proxy (admin API on) |
+| `dario keys create <name>` / `list` / `revoke` / `rotate` | One credential per developer on a shared dario: attributed by key, optional preferred seat and model allowlist, hashes on disk ([keys.md](./docs/keys.md)) |
 | `dario backend list` / `add` / `remove` | OpenAI-compatible API-key backends |
 | `dario codex list` / `add` / `remove` | ChatGPT accounts (the long form of `dario add altman`) |
-| `dario usage` · `dario compare` · `dario config` · `dario status` | Lifetime API-equivalent spend + burn rate for the last hour (`--card` writes the share card) · read the shadow-compare log · effective config, redacted · token health |
+| `dario usage` · `dario compare` · `dario config` · `dario status` | Lifetime API-equivalent spend + burn rate for the last hour (`--card` writes the share card, `--by-key` splits it per key) · read the shadow-compare log · effective config, redacted · token health |
 | `dario resume` · `dario refresh` · `dario logout` · `dario upgrade` | Clear an overage halt · force a token refresh · delete credentials · safe self-update |
 | `dario mcp` · `dario subagent install` / `remove` / `status` | Reach dario from inside any MCP client, or from inside a Claude Code session, read-only |
 
@@ -529,7 +541,7 @@ Longer version, with specifics: [#68](https://github.com/askalf/dario/discussion
 | `GET /status` · `GET /accounts` · `GET /analytics` | OAuth detail · per-seat utilization and grant age · per-account / per-model stats and burn rate |
 | `POST /v1/messages/count_tokens` · `POST /v1/complete` | Token counting and the legacy Text Completions shape |
 | `GET /analytics/stream` · `GET /analytics/ledger` · `GET /codex` | Live analytics over SSE · the ledger's per-day table · ChatGPT-seat status, read without spending or exposing a token |
-| `/admin/*` | Provisioning, `GET /admin/accounts`, `POST /admin/resume`; only with `DARIO_ADMIN=1` ([admin API](./docs/admin-api.md)) |
+| `/admin/*` | Provisioning, `GET /admin/accounts`, `/admin/keys`, `POST /admin/resume`; only with `DARIO_ADMIN=1` ([admin API](./docs/admin-api.md)) |
 
 Flags: [commands.md](./docs/commands.md), plus `dario --help` for the ones it doesn't list yet (`--effort`, `--max-tokens`, `--model-alias`, `--fast-model`, session rotation, concurrency caps, the pacing knobs behind `--stealth`) · env vars grouped by task, for Docker / k8s / systemd: [configuration.md](./docs/configuration.md) · SDK examples: [usage.md](./docs/usage.md).
 

package/dist/admin-api.d.ts

@@ -68,6 +68,7 @@
  * against it.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type KeyStore } from './keys.js';
 /** Persisted account metadata surfaced by `GET /admin/accounts`. */
 export interface AdminAccountRecord {
     alias: string;
@@ -142,11 +143,13 @@ export interface AdminAccountLive {
 }
 /** An audited admin action — see `AdminDeps.audit`. Never carries secrets. */
 export interface AdminAuditEvent {
-    action: 'login_start' | 'login_complete' | 'account_remove' | 'auth_reject' | 'rate_limited';
+    action: 'login_start' | 'login_complete' | 'account_remove' | 'auth_reject' | 'rate_limited' | 'key_create' | 'key_revoke' | 'key_rotate';
     ok: boolean;
     status: number;
     /** Account alias, when the action targets one. */
     alias?: string;
+    /** Named key, when the action targets one (dario#1318). The name only, never the secret. */
+    key?: string;
     /** Client address (`req.socket.remoteAddress`), when known. */
     remote?: string;
     /** Extra context, e.g. the rate-limited category ('auth' | 'mutation'). */
@@ -187,6 +190,13 @@ export interface AdminDeps {
      * auth are never gated. Absent = no limiting. Owned by the proxy (#620).
      */
     rateLimit?: (category: 'auth' | 'mutation') => number;
+    /**
+     * Named keys (dario#1318): the store the running proxy authenticates
+     * from, so `/admin/keys` edits the same file `dario keys` does and a key
+     * minted here works on the next request. `null` / absent = named keys are
+     * off on this proxy; the routes answer 404.
+     */
+    keys?: KeyStore | null;
 }
 /**
  * Handle an `/admin/*` request. Returns `true` if it owned the request (matched

package/dist/admin-api.js

@@ -3,9 +3,11 @@ import { timingSafeEqual } from 'node:crypto';
 import { startAddAccount, completeAddAccount, removeAccount, listAccountAliases, loadAccount, } from './accounts.js';
 import { parseManualPaste } from './oauth.js';
 import { grantAge } from './refresh-grant.js';
+import { createKey, revokeKey, rotateKey, parseExpiry, publicKey, KEY_NAME_RE } from './keys.js';
 const PENDING_TTL_MS = 10 * 60_000;
 const MAX_PENDING = 64; // backstop against unbounded growth (distinct aliases)
 const ACCOUNTS_PREFIX = '/admin/accounts/';
+const KEYS_PREFIX = '/admin/keys/';
 /**
  * `consecutiveAuthFailures` floor for `/admin/login/start-needed` to treat an
  * account as needing a new login rather than mid-blip. Empirically: 1 failure
@@ -175,11 +177,23 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
     const method = req.method ?? 'GET';
     const remote = req.socket?.remoteAddress;
     const isAccountDelete = method === 'DELETE' && urlPath.startsWith(ACCOUNTS_PREFIX) && urlPath.length > ACCOUNTS_PREFIX.length;
+    // Named keys (dario#1318): `/admin/keys`, `/admin/keys/<name>`,
+    // `/admin/keys/<name>/rotate`. The name is validated after auth so a
+    // malformed one is a 400 to a caller who holds the token, not a route miss.
+    const keyTarget = urlPath.startsWith(KEYS_PREFIX) && urlPath.length > KEYS_PREFIX.length
+        ? decodeURIComponent(urlPath.slice(KEYS_PREFIX.length))
+        : null;
+    const isKeyRotate = keyTarget !== null && keyTarget.endsWith('/rotate');
+    const keyName = keyTarget === null ? null : isKeyRotate ? keyTarget.slice(0, -'/rotate'.length) : keyTarget;
+    const isKeyRevoke = keyTarget !== null && !isKeyRotate && method === 'DELETE';
     const known = urlPath === '/admin/login/start' ||
         urlPath === '/admin/login/start-needed' ||
         urlPath === '/admin/login/complete' ||
         urlPath === '/admin/accounts' ||
-        isAccountDelete;
+        urlPath === '/admin/keys' ||
+        isAccountDelete ||
+        isKeyRotate ||
+        isKeyRevoke;
     if (!known)
         return false;
     // Auth — always required, even on loopback (these mutate OAuth credentials).
@@ -209,7 +223,8 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
     // below). That is a deliberate cost-accounting choice, not an oversight: a
     // blanket pre-parse token here would let a single HTTP request move N
     // accounts' credentials for the price of one throttle token.
-    const isMutation = urlPath === '/admin/login/start' || isAccountDelete;
+    const isMutation = urlPath === '/admin/login/start' || isAccountDelete
+        || (urlPath === '/admin/keys' && method === 'POST') || isKeyRotate || isKeyRevoke;
     if (isMutation) {
         const wait = deps.rateLimit?.('mutation') ?? 0;
         if (wait > 0) {
@@ -415,6 +430,90 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
             send(res, removed ? 200 : 404, { alias, removed });
             return true;
         }
+        // Named keys (dario#1318). Every route below edits the store the proxy
+        // authenticates from; the secret appears in exactly one response and is
+        // never stored, listed or logged.
+        if (urlPath === '/admin/keys' || keyName !== null) {
+            const store = deps.keys ?? null;
+            if (!store) {
+                send(res, 404, { error: 'named keys are off on this proxy', hint: 'start without --no-keys / DARIO_KEYS=0' });
+                return true;
+            }
+            if (store.error) {
+                send(res, 503, { error: `keys file unreadable: ${store.error}`, path: store.path });
+                return true;
+            }
+            // GET /admin/keys — every key, hashes excluded.
+            if (urlPath === '/admin/keys' && method === 'GET') {
+                const keys = store.list(now);
+                send(res, 200, { keys, count: keys.length, path: store.path });
+                return true;
+            }
+            // POST /admin/keys  { name, seat?, models?, expires? } — the secret, once.
+            if (urlPath === '/admin/keys' && method === 'POST') {
+                const body = await readJsonBody(req);
+                const name = typeof body.name === 'string' ? body.name.trim() : '';
+                if (!KEY_NAME_RE.test(name)) {
+                    send(res, 400, { error: 'invalid or missing "name": letters, digits, _ - . only, up to 64, starting with a letter or digit' });
+                    return true;
+                }
+                const seat = typeof body.seat === 'string' && body.seat.trim() ? body.seat.trim() : undefined;
+                const models = Array.isArray(body.models)
+                    ? body.models.filter((m) => typeof m === 'string' && m.trim().length > 0).map((m) => m.trim())
+                    : typeof body.models === 'string' ? body.models.split(',').map((m) => m.trim()).filter(Boolean) : undefined;
+                let expiresAt;
+                if (typeof body.expires === 'string' && body.expires.trim()) {
+                    const parsed = parseExpiry(body.expires, now);
+                    if (parsed === null) {
+                        send(res, 400, { error: 'invalid "expires": use 30d, 12h, 2w, or an ISO date' });
+                        return true;
+                    }
+                    expiresAt = parsed;
+                }
+                try {
+                    const made = store.mutate((file) => createKey(file, name, { seat, models, expiresAt, now }));
+                    deps.audit?.({ action: 'key_create', ok: true, status: 201, key: made.record.name, remote, detail: seat ? `seat=${seat}` : undefined });
+                    send(res, 201, { key: publicKey(made.record, now), secret: made.secret, note: 'the secret is shown once and is not stored' });
+                }
+                catch (err) {
+                    const message = err.message;
+                    const status = /already exists/.test(message) ? 409 : 400;
+                    deps.audit?.({ action: 'key_create', ok: false, status, key: name, remote });
+                    send(res, status, { error: message });
+                }
+                return true;
+            }
+            if (urlPath === '/admin/keys') {
+                send(res, 405, { error: 'Method not allowed (use GET or POST)' });
+                return true;
+            }
+            if (!KEY_NAME_RE.test(keyName)) {
+                send(res, 400, { error: 'invalid key name' });
+                return true;
+            }
+            // POST /admin/keys/<name>/rotate — a new secret under the same name; the old one stops at once.
+            if (isKeyRotate) {
+                if (method !== 'POST') {
+                    send(res, 405, { error: 'Method not allowed (use POST)' });
+                    return true;
+                }
+                const rotated = store.mutate((file) => rotateKey(file, keyName, now));
+                deps.audit?.({ action: 'key_rotate', ok: rotated !== null, status: rotated ? 200 : 404, key: keyName, remote });
+                if (!rotated) {
+                    send(res, 404, { error: `no key named "${keyName}"` });
+                    return true;
+                }
+                send(res, 200, { key: publicKey(rotated.record, now), secret: rotated.secret, note: 'the secret is shown once and is not stored' });
+                return true;
+            }
+            // DELETE /admin/keys/<name> — revoked, kept for the list.
+            if (isKeyRevoke) {
+                const revoked = store.mutate((file) => revokeKey(file, keyName));
+                deps.audit?.({ action: 'key_revoke', ok: revoked, status: revoked ? 200 : 404, key: keyName, remote });
+                send(res, revoked ? 200 : 404, { name: keyName, revoked });
+                return true;
+            }
+        }
         send(res, 405, { error: 'Method not allowed' });
         return true;
     }

package/dist/cli.js

@@ -17,7 +17,8 @@
 // just want `parsePositiveIntEnv`) doesn't trigger a Bun relaunch or any
 // other startup side effect.
 import { unlink, writeFile } from 'node:fs/promises';
-import { formatLedgerSummary, formatUsd, renderLedgerCard, readLedgerFile, resolveLedgerPath, summarizeLedger } from './ledger.js';
+import { formatLedgerSummary, formatLedgerConsumers, formatUsd, renderLedgerCard, readLedgerFile, resolveLedgerPath, summarizeLedger } from './ledger.js';
+import { KeyStore, createKey, revokeKey, rotateKey, deleteKey, parseExpiry, publicKey, resolveKeysPath, KEY_NAME_RE } from './keys.js';
 import { loadAllAccounts as loadAllAccountsForIdentity, regenerateClientIdentity } from './accounts.js';
 import { maskEmail } from './pool.js';
 import { realpathSync, readFileSync } from 'node:fs';
@@ -635,6 +636,12 @@ async function proxy() {
     // On by default; see ProxyOptions.ledger.
     const ledger = !(args.includes('--no-ledger')
         || ['0', 'false', 'no', 'off'].includes((process.env['DARIO_LEDGER'] ?? '').toLowerCase()));
+    // --no-keys / DARIO_KEYS=0 — ignore ~/.dario/keys.json (v6.8, dario#1318);
+    // --keys-path=<file> / DARIO_KEYS_PATH moves it. See ProxyOptions.keys.
+    const keys = !(args.includes('--no-keys')
+        || ['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;
     // --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.
@@ -659,7 +666,166 @@ 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, 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, poolStrategy, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, 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, poolStrategy, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath });
+}
+/**
+ * `dario keys` — named keys for a shared dario (v6.8, dario#1318). One
+ * credential per developer, stored as a hash in ~/.dario/keys.json; the
+ * secret is printed once, here, and nowhere else. The running proxy re-reads
+ * the file on the next request, so nothing restarts.
+ */
+async function keys() {
+    const sub = args[1];
+    const asJson = args.includes('--json');
+    const pathArg = args.find(a => a.startsWith('--keys-path='));
+    const path = pathArg ? pathArg.slice('--keys-path='.length) : resolveKeysPath();
+    const store = new KeyStore(path);
+    const now = Date.now();
+    const fmtDay = (iso) => iso ? iso.slice(0, 10) : '-';
+    const fmtAgo = (iso) => {
+        if (!iso)
+            return 'never';
+        const ms = now - Date.parse(iso);
+        if (ms < 60_000)
+            return 'just now';
+        if (ms < 3_600_000)
+            return `${Math.floor(ms / 60_000)}m ago`;
+        if (ms < 86_400_000)
+            return `${Math.floor(ms / 3_600_000)}h ago`;
+        return `${Math.floor(ms / 86_400_000)}d ago`;
+    };
+    const printSecret = (verb, k, secret) => {
+        if (asJson) {
+            process.stdout.write(JSON.stringify({ key: k, secret }, null, 2) + '\n');
+            return;
+        }
+        console.log('');
+        console.log(`  Key "${k.name}" ${verb} (id ${k.id}).`);
+        console.log('');
+        console.log(`    ${secret}`);
+        console.log('');
+        console.log('  Shown once; dario keeps only a hash. Give it to the client as its API');
+        console.log('  key — every request it authenticates is attributed to this name in');
+        console.log('  /analytics, the ledger (`dario usage --by-key`) and the log.');
+        if (k.seat)
+            console.log(`  Preferred seat: ${k.seat} (used when it has headroom; otherwise normal routing)`);
+        if (k.models.length > 0)
+            console.log(`  Models: ${k.models.join(', ')} (anything else is refused with 403)`);
+        if (k.expires)
+            console.log(`  Expires: ${k.expires}`);
+        console.log('  A running proxy picks this up on its next request; no restart.');
+        console.log('');
+    };
+    if (!sub || sub === 'list' || sub === 'ls') {
+        store.load();
+        if (store.error) {
+            console.error(`[dario] keys: ${path} is unreadable: ${store.error}`);
+            process.exit(1);
+        }
+        const list = store.list(now);
+        if (asJson) {
+            process.stdout.write(JSON.stringify({ path, keys: list, count: list.length }, null, 2) + '\n');
+            return;
+        }
+        console.log('');
+        console.log('  dario — Keys');
+        console.log('  ────────────');
+        console.log('');
+        if (list.length === 0) {
+            console.log(`  No named keys yet (${path}).`);
+            console.log('');
+            console.log('  One key per developer on a shared dario, attributed by credential:');
+            console.log('');
+            console.log('    dario keys create alice');
+            console.log('    dario keys create bob --seat=bobs-max --models=claude-sonnet-5');
+            console.log('');
+            return;
+        }
+        const w = Math.max(4, ...list.map((k) => k.name.length));
+        console.log(`  ${'NAME'.padEnd(w)}  ${'STATUS'.padEnd(7)}  ${'SEAT'.padEnd(12)}  ${'LAST USED'.padEnd(10)}  ${'EXPIRES'.padEnd(10)}  MODELS`);
+        for (const k of list) {
+            console.log(`  ${k.name.padEnd(w)}  ${k.status.padEnd(7)}  ${(k.seat ?? '-').padEnd(12)}  ${fmtAgo(k.last_used).padEnd(10)}  ${fmtDay(k.expires).padEnd(10)}  ${k.models.length ? k.models.join(', ') : 'any'}`);
+        }
+        console.log('');
+        console.log(`  ${list.length} key${list.length === 1 ? '' : 's'} in ${path}. Spend per key: dario usage --by-key`);
+        console.log('');
+        return;
+    }
+    if (sub === 'create' || sub === 'add' || sub === 'new') {
+        const name = args[2];
+        if (!name || name.startsWith('--')) {
+            console.error('');
+            console.error('  Usage: dario keys create <name> [--seat=<alias>] [--models=a,b,prefix*] [--expires=30d|12h|2w|<ISO date>]');
+            console.error('');
+            process.exit(1);
+        }
+        const seatArg = args.find(a => a.startsWith('--seat='));
+        const modelsArg = args.find(a => a.startsWith('--models='));
+        const expiresArg = args.find(a => a.startsWith('--expires='));
+        const seat = seatArg ? seatArg.slice('--seat='.length).trim() : undefined;
+        const models = modelsArg ? modelsArg.slice('--models='.length).split(',').map((m) => m.trim()).filter(Boolean) : undefined;
+        let expiresAt;
+        if (expiresArg) {
+            const parsed = parseExpiry(expiresArg.slice('--expires='.length), now);
+            if (parsed === null) {
+                console.error(`[dario] --expires: "${expiresArg.slice('--expires='.length)}" is not 30d, 12h, 2w or an ISO date.`);
+                process.exit(1);
+            }
+            expiresAt = parsed;
+        }
+        try {
+            const made = store.mutate((file) => createKey(file, name, { seat, models, expiresAt, now }));
+            printSecret('created', publicKey(made.record, now), made.secret);
+        }
+        catch (err) {
+            console.error(`[dario] ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (sub === 'rotate' || sub === 'revoke' || sub === 'remove' || sub === 'rm' || sub === 'delete') {
+        const name = args[2];
+        if (!name || !KEY_NAME_RE.test(name)) {
+            console.error('');
+            console.error(`  Usage: dario keys ${sub} <name>`);
+            console.error('');
+            process.exit(1);
+        }
+        try {
+            if (sub === 'rotate') {
+                const rotated = store.mutate((file) => rotateKey(file, name, now));
+                if (!rotated) {
+                    console.error(`[dario] No key named "${name}".`);
+                    process.exit(1);
+                }
+                printSecret('rotated — the old secret stopped working', publicKey(rotated.record, now), rotated.secret);
+                return;
+            }
+            if (sub === 'revoke') {
+                const ok = store.mutate((file) => revokeKey(file, name));
+                if (!ok) {
+                    console.error(`[dario] No key named "${name}".`);
+                    process.exit(1);
+                }
+                console.log(`[dario] Key "${name}" revoked. It stays in the list; \`dario keys remove ${name}\` forgets it.`);
+                return;
+            }
+            const ok = store.mutate((file) => deleteKey(file, name));
+            if (!ok) {
+                console.error(`[dario] No key named "${name}".`);
+                process.exit(1);
+            }
+            console.log(`[dario] Key "${name}" removed.`);
+        }
+        catch (err) {
+            console.error(`[dario] ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
+    console.error(`[dario] Unknown keys subcommand: ${sub}`);
+    console.error('Usage: dario keys [list|create <name> [--seat=..] [--models=..] [--expires=..]|revoke <name>|rotate <name>|remove <name>] [--json] [--keys-path=<file>]');
+    process.exit(1);
 }
 /**
  * Parse `--system-prompt=<verbatim|partial|aggressive|filepath>` (or the
@@ -1505,6 +1671,25 @@ async function help() {
                              entry by its platform identifier (Linux account
                              attribute, Windows TargetName).
     dario accounts remove N  Remove an account from the pool
+    dario keys create NAME [--seat=ALIAS] [--models=a,b,prefix*] [--expires=30d]
+                             Mint a named key for one developer on a shared
+                             dario (v6.8). Prints the secret once; stores a
+                             hash in ~/.dario/keys.json. Requests it
+                             authenticates are attributed to NAME in
+                             /analytics, the ledger and the log, next to
+                             the root DARIO_API_KEY which keeps working.
+                             --seat prefers a pool seat when it has
+                             headroom (normal routing otherwise); --models
+                             refuses any other model with 403 before
+                             anything goes upstream; --expires refuses the
+                             key after 30d / 12h / 2w / an ISO date. The
+                             running proxy sees it on the next request.
+    dario keys list          Named keys: status, seat, last used, expiry,
+                             models. --json for the raw list.
+    dario keys revoke NAME   Refuse a key from now on (kept in the list).
+    dario keys rotate NAME   New secret, same name and settings; the old
+                             secret stops at once.
+    dario keys remove NAME   Forget a key entirely.
     dario codex list         List ChatGPT-subscription accounts, served on
                              /v1/chat/completions.
     dario codex add NAME     Add a ChatGPT-subscription account (prints an
@@ -1594,6 +1779,9 @@ async function help() {
                              down). --card[=file.svg] writes a share
                              card of that number (default
                              dario-api-equivalent.svg). (v6.6)
+                             --by-key splits the lifetime number per
+                             consumer: named key, x-dario-consumer
+                             header, or hashed user id. (v6.8)
     dario compare            Read the shadow-compare log written by
                              requests carrying \`x-dario-compare\`:
                              per-model calls, success rate, median
@@ -1729,6 +1917,10 @@ async function help() {
                              first request, across restarts. Env:
                              DARIO_LEDGER=0; DARIO_LEDGER_PATH=<file>
                              moves it. (v6.6)
+    --no-keys                Ignore named keys (~/.dario/keys.json): only
+                             DARIO_API_KEY authenticates. Env: DARIO_KEYS=0;
+                             --keys-path=<file> / DARIO_KEYS_PATH moves the
+                             file. See \`dario keys\`. (v6.8)
     --session-idle-rotate=MS Idle ms before an account's session id
                              rotates (default: 900000 = 15 min).
                              Real CC rotates once per conversation, not
@@ -2353,8 +2545,13 @@ async function usage() {
     const url = `http://127.0.0.1:${port}/analytics`;
     let payload = null;
     let connectError = null;
+    // A proxy with DARIO_API_KEY set gates /analytics too; present the key when
+    // the environment has it, as `accounts list --live` does (v6.8).
+    const usageHeaders = {};
+    if (process.env['DARIO_API_KEY'])
+        usageHeaders['x-api-key'] = process.env['DARIO_API_KEY'];
     try {
-        const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+        const res = await fetch(url, { signal: AbortSignal.timeout(3000), headers: usageHeaders });
         if (!res.ok) {
             connectError = `proxy responded ${res.status}`;
         }
@@ -2408,6 +2605,18 @@ async function usage() {
         for (const line of formatLedgerSummary(lifetime))
             console.log(line);
         console.log('');
+        // --by-key: the same number split by consumer — named key, header, or
+        // hashed user id (v6.8, dario#1318).
+        const consumers = Object.keys(lifetime.perConsumer ?? {}).length;
+        if (args.includes('--by-key')) {
+            for (const line of formatLedgerConsumers(lifetime))
+                console.log(line);
+            console.log('');
+        }
+        else if (consumers > 0) {
+            console.log(`  ${consumers} consumer${consumers === 1 ? '' : 's'} named — \`dario usage --by-key\` splits the number per key.`);
+            console.log('');
+        }
     }
     else if (lifetimeNote) {
         console.log(`  API-equivalent spend: ${lifetimeNote}.`);
@@ -2612,6 +2821,7 @@ const commands = {
     resume,
     logout,
     accounts,
+    keys,
     add,
     codex,
     backend,

package/dist/keys.d.ts

@@ -0,0 +1,127 @@
+export declare const KEYS_VERSION = 1;
+export declare const KEY_PREFIX = "dk_";
+/** Same charset as a pool alias — a key name is printed next to one. */
+export declare const KEY_NAME_RE: RegExp;
+export declare const KEYS_FLUSH_DELAY_MS = 3000;
+export interface KeyRecord {
+    /** Stable short id (8 hex), for logs and rotation; never the secret. */
+    id: string;
+    name: string;
+    /** sha256 hex of the secret. */
+    hash: string;
+    /** ISO timestamp. */
+    created: string;
+    /** ISO timestamp of the last request this key authenticated. */
+    lastUsed?: string;
+    /** Refused, kept for the record. `dario keys revoke` sets it; `list` shows it. */
+    disabled?: boolean;
+    /** ISO timestamp; refused after. */
+    expires?: string;
+    /** Preferred pool seat alias. */
+    seat?: string;
+    /** Model allowlist: exact ids, or `prefix*`. Empty / absent = any model. */
+    models?: string[];
+}
+export interface KeysFile {
+    version: number;
+    keys: KeyRecord[];
+}
+export declare function keysPathFor(home?: string): string;
+export declare function resolveKeysPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * sha256, not a slow KDF, on purpose: a key is 24 bytes from `randomBytes`
+ * (192 bits of entropy), never a human-chosen password, so a guess is not
+ * a threat a KDF could slow down, and this hash runs once per request on the
+ * hot path. This is how GitHub and Stripe store their API tokens.
+ * (CodeQL's js/insufficient-password-hash fires on the x-api-key source and
+ * is dismissed as a false positive for exactly this reason.)
+ */
+export declare function hashKey(secret: string): string;
+/** `dk_` + 48 hex characters. The prefix lets a reject log say "a named key" without the value. */
+export declare function mintSecret(): string;
+export declare function looksLikeNamedKey(value: string | undefined): boolean;
+export declare function emptyKeysFile(): KeysFile;
+/**
+ * Parse a keys file's text, keeping only well-formed records. A file that is
+ * not a keys file at all throws; the caller decides whether to move it aside.
+ */
+export declare function parseKeysFile(text: string): KeysFile;
+/** Missing file → empty. Unreadable or malformed → throws (never silently empty: that would "revoke" everyone). */
+export declare function readKeysFile(path: string): KeysFile;
+/** Atomic, 0600, parent 0700 — the same primitive config.json uses. */
+export declare function writeKeysFile(path: string, file: KeysFile): void;
+export interface CreateKeyOptions {
+    seat?: string;
+    models?: string[];
+    /** Absolute expiry, epoch ms. */
+    expiresAt?: number;
+    now?: number;
+}
+/** Mint a key. Returns the record (stored) and the secret (shown once). Mutates `file`. */
+export declare function createKey(file: KeysFile, name: string, opts?: CreateKeyOptions): {
+    record: KeyRecord;
+    secret: string;
+};
+/** Mark a key refused. Returns false when there is no such key. The record stays, for the list. */
+export declare function revokeKey(file: KeysFile, name: string): boolean;
+/** Forget a key entirely (list no longer shows it). */
+export declare function deleteKey(file: KeysFile, name: string): boolean;
+/** New secret, same name, seat, models and expiry; the old secret stops working at once. */
+export declare function rotateKey(file: KeysFile, name: string, now?: number): {
+    record: KeyRecord;
+    secret: string;
+} | null;
+export declare function keyIsUsable(k: KeyRecord, now?: number): boolean;
+/**
+ * The record a presented secret belongs to, or null. Compares hashes in
+ * constant time, every record every time, so a miss takes as long as a hit
+ * and neither the count of keys nor which one matched leaks through timing.
+ * A disabled or expired key matches nothing — the caller cannot tell it from
+ * a wrong secret, on purpose.
+ */
+export declare function matchKey(file: KeysFile, provided: string, now?: number): KeyRecord | null;
+/** `models` entries are exact ids, or `prefix*`; case-insensitive. Absent list = any model. */
+export declare function keyAllowsModel(k: Pick<KeyRecord, 'models'>, model: string | null | undefined): boolean;
+/** What `dario keys list` and `GET /admin/keys` show: everything but the hash. */
+export interface KeyPublic {
+    id: string;
+    name: string;
+    created: string;
+    last_used: string | null;
+    status: 'active' | 'revoked' | 'expired';
+    expires: string | null;
+    seat: string | null;
+    models: string[];
+}
+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;
+/**
+ * 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
+ * debounced write that re-reads first so it never clobbers an edit the CLI
+ * made in between.
+ */
+export declare class KeyStore {
+    readonly path: string;
+    private file;
+    private mtimeMs;
+    private loadError;
+    private dirtyLastUsed;
+    private flushTimer;
+    constructor(path: string);
+    /** Read the file now. A malformed file is reported and leaves the last good state in place. */
+    load(): void;
+    get error(): string | null;
+    size(): number;
+    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;
+    /** 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. */
+    mutate<T>(fn: (file: KeysFile) => T): T;
+    /** Persist pending last-used stamps. Safe to call at any time; a no-op when nothing is pending. */
+    flush(): void;
+    close(): void;
+}