@askalf/dario 6.7.1 → 6.8.0

package/dist/proxy.js

@@ -12,11 +12,12 @@ import { darioVersion } from './version.js';
 import { buildCCRequest, applyCcPromptCaching, isGenuineCCClient, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
 import { describeTemplate, detectDrift, checkCCCompat, probeInstalledCCVersion } from './live-fingerprint.js';
-import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, reconcilePoolAccounts, resolvePoolStrategy, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail } from './pool.js';
+import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, reconcilePoolAccounts, resolvePoolStrategy, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail, isAccountEligible } from './pool.js';
 import { backfillIdentity } from './accounts.js';
 import { PoolSync, DEFAULT_POOL_SYNC_INTERVAL_MS } from './pool-sync.js';
 import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM } from './analytics.js';
 import { Ledger, resolveLedgerPath, ledgerDisabledByEnv } from './ledger.js';
+import { KeyStore, keyAllowsModel, resolveKeysPath, looksLikeNamedKey } from './keys.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
 import { grantAge, grantThresholds, worstGrantLevel, describeGrantAge } from './refresh-grant.js';
@@ -1944,6 +1945,18 @@ export async function startProxy(opts = {}) {
     // Optional proxy authentication — pre-encode key buffer for performance
     const apiKey = process.env.DARIO_API_KEY;
     const apiKeyBuf = apiKey ? Buffer.from(apiKey) : null;
+    // Named keys (dario#1318): one credential per developer, hashes on disk,
+    // re-read when the file moves. Attribution and per-key limits ride on the
+    // match; the root DARIO_API_KEY keeps working beside them.
+    const keysOn = opts.keys !== false && process.env['DARIO_KEYS'] !== '0';
+    const keyStore = keysOn ? new KeyStore(opts.keysPath ?? resolveKeysPath()) : null;
+    if (keyStore) {
+        keyStore.load();
+        if (keyStore.error)
+            console.error(`[dario] keys: ${keyStore.path} is unreadable (${keyStore.error}) — named keys are off until it is fixed`);
+        else if (keyStore.size() > 0)
+            console.log(`[dario] keys: ${keyStore.size()} named key${keyStore.size() === 1 ? '' : 's'} from ${keyStore.path}`);
+    }
     // Admin API (#599) — opt-in headless account management at /admin/*. Off
     // unless DARIO_ADMIN=1. Auth is ALWAYS required (even on loopback) because
     // these endpoints add/remove OAuth accounts: the admin token is
@@ -2046,8 +2059,26 @@ 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' });
-    function checkAuth(req) {
-        return authenticateRequest(req.headers, apiKeyBuf);
+    /**
+     * 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,
+     * including the open-on-loopback default when no key is configured at all.
+     * A revoked or expired named key is indistinguishable from a wrong one.
+     */
+    function resolveRequestAuth(req) {
+        const provided = req.headers['x-api-key']
+            || req.headers.authorization?.replace(/^Bearer\s+/i, '');
+        const key = keyStore ? keyStore.match(provided) : null;
+        if (key) {
+            keyStore.touch(key);
+            return { ok: true, key };
+        }
+        // A `dk_` value that matched nothing is refused even on a proxy with no
+        // root key (where an absent credential would pass): the client presented
+        // a dario credential, and a revoked one must mean refused, not anonymous.
+        if (keyStore && !apiKeyBuf && looksLikeNamedKey(provided))
+            return { ok: false, key: null };
+        return { ok: authenticateRequest(req.headers, apiKeyBuf), key: null };
     }
     /**
      * A ChatGPT seat declined. Cool the SEAT, and the provider only once every
@@ -2355,6 +2386,10 @@ export async function startProxy(opts = {}) {
         if (adminEnabled && urlPath.startsWith('/admin/')) {
             const handled = await handleAdminRequest(req, res, urlPath, {
                 adminTokenBuf,
+                // Named keys over HTTP (dario#1318): the same file `dario keys` edits,
+                // through the store the live proxy authenticates from, so a key made
+                // here works on the next request.
+                keys: keyStore,
                 onAccountsChanged: async () => {
                     // Hot-reload the live pool from disk so accounts added / removed via
                     // the admin API take effect immediately — no proxy restart (#599).
@@ -2418,7 +2453,8 @@ export async function startProxy(opts = {}) {
                 // line when --log-file / DARIO_LOG_FILE is set.
                 audit: (e) => {
                     const detail = e.detail ? ` detail=${e.detail}` : '';
-                    const line = `[dario] admin-audit: ${e.action} alias=${e.alias ?? '-'} ok=${e.ok} status=${e.status} from=${e.remote ?? '-'}${detail}`;
+                    const target = e.key ? `key=${e.key}` : `alias=${e.alias ?? '-'}`;
+                    const line = `[dario] admin-audit: ${e.action} ${target} ok=${e.ok} status=${e.status} from=${e.remote ?? '-'}${detail}`;
                     if (e.ok)
                         console.log(line);
                     else
@@ -2431,6 +2467,7 @@ export async function startProxy(opts = {}) {
                         status: e.status,
                         event: `admin.${e.action}`,
                         account: e.alias,
+                        key: e.key,
                         reject: e.ok ? undefined : 'admin-auth',
                     });
                 },
@@ -2446,12 +2483,16 @@ export async function startProxy(opts = {}) {
             if (handled)
                 return;
         }
-        if (!checkAuth(req)) {
+        const requestAuth = resolveRequestAuth(req);
+        if (!requestAuth.ok) {
             if (verbose) {
                 // Silent auth rejects are hard to diagnose when a client's config
                 // doesn't quite match what dario expects (dario#97). Emit a
-                // one-line reject log under -v so operators see auth misfires.
-                console.error(`[dario] #${requestCount} 401 rejected (DARIO_API_KEY mismatch): ${describeAuthReject(req.headers)}`);
+                // one-line reject log under -v so operators see auth misfires. A
+                // `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)}`);
             }
             writeLogLine(logFileStream, {
                 ts: new Date().toISOString(), req: requestCount,
@@ -2810,7 +2851,10 @@ export async function startProxy(opts = {}) {
         // attribution. Without one, attribution falls back to a hash of the
         // body's user id once the body is parsed; the cap needs the name before
         // the slot is taken, so only the header gates.
-        const consumerFromHeaders = consumerFromHeader(req.headers[CONSUMER_HEADER]);
+        // A named key (dario#1318) is the consumer: the credential says who this
+        // is, and a header cannot overrule it. Without one, the header names the
+        // consumer as before.
+        const consumerFromHeaders = requestAuth.key?.name ?? consumerFromHeader(req.headers[CONSUMER_HEADER]);
         let consumer = consumerFromHeaders;
         // Proxy to Anthropic (with concurrency control). The bounded queue
         // replaces the v3.30.x-and-earlier unbounded semaphore — dario#80. A
@@ -3041,6 +3085,9 @@ export async function startProxy(opts = {}) {
             }
             if (pinnedAccount && verbose)
                 console.log(`[dario] seat pin → ${pinnedAccount.alias} (no failover)`);
+            // True when a named key's preferred seat was taken for this request
+            // (dario#1318): the sticky binding then follows the key, not the pool.
+            let keySeatTaken = false;
             const selectPoolAccount = () => {
                 if (upstreamApiKey) {
                     // Per-token API-key mode: no OAuth, no pool selection. `poolAccount`
@@ -3055,7 +3102,12 @@ export async function startProxy(opts = {}) {
                     accessToken = pinnedAccount.accessToken;
                     return true;
                 }
-                poolAccount = pool.select();
+                // A named key's preferred seat (dario#1318): taken when that seat is
+                // eligible right now, else the pool picks as usual. Failover
+                // mid-request is unchanged either way — a preference, not a pin.
+                const preferredSeat = requestAuth.key?.seat ? (pool.get(requestAuth.key.seat) ?? null) : null;
+                keySeatTaken = preferredSeat !== null && isAccountEligible(preferredSeat, Date.now());
+                poolAccount = keySeatTaken ? preferredSeat : pool.select();
                 if (poolAccount)
                     poolParkedAnnounced = false;
                 // Every seat parked inside a live window (dario#1244): cool the
@@ -3262,6 +3314,24 @@ export async function startProxy(opts = {}) {
                     return;
                 }
             }
+            // A named key's model allowlist (dario#1318): refused here, in the
+            // request's own wire shape, before anything goes upstream.
+            if (requestAuth.key?.models?.length && parsedBody) {
+                const wanted = typeof parsedBody.model === 'string' ? parsedBody.model : '';
+                if (!keyAllowsModel(requestAuth.key, wanted)) {
+                    requestCount++;
+                    writeLogLine(logFileStream, {
+                        ts: new Date().toISOString(), req: requestCount,
+                        method: req.method ?? '', path: urlPath, status: 403, reject: 'key-model',
+                    });
+                    const msg = `model "${wanted}" is not allowed for key "${requestAuth.key.name}" (allowed: ${requestAuth.key.models.join(', ')})`;
+                    res.writeHead(403, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
+                    res.end(JSON.stringify(isOpenAI
+                        ? { error: { message: msg, type: 'permission_error', param: 'model', code: 'model_not_allowed' } }
+                        : { type: 'error', error: { type: 'permission_error', message: msg } }));
+                    return;
+                }
+            }
             // Responses shape → Messages shape, once, before any routing peeks at
             // the body. The translated body is what a continuation re-issues too:
             // the loopback goes to /v1/messages, which is what this body now is.
@@ -4025,7 +4095,14 @@ export async function startProxy(opts = {}) {
                         // that already has the Anthropic prompt cache warmed for it.
                         // Rotating off mid-session costs cache-create on every turn.
                         stickyKey = computeStickyKey(userMsg);
-                        if (stickyKey && !pinnedAccount) {
+                        if (stickyKey && keySeatTaken && poolAccount) {
+                            // A named key's seat is the binding (dario#1318): the
+                            // developer's conversation stays on their own subscription, and
+                            // a 429 failover below rebinds it exactly as any other.
+                            pool.rebindSticky(stickyKey, poolAccount.alias);
+                            poolSync?.bindSticky(stickyKey, poolAccount.alias);
+                        }
+                        else if (stickyKey && !pinnedAccount) {
                             // Shared state (pool-sync.ts): a conversation a peer instance
                             // already bound lands on the same seat here, so its prompt
                             // cache is read rather than rewritten. Only consulted when this
@@ -5582,6 +5659,7 @@ export async function startProxy(opts = {}) {
         // Flush tokens first (best-effort, bounded), then close the server. The
         // flush is fire-and-forget under the same 5s force-exit guard below so a
         // hung fsync can't wedge shutdown.
+        keyStore?.close();
         void Promise.all([flushPoolTokens(), ledger?.close()]).finally(() => {
             server.close(() => process.exit(0));
         });

package/docs/admin-api.md

@@ -93,6 +93,16 @@ All endpoints accept the token as `authorization: Bearer <token>` or
 | `POST /admin/login/complete` (batch) | `{ "items": [{ "alias", "code" }, ...] }` | `{ results: [...], count, truncated? }` |
 | `GET /admin/accounts` | — | `{ accounts: [...], count }` |
 | `DELETE /admin/accounts/<alias>` | — | `{ alias, removed }` (`404` if no such alias) |
+| `GET /admin/keys` | — | `{ keys: [...], count, path }` — every named key, hashes excluded (v6.8) |
+| `POST /admin/keys` | `{ "name": string, "seat"?: string, "models"?: string[] \| "a,b", "expires"?: "30d" \| ISO }` | `201 { key, secret }` — the secret once; `409` if the name exists |
+| `POST /admin/keys/<name>/rotate` | — | `{ key, secret }` — a new secret, the old one dead at once (`404` if unknown) |
+| `DELETE /admin/keys/<name>` | — | `{ name, revoked }` — refused from now on, kept in the list (`404` if unknown) |
+
+The three `/admin/keys` mutations edit the same `~/.dario/keys.json` that
+`dario keys` does, through the store the running proxy authenticates from,
+so a key minted here works on the next request. With named keys off
+(`--no-keys` / `DARIO_KEYS=0`) the routes answer `404`. What a key carries
+and where it shows: [keys.md](./keys.md).
 
 `GET /admin/accounts` is the monitoring surface: each entry carries the
 persisted metadata (`alias`, `scopes`, `expires_in_ms`, the grant-age fields)
@@ -213,12 +223,13 @@ container being *up* (TCP/HTTP response), not *healthy*.
 
 ## Audit trail
 
-Every mutation (`login_start`, `login_complete`, `account_remove`) and every
-auth reject or throttle is logged with the action, target alias, outcome, HTTP
-status, and client address — to the console always (so `docker logs` /
-journald has the trail with zero setup), and as a structured
-`event: "admin.<action>"` line when `--log-file` / `DARIO_LOG_FILE` is set.
-Secrets never reach the audit sink.
+Every mutation (`login_start`, `login_complete`, `account_remove`,
+`key_create`, `key_rotate`, `key_revoke`) and every auth reject or throttle
+is logged with the action, target alias or key name, outcome, HTTP status,
+and client address — to the console always (so `docker logs` / journald has
+the trail with zero setup), and as a structured `event: "admin.<action>"`
+line when `--log-file` / `DARIO_LOG_FILE` is set. Secrets never reach the
+audit sink; a key event carries the key's name, never its secret.
 
 ## Rate limiting
 
@@ -228,12 +239,12 @@ mutations and **to failed auth attempts** separately:
 
 - **Failed auth**: 10 burst, then 1 per 2s — a wrong-token flood is slowed,
   not answered at full speed.
-- **Mutations** (`login/start`, `login/complete`, account removal): 30 burst,
-  then 1 per 1s.
+- **Mutations** (`login/start`, `login/complete`, account removal, key
+  create / rotate / revoke): 30 burst, then 1 per 1s.
 
 Over the limit returns `429` with a `Retry-After` header, and the throttle
-itself is audited (`rate_limited`). Reads (`GET /admin/accounts`) and
-successful auth are never throttled. `DARIO_ADMIN_RATE_LIMIT=off` disables
+itself is audited (`rate_limited`). Reads (`GET /admin/accounts`,
+`GET /admin/keys`) and successful auth are never throttled. `DARIO_ADMIN_RATE_LIMIT=off` disables
 both buckets; the defaults are generous for a human plus scripts and only
 bite runaway callers.
 

package/docs/api-equivalent-spend.md

@@ -91,6 +91,20 @@ port would write. `--card[=file.svg]` renders the headline as a 640×320 SVG
 fetch, so it looks the same in a README and a screenshot. `--json` is the raw
 `/analytics` payload, `lifetime` included.
 
+`--by-key` (6.8) splits the number per consumer — a [named key](./keys.md),
+an `x-dario-consumer` header, or the `u_…` hash of a client's user id,
+whichever named the request. The file keeps a second table for it,
+`consumers`, with the same per-day, per-model, per-bucket rows; only requests
+that named a consumer land there, so the headline and the split can differ
+by the anonymous traffic.
+
+```
+  By key (3 consumers; API-equivalent, lifetime · today · 7d · 30d):
+    alice      $301.44 ·   $31.10 ·  $301.44 ·  $301.44   900 reqs, Opus 5, Sonnet 5
+    bob         $86.68 ·   $12.00 ·   $86.68 ·   $86.68   304 reqs, Sonnet 5
+    ci          $24.75 ·    $5.10 ·   $24.75 ·   $24.75   311 reqs, gpt-5.6-terra
+```
+
 `GET /analytics` → `lifetime`:
 
 ```json
@@ -104,7 +118,8 @@ fetch, so it looks the same in a README and a screenshot. `--json` is the raw
   "tokens": { "input": 1204000, "output": 388000, "cacheRead": 91200000, "cacheCreate": 4100000 },
   "perProvider": { "anthropic": { "requests": 1204, "apiEquivalentCost": 388.12 }, "openai": { "requests": 311, "apiEquivalentCost": 24.75 } },
   "perModel": { "claude-opus-5": { "provider": "anthropic", "requests": 900, "apiEquivalentCost": 301.44, "meteredCost": 1.1, "...": "token totals" } },
-  "recent": { "today": 48.2, "last7d": 412.87, "last30d": 412.87 }
+  "recent": { "today": 48.2, "last7d": 412.87, "last30d": 412.87 },
+  "perConsumer": { "alice": { "requests": 900, "apiEquivalentCost": 301.44, "meteredCost": 0, "recent": { "...": "same three windows" }, "lastDay": "2026-09-13", "models": ["claude-opus-5", "claude-sonnet-5"] } }
 }
 ```
 

package/docs/commands.md

@@ -9,7 +9,8 @@ This page is the per-flag reference. For environment variables grouped by task
 | `dario login [--manual]` | Log in to the Claude backend. Detects CC credentials or runs its own OAuth flow. `--manual` (v3.20) mirrors CC's code-paste flow for SSH / container setups without a browser. |
 | `dario proxy` | Start the local API proxy on port 3456 |
 | `dario doctor [--probe] [--auth-check] [--json] [--bun-bootstrap]` | Aggregated health report — dario / Node / runtime-TLS / CC binary + compat / template + drift / per-request overhead / OAuth / pool + pool routing (next account in rotation when 2+ loaded) / backends / sub-agent. `--probe` (v3.31.7) hits the live `claude.ai/oauth/authorize` endpoint and surfaces the verdict, so scope-policy drift is catchable from a user's machine (not just CI). `--auth-check` (v3.31.9) opens a one-shot `x-api-key` listener and classifies whatever a client actually sends (match / mismatch / no-auth / timeout), with only redacted previews in output. `--json` (v3.31.8) emits structured output for deepdive's health probes and CI scrapers. `--bun-bootstrap` runs the canonical bun.sh installer when the runtime/TLS check is warning that Bun isn't on PATH. |
-| `dario usage [--port=N] [--json]` | Burn-rate summary of the running proxy's traffic over the last 60 minutes: requests, input/output tokens, avg latency, error rate, subscription % vs. extra-usage, estimated API-equivalent cost, plus per-account breakdown when pool mode is active. Hits `/analytics` on the local proxy. When the proxy isn't reachable, prints a hint pointing at `dario doctor --usage` (the one-off rate-limit probe). `--json` emits the raw `/analytics` payload for status bars / CI dashboards. Also exposed as the `usage` tool in `dario mcp`. |
+| `dario usage [--port=N] [--json] [--by-key]` | Burn-rate summary of the running proxy's traffic over the last 60 minutes: requests, input/output tokens, avg latency, error rate, subscription % vs. extra-usage, estimated API-equivalent cost, plus per-account breakdown when pool mode is active. Hits `/analytics` on the local proxy (presenting `DARIO_API_KEY` when the environment has it). When the proxy isn't reachable, prints a hint pointing at `dario doctor --usage` (the one-off rate-limit probe). `--json` emits the raw `/analytics` payload for status bars / CI dashboards. `--by-key` (v6.8) splits the lifetime API-equivalent number per consumer — named key, `x-dario-consumer` header, or hashed user id. Also exposed as the `usage` tool in `dario mcp`. |
+| `dario keys create <name> [--seat=<alias>] [--models=a,b,prefix*] [--expires=30d]` / `list [--json]` / `revoke <name>` / `rotate <name>` / `remove <name>` | Named keys (v6.8): one credential per developer on a shared dario, attributed by key in `/analytics`, the ledger and the log. `create` prints the secret once and stores a hash in `~/.dario/keys.json`; `--seat` prefers a pool seat while it has headroom; `--models` refuses any other model with `403`; `--expires` refuses the key after `30d` / `12h` / `2w` / an ISO date. The running proxy sees a change on its next request. `--keys-path=<file>` on any of them names another file. See [Named keys](./keys.md). |
 | `dario config [--json]` | Prints the effective dario configuration with credentials redacted. Complementary to `doctor` — doctor answers *is it working?*, config answers *what IS it?* (v3.31.10) |
 | `dario upgrade` | Safe wrapper over `npm install -g @askalf/dario@latest` — probes npm for the `@latest` version first (3s timeout, 60s cache), refuses to run if already on latest, fails with a clear hint if npm is missing. (v3.31.10) |
 | `dario status` | Show Claude backend OAuth token health and expiry |
@@ -38,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 |
+| `--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 |
 | `--passthrough-betas=<csv>` / `DARIO_PASSTHROUGH_BETAS` | Beta flags ALWAYS forwarded upstream regardless of CC's captured set or the client's `anthropic-beta` header. Bypasses the billable-beta filter (so `extended-cache-ttl-*` survives if you opt in). Per-account rejection cache still applies — a pinned flag the upstream 400's gets dropped on retry rather than re-sent forever. Use when you know a beta works on your account but isn't in the captured template, or when client traffic should be force-augmented. Empty flag value (`--passthrough-betas=`) clears the env-default. | off |

package/docs/configuration.md

@@ -43,6 +43,13 @@ Halts the proxy when an upstream response reports `representative-claim: overage
 | `DARIO_QUEUE_TIMEOUT_MS` | `--queue-timeout=MS` | `60000` | a queued request waiting longer gets 504 `queue-timeout` |
 | `DARIO_MAX_CONCURRENT_PER_CONSUMER` | `--max-concurrent-per-consumer=N` | `0` (off) | in-flight ceiling per consumer, keyed by the `x-dario-consumer` request header; a consumer at the cap waits in the queue while everyone else keeps flowing. See [Consumers](./multi-account-pool.md#consumers-who-a-request-is-for) |
 
+## Named keys
+
+| Variable | Flag | Default | Notes |
+|---|---|---|---|
+| `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 |
+
 ## Multi-instance
 
 | Variable | Flag | Default | Notes |

package/docs/keys.md

@@ -0,0 +1,112 @@
+# Named keys — one credential per developer
+
+A team runs one dario for several people. `DARIO_API_KEY` is one secret for
+all of them, so nothing says whose traffic is whose except an
+`x-dario-consumer` header any client can set to anything. A named key ties
+attribution to the credential: the request authenticated with alice's key
+*is* alice's — in `/analytics`, in the ledger, on every log line — and a key
+can carry two things a header never could: a preferred seat and a model
+allowlist.
+
+```bash
+dario keys create alice
+#   Key "alice" created (id 3f1c9a2b).
+#
+#     dk_7c0e…   ← shown once; dario keeps only a hash
+#
+dario keys create bob --seat=bobs-max --models=claude-sonnet-5,claude-haiku*
+dario keys create ci --expires=30d
+dario keys list
+```
+
+Give each person their key as the API key of whatever they point at dario
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, a `Bearer` header — both wire shapes,
+both headers). Nothing else changes: the root `DARIO_API_KEY` keeps working
+beside the named keys, and a running proxy sees a new, rotated or revoked key
+on its next request, no restart.
+
+## What a key carries
+
+| Option | Effect |
+|---|---|
+| `--seat=<alias>` | The pool seat this key's traffic prefers. Taken whenever that seat is eligible right now; when it is parked on a 429, cooling down after an auth failure, or missing, the request routes like any other. A preference, not a pin: in-flight failover is unchanged, and the sticky binding follows the key so a conversation stays on the developer's own subscription. |
+| `--models=a,b,prefix*` | An allowlist. A request for any other model is refused with `403` — in the request's own wire shape, before anything goes upstream. Entries are exact ids or `prefix*`, case-insensitive. |
+| `--expires=30d` | Refused after this, like a revoked key. `12h`, `2w`, or an ISO date. |
+
+`dario keys revoke <name>` refuses a key from now on and keeps it in the list;
+`dario keys rotate <name>` prints a new secret under the same name, seat,
+models and expiry, and the old secret stops at once; `dario keys remove
+<name>` forgets it.
+
+## Where it shows
+
+- **`GET /analytics`** — `perConsumer` (the rolling window) and
+  `lifetime.perConsumer` (the ledger) are keyed by the key's name. A request
+  that carries a named key *and* an `x-dario-consumer` header is attributed
+  to the key; the header cannot overrule a credential.
+- **`dario usage --by-key`** — the lifetime API-equivalent number split per
+  consumer: named keys, header names, and the `u_…` hash of a client's user
+  id, whichever named the request.
+- **The log file** — `consumer` on every request line; `reject: "key-model"`
+  on a model refusal; `event: "admin.key_create|key_rotate|key_revoke"` with
+  `key: <name>` when the admin API changed something.
+- **`--max-concurrent-per-consumer`** — the per-consumer cap keys on the same
+  name, so a named key is paced like a header-named consumer.
+
+## The file
+
+`~/.dario/keys.json`, mode `0600`, holding a `sha256` hash per key and never
+a secret. `DARIO_KEYS_PATH=<file>` / `--keys-path=<file>` moves it;
+`--no-keys` / `DARIO_KEYS=0` ignores it (only `DARIO_API_KEY` authenticates).
+The proxy re-reads the file when its mtime moves — one `stat` per
+authenticated request, the cost of "no restart" — and records each key's
+`last_used` with a debounced write that re-reads first, so it never clobbers
+an edit the CLI made in between. A file that does not parse is reported and
+the last good state stays in force: a bad edit does not lock everyone out,
+and an empty read never silently revokes everyone.
+
+Matching is constant-time over every record, every time, so a miss takes as
+long as a hit and neither the number of keys nor which one matched leaks
+through timing. A revoked, expired and unknown key are the same `401`.
+
+The wire is untouched. dario already replaces the inbound key with the seat's
+own bearer before upstream, so a named key changes what dario knows, not what
+Anthropic or OpenAI sees — passthrough stays byte-identical.
+
+## Over HTTP
+
+With the [admin API](./admin-api.md) on (`DARIO_ADMIN=1`, `DARIO_ADMIN_TOKEN`),
+the same file is editable without shell access:
+
+```bash
+curl -s -H "authorization: Bearer $DARIO_ADMIN_TOKEN" http://localhost:3456/admin/keys
+curl -s -X POST -H "authorization: Bearer $DARIO_ADMIN_TOKEN" -H 'content-type: application/json' \
+  -d '{"name":"alice","seat":"work","models":["claude-sonnet-5"],"expires":"30d"}' \
+  http://localhost:3456/admin/keys
+# -> 201 { "key": { "id", "name", "status", "seat", "models", "expires", … }, "secret": "dk_…" }
+curl -s -X POST   -H "authorization: Bearer $DARIO_ADMIN_TOKEN" http://localhost:3456/admin/keys/alice/rotate
+curl -s -X DELETE -H "authorization: Bearer $DARIO_ADMIN_TOKEN" http://localhost:3456/admin/keys/alice
+```
+
+Every mutation is audited by key name; the secret appears in exactly one
+response and is never stored, listed or logged.
+
+## A keys-only proxy
+
+A named key is additive: it never changes what a request *without* one gets.
+On loopback with no `DARIO_API_KEY`, an anonymous request is still served, as
+it always was; a request that presents a `dk_` credential that matches
+nothing is refused, because a revoked key must mean refused, not anonymous.
+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.
+
+## Compared with a gateway
+
+A LiteLLM-style gateway in front of dario does this with a database, a UI and
+its own key format, and knows nothing about seats. A named key is a line in a
+0600 file, attribution rides the credential rather than a header the client
+chooses, and the seat preference is something only the thing holding the
+subscriptions can offer. Quotas per key — a share of a seat's 5-hour and
+7-day window — are the obvious next step and are deliberately not in this
+version; the attribution they would need is.

package/docs/multi-account-pool.md

@@ -174,10 +174,11 @@ The running proxy presents a rewritten identity on the seat's next request; no r
 
 A pool shared by a team serves several people through one `DARIO_API_KEY`, and until now nothing said whose traffic went where. A request can now name its consumer, and dario attributes and, optionally, paces by it:
 
+- **A named key** (6.8) — `dario keys create alice` mints a credential whose name is the consumer. Attribution rides the credential, so a header cannot overrule it, and the key can prefer a seat or be held to a model allowlist. The rest of this section applies to it unchanged. See [Named keys](./keys.md).
 - **`x-dario-consumer: <name>`** — one printable token, up to 64 characters, no spaces. Set it per user in whatever fronts dario (LiteLLM's per-key headers, a reverse proxy, the client itself). This is the name the per-consumer cap keys on.
 - **Without the header**, attribution falls back to a hash of the body's user id: the Anthropic `metadata.user_id` (Claude Code sends `user_<hash>_account_<uuid>_session_<uuid>`; the session part is dropped, so one person is one key across sessions) or the OpenAI `user` field. The key is `u_` plus twelve hex characters — no account id or raw user id becomes an analytics key. The fallback is attribution only: the body is parsed after the concurrency slot is taken, so only the header can pace.
 
-Where it shows: `GET /analytics` gains `perConsumer` (requests, tokens, cache share, estimated cost, the seats the consumer landed on, last model) next to `perAccount`; every request log line and the `-v` usage line carry `consumer`; the TUI's Hits tab shows it on the selected request.
+Where it shows: `GET /analytics` gains `perConsumer` (requests, tokens, cache share, estimated cost, the seats the consumer landed on, last model) next to `perAccount`, and `lifetime.perConsumer` splits the ledger the same way (`dario usage --by-key`); every request log line and the `-v` usage line carry `consumer`; the TUI's Hits tab shows it on the selected request.
 
 **Fairness.** `--max-concurrent-per-consumer=N` (`DARIO_MAX_CONCURRENT_PER_CONSUMER`) caps in-flight requests per named consumer. A consumer at the cap waits in the queue while slots are free for everyone else; when a slot frees, the first waiter whose consumer is under its cap is admitted, so one heavy user's backlog never holds up another user's next turn. Requests that name no consumer are never capped. Off by default — the plain `--max-concurrent` ceiling still applies to everyone together.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.7.1",
+  "version": "6.8.0",
   "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": {
@@ -86,7 +86,7 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.5.1",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }