mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-22 13:35:10 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 
|
ba69a3c13b | ||
|
|
679e3b367d | ||
|
|
9b66326e72 | ||
|
|
1062e88e77 | ||
|
|
1661f336cd | ||
|
|
5ebe3dc77c | ||
|
|
179b4707a7 | ||
|
|
b1afcde929 | ||
|
|
6d9ab1f334 | ||
|
|
68e50da68a | ||
|
|
408d5a839a | ||
|
|
251b578114 | ||
|
|
f9f2eaa059 | ||
|
|
686794e316 | ||
|
|
c0b696984f | ||
|
|
e87b6b73ec | ||
|
|
939f3e6bd9 | ||
|
|
06f619120d | ||
|
|
40064955ab | ||
|
|
4b9916341b | ||
|
|
d253c2b98d | ||
|
|
68851fe3d7 |
@@ -37,15 +37,19 @@ Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mj
|
||||
- `lib/ir/` — Intermediate Representation definition + serializers. Governed by ADR 0003.
|
||||
- `lib/cache/` — content-addressed cache layer (per-key isolation, `cache_control` bypass, chunked stream replay, singleflight). Governed by ADR 0005.
|
||||
- `lib/fallback/` — fallback engine (trigger detection, chain advancement, idempotent-failure safety, header annotation). Governed by ADR 0004.
|
||||
- `lib/keys.mjs` — multi-key auth, per-key namespacing, audit log. Carries OCP's per-key isolation model into OLP. **📋 Planned (Phase 2) — not yet authored.**
|
||||
- `dashboard.html` — owner-only multi-provider dashboard (quota panels, fallback rate, cache hit rate). **📋 Planned (Phase 6) — not yet authored.**
|
||||
- `lib/keys.mjs` — multi-key auth, per-key namespacing, identity layer. Carries OCP's per-key isolation model into OLP. **✅ Phase 2 — D44 core + D45 server integration + D46 owner gating shipped (validateKey on every /v1/* + /health; chain filtered by providers_enabled; touchLastUsed fires post-response; /health payload trimmed for non-owner; X-OLP-Fallback-Detail gated by fallback_detail_header_policy).**
|
||||
- `bin/olp-keys.mjs` — keygen CLI bootstrap surface per ADR 0007 § 9.1. **✅ Shipped at D47.** Subcommands: `keygen [--owner|--name=X|--providers=csv|--force]`, `list [--owner-only|--include-revoked]`, `revoke --id=X`. Plaintext token printed once on keygen. Installed via `package.json bin` so `npx olp-keys ...` works (also `npm run olp-keys ...`).
|
||||
- `lib/audit.mjs` — append-only ndjson audit per ADR 0007 § 6.2 + § 8 + daily rotation per ADR 0008 § 5. **✅ D45 (append) + D52 (rotation) shipped. `appendAuditEvent` fires per /v1/chat/completions + /v1/models + /v0/management/* request (warn + 1 retry; no memory buffer). `_maybeRotateAudit` (sync) is called BEFORE the append when the UTC date changes; renames live → `audit-YYYY-MM-DD.ndjson`. Optional external cron tool `bin/olp-audit-rotate.mjs` for exact-at-midnight rotation.**
|
||||
- `bin/olp-audit-rotate.mjs` — external audit rotation cron tool per ADR 0008 § 5.2. **✅ D52 — `runCli(argv, { out, err })` invocable + main-guard for direct execution. Installed via `package.json bin` so `npx olp-audit-rotate` works (also `npm run olp-audit-rotate`). Idempotent + safe alongside in-server first-append trigger.**
|
||||
- `lib/audit-query.mjs` — audit ndjson aggregate query layer per ADR 0008 § 4. **🟡 D49 — discoverAuditFiles + readAuditWindow + aggregateRequests + topFallbackChains + spendTrendDaily + cacheHitRateWindow shipped. Cross-file walk over `audit.ndjson` (live) + `audit-YYYY-MM-DD.ndjson` (rotated). PII guard: aggregate shapes never include message content. In-memory scan per request (ADR 0008 Lane 2 = A; SQLite hybrid deferred to ADR 0007 § 13 trigger).**
|
||||
- `dashboard.html` — owner-only multi-provider dashboard (4 panels: per-provider quota / 24h request+cache+fallback / 30d spend trend SVG sparkline / top-10 fallback chains). **✅ D51 — full UI shipped at repo root per ADR 0008 § 6. Vanilla HTML + JS + fetch (no build step, no framework, no CDN). 30s page poll with `document.visibilityState` pause/resume. Served by `/dashboard` route in server.mjs owner-only_block. Cached in memory at first request via `_loadDashboardHtml`.**
|
||||
- `models-registry.json` — single source of truth for `(provider, model) → metadata`. SPOT.
|
||||
- `ALIGNMENT.md` — the constitution. Binding for any plugin / entry-surface / IR change.
|
||||
- `docs/adr/` — Architecture Decision Records. Read the index in `docs/adr/README.md` before proposing governance, SPOT, or contract changes.
|
||||
- `.github/workflows/alignment.yml` — CI blacklist grep + per-provider citation soft check; fails the build on known-hallucinated tokens.
|
||||
- `CLAUDE.md` — Claude-Code-specific session instructions + `release_kit` overlay (Iron Rule 5.5).
|
||||
|
||||
**Implementation status note (as of 2026-05-24):** Files marked 📋 above are designed and documented but not yet on disk. For the full status table see `README.md § "Implementation status"`. Do not attempt to read or import these files — they will not be found. The shipped set as of Phase 1 is: `server.mjs`, `lib/ir/`, `lib/providers/{anthropic,codex,mistral}.mjs`, `lib/cache/{keys,store}.mjs`, `lib/fallback/engine.mjs`, `models-registry.json`, `test-features.mjs`.
|
||||
**Implementation status note (as of 2026-05-25):** Files marked 📋 above are designed and documented but not yet on disk; files marked 🟡 are partially shipped; files marked ✅ are Phase 2 deliverables. The shipped set as of D47 is: `server.mjs` (with Phase 2 auth middleware + audit wire + owner-vs-non-owner gating), `lib/ir/`, `lib/providers/{anthropic,codex,mistral}.mjs`, `lib/cache/{keys,store}.mjs`, `lib/fallback/engine.mjs`, `lib/keys.mjs` (core + loadAuthConfigSync — D44 + D45), `lib/audit.mjs` (D45), `bin/olp-keys.mjs` (D47), `models-registry.json`, `test-features.mjs` (Suites 19–22). Phase 2 functional scope is complete; remaining is Phase 2 close → v0.2.0 (maintainer-triggered, explicit per CLAUDE.md `release_kit.phase_close_trigger`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -124,6 +124,8 @@ OLP distinguishes **Candidate Providers** (declared in this constitution as inte
|
||||
|
||||
The v0.1 founding commit ships **zero Enabled Providers**. This is intentional: a constitution that names a provider as "default-enabled" while its CLI version, output shape, auth artifact, and exit-code semantics are still TBD violates Rules 1 (Cite First) and 3 (Match the Implementation). Enablement is a Phase audit deliverable, not a bootstrap claim.
|
||||
|
||||
**Note on phase terminology.** "Phase" in the tables and audit triggers below (and in § One-shot Triggered Audits → "OpenAI Codex ToS formal pin") refers to the **original per-plugin enablement plan** captured at project founding (one Tier-D plugin enabled per phase). The milestone phase numbering in [`README.md` § Phase plan](./README.md#phase-plan) was re-aligned at v0.1.1 close (D43-A, 2026-05-25) to reflect actually-shipped bundling — Phase 1 shipped all three Tier-D plugins + cache + fallback together as a single milestone, and Phase 2 became multi-key auth per ADR 0007. The two numberings are orthogonal: ALIGNMENT.md tracks **per-plugin enablement maturity**; README tracks **milestone release scope**.
|
||||
|
||||
### Enabled Providers
|
||||
|
||||
| Provider key | Tier | Default state | Authority pin | Inclusion source |
|
||||
|
||||
+440
-1
@@ -4,7 +4,446 @@ All notable changes to OLP land here. Per `CLAUDE.md` release_kit overlay, this
|
||||
|
||||
## Unreleased
|
||||
|
||||
(empty — Phase 2 entries land here once Phase 2 opens)
|
||||
(empty — Phase 4 entries land here once Phase 4 opens)
|
||||
|
||||
## v0.3.2 — 2026-05-25
|
||||
|
||||
### Post-Phase-3 cleanup batch #2 — streaming-path singleflight + TOCTOU close (D57 + D58 + D59)
|
||||
|
||||
Patch release closing v1.x roadmap #1 end-to-end. The cache layer's D4 singleflight (one spawn per identical concurrent request) was fully wired on the buffered path since v0.1 but NOT on the streaming path — N concurrent identical streaming requests each spawned their own CLI process. v0.3.2 ships the streaming sibling: tee fan-out, late-joiner replay, per-client backpressure, AbortController propagation, and TOCTOU close. 3 D-day commits (D57 + D58 + D59); ADR 0005 Amendment 8 §§1–14 implemented.
|
||||
|
||||
- **D57** (PR #36) — **cache layer.** New `cacheStore.getOrComputeStreaming(keyId, cacheKey, sourceFactory, opts) → { stream, isFirst, role }` mirroring `getOrCompute` on the streaming side. Internals: `_streamingInflight: Map<compositeKey, StreamingInflightEntry>` (composite key `keyId + '\0' + cacheKey`) with synchronous check+insert atomicity (closes TOCTOU per ADR 0005 Amendment 8 §1, §6); single-reader tee fan-out across all attached clients; late-joiner replay buffer (synchronous drain on attach; `STREAM_BACKPRESSURE` terminator if drain or replay-truncation would corrupt); per-client backpressure (`PER_CLIENT_QUEUE_CAP = 1 MB`, overridable via opts); accumulated replay cap (`ACCUMULATED_REPLAY_CAP = 10 MB`, mirrors D23 cache-entry cap); AbortController fires source-iterator return when all clients disconnect. New `'STREAM_BACKPRESSURE'` entry in `PROVIDER_ERROR_CODES` — NOT a hard trigger (whitelist-only `HARD_TRIGGER_CODES`). Suite 27 = 12 unit tests.
|
||||
- **D58** (PR #37) — **server wiring.** Streaming branch in `server.mjs` swapped from the peek+spawn pattern to `cacheStore.getOrComputeStreaming(...)`. `tryAcquireSpawn`/`releaseSpawn` moved INSIDE the `sourceFactory` closure per ADR 0005 Amendment 8 §7 (only the first caller acquires; attached joiners share the slot; release fires exactly once on source completion/error/abort). `CONCURRENCY_LIMIT` thrown by the factory triggers fallthrough to the buffered path (preserves today's behaviour). New `X-OLP-Streaming-Inflight: source | attached` HTTP header annotates per-response role (§11). New `cache_status: 'streaming_attached'` audit value tracks the singleflight win. `lib/audit-query.mjs` aggregate APIs (`aggregateRequests`, `cacheHitRateWindow`) extended with `cache_streaming_attached` / `streaming_attached` fields so the cache_status breakdown reconciles. `res.on('close')` propagates client disconnect into the tee's `attachedClients` accounting (§9). D16 truncated-not-cached invariant preserved via server-layer `cacheStore.delete` on stop-less exhaustion (the cache layer is IR-agnostic and writes accumulatedChunks on any source exhaustion; the IR-aware server deletes the entry when the source returned without a `{type:'stop'}` chunk). Suite 28 = 8 HTTP integration tests.
|
||||
- **D59** (PR #38) — **docs polish.** README § Known limitations bullet inverted to ✅ shipped marker. `docs/v1x-roadmap.md` #1 rewritten to closed state with 3-D-day breakdown. #6 (streaming SPAWN_FAILED salvage) unbundled from #1 because the tee architecture as implemented does not carry salvage semantics. Issue #16 closed with refs to PRs #36 / #37 / #38.
|
||||
- **Test count:** 603 (v0.3.1) → 623 (v0.3.2). +20 streaming-SF tests (Suite 27 = 12 unit, Suite 28 = 8 HTTP integration).
|
||||
- **Deferred sub-items (not blocking #1 closure):** (a) `X-OLP-Streaming-Inflight: solo` wire value not emitted — observable only post-stream via `streaming_inflight_source_done` log event's `attached_count: 0`. Future ADR amendment may expose via HTTP trailer. (b) `streaming_inflight_join` log event not emitted from the cache-layer `_attachClient` path because provider/model context lives in the sourceFactory closure (server-layer concern). (c) `isFirst` field returned by `getOrComputeStreaming` is unused by server.mjs (`role` supersedes); could be removed in a future cache-layer API cleanup.
|
||||
- **Authority:** ADR 0005 Amendment 8 (design ratified at D42 2026-05-25; implementation gated on maintainer "go" — fired 2026-05-25 post-v0.3.1). `docs/v1x-roadmap.md` #1 (closed). GitHub issue #16 (closed). ADR 0002 Amendment 6 (D38 `tryAcquireSpawn`/`releaseSpawn` semantics, now invoked from sourceFactory closure).
|
||||
|
||||
**Patch-release classification.** Per `release_kit.phase_rolling_mode` cross-Phase discipline + maintainer release-cut decision (this session, 2026-05-25): the new wire surface (`X-OLP-Streaming-Inflight` header + `streaming_attached` cache_status) is semver-wise a minor bump, but this is roadmap-cleanup work — NOT Phase 4 product scope. The reserved `0.4.0` identifier stays for the formal Phase 4 close. v0.3.2 ships as a patch under the Phase 4 pre-release banner. Tag push triggers `release.yml`.
|
||||
|
||||
## v0.3.1 — 2026-05-25
|
||||
|
||||
### Post-Phase-3 cleanup batch #1 (D56)
|
||||
|
||||
Patch release closing two XS v1.x-roadmap deferrals (`docs/v1x-roadmap.md` #4 + #7) that became actionable now that Phase 3 management endpoints exist. No new feature surface; pins existing behaviour into tests + finally wires the ADR-documented `activeSpawns` field on `/health`.
|
||||
|
||||
- **AUTH_MISSING tuple test** (v1.x roadmap #7 / D45 reviewer P3 deferral). New engine-level test in Suite D40 asserts that an `AUTH_MISSING` hop produces a `fallbackDetail` tuple with `trigger_type: 'auth_missing'` AND that the engine does NOT advance past the AUTH_MISSING hop (per ADR 0004 § Decision — `HARD_TRIGGER_CODES[AUTH_MISSING] = false`). Pre-D56 the behaviour was implicit through other engine-path tests; this commit makes it explicit so a future refactor that moves the tuple-push past the auth_missing branch fails this test directly.
|
||||
- **`/health` `activeSpawns` integration** (v1.x roadmap #4 / ADR 0002 Amendment 6 forward note). `handleHealth` now surfaces `providers.status.<name>.activeSpawns` (sourced from D38 `getActiveSpawnCount(name)`). The field is computed BEFORE `healthCheck()` is awaited so it remains present even when `healthCheck()` throws (cheap in-memory counter read). New Suite 21c-extra test pins the field presence + non-negative value for every enabled provider. With no requests in flight: 0; under saturation: equals `hints.maxConcurrent`.
|
||||
- **Test count:** 601 (v0.3.0) → 603 (v0.3.1). +2 D56 tests.
|
||||
- **Authority:** `docs/v1x-roadmap.md` #4 + #7; ADR 0002 Amendment 6 (concurrency observability forward note); ADR 0004 § Decision + Amendment 5 (X-OLP-Fallback-Detail tuple shape).
|
||||
|
||||
**Patch-release classification.** Per `release_kit.phase_rolling_mode` cross-Phase discipline: D56 landed on main after v0.3.0 was tagged, so this is a hotfix-class patch — bump patch, tag, release before next push. Tag push triggers `release.yml`.
|
||||
|
||||
## v0.3.0 — 2026-05-25
|
||||
|
||||
### Phase 3 — Dashboard + audit query layer + daily audit rotation (D48 → D54)
|
||||
|
||||
**Overview.** v0.3.0 closes Phase 3 — the dashboard / audit aggregate query / daily rotation track that grew OLP from "audit ndjson exists but is grep-only" (v0.2.0) to a live multi-panel owner-only dashboard with aggregate queries + automatic daily file rotation. 7 D-day commits (D48 through D54) shipped between 2026-05-25 under the standing-autopilot grant. All 15 ADR 0008 § 10 acceptance criteria are implemented + tested.
|
||||
|
||||
**Test count: 544 (v0.2.0) → 601 (v0.3.0).** +57 tests across the Phase 3 arc.
|
||||
|
||||
**Phase 3 release_kit checklist**
|
||||
|
||||
- [x] All 7 D-day deliverables landed on main (D48 ADR + D49-D54 implementation)
|
||||
- [x] CI green on every D-day merge commit + on this release commit's head
|
||||
- [x] Fresh-context opus reviewer on every implementation D-day (D49/D50/D51/D52/D53) + D48 ADR draft + D54 docs polish
|
||||
- [x] All 15 ADR 0008 § 10 acceptance criteria (#1–#15) covered by Suite 23/24/25/26/20h-extra-audit tests
|
||||
- [x] CHANGELOG "Unreleased" promoted to "## v0.3.0 — 2026-05-25" with D48 through D54 entries
|
||||
- [x] `package.json` bumped 0.2.0 → 0.3.0
|
||||
- [x] `CLAUDE.md release_kit.phase_rolling_mode`: `current_phase` Phase 3 → Phase 4; `current_pre_release_identifier` `0.3.0-phase3` → `0.4.0-phase4`
|
||||
- [x] README status header + Implementation Status + Phase plan reflect Phase 3 shipped
|
||||
- [ ] Tag pushed (next step in this PR's lifecycle)
|
||||
- [ ] `release.yml` triggered + GitHub Release created (auto on tag push; D37 phase_rolling_mode gate will pass because Unreleased is now sentinel-only)
|
||||
|
||||
**ADR 0008 § 10 acceptance criteria — final ship status**
|
||||
|
||||
| # | Criterion | Covering tests |
|
||||
|---|---|---|
|
||||
| 1 | `readAuditWindow` iterates events from today + N prior rotated files | Suite 23b-1, 23b-2, 23b-3 |
|
||||
| 2 | `readAuditWindow` skips malformed lines without throwing + logs warn | Suite 23b-6 |
|
||||
| 3 | `aggregateRequests` counts by provider / cache_status / owner_tier / path + median/p95 latency | Suite 23c-1, 23c-2, 23c-3 |
|
||||
| 4 | `topFallbackChains` sort desc by count + tied-count tiebreak | Suite 23d-1, 23d-4 |
|
||||
| 5 | `spendTrendDaily` sparse-fills zero-request days + UTC day boundaries | Suite 23e-1, 23e-2, 23e-3 |
|
||||
| 6 | Daily rotation past UTC midnight | Suite 26a-3, 26b-1 |
|
||||
| 7 | Cross-file query with mixed rotated files | Suite 26e-1 + Suite 23b-1 |
|
||||
| 8 | Concurrent rotation safety (N appends → 1 rename) | Suite 26c-1 |
|
||||
| 9 | `GET /dashboard` 200 to owner; 401 to non-owner | Suite 24a, 24b, 24c, 24d |
|
||||
| 10 | `GET /v0/management/dashboard-data` 200 to owner with all required fields | Suite 24e |
|
||||
| 11 | `GET /cache/stats` 200 to owner with live stats | Suite 24h |
|
||||
| 12 | Dashboard HTML smoke (4 panel containers + 30s poll + no external resources) | Suite 25a-25f |
|
||||
| 13 | Audit row on management endpoints (success + 401) | Suite 24i, 24j |
|
||||
| 14 | Graceful degradation on `quotaStatus()` throw (panel surfaces null + error) | server.mjs `handleManagementDashboardData` try/catch verified by code |
|
||||
| 15 | PII guard — no message-content fields in any aggregate output | Suite 23g-1, 23g-2, 23g-3 |
|
||||
|
||||
**Phase 3 D-day index**
|
||||
|
||||
- **D48** (`c0b6969`) — ADR 0008 Phase 3 design draft (Dashboard + audit query layer) + lane decisions A/A/B/A/B
|
||||
- **D49** (`686794e`) — `lib/audit-query.mjs` aggregate query layer (5 functions, PII-guarded)
|
||||
- **D50** (`f9f2eaa`) — `server.mjs` 4 management endpoints (owner_only_block per ADR 0008 § 8) + dashboard.html placeholder
|
||||
- **D51** (`251b578`) — `dashboard.html` full multi-panel UI (vanilla HTML+JS+fetch, 30s poll with visibilitychange pause)
|
||||
- **D52** (`408d5a8`) — Daily audit rotation in `lib/audit.mjs` (synchronous trigger on first append after UTC midnight) + `bin/olp-audit-rotate.mjs` external cron tool
|
||||
- **D53** (`68e50da`) — `tried_providers` schema semantic fix (D45 P2 deferral closed; ADR 0007 § 8 amendment)
|
||||
- **D54** (`6d9ab1f`) — README Phase 3 polish (docs-only)
|
||||
|
||||
**Bonus: also resolved at D53** — D45 fresh-context opus reviewer P2 deferral (`tried_providers` semantics on `key_no_provider_access` 403). ADR 0007 § 8 amended; server.mjs sets `tried_providers = []` on the 403 path so downstream audit queries stay accurate.
|
||||
|
||||
**Known limitations carried beyond v0.3.0**
|
||||
|
||||
Phase 3 functional scope is complete. The following remain as Phase 4+ deferrals (tracked in `docs/v1x-roadmap.md` + the new Phase 4 entry below):
|
||||
|
||||
- **Per-key per-provider auth artifact mapping** — ADR 0007 § 12. Each OLP key independently authenticated to a different provider account.
|
||||
- **Audit query rotation / retention policies** — ADR 0008 § 11. Currently unbounded; operator manages disk. A Phase 4+ amendment adds `audit_max_days` config when an operational need emerges.
|
||||
- **SQLite hybrid migration** — ADR 0007 § 13. Trigger: query latency > 2s on typical owner session OR > 5 owners polling. Requires engines bump + CI matrix change as a separate prior PR.
|
||||
- **Provider-cost weights for spend trend** — ADR 0008 § 11. At v0.3.0 "spend" is proxied by request count; cost integration when commercial cost-tracking lands.
|
||||
- **Per-key dashboard views** — owner sees aggregate; per-key drill-down is a future amendment.
|
||||
- **Key-mgmt UI on dashboard** — owner can create / revoke / edit keys from web. Out of Phase 3 scope; needs separate security review per ADR 0008 § 11.
|
||||
- **Manual smoke for dashboard** — per ADR 0008 § 10 #12 the "no JS console errors in real browser" sub-claim is manual / playwright; Phase 3 acceptance shipped with server-observable checks (Suite 25); a Phase 4+ amendment may add playwright smoke if dashboard complexity grows.
|
||||
|
||||
### D54 — README Phase 3 polish (docs-only, no code change)
|
||||
|
||||
Seventh Phase 3 D-day. Documentation polish ahead of Phase 3 close (D55, maintainer-triggered). Brings README status header / Implementation Status / API Endpoints / Known limitations / Phase plan up to date with Phase 3 work shipped to main through D48-D53.
|
||||
|
||||
- **Status header**: `v0.2.0 shipped` → `v0.2.0 shipped; v0.3.0 in progress` + lists D48-D54 highlights.
|
||||
- **Implementation status note**: Phase 3 description updated from "next milestone" to "shipped to main through D54; v0.3.0 release pending maintainer-triggered close (D55)".
|
||||
- **Implementation Status table** — 4 row updates:
|
||||
- `lib/audit.mjs`: 🟡 D45-only → ✅ D45 append + D52 rotation; describes both responsibilities.
|
||||
- `lib/audit-query.mjs`: NEW row (D49 shipped, 5-function aggregate query API).
|
||||
- `dashboard.html`: 📋 Planned (Phase 6) → ✅ Phase 3 shipped (D50 stub + D51 full UI); describes the 4 panels.
|
||||
- `bin/olp-audit-rotate.mjs`: NEW row (D52 shipped, external cron tool).
|
||||
- **API Endpoints table** — `/cache/stats`, `/v0/management/quota`, `/dashboard` (Phase 6 📋 Planned → Phase 3 ✅ Shipped); new `/v0/management/dashboard-data` row; `/health` row clarified to spell out owner-only-trim semantic. Removed the "placeholder — full table lands" stub since the table is now substantively complete.
|
||||
- **Known limitations** — Phase 2 paragraph kept (now reads as historical Phase 2 completion note); new Phase 3 paragraph summarizing D48-D54 shipped + D55 close pending.
|
||||
- **Phase plan** — Phase 3 description (was "next") → "🟡 In progress — D48 (ADR) + D49–D54 shipped to main 2026-05-25; v0.3.0 close awaits maintainer trigger." Added Phase 4+ entry covering the deferred items (per-key per-provider auth, SQLite hybrid, audit rotation/retention policies, provider-cost weights).
|
||||
- **Test count:** 601 → 601 (docs-only).
|
||||
- **Authority:** CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; ADR 0008 § 13 sprint shape (D54 = "E2E + AGENTS / README polish"); standing autopilot grant.
|
||||
|
||||
### D53 — `tried_providers` schema semantic fix (D45 P2 deferral closed)
|
||||
|
||||
Sixth Phase 3 D-day. Small focused fix for the D45 fresh-context opus reviewer P2 finding that was deferred: `auditCtx.tried_providers` on the `key_no_provider_access` 403 path was being stamped with the ORIGINAL chain (which was filtered out, never dispatched), distorting downstream audit queries like "which providers did key X actually call".
|
||||
|
||||
- **`server.mjs` 403 path fix** (around L815): `auditCtx.tried_providers = []` (was `_originalChainProviders`). The configured-but-blocked chain still appears in the human-readable error message body — the audit just doesn't claim those providers were "tried" when the server's filter dispatched zero.
|
||||
- **ADR 0007 § 8 amendment**: new paragraph spelling out the `tried_providers` semantic — "the list of providers the server actually dispatched a spawn against. A provider that was configured in the chain but filtered out by `providers_enabled` gating is NOT included — the key didn't try the provider, the gate did. On the 403 path `tried_providers` is the empty array." Plus a forward note that audit log rotation moved to Phase 3 / ADR 0008 § 5.
|
||||
- **Suite 20h-extra-audit (+1 test — 600 → 601):** creates a guest key with `providers_enabled: ['mistral']`; fires a request for an Anthropic-routed model; asserts 403 `key_no_provider_access`; reads the audit row from `audit.ndjson`; asserts `tried_providers === []`. This pins the D53 semantic against regression — if a future change reverts to stamping the original chain, the test fails.
|
||||
- **Documentation:** CHANGELOG D53 entry; ADR 0007 § 8 amendment.
|
||||
- **Test count:** 600 → 601 (+1 D53 regression test).
|
||||
- **Authority:** ADR 0007 § 8 amendment (D53, 2026-05-25); D45 fresh-context opus reviewer P2 deferral note; CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant.
|
||||
|
||||
### D52 — Daily audit rotation (`lib/audit.mjs` extension + `bin/olp-audit-rotate.mjs`)
|
||||
|
||||
Fifth Phase 3 D-day. Adds daily UTC-aware rotation to `lib/audit.mjs` per ADR 0008 § 5 + ships an external cron tool. Rotation is **synchronous** at v0.3.0 (Lane 3 = B daily rotation; synchronous design eliminates the race that an async wrapper would create between date-change-detection and the append).
|
||||
|
||||
- **`lib/audit.mjs` extended**:
|
||||
- New `_maybeRotateAudit({ olpHome, logEvent })` (synchronous): probes the live `audit.ndjson`; if it holds events from a past UTC date, renames it to `audit-YYYY-MM-DD.ndjson`. Idempotent. If the target file already exists (cron beat the in-server check), logs warn + skips per ADR 0008 § 5.3 race safety.
|
||||
- `appendAuditEvent` extended: cheap fast-path date check via module-cached `_lastSeenUtcDate`. On date change, calls `_maybeRotateAudit` synchronously BEFORE `appendFileSync` — so old-date events land in the rotated file and new-date events land in the fresh live file. No event straddles the boundary.
|
||||
- Why synchronous instead of async: an async wrapper would let the sync `appendFileSync` race the not-yet-completed `renameSync`, landing today's event in the about-to-be-renamed file. Sync rotation is the only correct ordering at the append-fired-from-many-routes scale OLP runs.
|
||||
- New exports: `_maybeRotateAudit` (sync), `getAuditRotateCount`, `getAuditRotateFailCount`, `__resetAuditRotateState`, `__setLastSeenUtcDateForTesting`.
|
||||
- First-event-date discovery: when probing the live file's date, reads only the first ndjson line + parses its `ts`. Falls back to file mtime if events absent (corrupt/empty edge).
|
||||
- **`bin/olp-audit-rotate.mjs`** (~95 lines): external cron tool per ADR 0008 § 5.2. Calls `_maybeRotateAudit` once + reports outcome. Exit codes 0 (success or no-op), 1 (bad usage), 2 (rotation failed). Installed via `package.json bin` so `npx olp-audit-rotate [--olp-home=<path>]` works. Example cron line documented in the file header.
|
||||
- **Concurrent-safety semantics** (ADR 0008 § 5.3): in-process sequential appends after the first date-change detection short-circuit via the updated `_lastSeenUtcDate` cache → exactly 1 rename even under N sequential appends. Cross-process (cron + server) coexistence handled by the "target already exists → skip + warn" branch.
|
||||
- **Test surface (Suite 26, +12 tests — 588 → 600):**
|
||||
- 26a-1..5: `_maybeRotateAudit` (no live file / today already / yesterday→rotate / idempotent re-call / cron-race target-exists warn)
|
||||
- 26b-1: `appendAuditEvent` past UTC date change triggers sync rotation + append lands in fresh live file
|
||||
- 26c-1: 10 sequential `appendAuditEvent` across date change → exactly 1 rotation + all 10 events in new live file
|
||||
- 26d-1..4: `bin/olp-audit-rotate.mjs` CLI (--help / no-live-file / yesterday-file-rotates / unknown-flag exit 1)
|
||||
- 26e-1: rotated files queryable via `lib/audit-query.mjs` `discoverAuditFiles` + `readAuditWindow` cross-file read
|
||||
- **`package.json`**: `bin.olp-audit-rotate` + `scripts.olp-audit-rotate` entries added.
|
||||
- **Documentation:** AGENTS.md `lib/audit.mjs` marker promoted to ✅ (D45 append + D52 rotation both shipped); new `bin/olp-audit-rotate.mjs` entry.
|
||||
- **Test count:** 588 → 600 (+12 D52 tests in Suite 26).
|
||||
- **Authority:** ADR 0008 § 5.1 (first-append-after-UTC-midnight trigger), § 5.2 (external cron alternative), § 5.3 (concurrent-rotation safety + cron-coexistence semantics), § 5.4 (renamed-file query path consumed by D49 lib/audit-query.mjs); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant.
|
||||
|
||||
### D51 — `dashboard.html` full multi-panel UI (Phase 3)
|
||||
|
||||
Fourth Phase 3 D-day. Replaces the D50 `dashboard.html` placeholder with the full 4-panel UI per ADR 0008 § 6. Vanilla HTML + JS + fetch — no build step, no framework, no CDN (Lane 1 = A). 30s page poll with `document.visibilityState` pause/resume (Lane 4 = A).
|
||||
|
||||
- **4 panels rendered from `/v0/management/dashboard-data`** (the single backing endpoint, per Lane 2 in-memory query model):
|
||||
- **Panel 1 — Per-provider quota**: table of `{ Provider | Available | Status }`; surfaces `null` available as "n/a" + capturing per-provider `provider.quotaStatus()` errors as a red status pill (graceful degradation per ADR § 9).
|
||||
- **Panel 2 — Last 24h: request count + cache hit + fallback rate**: per-provider row of `{ Requests | Cache hit % | Fallback rate % }`. Cache hit sourced from `cache_hit_24h.by_provider[p].hit_rate`; fallback rate computed from `window_24h.by_provider[p].fallback_count / count`.
|
||||
- **Panel 3 — Request count last 30 days (SVG sparkline)**: vanilla SVG bar chart with `<title>` tooltips showing per-day per-provider breakdown. Y-axis: requests per day (scaled to max); X-axis: 30 daily buckets (UTC). Each bar `<title>` includes the date + total count + provider breakdown.
|
||||
- **Panel 4 — Top fallback chains (last 24h)**: numbered table of `{ # | Chain | Count | First seen | Last seen }` with chain arrows rendered in monospace (`anthropic → openai`).
|
||||
- **30s poll + visibilitychange pause** (ADR 0008 § 6.5):
|
||||
- `setInterval(refresh, 30000)` after the initial fetch.
|
||||
- `document.addEventListener('visibilitychange', ...)` → `stopPolling()` on hidden / `refresh() + startPolling()` on visible.
|
||||
- Per ADR § 6.5 this prevents 2880 background polls/day per owner when the dashboard tab is in the background.
|
||||
- **Error handling**:
|
||||
- 401 from `/v0/management/dashboard-data` → in-page error banner explains owner-tier requirement + suggests SSH-tunnel + header-injection workaround (browsers can't natively send `Authorization: Bearer` without a proxy/extension).
|
||||
- Other HTTP errors → generic "HTTP <code>" banner; console.warn for operator debugging.
|
||||
- Per-panel "Loading…" / "No requests in window." / "No fallback chains triggered" empty states.
|
||||
- **DOM helpers**: small `el(tag, attrs, ...children)` + `svgEl(tag, attrs)` factories — no framework, ~10 lines each. Sparkline uses native `<title>` for tooltips (no JS hover handlers).
|
||||
- **Critical correctness invariants** (per ADR 0008 § 6 + Lane 1 = A):
|
||||
- No `<script src>` — entire JS inline in `<script>` tag (Suite 25d asserts).
|
||||
- No `<link rel="stylesheet" href=>` — all CSS in `<style>` tag (Suite 25d asserts).
|
||||
- Only one backing endpoint hit: `/v0/management/dashboard-data` (Suite 25e asserts). All 4 panels consume slices of its response.
|
||||
- 401 path keeps panels in last-good state rather than clearing them; operator sees the error banner + can debug.
|
||||
- **Test surface (Suite 25, +6 tests — 582 → 588):**
|
||||
- 25a: owner /dashboard response contains all 4 panel container IDs (`panel-quota`, `panel-24h`, `panel-trend`, `panel-chains`).
|
||||
- 25b: dashboard JS declares `POLL_INTERVAL_MS = 30000` + uses `setInterval` + `clearInterval`.
|
||||
- 25c: visibilitychange listener wired + checks `document.visibilityState === 'hidden'`.
|
||||
- 25d: NO external `<script src>` and NO external stylesheet `<link href>` — pinning Lane 1 = A.
|
||||
- 25e: dashboard JS fetches `/v0/management/dashboard-data` (the single consolidated D50 endpoint).
|
||||
- 25f: 401 in-page error banner mentions owner-tier so a maintainer who lands on a 401 knows the route forward.
|
||||
- **Manual smoke (ADR 0008 § 10 #12 manual acceptance)**: the dashboard renders without console errors in a real browser when served by a running OLP instance + owner-tier Bearer token injected via SSH-tunnel + header-injection extension. Not automated at Phase 3 (Lane 4 = A poll model doesn't need playwright; Phase 4+ may add a playwright smoke if dashboard complexity grows).
|
||||
- **Documentation:** AGENTS.md `dashboard.html` marker promoted from 🟡 D50 placeholder to ✅ D51 full UI.
|
||||
- **Test count:** 582 → 588 (+6 D51 tests in Suite 25).
|
||||
- **Authority:** ADR 0008 § 6 (panels + refresh + localhost) + § 6.5 (poll + visibilityState pause) + Lane 1 = A (no build step) + Lane 4 = A (30s poll) + Lane 5 = B (full 4-panel scope); ADR § 9 (graceful degradation surfaced in Panel 1); ADR § 10 criterion #12 (HTML smoke); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant.
|
||||
|
||||
### D50 — `server.mjs` management endpoints (Phase 3 dashboard wire-up)
|
||||
|
||||
Third Phase 3 D-day. Wires the D49 `lib/audit-query.mjs` aggregate query layer into 4 owner_only_block HTTP endpoints per ADR 0008 §§ 7-8. Ships a placeholder `dashboard.html` at repo root (D51 lands the full multi-panel UI). All endpoints follow the Phase 2 / D45 auth + audit + touchLastUsed pattern.
|
||||
|
||||
- **4 new endpoints** (all owner_only_block per ADR 0008 § 8 — anonymous + guest + missing-key all → 401):
|
||||
- `GET /dashboard` — serves `dashboard.html` (Content-Type text/html; charset=utf-8). D50 stub explains the state + lists backing endpoints; D51 replaces with full UI.
|
||||
- `GET /v0/management/dashboard-data` — full aggregate per ADR 0008 § 7.2: `{ generated_at, window_24h (auditAggregateRequests), cache_hit_24h (auditCacheHitRateWindow), quota (per-provider provider.quotaStatus + error capture), spend_trend_30d (auditSpendTrendDaily — exactly 30 entries), top_fallback_chains_24h (auditTopFallbackChains limit 10), cache_stats (live cacheStore.stats()) }`.
|
||||
- `GET /v0/management/quota` — quota subset only (subset of dashboard-data; useful for scripted monitoring).
|
||||
- `GET /cache/stats` — live in-memory `cacheStore.stats()` shape (`{ hits, misses, size, inflightCount }` + `generated_at` wrapper).
|
||||
- **`_runOwnerOnlyManagementEndpoint(req, res, method, path, inner)` helper** factors the common auth + audit ctx + owner-block + res.on('finish') wire. inner is async (req, res, olpIdentity, auditCtx) → returns void. Eliminates 4× boilerplate.
|
||||
- **`owner_only_block` mode** (ADR 0008 § 8): authenticate → if not owner → 401 `owner_required`. Distinct from `owner_only_trim` (Phase 2 /health pattern). Anonymous identity (when `allow_anonymous: true`) reaches the handler and is 401'd by the owner check — verified by Suite 24c.
|
||||
- **Provider quotaStatus error capture**: dashboard-data + quota endpoints catch per-provider throws and surface `{ provider, error, available: null }` so one bad provider doesn't fail the whole panel (ADR 0008 § 9 graceful degradation).
|
||||
- **`dashboard.html` placeholder** (~50 lines at repo root): explains the D50 state, lists backing endpoints with curl example. Cached in memory at first /dashboard request (`_loadDashboardHtml` with module-scope `_dashboardHtmlCache`); falls back to an in-memory stub if the file is missing (e.g., test imports from non-repo cwd).
|
||||
- **Audit on management endpoints** (ADR 0008 § 7.5): every management request appends an audit row including 401 paths (verified by Suite 24j). Touch wire skips anonymous + env-owner identities (matches Phase 2 pattern).
|
||||
- **Router**: 4 new GET branches added between /v1/chat/completions and the 404 fallback.
|
||||
- **Test surface (Suite 24, +11 tests — 571 → 582):**
|
||||
- 24a-d: /dashboard owner_only_block (owner 200 / guest 401 / anonymous-with-allow_anonymous=true 401 / no-auth-with-allow_anonymous=false 401)
|
||||
- 24e: dashboard-data owner → 200 JSON with all required ADR § 7.2 fields (asserts `spend_trend_30d.length === 30`)
|
||||
- 24f: dashboard-data guest → 401 owner_required
|
||||
- 24g: quota owner → 200 JSON with quota array
|
||||
- 24h: cache/stats owner → 200 JSON with `{ hits, misses, size, inflightCount, generated_at }`
|
||||
- 24h-401: cache/stats guest → 401
|
||||
- 24i: successful dashboard-data appends audit row with `status_code: 200` + `key_id` + `path: '/v0/management/dashboard-data'`
|
||||
- 24j: 401 (guest blocked) dashboard-data appends audit row with `error_code: 'owner_required'` + `owner_tier: 'guest'`
|
||||
- **Documentation:** AGENTS.md `lib/audit-query.mjs` D49 marker note added + new `dashboard.html` entry (D50 placeholder).
|
||||
- **Test count:** 571 → 582 (+11 D50 tests in Suite 24).
|
||||
- **Authority:** ADR 0008 § 7 (endpoints) + § 8 (owner_only_block mode) + § 9 (graceful degradation) + § 7.5 (audit on management endpoints); ADR 0007 § 7 (auth model reused); ADR 0002 § Provider contract (quotaStatus); ADR 0005 (cacheStore.stats); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant.
|
||||
|
||||
### D49 — `lib/audit-query.mjs` audit aggregate query layer (Phase 3)
|
||||
|
||||
Second Phase 3 D-day. Implements ADR 0008 § 4 query API. Pure in-memory ndjson scan; cross-file walk over `audit.ndjson` (live) + `audit-YYYY-MM-DD.ndjson` (rotated). No server.mjs integration in this D-day (D50 wires the consuming endpoints).
|
||||
|
||||
- **New file `lib/audit-query.mjs`** (~370 lines): 5 public API functions per ADR 0008 § 4.1:
|
||||
- `discoverAuditFiles({ olpHome })` — filesystem scan; returns `Map<date|'live', path>`.
|
||||
- `readAuditWindow({ startMs, endMs, olpHome, logEvent })` — generator over events in half-open window [startMs, endMs). Walks rotated date files + live file. Skips malformed lines + logs warn.
|
||||
- `aggregateRequests({ windowMs, olpHome })` — counts + status buckets + by_provider + by_owner_tier + by_path + median/p95 latency over rolling window.
|
||||
- `topFallbackChains({ windowMs, limit, olpHome })` — top-N chains by trigger count from events with `fallback_hops > 0`. Tied-count tiebreak: ascending first_seen.
|
||||
- `spendTrendDaily({ days, olpHome })` — daily series ending today with sparse-fill for zero-request days. Per-day request_count + median latency + by_provider breakdown.
|
||||
- `cacheHitRateWindow({ windowMs, olpHome })` — audit-derived cache hit rate (bypass excluded from denominator); per-provider + overall.
|
||||
- **PII discipline** (ADR 0008 § 4.3): every aggregate function relays only schema fields; never message content. Suite 23g actively asserts the absence of `content`/`message`/`messages`/`prompt`/`response`/`body` keys in every aggregate output.
|
||||
- **Cross-file walk semantics** (ADR 0008 § 4.2): half-open window [startMs, endMs); date-range computed once from window bounds; each rotated date file checked; live `audit.ndjson` always checked (it covers today regardless of whether the window endpoint is past midnight).
|
||||
- **`spendTrendDaily` calendar-date semantics**: `days: N` returns "last N calendar UTC dates ending today" — NOT "events within a rolling N×86400-ms window" (which would span N+1 distinct UTC dates and produce off-by-one buckets at non-midnight call times). Computed via `for (let i = days-1; i >= 0; i--) dates.push(_utcDateFromMs(now - i*86400*1000));`.
|
||||
- **`cacheHitRateWindow` denominator**: hit_rate = hit / (hit + miss). Bypass is intentional non-cacheable (Anthropic cache_control marker), NOT a cache miss; excluding it from the denominator gives a clean cache-effectiveness signal.
|
||||
- **Test surface (Suite 23, +27 tests — 544 → 571):**
|
||||
- 23a-1..4: `discoverAuditFiles` (empty dir / live only / live+rotated / non-audit files ignored)
|
||||
- 23b-1..6: `readAuditWindow` (all-coverage / single-day / half-open exclusivity / empty window / missing files / malformed-skip with warn)
|
||||
- 23c-1..4: `aggregateRequests` (counts + status buckets + by_provider; by_owner_tier; median+p95 latency over realistic distribution; invalid windowMs rejection)
|
||||
- 23d-1..4: `topFallbackChains` (sort desc by count; limit truncation; fallback_hops=0 excluded; first_seen/last_seen carried)
|
||||
- 23e-1..3: `spendTrendDaily` (N-day range correctness; populated day breakdown; empty day sparse-fill)
|
||||
- 23f-1..3: `cacheHitRateWindow` (overall + per-provider hit_rate; bypass not in denominator; cache_status=null events excluded)
|
||||
- 23g-1..3: PII guard for `aggregateRequests` / `spendTrendDaily` / `topFallbackChains` + `cacheHitRateWindow` — every output JSON-stringified + scanned for forbidden PII keys
|
||||
- **Documentation:** AGENTS.md `lib/audit-query.mjs` new entry; `lib/audit.mjs` note added that D52 extends with daily rotation.
|
||||
- **Test count:** 544 → 571 (+27 D49 tests).
|
||||
- **Authority:** ADR 0008 § 4 (query API surface) + § 5 (rotation file naming pattern) + § 3 (storage layout); ADR 0007 § 8 (audit ndjson event schema — input data); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant.
|
||||
|
||||
### D48 — ADR 0008 Phase 3 design draft (Dashboard + audit query layer)
|
||||
|
||||
First Phase 3 D-day. Design-only. Ratifies the storage / query model / rotation / dashboard / refresh / scope decisions ahead of D49+ implementation D-days. Opens ADR 0007 § 12 deferral for Dashboard + audit query layer + rotation.
|
||||
|
||||
- **New file `docs/adr/0008-dashboard-and-audit-query.md`** (~390 lines): 13 sections + Consequences + Authority citations. Decisions per maintainer-pinned lanes:
|
||||
- Lane 1 (tech stack): static HTML + vanilla JS + fetch (no build step; matches OLP "no bundler" ethos)
|
||||
- Lane 2 (query model): in-memory scan of audit ndjson per request (defers SQLite hybrid per ADR 0007 § 13)
|
||||
- Lane 3 (rotation): daily rotation, `audit-YYYY-MM-DD.ndjson` on first append after UTC midnight + optional `bin/olp-audit-rotate.mjs` external cron
|
||||
- Lane 4 (refresh): 30s page poll (no SSE infra at v0.3.0)
|
||||
- Lane 5 (dashboard scope): full per spec § 4.6 — 4 panels (quota / per-provider 24h counts / 30d spend trend / top fallback chains)
|
||||
- **`docs/adr/README.md` index**: added ADR 0008 row with one-paragraph summary.
|
||||
- **CHANGELOG.md** Unreleased: this entry.
|
||||
- **Phase 3 sprint shape:** D49 `lib/audit-query.mjs` + Suite 23 → D50 `/v0/management/*` endpoints + Suite 24 → D51 `dashboard.html` → D52 daily audit rotation + Suite 25 → D53 `tried_providers` schema fix (D45 P2 deferral) → D54 E2E + docs → D55 Phase 3 close → v0.3.0 (maintainer-triggered).
|
||||
- **Fold-in (fresh-context opus reviewer findings — 1 P2 + 2 P3, all ADR-text polish):**
|
||||
- **P2 § 8 + § 10 #9 gating-mode wording** — original § 8 implied a new "block non-owner identities" behaviour without naming it; § 10 #9 tested only the universal `allow_anonymous: false` 401 case. Fix: § 8 now formalizes two gating modes — `owner_only_trim` (Phase 2 /health pattern) vs `owner_only_block` (new Phase 3 management-endpoints pattern) — and explains the management endpoints are `owner_only_block` because the entire payload is sensitive. § 10 #9 now covers both 401 paths (with `allow_anonymous: true` + no header → anonymous identity → still 401 because management endpoints are `owner_only_block`; AND with `allow_anonymous: false` + no header → 401 at the authenticate middleware itself).
|
||||
- **P3 `/cache/stats` citation accuracy** — original § 7.4 + Authority block cited "ADR 0005 § Cache stats" which is not a real section. Corrected: planning authority is OLP v0.1 spec § 4.6; ADR 0005 references the endpoint in `Consequences/Mitigations` (~line 279) for the per-`(provider, model)` cache-hit-rate breakdown surface.
|
||||
- **P3 `cacheStore.stats()` shape gap** — § 7.4 now explicitly acknowledges the current shape (`{ hits, misses, size, inflightCount }` global aggregate) lacks the per-`(provider, model)` breakdown spec § 4.6 implies; Phase 3 Panel 2 sources per-provider counts from `aggregateRequests` (audit-side) instead. If a future panel needs the breakdown, D50 amends the store shape + an ADR 0005 amendment fires at that time. Phase 3 acceptance criteria do not require the breakdown.
|
||||
- **Test count:** 544 → 544 (design-only, no test change).
|
||||
- **Authority:** ADR 0007 § 12 (opens deferral) + § 13 (rejects SQLite at Phase 3 per Node baseline); v0.1 spec § 4.6 / § 4.7 (Dashboard + observability endpoints planning authority); OCP `dashboard.html` (prior art); CC 开发铁律 v1.6 § 10 — fresh-context opus reviewer required for design ADR; Phase 3 kickoff via maintainer "go" 2026-05-25 + standing-autopilot grant; PR #25 fresh-context opus reviewer findings (3 polish items).
|
||||
|
||||
## v0.2.0 — 2026-05-25
|
||||
|
||||
### Phase 2 — Multi-key auth + audit + owner gating + keygen CLI (D43-A → D47)
|
||||
|
||||
**Overview.** v0.2.0 closes Phase 2 — the multi-key authentication track that grew OLP from single-tenant anonymous-only proxy (v0.1.1) to a multi-identity deployment with per-key cache isolation, audit attribution, owner-vs-guest header gating, and a reproducible bootstrap CLI. 6 D-day commits (D43-A through D47) shipped between 2026-05-25 (single intensive session under the standing-autopilot grant). All 11 ADR 0007 § 10 acceptance criteria are implemented + tested.
|
||||
|
||||
**Test count: 468 (v0.1.1) → 544 (v0.2.0).** +76 tests across the Phase 2 arc.
|
||||
|
||||
**Phase 2 release_kit checklist**
|
||||
|
||||
- [x] All 6 D-day deliverables landed on main (D43-A, D43-B ADR draft, D44, D45, D46, D47)
|
||||
- [x] CI green on every D-day merge commit + on this release commit's head
|
||||
- [x] Fresh-context opus reviewer on every implementation D-day (D44/D45/D46/D47), maintainer text-review on D43-B ADR
|
||||
- [x] All 11 ADR 0007 § 10 acceptance criteria (#1–#11) covered by Suite 19/20/21/22 tests
|
||||
- [x] CHANGELOG "Unreleased" promoted to "## v0.2.0 — 2026-05-25" with D43-A through D47 entries
|
||||
- [x] `package.json` bumped 0.1.1 → 0.2.0
|
||||
- [x] `CLAUDE.md release_kit.phase_rolling_mode`: `current_phase` Phase 2 → Phase 3; `current_pre_release_identifier` `0.2.0-phase2` → `0.3.0-phase3`
|
||||
- [x] README status header + Implementation Status + Phase plan reflect Phase 2 shipped
|
||||
- [ ] Tag pushed (next step in this PR's lifecycle)
|
||||
- [ ] `release.yml` triggered + GitHub Release created (auto on tag push; D37 phase_rolling_mode gate will pass because Unreleased is now sentinel-only)
|
||||
|
||||
**ADR 0007 § 10 acceptance criteria — final ship status**
|
||||
|
||||
| # | Criterion | Covering tests |
|
||||
|---|---|---|
|
||||
| 1 | Per-key cache namespace isolation | Suite 20i |
|
||||
| 2 | Anonymous prod-default off → 401 | Suite 20a |
|
||||
| 3 | Anonymous dev-mode on → 200 | Suite 20g |
|
||||
| 4 | Owner-vs-guest `/health` gating | Suite 21a-d |
|
||||
| 5 | Owner-vs-guest `X-OLP-Fallback-Detail` gating | Suite 21e-h |
|
||||
| 6 | Post-revoke 401 within next request | Suite 19o + Suite 20e |
|
||||
| 7 | Manifest atomicity + revoke-dominates-touch | Suite 19y-1..4 |
|
||||
| 8 | Audit ndjson round-trip + PII guard | Suite 20j + 20j-stream + 20j-401 |
|
||||
| 9 | Bootstrap keygen surface reproducible | Suite 22 |
|
||||
| 10 | `OLP_OWNER_TOKEN` env override | Suite 19p + Suite 20f |
|
||||
| 11 | `providers_enabled` 403 scope enforcement | Suite 20h |
|
||||
|
||||
**Known limitations carried beyond v0.2.0**
|
||||
|
||||
Phase 2 functional scope is complete. The following remain as Phase 3+ deferrals (tracked in `docs/v1x-roadmap.md` + new entries below):
|
||||
|
||||
- **Dashboard (`dashboard.html`)** — owner-only multi-provider quota / fallback / cache-hit-rate panels. Per ADR 0007 § 12 + v0.1 spec § 4.6. Phase 3 mainline.
|
||||
- **Audit query layer + rotation** — `audit.ndjson` is append-only at v0.2.0; aggregate queries + log rotation deferred to Phase 3 alongside Dashboard.
|
||||
- **`tried_providers` semantics on `key_no_provider_access` 403** — schema currently reports filter-rejected hops as "tried"; either ADR § 8 amendment (rename / add field) or D46+ semantic fix. Noted by D45 opus reviewer.
|
||||
- **Per-provider per-key auth artifact mapping** — ADR § 12 explicit out-of-scope. Per-key cache + audit isolation works; per-key per-provider OAuth tokens (e.g., two OLP keys each authenticated to different OpenAI Codex accounts) is Phase 3+ work.
|
||||
- **SQLite migration (Option 3 hybrid)** — ADR § 13 documents the forward path; trigger is Dashboard / SQL-aggregate-quota / multi-second audit-query workload. Requires engines bump (`>=22.13.0` or `>=23.4.0`) per ADR § 11 as a separate prior PR.
|
||||
|
||||
### D47 — `bin/olp-keys.mjs` keygen CLI (Phase 2 functional scope closes)
|
||||
|
||||
Fourth Phase 2 implementation D-day. Closes ADR 0007 § 10 acceptance criterion #9 (bootstrap workflow must be reproducible without manual file editing) by shipping a minimal keygen CLI per § 9.1. **Phase 2 functional scope is complete with this D-day** — remaining work is Phase 2 close → v0.2.0 (maintainer-triggered, explicit per CLAUDE.md `release_kit.phase_close_trigger`).
|
||||
|
||||
- **New file `bin/olp-keys.mjs`** (~250 lines): subcommand CLI with three subcommands:
|
||||
- `keygen [--owner] [--name=<label>] [--tier=guest|owner] [--providers=<csv>] [--force]` — creates a key + prints plaintext token to stdout ONCE; manifest stores only SHA-256 hash. `--force` revokes existing owner keys before creating the new owner (recovery flow per ADR § 9.3). `--providers=*` (default) or comma-separated allowlist.
|
||||
- `list [--owner-only] [--include-revoked]` — lists keys with `token_hash` redacted (lib/keys.mjs `listKeys` already redacts).
|
||||
- `revoke --id=<key-id>` — marks the key's `revoked_at`; idempotent (already-revoked → no-op + status message); missing id → exit 2.
|
||||
- Common flag `--olp-home=<path>` overrides `~/.olp/`; defaults to `OLP_HOME` env or `~/.olp/`.
|
||||
- **`package.json` `bin` field**: `olp-keys` → `./bin/olp-keys.mjs` so `npx olp-keys ...` resolves; also `npm run olp-keys ...` via scripts.
|
||||
- **Module shape**: CLI exposes `runCli(argv, { out, err })` so tests can invoke it with synthetic argv + IO writers (no process spawn). Main guard auto-runs when invoked as entrypoint.
|
||||
- **Plaintext token discipline**: per ADR § 5 + § 9.1, plaintext is printed exactly once on stdout. Never logged, never written to manifest, never written to audit. Operators must capture immediately; lost → `--force` revoke + regenerate.
|
||||
- **`--force` async correctness**: `cmdKeygen` is async and `await`s each `revokeKey` (which is async — acquires per-key write lock per § 6.4). Sequence: revoke each existing owner manifest atomically → then `createKey` for new owner. Avoids the race where create-new runs before revoke-old completes.
|
||||
- **Test surface (Suite 22, +20 tests — 524 → 544):**
|
||||
- 22a-1..5: parseArgv unit tests (`--flag=value`, `--flag value`, boolean, mixed positional)
|
||||
- 22b-1..5: keygen subcommand (owner default, name+providers, missing-name error, invalid-tier error, --force revoke-then-create flow with isolation tmpdir)
|
||||
- 22c-1..3: list subcommand (empty, populated with token_hash-redaction check, --owner-only filter)
|
||||
- 22d-1..4: revoke subcommand (valid id, idempotent re-revoke, missing-id error, nonexistent-id error)
|
||||
- 22e-1..3: top-level CLI behaviour (--help / no args / unknown subcommand exit codes)
|
||||
- **Documentation:** AGENTS.md `lib/keys.mjs` marker promoted to ✅; new `bin/olp-keys.mjs` entry. Implementation-status-note + shipped-set updated. README.md Implementation Status table gains `bin/olp-keys.mjs` row; Known limitations note updated to "Phase 2 functional scope complete; close pending"; new "Bootstrap workflow" section with copy-pasteable npx commands + recovery flow.
|
||||
- **Test count:** 524 → 544 (+20 D47 tests in Suite 22).
|
||||
- **Authority:** ADR 0007 (multi-key auth — § 5 token format, § 9.1 minimal keygen command surface, § 9.3 recovery, § 10 acceptance criterion #9 covered); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant.
|
||||
|
||||
### D46 — owner-vs-guest gating for `/health` + `X-OLP-Fallback-Detail` (Phase 2 closes header observability gap)
|
||||
|
||||
Third Phase 2 implementation D-day. Closes ADR 0007 § 10 acceptance criteria #4 (`/health` payload trimming for non-owner) + #5 (`X-OLP-Fallback-Detail` emission gating per `fallback_detail_header_policy`). Phase 2 server surface is now fully gated end-to-end; remaining D-days are keygen CLI surface (D47+) and Phase 2 close (v0.2.0, maintainer-triggered).
|
||||
|
||||
- **`server.mjs` `handleHealth` identity-aware payload** per ADR § 7.1:
|
||||
- Auth gate at top — `authenticate(req)` returns 401 for unauth + `allow_anonymous: false` (consistent with /v1/* routes); 200 with trimmed payload for anonymous / guest; 200 with full payload for owner.
|
||||
- Trim controlled by `_authConfig.owner_only_endpoints` — if `/health` is in the list, non-owner gets `{ ok: true, version }`; else (operator removes it) full payload to everyone (v0.1.1 opt-out knob).
|
||||
- `touchLastUsed` fired on `res.on('finish')` for filesystem identities (matches /v1/* pattern). No audit row on /health — high-volume monitoring endpoint, audit volume noise not justified at Phase 2 (would land with Phase 3 Dashboard if aggregate /health stats become needed).
|
||||
- **`server.mjs` `withFallbackDetailHeader` identity-aware emission** per ADR § 7.2:
|
||||
- New helper `shouldEmitFallbackDetailHeader(olpIdentity)` reads `_authConfig.fallback_detail_header_policy`:
|
||||
- `'owner_only'` (default) → emit only when `olpIdentity.owner_tier === 'owner'`
|
||||
- `'all'` → emit unconditionally (v0.1.1 opt-back-in for operators who want the diagnostic header for all identities)
|
||||
- `'none'` → suppress unconditionally
|
||||
- When `olpIdentity` is null (pre-auth error paths), defaults to emit — preserves the v0.1.1 ungated behaviour for pre-auth errors where identity is unknown.
|
||||
- `withFallbackDetailHeader` signature gains a third `olpIdentity` argument; both call sites in `handleChatCompletions` updated to pass `olpIdentity`.
|
||||
- **Test surface (Suite 21, +9 tests + 1 added in Suite 20 — 515 → 524):**
|
||||
- **20m** /health with no auth + `allow_anonymous=false` → 401 (consistency with /v1/* routes)
|
||||
- **21a-d** /health payload trimming (criterion #4): anonymous trimmed; guest trimmed; owner full; `owner_only_endpoints: []` opts out (guest gets full)
|
||||
- **21e-h** X-OLP-Fallback-Detail emission gating (criterion #5): `owner_only` + guest → header absent; `owner_only` + owner → header present + valid JSON; `'all'` + guest → header present (v0.1.1 opt-back); `'none'` + owner → header absent (full suppression). Tests use a 2-hop chain (anthropic primary fail + openai secondary) to produce non-empty `fallbackDetail` for the header content.
|
||||
- **Test-mode setup updated:** the global `__setAuthConfig({ allow_anonymous: true })` was extended to also pass `owner_only_endpoints: []` + `fallback_detail_header_policy: 'all'` so pre-D46 tests (Suite 18, F5 /health tests, D40 fallback-detail tests, etc.) continue to pass without modification — Suite 21 explicitly overrides per-case to exercise the production-default-gated paths.
|
||||
- **Documentation:** AGENTS.md `lib/keys.mjs` marker updated to reflect D46 ship; Implementation-status-note updated. README.md Implementation Status row + Known limitations "Multi-key auth" note rewritten to reflect D46 ship + remaining keygen CLI.
|
||||
- **Test count:** 515 → 524 (+9 D46 tests).
|
||||
- **Authority:** ADR 0007 (multi-key auth — §§ 7.1 + 7.2 implementation contracts + § 10 acceptance criteria #4 + #5 covered); ADR 0004 Amendment 5 (D40 ratification of "Phase 2 will re-introduce owner-vs-non-owner gating when `lib/keys.mjs` lands" — this D-day fulfils the deferral); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; standing autopilot grant (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a`).
|
||||
|
||||
### D45 — `server.mjs` auth integration + `lib/audit.mjs` (Phase 2 wire-up)
|
||||
|
||||
Second Phase 2 implementation D-day. Wires the D44 `lib/keys.mjs` identity layer into the request flow + lands `lib/audit.mjs` per ADR 0007 § 6.2 + § 8. Closes acceptance criteria #1 (per-key cache isolation, validation-side end-to-end), #2 (anonymous prod-default off), #3 (anonymous dev-mode on), #6 (post-revoke 401 within next request — full), #8 (audit ndjson round-trip), #10 (`OLP_OWNER_TOKEN` env override — full server-side), #11 (`providers_enabled` 403 scope). Owner-vs-guest gating for `/health` + `X-OLP-Fallback-Detail` (criteria #4, #5) remains in D46 scope.
|
||||
|
||||
- **New file `lib/audit.mjs`** (~75 lines): `appendAuditEvent(event, opts)` writes one JSON event per line to `~/.olp/logs/audit.ndjson` (file 0600, dir 0700). § 6.2 retry semantics: warn + 1 retry on first failure; per-process drop counter + warn on second failure; NEVER throws. Per-call `OLP_HOME` env resolution (matches `lib/keys.mjs`). Exports `getAuditDropCount` for future /health surface.
|
||||
- **`lib/keys.mjs`** extended with `loadAuthConfigSync({ olpHome })` reading the `auth` block from `~/.olp/config.json` with defaults per ADR § 7.2 (`allow_anonymous: false`, `owner_only_endpoints: ['/health']`, `fallback_detail_header_policy: 'owner_only'`). Both `lib/keys.mjs` + `lib/audit.mjs` now resolve `OLP_HOME` env per call (precedence: opts.olpHome → process.env.OLP_HOME → ~/.olp) so tests and operator deployments can redirect without code edits.
|
||||
- **`server.mjs` auth middleware integration:**
|
||||
- `extractToken(req)` parses `Authorization: Bearer <token>` first, then `x-api-key: <token>`.
|
||||
- `authenticate(req)` calls `validateKey(token, { allowAnonymous: _authConfig.allow_anonymous })`; returns identity on success, 401 `{ auth_required | invalid_or_revoked_key }` on failure.
|
||||
- `isProviderEnabled(olpIdentity, providerKey)` enforces `providers_enabled` allowlist (`'*'` = all).
|
||||
- `_authConfig` loaded at startup; warn `auth_allow_anonymous_enabled` fires if `allow_anonymous: true` so the relaxed posture is visible. Test seams `__setAuthConfig` / `__resetAuthConfig`.
|
||||
- `handleChatCompletions` and `handleModels` both gated by `authenticate(req)` at top. Audit ctx object built throughout the handler lifecycle; `res.on('finish')` appends the row + fires `touchLastUsed` async (best-effort).
|
||||
- **Identity-vs-credentials separation:** `olpIdentity` (the new validated identity) is consumed for cache namespacing + providers_enabled + audit; `authContext` passed to `provider.spawn()` REMAINS `null` so providers continue their own credential discovery (env / keychain / file). Per-provider per-key credential mapping is Phase 3+ scope per ADR § 12.
|
||||
- `handleChatCompletions` chain filtered by `chain.filter(hop => isProviderEnabled(olpIdentity, hop.provider))`; empty result returns 403 `key_no_provider_access` with helpful diagnostic message.
|
||||
- `keyId = olpIdentity.keyId` (replacing hardcoded `'__anonymous__'` at the cache call sites).
|
||||
- Audit captures fields throughout: post-auth (key_id, owner_tier); post-IR (model); post-chain-success (provider, fallback_hops, tried_providers, cache_status); post-chain-exhausted (error_code, providerUsed=chain[0], cache_status='miss'). Status code + latency populated on `res.on('finish')`.
|
||||
- **Test surface (Suite 20, +15 tests, 499 → 514):**
|
||||
- 20a-d: header parsing + valid key happy paths (Bearer / x-api-key / invalid → 401)
|
||||
- 20e: revoked key 401 (closes criterion #6 end-to-end)
|
||||
- 20f: `OLP_OWNER_TOKEN` env override returns 200 (criterion #10 full coverage)
|
||||
- 20g: `allow_anonymous: true` + no header returns 200 (criterion #3)
|
||||
- 20h + 20h-extra: `providers_enabled: ['mistral']` for anthropic model → 403; `'*'` baseline returns 200 (criterion #11)
|
||||
- 20i: per-key cache namespace isolation — keys A/B with identical payload do not share cache (criterion #1 end-to-end)
|
||||
- 20j + 20j-401: audit.ndjson written with § 8 schema fields including PII guard; 401 path also appends (criterion #8)
|
||||
- 20k: filesystem key `last_used_at` populated after first successful request (D45 touchLastUsed wire)
|
||||
- 20l + 20l-200: `/v1/models` also enforces auth (consistent gating across `/v1/*`)
|
||||
- **Test-mode setup:** test-features.mjs sets `process.env.OLP_HOME` to a tmpdir at module load so audit + key writes don't pollute `~/.olp/`. After the server.mjs import resolves, calls `__setAuthConfig({ allow_anonymous: true })` so pre-D45 HTTP integration tests (Suite 18 etc.) that don't pass an Authorization header continue to pass as anonymous; Suite 20 explicitly overrides per-case for production-default-off coverage.
|
||||
- **Documentation:** AGENTS.md `lib/keys.mjs` 🟡 marker updated + new `lib/audit.mjs` entry; AGENTS.md Implementation-status-note + shipped-set updated. README.md Implementation Status table gains `lib/audit.mjs` row + `lib/keys.mjs` row updated; Known limitations "Multi-key auth" note rewritten to reflect D45 ship + D46 follow-up; new env-vars and config block surfaced for users.
|
||||
- **Test count:** 499 → 515 (+15 initial Suite 20 tests + 1 fold-in regression test `20j-stream` covering opus-P1 streaming audit-fidelity).
|
||||
- **Fold-in (CI-fail recovery + fresh-context opus reviewer findings, 1 CI + 1 P1 + 2 P2 + 1 P3):**
|
||||
- **CI Node 24 failure** — Suite 20 setup did not stub `CLAUDE_CODE_OAUTH_TOKEN` before the mock spawn ran; lib/providers/anthropic.mjs `_spawnAndStream` checks for an OAuth token BEFORE invoking the (mock) spawn, so the AUTH_MISSING pre-check fired and every Suite 20 200-expecting test 502'd on CI Node 24 (local Node 22 had the env from the maintainer's claude install). Fixed by `ensureSuite20FakeOAuth` / `restoreSuite20OAuth` helpers in `makeSuite20Server` / `teardownSuite20`; matches the existing pattern used at Suite 9 line ~2154 (`test-fake-oauth-token-for-cache-tests`).
|
||||
- **P1 real-streaming audit fidelity** — single-hop streaming success path (server.mjs ~L1050+ `if (ir.stream && chain.length === 1 && !bypassCacheForFirstHop ...)`) did not populate `auditCtx.provider` / `tried_providers` / `cache_status`, so audit rows for the most common deployed shape carried `provider: null`. Fixed by stamping these fields at the top of the streaming branch (between the streamPlugin null-check and the `streamHeaders` build) and amending `error_code` on the two streaming failure exit paths (`streaming_error_after_first_chunk` + `streaming_error_before_first_chunk`). New regression test `20j-stream` makes a streaming request and asserts the audit row's `provider`, `cache_status`, and `tried_providers` fields are populated.
|
||||
- **P2 global test tmpdir cleanup** — `process.env.OLP_HOME = mkdtempSync(...)` at module load left a `/var/folders/.../olp-test-home-*` directory leak per `npm test` run. Fixed by `process.on('exit', () => rmSync(...))` registered immediately after the mkdtempSync. Best-effort; never throws at exit.
|
||||
- **P3 handleModels 401 lacks OLP diagnostic headers** — `handleChatCompletions` 401 path passes `olpErrorHeaders({ startMs })` but `handleModels` did not. Aligned by adding the same headers to the `handleModels` `authResult.ok=false` return.
|
||||
- **Deferred (acknowledged by reviewer as non-blocking):** P2 `tried_providers` semantics on `key_no_provider_access` 403 — schema currently reports filter-rejected hops as "tried" which a downstream Dashboard would misread; either ADR § 8 amendment (rename / add field) or D46+ semantic fix.
|
||||
- **Authority:** ADR 0007 (multi-key auth — §§ 5/6.2/7/9.4 implementation contracts + § 10 acceptance criteria #1/#2/#3/#6/#8/#10/#11); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; Phase 2 kickoff handoff (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`); standing autopilot grant (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a`).
|
||||
|
||||
### D44 — `lib/keys.mjs` core landed (multi-key auth, no server wire-up yet)
|
||||
|
||||
First Phase 2 implementation D-day. Lands the `lib/keys.mjs` module per ADR 0007 §§ 5/6.1/6.3/6.3.5/6.4/9.4. Identity / lifecycle layer for OLP API keys is now in-tree; `server.mjs` integration scheduled D45 (until then, requests still use the hardcoded `'__anonymous__'` cache namespace — no behavioural change at v0.1.1 / D44).
|
||||
|
||||
- **New file `lib/keys.mjs`** (~462 lines after fold-in) — public API surface:
|
||||
- `createKey({ name, owner_tier, providers_enabled, notes, olpHome })` — generates opaque `olp_<32-byte base64url>` token (47-char total), SHA-256 hashes it for manifest storage, atomically writes `keys/<id>/manifest.json` (mode 0600, dir 0700). Returns `{ id, plaintext_token, manifest }` — plaintext token is printed once and never persisted.
|
||||
- `validateKey(plaintext, { allowAnonymous, olpHome })` — three-tier resolution per § 5 / § 7 / § 9.4: env override (`OLP_OWNER_TOKEN` → `__env_owner__` synthetic identity) → anonymous (only when `allowAnonymous: true`, returns `__anonymous__` identity) → filesystem manifest lookup (constant-time hash compare via `crypto.timingSafeEqual`). Revoked manifests return null (caller produces 401). Per § 6.3.5 — MUST hit manifest every request; no in-process validation cache.
|
||||
- `revokeKey({ id, olpHome })` — idempotent; sets `revoked_at` via atomic write inside per-key write-lock.
|
||||
- `listKeys({ olpHome })` — returns manifest objects with `token_hash` redacted.
|
||||
- `touchLastUsed(id, { olpHome })` — async best-effort lazy update per § 6.3 revoke-dominates-touch: re-reads latest manifest inside the per-key lock, NO-OPs if `revoked_at` is non-null, otherwise merges `last_used_at` preserving all other fields. Failure logs warn and never throws.
|
||||
- **§ 6.4 in-process per-key write-lock** — `Map<key-id, Promise>` chain; serializes intra-process writes. External (CLI) writes not lock-protected at Phase 2; atomic-rename + § 6.3 read-before-write give the `revoke dominates touch` safety property.
|
||||
- **Test-only hooks** — `__setTouchInterleaveHook` (inject deterministic pause between touch's lock acquisition and read for race tests) + `__resetWriteLocks` (test cleanup).
|
||||
- **What is NOT in D44 (split per ADR §§ 6.2 / 9.1 separation):** audit ndjson append (request-layer concern; D45 server glue); keygen CLI bootstrap surface (D45+); `server.mjs` integration replacing the hardcoded `'__anonymous__'` keyId at `server.mjs:502, :531` (D45); owner-vs-guest gating for `/health` and `X-OLP-Fallback-Detail` (D46).
|
||||
- **Test count:** 468 → 496 (+28 tests in new Suite 19):
|
||||
- 19a-d token generation (§ 5)
|
||||
- 19e-j manifest write+read + chmod 0600/0700 + schema validation (§ 4, § 6.1)
|
||||
- 19k-p validateKey: filesystem / wrong / missing / anonymous / revoked / env override (§ 5, § 6.3.5, § 9.4)
|
||||
- 19q-r revokeKey idempotency + non-existent id
|
||||
- 19s-t listKeys empty + redaction
|
||||
- 19u-x touchLastUsed updates + NO-OP on revoked + NO-OP on anonymous/env identities + best-effort failure
|
||||
- **19y-1 to 19y-4 acceptance criterion #7 (concurrent revoke + touch race tests)**: revoke→touch, touch→revoke, interleaved external-revoke-via-hook (deterministically reproduces the § 6.3 race the maintainer's text review caught), 30-iteration concurrent-promise stress
|
||||
- **Documentation:** AGENTS.md `lib/keys.mjs` 📋 marker → 🟡 "core landed at D44"; AGENTS.md Implementation-status-note + shipped-set updated to include `lib/keys.mjs`; README.md Implementation Status row + Known limitations "Multi-key auth" note updated to "core landed, server integration pending D45".
|
||||
- **Fold-in (fresh-context opus reviewer findings, 2 P2 correctness + 2 P3 polish):**
|
||||
- **P2 #1 lock-map cleanup** (`lib/keys.mjs` `_withKeyLock`): prior version stored `prev.then(() => next)` as the Map tail, but the cleanup-identity check `_writeLocks.get(id) === next` could never match the derived promise — Map entries leaked one-per-unique-key-id. Bounded impact at family scale (~5–10 entries) but a real correctness bug. Fixed by storing `next` directly. New regression tests `19x-extra` (sequential) + `19x-extra-2` (concurrent 3-key × 3-touch contention) assert `__writeLockSize() === 0` post-drain.
|
||||
- **P2 #2 `validateKey` non-string defensive coding**: prior version threw `TypeError` when called with a non-string truthy plaintext (`validateKey(42)` / `validateKey({})`), reaching `hashToken(<non-string>)` → `createHash().update(<non-string>)`. Q2 promised "bad inputs return null." Fixed via top-of-function `if (plaintextToken != null && typeof plaintextToken !== 'string') return null;`. New test `19m-extra` covers number / object / array / `allowAnonymous: true` paths.
|
||||
- **P3 #3 19y-3 test scope comment**: test simulates external revoke landing BEFORE touch's read, not BETWEEN touch's read and write (which is currently unreachable because `touchLastUsed` has synchronous read→write — no await between `readManifest` and `writeManifestAtomic`). Added explanatory comment documenting the synchronous-read-write property as the satisfaction mechanism for ADR § 10 criterion #7 scenario 3, with a note that a post-read hook + matching test would be required if a future refactor introduces an await between read and write.
|
||||
- **P3 #4 CHANGELOG line count**: corrected `~330 lines` to `~462 lines after fold-in` (matches `wc -l lib/keys.mjs`).
|
||||
- **Test count after fold-in:** 468 → 499 (+31 tests: 28 initial + 3 fold-in regression tests).
|
||||
- **Authority:** ADR 0007 (multi-key auth — Decision: Option 2 filesystem manifest + opaque token; §§ 5/6.1/6.3/6.3.5/6.4/9.4 implementation contracts; § 10 acceptance criteria #6/#7 partially-covered by D44 tests, full coverage requires D45+ server integration); CLAUDE.md `release_kit overlay phase_rolling_mode` — under Unreleased; Phase 2 kickoff handoff (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`); PR #20 fresh-context opus reviewer findings.
|
||||
|
||||
### D43-B — ADR 0007 multi-key auth design draft (design-only, no code change)
|
||||
|
||||
Phase 2 mainline design ADR. Ratifies the storage / token / manifest / atomic-write / owner-gating / bootstrap / Node-baseline decisions ahead of D44+ implementation D-days. Pure design doc — no `.mjs` / no tests / 4 files touched.
|
||||
|
||||
- `docs/adr/0007-multi-key-auth.md` (new, ~420 lines after fold-ins): 13 sections covering Context / Decision (Option 2 + opaque key) / Storage layout (`~/.olp/keys/<key-id>/manifest.json` + `~/.olp/logs/audit.ndjson`) / Manifest schema (schema_version, token_hash, owner_tier, providers_enabled) / Token format (`olp_<32-byte base64url>`, SHA-256 hash) / Atomic write & audit append (manifest lifecycle-only atomic via tmpfile+fsync+rename; audit per-request append, warn + 1 retry, no memory buffer at Phase 2) / Owner-vs-guest-vs-anonymous gating (config.json `auth.allow_anonymous` default false, no env auto-detection) / Audit ndjson schema (no PII) / Bootstrap & recovery (minimal keygen command surface + `OLP_OWNER_TOKEN` env override with stable `__env_owner__` keyId) / Acceptance criteria (11 test surfaces for D44+) / Node baseline (Option 1 SQLite port rejection rationale citing `engines >=18` + CI 20/24 vs `node:sqlite` v22.5.0 with flag) / Out of scope (Dashboard, quota enforcement, audit query, file locking deferred to Phase 3+) / Future forward (Option 3 hybrid migration trigger + preconditions).
|
||||
- `docs/adr/README.md` index: added ADR 0007 row with one-paragraph summary.
|
||||
- `docs/v1x-roadmap.md` #2: marked **PHASE 2 ACTIVE (no longer deferred)**; "Design ADR (NOT YET RATIFIED)" → "Design ADR (ratified) → ADR 0007"; trigger updated to "already fired 2026-05-25"; code anchors pinned to exact line numbers (cache/store.mjs:77-79/:287, server.mjs:502/:531/:392/:1072/:1101).
|
||||
- `CHANGELOG.md` Unreleased: this entry.
|
||||
- **Fold-in #1 (fresh-context opus reviewer findings, 2 P2 + 3 P3, all polish):** § 6.2 step 1 — pin audit serialization timing to after status_code + latency_ms are known (resolves §10 #2 testability gap); new § 6.3.5 — explicit "no in-process validation cache at Phase 2" rule (resolves §10 #6 implicit-contract gap); § 6.1 — document deliberate omission of directory fsync after rename (single-process trade-off); § 9.4 — token-collision policy between `OLP_OWNER_TOKEN` and filesystem keys declared undefined behaviour; §10 #4 — test rephrased to assert against config-driven `owner_only_endpoints` rather than hardcoded payload shape.
|
||||
- **Fold-in #2 (maintainer text-review findings, 1 P1 + 1 P2 + 1 P3):** § 6.3 rewritten to `last_used_at` revoke-dominates-touch semantics (P1 — fixes safety bug where lazy touch could overwrite revoke and silently clear `revoked_at`, breaking acceptance criterion #6 under concurrent CLI revoke + in-flight server request); § 6.4 reframed from "both states are valid" / "observability-grade" to "revoke dominates touch" with §6.3 as the load-bearing discipline; § 10 criterion #7 expanded to test all three orderings (revoke→touch, touch→revoke, interleaved) with explicit MUST: `revoked_at` non-null after revoke regardless of ordering; § 11 forward path step (1) corrected Node version history — minimum non-flag-gated baseline is v22.13.0 (LTS) / v23.4.0 (current), RC since v25.7.0, stable TBD (previous wording "Node v22.5.0+ for unflagged but RC" was factually wrong per https://nodejs.org/download/release/v22.12.0/docs/api/sqlite.html and https://nodejs.org/api/sqlite.html); this CHANGELOG entry line-count corrected from "~270 lines" to "~420 lines after fold-ins".
|
||||
- **Test count:** 468 → 468 (design-only, no test change).
|
||||
- **Authority:** Phase 2 kickoff handoff (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`); OLP v0.1 spec § 4.5 (planning authority for `~/.olp/` layout); OCP `keys.mjs` (prior-art for opaque-key + per-key isolation model); Node `node:sqlite` docs (https://nodejs.org/api/sqlite.html — Option 1 rejection rationale per ADR 0007 § 11); CC 开发铁律 v1.6 § 10 — fresh-context opus reviewer required for design ADR per Iron Rule 10.
|
||||
|
||||
### D43-A — Phase 2 doc alignment (no code change)
|
||||
|
||||
Phase 1 was closed at v0.1.1; this commit aligns documentation surfaces to the Phase 2 reality before D43-B (ADR 0007 draft) lands. Pure doc cleanup; no `.mjs` or test changes.
|
||||
|
||||
- `CLAUDE.md release_kit.current_phase` Phase 1 → Phase 2; `current_pre_release_identifier` `0.1.0-bootstrap` → `0.2.0-phase2`.
|
||||
- `README.md` status header + Implementation Status + Phase plan rewritten to reflect actually-shipped reality (v0.1.0 + v0.1.1 bundled the three Tier-D plugins + cache + fallback into a single Phase 1 milestone, not one phase per plugin as the original v0.1 spec planned). `lib/keys.mjs` row + "Multi-key auth not yet implemented" note updated to "Phase 2 active per ADR 0007 (drafting at D43-B)".
|
||||
- `AGENTS.md` § Key files to know — `lib/keys.mjs` 📋 marker updated to "Phase 2 active per ADR 0007 (drafting at D43-B)"; Implementation-status-note paragraph dated 2026-05-25 + reflects Phase 1 close + Phase 2 active scope.
|
||||
- `ALIGNMENT.md` § Provider Inventory — added one-paragraph "Note on phase terminology" clarifying that "Phase" in the Provider Inventory tables + § One-shot Triggered Audits "OpenAI Codex ToS formal pin" refers to the original per-plugin enablement plan, orthogonal to the milestone phase numbering in README. Fold-in for D43-A reviewer P2 finding; no governance-text change, no Speculative-Candidate plugin reclassification.
|
||||
- **Test count:** 468 → 468 (no test change).
|
||||
- **Authority:** `CLAUDE.md release_kit overlay phase_rolling_mode` — under Unreleased; Phase 2 kickoff handoff at `~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md`; ADR 0007 forthcoming at D43-B.
|
||||
|
||||
## v0.1.1 — 2026-05-25
|
||||
|
||||
|
||||
@@ -135,7 +135,7 @@ release_kit:
|
||||
# This overlay is the authoritative source. If Iron Rule 5 appears to be silently
|
||||
# violated (no version bump after many D-day pushes), check this section first
|
||||
# before filing a compliance finding.
|
||||
current_phase: Phase 1
|
||||
current_pre_release_identifier: "0.1.0-bootstrap"
|
||||
current_phase: Phase 4
|
||||
current_pre_release_identifier: "0.4.0-phase4"
|
||||
phase_close_trigger: explicit maintainer action (not automated)
|
||||
```
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
A personal- and family-scale multi-provider LLM proxy. One HTTP endpoint, many subscriptions behind it, automatic routing, automatic fallback, content-addressed caching — so your IDEs and family clients keep working as long as *any* of your subscriptions has quota left.
|
||||
|
||||
> **Status:** v0.1 — bootstrap. Most of this README is a skeleton; sections marked _placeholder_ land alongside the relevant phase of work (see [phase plan](#phase-plan)).
|
||||
> **Status:** v0.3.0 shipped (2026-05-25) — Phase 1 multi-provider proxy core (v0.1.0 + v0.1.1) + Phase 2 multi-key auth + audit + owner gating + keygen CLI (v0.2.0) + Phase 3 Dashboard + audit query layer + daily audit rotation (v0.3.0). Phase 4 (per-key per-provider auth + audit retention + SQLite hybrid + provider-cost weights) is the next planned milestone. Sections marked _placeholder_ land alongside the relevant phase of work (see [phase plan](#phase-plan)).
|
||||
|
||||
---
|
||||
|
||||
@@ -94,16 +94,15 @@ Trigger types, fallback safety, idempotency rules, and the full example config l
|
||||
|
||||
## API Endpoints
|
||||
|
||||
_placeholder — full table lands as each endpoint lands._
|
||||
|
||||
| Endpoint | Method | Phase | Status | Description |
|
||||
|---|---|---|---|---|
|
||||
| `/v1/chat/completions` | POST | 1 | ✅ Shipped | OpenAI-compatible Chat Completions entry. Internally normalized to IR, dispatched to a provider plugin, response shape converted back. |
|
||||
| `/v1/models` | GET | 1 | ✅ Shipped | Lists models from `models-registry.json`. |
|
||||
| `/health` | GET | 1 | ✅ Shipped | Per-provider health snapshot (owner-only). |
|
||||
| `/cache/stats` | GET | 5 | 📋 Planned | Cache hit rate, by-provider breakdown. |
|
||||
| `/v0/management/quota` | GET | 6 | 📋 Planned | Per-provider quota / credit pool status (best-effort). |
|
||||
| `/dashboard` | GET | 6 | 📋 Planned | Owner-only dashboard (localhost-bound by default). |
|
||||
| `/health` | GET | 1 | ✅ Shipped | Per-provider health snapshot. Phase 2 owner-only-trim: full per-provider details to owner identity; trimmed `{ ok, version }` to guest / anonymous. Gate via `auth.owner_only_endpoints` config. |
|
||||
| `/dashboard` | GET | 3 | ✅ Shipped (D50 + D51) | Owner-only multi-provider dashboard HTML (4 panels: quota / 24h request stats / 30d spend trend / top fallback chains; 30s poll with visibilitychange pause). Owner-only_block; non-owner identities receive 401. Localhost-bound by default. |
|
||||
| `/v0/management/dashboard-data` | GET | 3 | ✅ Shipped (D50) | JSON aggregate consumed by the dashboard 30s poll: `{ generated_at, window_24h, cache_hit_24h, quota, spend_trend_30d, top_fallback_chains_24h, cache_stats }`. Owner-only_block. |
|
||||
| `/v0/management/quota` | GET | 3 | ✅ Shipped (D50) | Per-provider quota snapshot via `provider.quotaStatus()` (subset of dashboard-data; useful for scripted monitoring). Owner-only_block. |
|
||||
| `/cache/stats` | GET | 3 | ✅ Shipped (D50) | Live in-memory `cacheStore.stats()` (`{ hits, misses, size, inflightCount }` + `generated_at`). Owner-only_block. |
|
||||
|
||||
---
|
||||
|
||||
@@ -165,9 +164,9 @@ If a fallback chain is exhausted, `X-OLP-Fallback-Exhausted` lists the tried pro
|
||||
|
||||
---
|
||||
|
||||
## Implementation status (as of 2026-05-24)
|
||||
## Implementation status (as of 2026-05-25, post-v0.2.0)
|
||||
|
||||
Phase 1 is in progress. This table reflects what is currently shipped vs. what is designed for later phases.
|
||||
Phase 1 closed at v0.1.1 (multi-provider proxy core + pre-Phase-2 cleanup). Phase 2 closed at v0.2.0 (multi-key auth + audit + owner gating + keygen CLI; ADR 0007 § 10 all 11 acceptance criteria shipped). Phase 3 closed at v0.3.0 (Dashboard + `lib/audit-query.mjs` + daily audit rotation; ADR 0008 § 10 all 15 acceptance criteria shipped). Phase 4 (per-key per-provider auth + audit retention + SQLite hybrid + provider-cost weights) is the next planned milestone. This table reflects what is currently shipped vs. what is designed for later phases.
|
||||
|
||||
| File / artifact | Status | Notes |
|
||||
|---|---|---|
|
||||
@@ -182,8 +181,12 @@ Phase 1 is in progress. This table reflects what is currently shipped vs. what i
|
||||
| Soft trigger data path (`quotaStatus()` polling) | 📋 Planned (v1.x) | Evaluation logic shipped + tested; data ingestion deferred per ADR 0004 Amendment 2 |
|
||||
| `models-registry.json` | ✅ Shipped | SPOT for `(provider, model)` metadata |
|
||||
| `test-features.mjs` | ✅ Shipped | Comprehensive test suite covering IR, cache, fallback, and integration paths (CI: `test.yml`) |
|
||||
| `lib/keys.mjs` | 📋 Planned (Phase 2) | Multi-key auth, per-key namespacing, audit log |
|
||||
| `dashboard.html` | 📋 Planned (Phase 6) | Owner-only multi-provider dashboard |
|
||||
| `lib/keys.mjs` | ✅ Phase 2 shipped (D44 + D45 + D46) | Multi-key auth core (`createKey` / `validateKey` / `listKeys` / `revokeKey` / `touchLastUsed`) per ADR 0007 §§ 5/6.1/6.3/6.3.5/6.4/9.4 + `loadAuthConfigSync` for `auth.allow_anonymous` / `owner_only_endpoints` / `fallback_detail_header_policy`. Server wires `validateKey` per request, filters chain by `providers_enabled`, fires `touchLastUsed` post-response, trims `/health` payload for non-owner, gates `X-OLP-Fallback-Detail` emission by policy. |
|
||||
| `bin/olp-keys.mjs` | ✅ Phase 2 shipped (D47) | Keygen CLI per ADR 0007 § 9.1. `npx olp-keys keygen --owner` generates an owner key + prints plaintext token once; `npx olp-keys list` enumerates keys (token_hash redacted); `npx olp-keys revoke --id=X` marks a key revoked. `--olp-home=<path>` overrides `~/.olp/`. |
|
||||
| `lib/audit.mjs` | ✅ Phase 2 + 3 (D45 append + D52 rotation) | Append-only ndjson audit at `~/.olp/logs/audit.ndjson` per ADR 0007 § 6.2 + § 8. `appendAuditEvent` fires for every `/v1/*` + `/v0/management/*` request (success, 401, 403, 5xx). Warn + 1 retry on append failure; no memory buffer at Phase 2 (forward path). PII excluded. D52 adds synchronous daily rotation per ADR 0008 § 5 — first append after UTC midnight renames live → `audit-YYYY-MM-DD.ndjson`. |
|
||||
| `lib/audit-query.mjs` | ✅ Phase 3 shipped (D49) | Audit ndjson aggregate query layer per ADR 0008 § 4. 5 functions: `discoverAuditFiles`, `readAuditWindow`, `aggregateRequests`, `topFallbackChains`, `spendTrendDaily`, `cacheHitRateWindow`. In-memory cross-file scan; PII guard at output. Consumed by `/v0/management/dashboard-data`. |
|
||||
| `dashboard.html` | ✅ Phase 3 shipped (D50 stub + D51 full UI) | Owner-only multi-provider dashboard per ADR 0008 § 6. 4 panels (quota / 24h request stats / 30d SVG sparkline / top fallback chains). Vanilla HTML+JS+fetch (no build step). 30s page poll with `document.visibilityState` pause. Served by `/dashboard` route owner-only_block. |
|
||||
| `bin/olp-audit-rotate.mjs` | ✅ Phase 3 shipped (D52) | External audit rotation cron tool per ADR 0008 § 5.2. `npx olp-audit-rotate [--olp-home=<path>]`. Idempotent + safe alongside the in-server first-append trigger. |
|
||||
| `docs/provider-caveats.md` | 📋 Planned (Phase 3+) | Lossy-translation reference; for now documented inline in each plugin header |
|
||||
| `docs/openai-spec-pin.md` | ✅ Shipped (D30) | OpenAI spec snapshot for annual audit; v0.1 baseline pinned 2026-05-24 |
|
||||
| `docs/alignment-audits/` | 📋 Planned | Output directory for annual alignment audits (first audit: 2027-05-14) |
|
||||
@@ -194,9 +197,33 @@ Phase 1 is in progress. This table reflects what is currently shipped vs. what i
|
||||
|
||||
Behaviors that work correctly at personal/family scale but have ratified follow-ups for a v1.x sprint. Single landing page: [`docs/v1x-roadmap.md`](./docs/v1x-roadmap.md).
|
||||
|
||||
- **Streaming-path singleflight not implemented.** The cache layer's D4 singleflight (one spawn per identical concurrent request) is fully wired on the buffered path but NOT on the streaming path. N concurrent identical streaming requests at v0.1 will each spawn their own CLI process. Design ratified in [ADR 0005 Amendment 8](./docs/adr/0005-cache-cross-provider.md); implementation tracked via [issue #16](https://github.com/dtzp555-max/olp/issues/16) and [v1.x roadmap #1](./docs/v1x-roadmap.md). At family scale this is observably fine — every caller still receives the correct response; the cost is N CLI processes instead of one.
|
||||
- **Streaming-path singleflight ✅ shipped (D57 + D58, 2026-05-25).** `cacheStore.getOrComputeStreaming(...)` mirrors the buffered-path `getOrCompute` and resolves the TOCTOU window between peek and spawn ([issue #16](https://github.com/dtzp555-max/olp/issues/16)). Two concurrent identical streaming requests share one CLI spawn via tee fan-out; late joiners receive accumulated replay + the live tail; per-client backpressure (`PER_CLIENT_QUEUE_CAP=1MB`) protects against slow consumers; full-disconnect aborts the source CLI via AbortController. New `X-OLP-Streaming-Inflight: source | attached` header annotates the role. New `cache_status: 'streaming_attached'` audit value tracks the singleflight win. Authority: [ADR 0005 Amendment 8](./docs/adr/0005-cache-cross-provider.md), v1.x roadmap #1.
|
||||
- **Soft triggers configured but inert.** `routing.soft_triggers` in `~/.olp/config.json` is honored by the engine's evaluation logic but `quotaStatus()` polling is not wired (ADR 0004 Amendment 2). A startup warning fires if the field is non-empty so the inert state is visible.
|
||||
- **Multi-key auth not yet implemented.** All requests today share the cache namespace `__anonymous__`. The cache data model is keyed by `keyId` and ready to accept real identities when `lib/keys.mjs` lands. Tracked in [v1.x roadmap #2](./docs/v1x-roadmap.md).
|
||||
- **Multi-key auth + owner gating + keygen CLI shipped at v0.2.0 (D44 + D45 + D46 + D47).** `lib/keys.mjs` (core), `lib/audit.mjs` (audit), owner-vs-guest `/health` payload trimming + `X-OLP-Fallback-Detail` policy gating, `bin/olp-keys.mjs` (keygen CLI). All 11 ADR 0007 § 10 acceptance criteria covered. v0.2.0 maintainer-merged 2026-05-25.
|
||||
|
||||
- **Phase 3 (Dashboard + audit query layer + rotation) shipped to main (D48-D54); v0.3.0 release pending.** `docs/adr/0008-dashboard-and-audit-query.md` ratified at D48. `lib/audit-query.mjs` (D49) implements the 5-function aggregate query API (in-memory ndjson scan, PII-guarded). 4 new owner-only_block endpoints at D50 (`/dashboard`, `/v0/management/dashboard-data`, `/v0/management/quota`, `/cache/stats`). `dashboard.html` full multi-panel UI at D51 (vanilla HTML+JS+fetch, 30s poll with visibilitychange pause). Daily audit rotation at D52 (synchronous on first append after UTC midnight; `audit-YYYY-MM-DD.ndjson` naming) + optional `bin/olp-audit-rotate.mjs` cron tool. `tried_providers` schema semantic fix at D53 (D45 P2 deferral). Phase 3 close to v0.3.0 is maintainer-triggered per CLAUDE.md `release_kit.phase_close_trigger`.
|
||||
|
||||
**Bootstrap workflow (D47):** for first-run / production setup:
|
||||
|
||||
```bash
|
||||
# 1. Generate an owner key (prints the plaintext token ONCE — capture it now)
|
||||
npx olp-keys keygen --owner
|
||||
|
||||
# 2. Set production config (defaults to allow_anonymous: false)
|
||||
# (Edit ~/.olp/config.json to enable providers + chains as usual)
|
||||
|
||||
# 3. Start the server
|
||||
npm start
|
||||
|
||||
# 4. Validate the key works (substitute the captured plaintext token)
|
||||
curl -H "Authorization: Bearer olp_..." http://localhost:3456/health
|
||||
```
|
||||
|
||||
**Recovery if owner token is lost:** `npx olp-keys keygen --owner --force` revokes the previous owner key + creates a fresh one (plaintext printed once).
|
||||
|
||||
**New env vars consumed at D45:** `OLP_HOME` (override `~/.olp/` location, used by tests + operator deployments); `OLP_OWNER_TOKEN` (synthetic env-owner identity for headless / CI deployments — bypasses filesystem manifest lookup with stable `__env_owner__` keyId).
|
||||
|
||||
**New config block consumed at D45:** `config.json auth.{ allow_anonymous, owner_only_endpoints, fallback_detail_header_policy }`. Default `allow_anonymous: false` (production-off); set true to accept requests without an OLP API key (development / single-user dev mode). Startup emits a warn when `allow_anonymous: true` so the relaxed posture is observable.
|
||||
- **Provider-level `cacheKeyFields` mask not implemented.** Cache keys include every IR field including ones individual plugins drop at spawn (e.g., Anthropic plugin drops `temperature`). Spurious cache misses possible (extra spawn cost; never spurious hits). Conservative posture documented in [ADR 0005 Amendment 7](./docs/adr/0005-cache-cross-provider.md). Tracked in [v1.x roadmap #5](./docs/v1x-roadmap.md).
|
||||
|
||||
---
|
||||
@@ -220,17 +247,17 @@ Read the ADRs in `docs/adr/` in order before proposing structural changes.
|
||||
|
||||
OLP lands in phases. Each phase has its own PR series and Iron-Rule-10 reviewer; this README's placeholders are filled per-phase via the [`release_kit`](./CLAUDE.md) overlay.
|
||||
|
||||
- Phase 0 — Repo bootstrap, `ALIGNMENT.md`, founding ADRs, CI workflows, PR template. **(current)**
|
||||
- Phase 1 — `server.mjs` skeleton, IR, Anthropic plugin, cache D1+D4. Port from OCP.
|
||||
- Phase 2 — OpenAI Codex plugin.
|
||||
- Phase 3 — Mistral Vibe plugin.
|
||||
- Phase 4 — Fallback engine + routing chains config + quota poll worker.
|
||||
- Phase 5 — Cache cross-provider hardening (D2+D3).
|
||||
- Phase 6 — Dashboard + observability (`/v0/management/quota`).
|
||||
- Phase 7 — Release v0.1, OCP enters maintenance.
|
||||
- Phase 8+ — Optional Grok / Kimi / tier-2 plugins; provider-native protocol endpoints; deterministic triggers.
|
||||
The original v0.1 spec (in `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations) planned one provider plugin per phase. The actual Phase 1 execution bundled the three Tier-D provider plugins + cache layer + fallback engine into a single shipped milestone (v0.1.0) followed by a cleanup batch (v0.1.1). The phase numbering below reflects what was actually shipped, not the original per-plugin partition.
|
||||
|
||||
Full spec (decision rationale, open questions, risks): `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations.
|
||||
- **Phase 0** — Repo bootstrap, `ALIGNMENT.md`, founding ADRs, CI workflows, PR template. ✅ Shipped (2026-05-23).
|
||||
- **Phase 1** — Multi-provider proxy core: `server.mjs`, IR, three Tier-D provider plugins (Anthropic / OpenAI Codex / Mistral Vibe), cache (D1+D4) + cleanup (D2 bypass / D3 chunked replay / D23 size cap), fallback engine with first-chunk safety + hard triggers + per-hop log observability, IR↔OpenAI translation under Rule 2(b). ✅ Shipped — v0.1.0 (2026-05-24) + v0.1.1 cleanup (2026-05-25, D35–D42).
|
||||
- **Phase 2** — Multi-key auth (`lib/keys.mjs`) per ADR 0007: opaque OLP API keys, per-key cache namespacing, owner-vs-guest tier for header gating, audit ndjson (`lib/audit.mjs`), `/health` payload trimming + `X-OLP-Fallback-Detail` emission gating, `OLP_OWNER_TOKEN` env override, keygen CLI (`bin/olp-keys.mjs`). ✅ Shipped — v0.2.0 (2026-05-25, D43-A → D47). All 11 ADR 0007 § 10 acceptance criteria covered.
|
||||
- **Phase 3** — Dashboard + audit query layer + daily audit rotation per ADR 0008: in-memory ndjson aggregate query layer (`lib/audit-query.mjs`), 4 owner-only_block management endpoints (`/dashboard` + `/v0/management/dashboard-data` + `/v0/management/quota` + `/cache/stats`), multi-panel `dashboard.html` with 30s poll, synchronous daily audit rotation + `bin/olp-audit-rotate.mjs` cron tool, `tried_providers` schema fix (D45 P2 deferral). ✅ Shipped — v0.3.0 (2026-05-25, D48 → D54). All 15 ADR 0008 § 10 acceptance criteria covered.
|
||||
- **Phase 4 (planned)** — Per-key per-provider auth artifact mapping (ADR 0007 § 12 deferral), audit query rotation/retention policies, SQLite hybrid migration (ADR 0007 § 13 trigger), provider-cost weights for spend trend.
|
||||
- **Phase 4+ (v1.x roadmap, triggered as needed)** — Full deferred-work tracker: [`docs/v1x-roadmap.md`](./docs/v1x-roadmap.md). Includes streaming-path singleflight ([issue #16](https://github.com/dtzp555-max/olp/issues/16) + ADR 0005 Amendment 8 design ratified), soft-trigger reactivation (ADR 0004 Amendment 2), `/health` activeSpawns integration, provider-level `cacheKeyFields` mask, streaming-path SPAWN_FAILED salvage.
|
||||
- **Phase N (opt-in)** — Tier-2 / Tier-C provider plugins (Grok / Kimi / MiniMax / GLM / Qwen) per [ADR 0006](./docs/adr/0006-provider-inclusion.md); provider-native protocol endpoints; deterministic triggers. Triggered by tier-2 demand, not on the bootstrap path.
|
||||
|
||||
Full spec (decision rationale, open questions, risks): `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations. Phase 2 kickoff handoff: `~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Executable
+94
@@ -0,0 +1,94 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* bin/olp-audit-rotate.mjs — External audit rotation cron tool (Phase 3 / D52)
|
||||
*
|
||||
* Authority: ADR 0008 § 5.2 (external cron alternative to in-server first-
|
||||
* append-after-UTC-midnight trigger).
|
||||
*
|
||||
* Use case: operators who want exact-at-UTC-midnight rotation rather than
|
||||
* "first request after midnight". Invoke from a host cron / launchd job.
|
||||
*
|
||||
* Idempotent + safe to run alongside the in-server check (both detect the
|
||||
* date condition; whichever fires first does the rename; the other no-ops).
|
||||
*
|
||||
* Usage:
|
||||
* olp-audit-rotate [--olp-home=<path>]
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 = success (rotation performed OR no rotation needed)
|
||||
* 1 = bad usage (unknown flag)
|
||||
* 2 = rotation attempted + failed (e.g., EACCES)
|
||||
*
|
||||
* Example cron line (UTC midnight):
|
||||
* 1 0 * * * /usr/local/bin/node /path/to/bin/olp-audit-rotate.mjs >> /var/log/olp-audit-rotate.log 2>&1
|
||||
*/
|
||||
|
||||
import { _maybeRotateAudit } from '../lib/audit.mjs';
|
||||
|
||||
function parseArgv(argv) {
|
||||
const flags = {};
|
||||
for (const arg of argv) {
|
||||
if (arg.startsWith('--')) {
|
||||
const eq = arg.indexOf('=');
|
||||
if (eq > 0) flags[arg.slice(2, eq)] = arg.slice(eq + 1);
|
||||
else flags[arg.slice(2)] = true;
|
||||
}
|
||||
}
|
||||
return flags;
|
||||
}
|
||||
|
||||
const USAGE = `OLP audit rotation cron tool
|
||||
|
||||
Usage:
|
||||
olp-audit-rotate [--olp-home=<path>]
|
||||
|
||||
Triggers a rotation check: if the live audit.ndjson holds events from a
|
||||
past UTC date, rename it to audit-YYYY-MM-DD.ndjson. Idempotent; safe to
|
||||
run alongside the in-server first-append-after-UTC-midnight trigger.
|
||||
|
||||
Authority: ADR 0008 § 5.2.`;
|
||||
|
||||
export async function runCli(argv, opts = {}) {
|
||||
const ioOut = opts.out ?? (s => process.stdout.write(s));
|
||||
const ioErr = opts.err ?? (s => process.stderr.write(s));
|
||||
|
||||
if (argv.includes('--help') || argv.includes('-h')) {
|
||||
ioOut(USAGE + '\n');
|
||||
return 0;
|
||||
}
|
||||
|
||||
const flags = parseArgv(argv);
|
||||
const allowed = new Set(['olp-home', 'help', 'h']);
|
||||
for (const k of Object.keys(flags)) {
|
||||
if (!allowed.has(k)) {
|
||||
ioErr(`Error: unknown flag --${k}\n${USAGE}\n`);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
const olpHome = typeof flags['olp-home'] === 'string' ? flags['olp-home'] : undefined;
|
||||
|
||||
try {
|
||||
// _maybeRotateAudit is synchronous at v0.3.0 (D52) — rotation must
|
||||
// complete BEFORE the next append so no event straddles the boundary.
|
||||
const result = _maybeRotateAudit({ olpHome });
|
||||
if (result.rotated) {
|
||||
ioOut(`Rotated ${result.fromPath} -> ${result.toPath} (dateUsed=${result.dateUsed}).\n`);
|
||||
} else {
|
||||
ioOut('No rotation needed (live audit is current or absent).\n');
|
||||
}
|
||||
return 0;
|
||||
} catch (err) {
|
||||
ioErr(`Error: rotation failed: ${err?.message ?? err}\n`);
|
||||
return 2;
|
||||
}
|
||||
}
|
||||
|
||||
// Main guard
|
||||
const isMain = (() => {
|
||||
try { return import.meta.url === `file://${process.argv[1]}`; }
|
||||
catch { return false; }
|
||||
})();
|
||||
if (isMain) {
|
||||
runCli(process.argv.slice(2)).then(code => process.exit(code));
|
||||
}
|
||||
Executable
+269
@@ -0,0 +1,269 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* bin/olp-keys.mjs — OLP key management CLI (Phase 2 / D47)
|
||||
*
|
||||
* Authority: ADR 0007 § 9 (Bootstrap & recovery — minimal keygen command
|
||||
* surface) + § 10 acceptance criterion #9 (bootstrap workflow must be
|
||||
* reproducible without manual file editing).
|
||||
*
|
||||
* Subcommands:
|
||||
* keygen create a new OLP key; prints plaintext token to stdout ONCE
|
||||
* list list all keys (manifests with token_hash redacted)
|
||||
* revoke mark a key as revoked (idempotent; manifest stays for audit)
|
||||
*
|
||||
* Usage:
|
||||
* olp-keys keygen --owner [--name=<label>] [--providers=anthropic,openai,...]
|
||||
* olp-keys keygen --name=<label> [--tier=guest|owner] [--providers=...]
|
||||
* olp-keys keygen --owner --force (revokes existing owner keys; new owner)
|
||||
* olp-keys list [--owner-only] [--include-revoked]
|
||||
* olp-keys revoke --id=<key-id>
|
||||
*
|
||||
* Flags applicable to all subcommands:
|
||||
* --olp-home=<path> override ~/.olp (defaults to OLP_HOME env or ~/.olp)
|
||||
* --help print usage and exit 0
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 = success
|
||||
* 1 = bad usage (missing args, unknown subcommand)
|
||||
* 2 = operational failure (key not found, manifest invalid, FS error)
|
||||
*
|
||||
* The plaintext token from `keygen` is printed exactly once to stdout. It is
|
||||
* never written to manifest, audit, or any log line. Operators must capture
|
||||
* it immediately; lost → revoke + regenerate. Per ADR 0007 § 5 + § 9.1.
|
||||
*/
|
||||
|
||||
import {
|
||||
createKey,
|
||||
listKeys,
|
||||
revokeKey,
|
||||
readManifest,
|
||||
} from '../lib/keys.mjs';
|
||||
|
||||
// ── Arg parsing ───────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Minimal flag parser. Supports:
|
||||
* --flag=value → { flag: 'value' }
|
||||
* --flag value → { flag: 'value' } (if next arg doesn't start with --)
|
||||
* --flag → { flag: true }
|
||||
* Returns { positional: string[], flags: Record<string, string|true> }.
|
||||
*/
|
||||
export function parseArgv(argv) {
|
||||
const positional = [];
|
||||
const flags = {};
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const arg = argv[i];
|
||||
if (arg.startsWith('--')) {
|
||||
const eq = arg.indexOf('=');
|
||||
if (eq > 0) {
|
||||
flags[arg.slice(2, eq)] = arg.slice(eq + 1);
|
||||
} else {
|
||||
const name = arg.slice(2);
|
||||
const next = argv[i + 1];
|
||||
if (next !== undefined && !next.startsWith('--')) {
|
||||
flags[name] = next;
|
||||
i++;
|
||||
} else {
|
||||
flags[name] = true;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
positional.push(arg);
|
||||
}
|
||||
}
|
||||
return { positional, flags };
|
||||
}
|
||||
|
||||
const USAGE = `OLP key management CLI
|
||||
|
||||
Usage:
|
||||
olp-keys keygen --owner [--name=<label>] [--providers=<csv>] [--force]
|
||||
olp-keys keygen --name=<label> [--tier=guest|owner] [--providers=<csv>]
|
||||
olp-keys list [--owner-only] [--include-revoked]
|
||||
olp-keys revoke --id=<key-id>
|
||||
|
||||
Common flags:
|
||||
--olp-home=<path> Override ~/.olp (default reads OLP_HOME env)
|
||||
--help Print this message
|
||||
|
||||
Authority: ADR 0007 § 9 (bootstrap & recovery).`;
|
||||
|
||||
// ── Subcommand implementations ────────────────────────────────────────────
|
||||
|
||||
async function cmdKeygen(flags, ioOut, ioErr) {
|
||||
const olpHome = flags['olp-home'];
|
||||
const owner = flags.owner === true;
|
||||
const force = flags.force === true;
|
||||
let tier = flags.tier;
|
||||
if (owner) tier = 'owner';
|
||||
if (!tier) tier = 'guest';
|
||||
if (tier !== 'owner' && tier !== 'guest') {
|
||||
ioErr(`Error: --tier must be "owner" or "guest" (got "${tier}").\n`);
|
||||
return 1;
|
||||
}
|
||||
const name = flags.name || (owner ? 'owner' : null);
|
||||
if (!name) {
|
||||
ioErr('Error: --name is required (or use --owner to default to "owner").\n');
|
||||
return 1;
|
||||
}
|
||||
const providersFlag = flags.providers;
|
||||
let providers_enabled;
|
||||
if (providersFlag === undefined || providersFlag === true) {
|
||||
providers_enabled = '*';
|
||||
} else if (typeof providersFlag === 'string') {
|
||||
providers_enabled = providersFlag.split(',').map(s => s.trim()).filter(Boolean);
|
||||
if (providers_enabled.length === 0) providers_enabled = '*';
|
||||
} else {
|
||||
providers_enabled = '*';
|
||||
}
|
||||
|
||||
// --force: revoke any existing owner keys before creating the new one.
|
||||
// revokeKey is async (acquires per-key write lock); await each so the new
|
||||
// owner key's createKey doesn't race the revoke writes.
|
||||
if (force && tier === 'owner') {
|
||||
const existing = listKeys({ olpHome });
|
||||
for (const m of existing) {
|
||||
if (m.owner_tier === 'owner' && m.revoked_at === null) {
|
||||
try {
|
||||
await revokeKey({ id: m.id, olpHome });
|
||||
ioErr(`Revoked existing owner key id=${m.id} name="${m.name}" (--force).\n`);
|
||||
} catch (err) {
|
||||
ioErr(`Warning: failed to revoke existing owner key id=${m.id}: ${err?.message ?? err}\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = createKey({ name, owner_tier: tier, providers_enabled, olpHome });
|
||||
} catch (err) {
|
||||
ioErr(`Error: createKey failed: ${err?.message ?? err}\n`);
|
||||
return 2;
|
||||
}
|
||||
|
||||
// Plaintext token — printed ONCE per ADR § 5 + § 9.1.
|
||||
ioOut(`\n OLP key created — capture the plaintext token NOW; it will not be shown again.\n\n`);
|
||||
ioOut(` id: ${result.id}\n`);
|
||||
ioOut(` name: ${result.manifest.name}\n`);
|
||||
ioOut(` owner_tier: ${result.manifest.owner_tier}\n`);
|
||||
ioOut(` providers_enabled: ${typeof result.manifest.providers_enabled === 'string' ? result.manifest.providers_enabled : `[${result.manifest.providers_enabled.join(', ')}]`}\n`);
|
||||
ioOut(` created_at: ${result.manifest.created_at}\n`);
|
||||
ioOut(` manifest: ~/.olp/keys/${result.id}/manifest.json\n`);
|
||||
ioOut(`\n token (plaintext): ${result.plaintext_token}\n\n`);
|
||||
ioOut(` Pass via: Authorization: Bearer ${result.plaintext_token.slice(0, 12)}...\n`);
|
||||
ioOut(` or: x-api-key: ${result.plaintext_token.slice(0, 12)}...\n\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
function cmdList(flags, ioOut, ioErr) {
|
||||
const olpHome = flags['olp-home'];
|
||||
const ownerOnly = flags['owner-only'] === true;
|
||||
const includeRevoked = flags['include-revoked'] === true;
|
||||
let keys = listKeys({ olpHome });
|
||||
if (ownerOnly) keys = keys.filter(k => k.owner_tier === 'owner');
|
||||
if (!includeRevoked) keys = keys.filter(k => k.revoked_at === null);
|
||||
|
||||
if (keys.length === 0) {
|
||||
ioOut('No keys.\n');
|
||||
return 0;
|
||||
}
|
||||
|
||||
ioOut(`\n ${keys.length} key${keys.length === 1 ? '' : 's'}:\n\n`);
|
||||
for (const k of keys) {
|
||||
const providers = typeof k.providers_enabled === 'string'
|
||||
? k.providers_enabled
|
||||
: `[${k.providers_enabled.join(', ')}]`;
|
||||
const status = k.revoked_at === null ? 'active' : `revoked (${k.revoked_at})`;
|
||||
const lastUsed = k.last_used_at ?? 'never';
|
||||
ioOut(` id=${k.id}\n`);
|
||||
ioOut(` name: ${k.name}\n`);
|
||||
ioOut(` owner_tier: ${k.owner_tier}\n`);
|
||||
ioOut(` providers: ${providers}\n`);
|
||||
ioOut(` status: ${status}\n`);
|
||||
ioOut(` created: ${k.created_at}\n`);
|
||||
ioOut(` last_used: ${lastUsed}\n`);
|
||||
if (k.notes) ioOut(` notes: ${k.notes}\n`);
|
||||
ioOut('\n');
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
async function cmdRevoke(flags, ioOut, ioErr) {
|
||||
const olpHome = flags['olp-home'];
|
||||
const id = typeof flags.id === 'string' ? flags.id : null;
|
||||
if (!id) {
|
||||
ioErr('Error: --id=<key-id> is required.\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Confirm the key exists before attempting revoke (clearer error path).
|
||||
const m = readManifest(id, { olpHome });
|
||||
if (m === null) {
|
||||
ioErr(`Error: no key with id="${id}".\n`);
|
||||
return 2;
|
||||
}
|
||||
if (m.revoked_at !== null) {
|
||||
ioOut(`Key id=${id} already revoked at ${m.revoked_at} (no-op).\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
try {
|
||||
await revokeKey({ id, olpHome });
|
||||
} catch (err) {
|
||||
ioErr(`Error: revokeKey failed: ${err?.message ?? err}\n`);
|
||||
return 2;
|
||||
}
|
||||
|
||||
ioOut(`Revoked key id=${id} name="${m.name}".\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
// ── CLI entry ────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Run the CLI with explicit argv + IO streams. Returns the intended exit code.
|
||||
* Exported for tests (no process.exit, no direct stdout/stderr).
|
||||
*
|
||||
* @param {string[]} argv - args AFTER the subcommand name (e.g., ['keygen', '--owner']).
|
||||
* The first element is the subcommand.
|
||||
* @param {object} [opts]
|
||||
* @param {(s: string) => void} [opts.out] - stdout writer; defaults to process.stdout.write
|
||||
* @param {(s: string) => void} [opts.err] - stderr writer; defaults to process.stderr.write
|
||||
* @returns {Promise<number>} exit code 0 / 1 / 2
|
||||
*/
|
||||
export async function runCli(argv, opts = {}) {
|
||||
const ioOut = opts.out ?? (s => process.stdout.write(s));
|
||||
const ioErr = opts.err ?? (s => process.stderr.write(s));
|
||||
|
||||
if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
|
||||
ioOut(USAGE + '\n');
|
||||
return argv.length === 0 ? 1 : 0;
|
||||
}
|
||||
|
||||
const [subcommand, ...rest] = argv;
|
||||
const { flags } = parseArgv(rest);
|
||||
|
||||
switch (subcommand) {
|
||||
case 'keygen': return await cmdKeygen(flags, ioOut, ioErr);
|
||||
case 'list': return cmdList(flags, ioOut, ioErr);
|
||||
case 'revoke': return await cmdRevoke(flags, ioOut, ioErr);
|
||||
default:
|
||||
ioErr(`Error: unknown subcommand "${subcommand}".\n${USAGE}\n`);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
// Main guard: only run when invoked as the entrypoint. ESM equivalent of
|
||||
// `require.main === module` is comparing import.meta.url against argv[1].
|
||||
const isMain = (() => {
|
||||
try {
|
||||
return import.meta.url === `file://${process.argv[1]}`;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
})();
|
||||
|
||||
if (isMain) {
|
||||
runCli(process.argv.slice(2)).then(code => process.exit(code));
|
||||
}
|
||||
+308
@@ -0,0 +1,308 @@
|
||||
<!DOCTYPE html>
|
||||
<!--
|
||||
OLP Dashboard — Phase 3 / D51
|
||||
------------------------------
|
||||
Multi-panel owner-only dashboard per ADR 0008 § 6. Polls
|
||||
/v0/management/dashboard-data every 30 seconds (paused when the
|
||||
page is hidden via document.visibilityState).
|
||||
|
||||
Panels (per spec v0.1 § 4.6 + ADR 0008 Lane 5 = B full):
|
||||
1. Per-provider quota / credit pool
|
||||
2. Per-provider 24h request count + cache hit rate + fallback rate
|
||||
3. 30-day spend trend (SVG sparkline; per-provider in tooltip)
|
||||
4. Top 10 fallback chains by trigger count
|
||||
|
||||
No build step, no framework, no external dependencies. Vanilla JS +
|
||||
fetch + DOM render. Owner-only_block: anonymous / guest / no-auth all
|
||||
receive 401 — non-owner identities will see an error banner.
|
||||
-->
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>OLP Dashboard</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<style>
|
||||
* { box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; margin: 0; padding: 1.5rem; background: #f9fafb; color: #1f2937; }
|
||||
h1 { margin: 0 0 0.5rem; font-size: 1.5rem; }
|
||||
.meta { color: #6b7280; font-size: 0.875rem; margin-bottom: 1.5rem; }
|
||||
.grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 1rem; max-width: 1200px; }
|
||||
.panel { background: #fff; border: 1px solid #e5e7eb; border-radius: 6px; padding: 1rem 1.25rem; }
|
||||
.panel h2 { margin: 0 0 0.75rem; font-size: 1rem; color: #374151; font-weight: 600; }
|
||||
.panel-error { color: #b91c1c; font-style: italic; padding: 0.5rem 0; }
|
||||
.panel-loading { color: #6b7280; font-style: italic; padding: 0.5rem 0; }
|
||||
table { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
|
||||
th, td { text-align: left; padding: 0.35rem 0.5rem; border-bottom: 1px solid #f3f4f6; }
|
||||
th { font-weight: 600; color: #4b5563; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.05em; }
|
||||
td.num { text-align: right; font-variant-numeric: tabular-nums; }
|
||||
.banner { background: #fef3c7; border-left: 4px solid #f59e0b; padding: 0.75rem 1rem; border-radius: 4px; margin-bottom: 1rem; }
|
||||
.banner.error { background: #fee2e2; border-color: #ef4444; color: #991b1b; }
|
||||
.sparkline { width: 100%; height: 120px; }
|
||||
.sparkline rect { fill: #3b82f6; }
|
||||
.sparkline rect:hover { fill: #1d4ed8; }
|
||||
.chain { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 0.85rem; color: #374151; }
|
||||
.pill { display: inline-block; background: #e5e7eb; color: #374151; padding: 0.05rem 0.4rem; border-radius: 3px; font-size: 0.75rem; }
|
||||
footer { margin-top: 2rem; color: #9ca3af; font-size: 0.75rem; text-align: center; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>OLP Dashboard</h1>
|
||||
<div id="meta" class="meta">Loading…</div>
|
||||
<div id="banner-slot"></div>
|
||||
<div class="grid">
|
||||
<section class="panel">
|
||||
<h2>Quota (per provider)</h2>
|
||||
<div id="panel-quota"><div class="panel-loading">Loading…</div></div>
|
||||
</section>
|
||||
<section class="panel">
|
||||
<h2>Last 24h — request count · cache hit · fallback rate</h2>
|
||||
<div id="panel-24h"><div class="panel-loading">Loading…</div></div>
|
||||
</section>
|
||||
<section class="panel" style="grid-column: span 2;">
|
||||
<h2>Request count — last 30 days (UTC)</h2>
|
||||
<div id="panel-trend"><div class="panel-loading">Loading…</div></div>
|
||||
</section>
|
||||
<section class="panel" style="grid-column: span 2;">
|
||||
<h2>Top fallback chains (last 24h)</h2>
|
||||
<div id="panel-chains"><div class="panel-loading">Loading…</div></div>
|
||||
</section>
|
||||
</div>
|
||||
<footer>OLP Dashboard · poll every 30s · paused when tab hidden · v0.3.0-phase3</footer>
|
||||
<script>
|
||||
(function () {
|
||||
'use strict';
|
||||
const POLL_INTERVAL_MS = 30000;
|
||||
let pollHandle = null;
|
||||
|
||||
function fmtNum(n) { return (n ?? 0).toLocaleString(); }
|
||||
function fmtPct(rate) { return (rate * 100).toFixed(1) + '%'; }
|
||||
function el(tag, attrs, ...children) {
|
||||
const node = document.createElement(tag);
|
||||
if (attrs) for (const [k, v] of Object.entries(attrs)) {
|
||||
if (k === 'class') node.className = v;
|
||||
else if (k === 'style') node.style.cssText = v;
|
||||
else if (k.startsWith('on') && typeof v === 'function') node.addEventListener(k.slice(2), v);
|
||||
else node.setAttribute(k, v);
|
||||
}
|
||||
for (const c of children) {
|
||||
if (c == null) continue;
|
||||
node.appendChild(typeof c === 'string' || typeof c === 'number' ? document.createTextNode(String(c)) : c);
|
||||
}
|
||||
return node;
|
||||
}
|
||||
|
||||
function svgEl(tag, attrs) {
|
||||
const node = document.createElementNS('http://www.w3.org/2000/svg', tag);
|
||||
if (attrs) for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
|
||||
return node;
|
||||
}
|
||||
|
||||
function renderQuota(data) {
|
||||
const target = document.getElementById('panel-quota');
|
||||
target.innerHTML = '';
|
||||
if (!Array.isArray(data) || data.length === 0) {
|
||||
target.appendChild(el('div', { class: 'panel-loading' }, 'No providers enabled.'));
|
||||
return;
|
||||
}
|
||||
const table = el('table', null,
|
||||
el('thead', null, el('tr', null,
|
||||
el('th', null, 'Provider'),
|
||||
el('th', null, 'Available'),
|
||||
el('th', null, 'Status'),
|
||||
)),
|
||||
);
|
||||
const tbody = el('tbody');
|
||||
for (const row of data) {
|
||||
const available = row.error ? el('span', { class: 'pill' }, 'unavailable')
|
||||
: row.available === null || row.available === undefined ? el('span', { class: 'pill' }, 'n/a')
|
||||
: el('span', null, fmtNum(row.available));
|
||||
const status = row.error ? el('span', { style: 'color: #b91c1c;' }, row.error)
|
||||
: row.available === null || row.available === undefined ? 'no quota API'
|
||||
: 'ok';
|
||||
tbody.appendChild(el('tr', null,
|
||||
el('td', null, row.provider),
|
||||
el('td', { class: 'num' }, available),
|
||||
el('td', null, status),
|
||||
));
|
||||
}
|
||||
table.appendChild(tbody);
|
||||
target.appendChild(table);
|
||||
}
|
||||
|
||||
function render24h(window24h, cacheHit24h) {
|
||||
const target = document.getElementById('panel-24h');
|
||||
target.innerHTML = '';
|
||||
const byProvider = (window24h && window24h.by_provider) || {};
|
||||
const providers = Object.keys(byProvider);
|
||||
if (providers.length === 0) {
|
||||
target.appendChild(el('div', { class: 'panel-loading' }, 'No requests in window.'));
|
||||
return;
|
||||
}
|
||||
const table = el('table', null,
|
||||
el('thead', null, el('tr', null,
|
||||
el('th', null, 'Provider'),
|
||||
el('th', null, 'Requests'),
|
||||
el('th', null, 'Cache hit'),
|
||||
el('th', null, 'Fallback rate'),
|
||||
)),
|
||||
);
|
||||
const tbody = el('tbody');
|
||||
for (const p of providers) {
|
||||
const pData = byProvider[p];
|
||||
const hitData = (cacheHit24h && cacheHit24h.by_provider && cacheHit24h.by_provider[p]) || null;
|
||||
const fallbackRate = pData.count > 0 ? pData.fallback_count / pData.count : 0;
|
||||
tbody.appendChild(el('tr', null,
|
||||
el('td', null, p),
|
||||
el('td', { class: 'num' }, fmtNum(pData.count)),
|
||||
el('td', { class: 'num' }, hitData ? fmtPct(hitData.hit_rate) : 'n/a'),
|
||||
el('td', { class: 'num' }, fmtPct(fallbackRate)),
|
||||
));
|
||||
}
|
||||
table.appendChild(tbody);
|
||||
target.appendChild(table);
|
||||
}
|
||||
|
||||
function renderTrend(spendTrend30d) {
|
||||
const target = document.getElementById('panel-trend');
|
||||
target.innerHTML = '';
|
||||
if (!Array.isArray(spendTrend30d) || spendTrend30d.length === 0) {
|
||||
target.appendChild(el('div', { class: 'panel-loading' }, 'No trend data.'));
|
||||
return;
|
||||
}
|
||||
const counts = spendTrend30d.map(d => d.request_count);
|
||||
const maxCount = Math.max(1, ...counts);
|
||||
const width = 800, height = 120, padding = { top: 8, right: 8, bottom: 20, left: 32 };
|
||||
const innerW = width - padding.left - padding.right;
|
||||
const innerH = height - padding.top - padding.bottom;
|
||||
const barGap = 2;
|
||||
const barW = (innerW - barGap * (spendTrend30d.length - 1)) / spendTrend30d.length;
|
||||
const svg = svgEl('svg', { class: 'sparkline', viewBox: `0 0 ${width} ${height}`, preserveAspectRatio: 'xMidYMid meet' });
|
||||
for (let i = 0; i < spendTrend30d.length; i++) {
|
||||
const d = spendTrend30d[i];
|
||||
const h = (d.request_count / maxCount) * innerH;
|
||||
const x = padding.left + i * (barW + barGap);
|
||||
const y = padding.top + innerH - h;
|
||||
const rect = svgEl('rect', { x, y, width: barW, height: Math.max(1, h) });
|
||||
const providerBreakdown = Object.entries(d.by_provider || {}).map(([p, n]) => `${p}: ${n}`).join(', ');
|
||||
const title = svgEl('title');
|
||||
title.textContent = `${d.date} — ${fmtNum(d.request_count)} requests${providerBreakdown ? ' (' + providerBreakdown + ')' : ''}`;
|
||||
rect.appendChild(title);
|
||||
svg.appendChild(rect);
|
||||
}
|
||||
// Y-axis labels (max + min)
|
||||
const maxLabel = svgEl('text', { x: 4, y: padding.top + 10, 'font-size': 10, fill: '#6b7280' });
|
||||
maxLabel.textContent = fmtNum(maxCount);
|
||||
svg.appendChild(maxLabel);
|
||||
const minLabel = svgEl('text', { x: 4, y: height - 4, 'font-size': 10, fill: '#6b7280' });
|
||||
minLabel.textContent = '0';
|
||||
svg.appendChild(minLabel);
|
||||
// Date labels (first + last only at v0.3.0; mid labels deferred — added if needed by Phase 4 UX feedback)
|
||||
if (spendTrend30d.length > 0) {
|
||||
const firstDate = svgEl('text', { x: padding.left, y: height - 4, 'font-size': 10, fill: '#6b7280' });
|
||||
firstDate.textContent = spendTrend30d[0].date.slice(5);
|
||||
svg.appendChild(firstDate);
|
||||
const lastDate = svgEl('text', { x: width - padding.right - 28, y: height - 4, 'font-size': 10, fill: '#6b7280' });
|
||||
lastDate.textContent = spendTrend30d[spendTrend30d.length - 1].date.slice(5);
|
||||
svg.appendChild(lastDate);
|
||||
}
|
||||
target.appendChild(svg);
|
||||
target.appendChild(el('div', { class: 'meta', style: 'margin-top: 0.5rem; font-size: 0.8rem;' },
|
||||
'Hover bars for per-day provider breakdown · y-axis: requests per day (max ' + fmtNum(maxCount) + ')'));
|
||||
}
|
||||
|
||||
function renderChains(chains) {
|
||||
const target = document.getElementById('panel-chains');
|
||||
target.innerHTML = '';
|
||||
if (!Array.isArray(chains) || chains.length === 0) {
|
||||
target.appendChild(el('div', { class: 'panel-loading' }, 'No fallback chains triggered in window.'));
|
||||
return;
|
||||
}
|
||||
const table = el('table', null,
|
||||
el('thead', null, el('tr', null,
|
||||
el('th', null, '#'),
|
||||
el('th', null, 'Chain'),
|
||||
el('th', null, 'Count'),
|
||||
el('th', null, 'First seen'),
|
||||
el('th', null, 'Last seen'),
|
||||
)),
|
||||
);
|
||||
const tbody = el('tbody');
|
||||
chains.forEach((c, i) => {
|
||||
tbody.appendChild(el('tr', null,
|
||||
el('td', { class: 'num' }, String(i + 1)),
|
||||
el('td', null, el('span', { class: 'chain' }, c.chain.join(' → '))),
|
||||
el('td', { class: 'num' }, fmtNum(c.count)),
|
||||
el('td', null, c.first_seen || ''),
|
||||
el('td', null, c.last_seen || ''),
|
||||
));
|
||||
});
|
||||
table.appendChild(tbody);
|
||||
target.appendChild(table);
|
||||
}
|
||||
|
||||
function showError(message) {
|
||||
const slot = document.getElementById('banner-slot');
|
||||
slot.innerHTML = '';
|
||||
slot.appendChild(el('div', { class: 'banner error' }, message));
|
||||
}
|
||||
|
||||
function clearError() {
|
||||
document.getElementById('banner-slot').innerHTML = '';
|
||||
}
|
||||
|
||||
async function fetchDashboardData() {
|
||||
const res = await fetch('/v0/management/dashboard-data', {
|
||||
headers: { 'Accept': 'application/json' },
|
||||
credentials: 'same-origin',
|
||||
});
|
||||
if (res.status === 401) {
|
||||
showError('401 — owner-tier OLP key required. The dashboard is owner-only_block (ADR 0008 §8). Pass `Authorization: Bearer <owner-token>` via a proxy/extension; OLP itself doesn\'t accept browser cookies. Common path: SSH-tunnel + curl + tee the dashboard-data JSON, OR use a browser extension that adds the header.');
|
||||
throw new Error('owner_required');
|
||||
}
|
||||
if (!res.ok) {
|
||||
showError('Dashboard data fetch failed: HTTP ' + res.status);
|
||||
throw new Error('http_' + res.status);
|
||||
}
|
||||
return await res.json();
|
||||
}
|
||||
|
||||
async function refresh() {
|
||||
try {
|
||||
const data = await fetchDashboardData();
|
||||
clearError();
|
||||
const generated = data.generated_at ? new Date(data.generated_at) : new Date();
|
||||
document.getElementById('meta').textContent =
|
||||
'Last refresh: ' + generated.toLocaleString() + ' · next in ~30s';
|
||||
renderQuota(data.quota);
|
||||
render24h(data.window_24h, data.cache_hit_24h);
|
||||
renderTrend(data.spend_trend_30d);
|
||||
renderChains(data.top_fallback_chains_24h);
|
||||
} catch (err) {
|
||||
// Error banner already shown by fetchDashboardData; keep panels in
|
||||
// their last-good state. Console for operator debugging.
|
||||
console.warn('OLP dashboard refresh failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
function startPolling() {
|
||||
if (pollHandle !== null) return;
|
||||
pollHandle = setInterval(refresh, POLL_INTERVAL_MS);
|
||||
}
|
||||
function stopPolling() {
|
||||
if (pollHandle === null) return;
|
||||
clearInterval(pollHandle);
|
||||
pollHandle = null;
|
||||
}
|
||||
|
||||
// Pause when tab hidden, resume on visible (ADR 0008 § 6.5).
|
||||
document.addEventListener('visibilitychange', () => {
|
||||
if (document.visibilityState === 'hidden') stopPolling();
|
||||
else { refresh(); startPolling(); }
|
||||
});
|
||||
|
||||
// Initial fetch + start poll.
|
||||
refresh().finally(startPolling);
|
||||
})();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,422 @@
|
||||
# ADR 0007 — Multi-Key Auth (`lib/keys.mjs`)
|
||||
|
||||
- **Date:** 2026-05-25
|
||||
- **Status:** Accepted (D43-B, design-only — implementation D-days D44+ follow)
|
||||
- **Authors:** project maintainer (with AI drafting assistance)
|
||||
- **Related:**
|
||||
- OLP v0.1 spec § 4.5 (Auth & multi-key) — the planning authority for the `~/.olp/` layout used in § 3 below
|
||||
- ADR 0001 (project founding) — single-tenant family-scale framing; this ADR keeps that framing while enabling multi-identity isolation within a single deployment
|
||||
- ADR 0002 (plugin architecture) — `hints.cacheable` opt-out demonstrates the per-plugin gating pattern this ADR extends to per-key gating
|
||||
- ADR 0004 Amendment 5 (D40 `X-OLP-Fallback-Detail`) — explicitly defers owner-only header gating to "Phase 2 when `lib/keys.mjs` lands"; this ADR is that landing event
|
||||
- ADR 0005 (cache cross-provider) — D1 per-key isolation: the cache layer is already keyed by `keyId` (`Map<keyId, Map<cacheKey, CacheEntry>>` at `lib/cache/store.mjs:77-79`); this ADR fills the `keyId` source that is hardcoded to `'__anonymous__'` in `server.mjs` at v0.1.1
|
||||
- **Prior-art authority:** OCP `keys.mjs` (at the maintainer workstation `~/ocp/keys.mjs`, OCP v3.13.0 production reference) — model adapted; storage strategy diverges per § 11 below
|
||||
- **Phase 2 provenance:** `~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` (committed in `cc-rules` `d9da966`) captures the catch-up brief, lane separation, and the four amendments the maintainer pinned during D43-B drafting
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
OLP v0.1.1 ships with the cache namespace hardcoded to `'__anonymous__'` (server.mjs ~L502 buffered handler, ~L531 streaming handler). The cache data model in `lib/cache/store.mjs` is already segmented by `keyId` (per-key Map + per-key stats + per-key singleflight key composition), but the identity layer that produces a real `keyId` does not exist yet.
|
||||
|
||||
Phase 2 of OLP introduces multi-key authentication so a single OLP deployment can serve multiple human users (e.g., maintainer + family members + a CI client) with:
|
||||
|
||||
- **Per-key cache namespace isolation** — already wired in `store.mjs`; only the `keyId` source needs to land.
|
||||
- **Per-key audit trail** — which key issued which request, what provider/model served it, what fallback / cache outcome resulted.
|
||||
- **Per-key provider access scoping** — each key declares which providers it may invoke (`providers_enabled`).
|
||||
- **Owner-vs-guest gating** for debug/observability surfaces that should not leak to non-owner identities, specifically:
|
||||
- `/health` — currently returns full per-provider details to any caller. README has long claimed `/health` is owner-only (README.md § API Endpoints), but no auth gate has shipped. Phase 2 closes that gap.
|
||||
- `X-OLP-Fallback-Detail` — D40 / ADR 0004 Amendment 5 explicitly shipped the header **ungated** at v0.1 with the note "Phase 2 will re-introduce owner-vs-non-owner gating when `lib/keys.mjs` lands."
|
||||
|
||||
OCP solved an adjacent problem with `keys.mjs` (~417 LOC, SQLite-backed, single-tenant LAN mode). OLP cannot port that code verbatim — see § 11 (Node runtime baseline) — but the model (opaque key + per-key namespace + per-key audit + per-key quota) is the prior art this ADR adapts.
|
||||
|
||||
**Phase 2 is not a v1.x cross-phase deliverable.** `docs/v1x-roadmap.md` lists seven deferred items; only **#2 (multi-key auth)** is the Phase 2 mainline. The others (#1 streaming SF, #3 soft triggers, #4 `/health` `activeSpawns`, etc.) are triggered on demand and stay on the v1.x tracker.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
OLP Phase 2 ships **filesystem-only multi-key auth with opaque tokens**, structured for migratability to a SQLite-indexed model when Phase 3+ Dashboard / SQL-aggregate quota work justifies that change.
|
||||
|
||||
Three load-bearing choices:
|
||||
|
||||
| Axis | Choice | Rationale |
|
||||
|---|---|---|
|
||||
| **Storage** | Filesystem manifest per key (`~/.olp/keys/<key-id>/manifest.json`) + append-only audit ndjson (`~/.olp/logs/audit.ndjson`) | Matches v0.1 spec § 4.5 layout; zero-dep within current Node baseline (§ 11); trivially backed-up / human-inspectable / git-crypt-encryptable; per-key isolation natural via filesystem hierarchy |
|
||||
| **Token format** | Opaque `olp_<32-byte base64url>`; manifest stores SHA-256 hash, never plaintext | Mirrors OCP's `ocp_<24-byte>` opaque pattern; revocation is single-record (no JWT revocation-list problem); validation is single manifest read; family-scale has no stateless-validation pressure |
|
||||
| **Migration lane** | Manifest remains the declarative SPOT in all future revisions; SQLite (if added in Phase 3+) becomes a query-side index synced on every manifest/audit write | Forward path documented in § 13 — never a single-direction door; manifest schema is always source of truth |
|
||||
|
||||
The decision **rejects** three plausible alternatives:
|
||||
|
||||
- **Option 1 (direct SQLite port from OCP)** — rejected at v0.2.0 because of a runtime baseline mismatch documented in § 11, not because of any flaw in SQLite or in OCP's design.
|
||||
- **JWT tokens** — rejected because OLP has no stateless-validation pressure (the deployment is a single Node process; one manifest read per request is cheaper than the JWT-issuance / rotation / revocation-list infrastructure).
|
||||
- **Auto-detected "dev mode" anonymous fallback** — rejected because behavioural divergence based on heuristics (NODE_ENV, hostname, port, etc.) creates security-incident-prone surprises. Anonymous access is an explicit configuration toggle (§ 7) or it does not happen.
|
||||
|
||||
---
|
||||
|
||||
## 3. Storage layout (`~/.olp/`)
|
||||
|
||||
The layout below is normative for v0.2.0. Each path is binary in spec — present-and-honored or absent-and-defaulted. No path may be silently created with a different name.
|
||||
|
||||
```
|
||||
~/.olp/
|
||||
config.json — top-level config (existing); gains `auth` block per § 7
|
||||
keys/ — chmod 0700; per-key SPOT
|
||||
<key-id>/
|
||||
manifest.json — chmod 0600; JSON; schema in § 4
|
||||
logs/ — chmod 0700
|
||||
audit.ndjson — chmod 0600; one JSON event per line; schema in § 8
|
||||
providers/ — existing; per-provider auth artifact root
|
||||
anthropic/credentials.json
|
||||
openai/codex_token.json
|
||||
mistral/api_key.env
|
||||
cache/ — file-backed cache (📋 v1.x); chmod 0700 when introduced
|
||||
```
|
||||
|
||||
**`<key-id>` format.** Lowercase alphanumeric + hyphen + underscore, 8–32 chars, generated by the keygen command. NOT derived from the secret token — `<key-id>` is the public namespace identifier (cache key prefix, audit `key_id` field, log correlator); the secret token is separate.
|
||||
|
||||
**Why a directory per key (vs one `keys.json` index file).** Future per-key augmentation (per-key cache index, per-key provider-specific auth override, per-key rate-limit state) can land as additional files in `keys/<key-id>/` without re-writing a shared index. The directory is the namespace.
|
||||
|
||||
---
|
||||
|
||||
## 4. Manifest schema (`keys/<key-id>/manifest.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"id": "<key-id>",
|
||||
"name": "<human-label>",
|
||||
"token_hash": "<sha256-hex of the opaque token>",
|
||||
"token_hash_algo": "sha256",
|
||||
"owner_tier": "owner" | "guest",
|
||||
"providers_enabled": ["<provider-key>", ...] | "*",
|
||||
"quota": null,
|
||||
"created_at": "<ISO-8601 UTC>",
|
||||
"revoked_at": null | "<ISO-8601 UTC>",
|
||||
"last_used_at": null | "<ISO-8601 UTC>",
|
||||
"notes": "<optional free-form>"
|
||||
}
|
||||
```
|
||||
|
||||
Field semantics:
|
||||
|
||||
- **`schema_version`** — `1` at v0.2.0. Increment on any non-additive change to this schema. Implementation reads `schema_version` first; rejects unrecognized versions with a clear error.
|
||||
- **`id`** — matches the parent directory name. If they disagree, validation fails (`manifest_id_mismatch`).
|
||||
- **`name`** — human label for `olp keys list` output. Required, non-empty.
|
||||
- **`token_hash`** — SHA-256 of the plaintext token (lowercase hex). The plaintext token is NEVER stored.
|
||||
- **`token_hash_algo`** — `"sha256"` at v0.2.0. Schema-versioned forward-compat for future algorithm rotation.
|
||||
- **`owner_tier`** — `"owner"` grants full /health + X-OLP-Fallback-Detail visibility; `"guest"` does not (§ 7).
|
||||
- **`providers_enabled`** — array of provider keys (matching `models-registry.json` provider entries) OR literal `"*"` for all providers. Empty array `[]` means the key can authenticate but cannot dispatch any provider call (returns 403 with `key_no_provider_access`).
|
||||
- **`quota`** — `null` at Phase 2 (no enforcement). Reserved for Phase 3+ quota work. Implementations MUST read `null` as "no quota enforcement"; non-null shapes are deferred to a Phase 3 ADR amendment.
|
||||
- **`created_at`** — set at key creation; never modified.
|
||||
- **`revoked_at`** — `null` while active; set to current timestamp on revocation. Revoked keys fail validation with `401 key_revoked`; their manifest stays on disk for audit attribution.
|
||||
- **`last_used_at`** — updated on successful validation. Best-effort (lazy write OK; failure to update does NOT fail the request — § 6).
|
||||
- **`notes`** — optional; useful for "spouse's laptop", "Pi staging", etc.
|
||||
|
||||
**Schema rigidity.** Unrecognized fields cause a warn but not a reject (forward-compat). Missing required fields cause a reject (`manifest_invalid`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Token format
|
||||
|
||||
```
|
||||
olp_<32 bytes from crypto.randomBytes, base64url-encoded, no padding>
|
||||
```
|
||||
|
||||
- Prefix `olp_` is fixed (mirrors OCP's `ocp_`); enables grep / regex detection in logs / secret-scanners.
|
||||
- 32 bytes = 256 bits of entropy. base64url-encoded = 43 characters; total token length = 47 characters including prefix.
|
||||
- Hash with `crypto.createHash('sha256')` over the full token string (prefix included). Hex-lowercase the digest for `manifest.token_hash`.
|
||||
|
||||
**Why SHA-256, not argon2/bcrypt.** Argon2-class slow hashes are for low-entropy secrets (passwords). A 256-bit random token has no brute-force exposure in the relevant attack-cost model; SHA-256 is sufficient and ~6 orders of magnitude faster, which matters because validation runs on every request.
|
||||
|
||||
**No plaintext storage, ever.** The plaintext token leaves the keygen command (printed to stdout once) and the authenticated request (HTTP header). It is never logged, never written to manifest, never written to audit. The only persistent representation is the hash in `manifest.token_hash`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Atomic write & audit append
|
||||
|
||||
Two distinct write surfaces with different semantics:
|
||||
|
||||
### 6.1 Manifest writes (lifecycle events only)
|
||||
|
||||
Manifest writes fire ONLY on key lifecycle events: `createKey`, `revokeKey`, `updateKey` (e.g., setting `providers_enabled`), and `touchLastUsed` (the lazy `last_used_at` update). Manifest is **not** written per request — per-request state goes to audit.
|
||||
|
||||
Atomic write pattern (POSIX):
|
||||
|
||||
1. Compute target path: `~/.olp/keys/<key-id>/manifest.json`.
|
||||
2. Write to tmpfile in same directory: `~/.olp/keys/<key-id>/manifest.json.tmp.<pid>.<counter>`.
|
||||
3. `fsync()` the tmpfile fd.
|
||||
4. `rename()` tmpfile → final path (same-filesystem atomic).
|
||||
5. Directory mode 0700, file mode 0600 enforced on every write.
|
||||
|
||||
POSIX-strict atomic-replace also requires `fsync()` on the containing directory after the rename to guarantee survival of an OS crash mid-flush. Phase 2 deliberately omits the directory fsync: the single-process family-scale deployment model accepts a tiny window where a rename can be lost under abrupt host crash. The trade-off is documented here so a future POSIX-strict deployment knows where to add the step.
|
||||
|
||||
Failure semantics:
|
||||
- Step 2/3/4 failure → throw; caller handles. Lifecycle commands (`olp keygen` / `olp keys revoke`) report failure to the operator and exit non-zero. Server requests do not trigger lifecycle writes (the `touchLastUsed` path is best-effort — see 6.3).
|
||||
|
||||
### 6.2 Audit ndjson appends (per-request)
|
||||
|
||||
Per-request audit events append a single newline-terminated JSON object to `~/.olp/logs/audit.ndjson`.
|
||||
|
||||
Append pattern:
|
||||
|
||||
1. Serialize event (§ 8 schema) with trailing `\n`. Serialization fires AFTER `status_code` is determined and `latency_ms` is measured (i.e., after the request handler emits the response, around `res.end()` finalization). This pinning is what makes acceptance criterion #2 testable — the 401-on-anonymous case records `status_code: 401` + `latency_ms` in the same audit event.
|
||||
2. `fs.appendFile(path, line, { mode: 0o600 })` (Node default opens with append flag).
|
||||
3. On EAGAIN / EBUSY / ENOSPC: log warn `audit_append_failed_once` + retry once (synchronous, no backoff at Phase 2 — family-scale write rate makes contention rare).
|
||||
4. On second-failure: log warn `audit_append_dropped` with the failure reason + a per-process drop counter; **do not block the request**; **do not buffer** (memory buffer is a forward path in § 13, deliberately not in Phase 2 scope).
|
||||
|
||||
Failure semantics:
|
||||
- Audit append failure NEVER fails the request. Auditing is observability, not authorization.
|
||||
- Dropped audit events surface via the warn log and the dropped-count metric (exposed in /health owner-tier view per § 7).
|
||||
|
||||
### 6.3 `last_used_at` lazy update (revoke-dominates-touch)
|
||||
|
||||
The `touchLastUsed` write goes through the same atomic-write pattern as 6.1, but is fired async after request response is dispatched. Failure logs warn `last_used_update_failed` and does NOT fail the request.
|
||||
|
||||
**Read-modify-write with revoke preservation.** `touchLastUsed` MUST:
|
||||
|
||||
1. Re-read the latest manifest from disk inside the per-key write-lock (§6.4) — not reuse the snapshot the validating request held.
|
||||
2. If `revoked_at` is non-null in the freshly-read manifest, NO-OP (do not write). A revocation occurred between request validation and this lazy touch; the request was the last legitimate use of the now-revoked key.
|
||||
3. Otherwise, merge the new `last_used_at` value into the freshly-read manifest, preserving ALL other fields including `revoked_at`, and write via the atomic-rename pattern.
|
||||
|
||||
This protects against the failure mode where a stale manifest snapshot held by the touch path overwrites a fresh revoke and silently clears `revoked_at` back to `null`. The safety property is **revoke dominates touch**: any ordering of CLI revoke and server-side `touchLastUsed` (revoke-then-touch, touch-then-revoke, or interleaved) leaves a revoked manifest. This is the contract that makes acceptance criterion #6 (post-revoke 401 within the next request) honest under concurrent CLI revoke + in-flight server request.
|
||||
|
||||
### 6.3.5 No in-process validation cache (Phase 2)
|
||||
|
||||
Token validation MUST hit the manifest on every authenticated request at Phase 2 — implementations MUST NOT introduce an in-process LRU / TTL cache of validation results. Rationale: revocation must take effect on the next request without an invalidation hop; the family-scale request rate makes per-request manifest read O(1) on the OS file-system cache. This is the contract that makes acceptance criterion #6 (post-revoke 401 within the next request) honest. A validation cache is a forward-path consideration if Phase 3+ load profile demands it; a separate ADR amendment ratifies the cache shape + invalidation contract before any cache code lands.
|
||||
|
||||
### 6.4 Locking (single-process Phase 2)
|
||||
|
||||
OLP at v0.2.0 is a single Node process per host. Concurrent manifest writes from inside the process are serialized via an in-process Map of per-key write-locks (`Map<key-id, Promise>`). Concurrent writes from outside the process (e.g., maintainer running `olp keys revoke` while server is running) are not protected by file locks at Phase 2.
|
||||
|
||||
Safety frame: the atomic-rename pattern guarantees corruption-free file content (no partial-merge state on disk), and the **read-before-write discipline in §6.3** makes the worst case "stale `last_used_at` field" (observability-grade) rather than "revoked_at silently cleared" (security-grade). Without §6.3, a touch carrying a pre-revoke snapshot could overwrite revoke and break acceptance criterion #6; with §6.3, any interleaving of revoke and touch leaves a revoked manifest. The CLI `revoke` writer always wins the dimension that matters; the touch writer may lose its `last_used_at` update if it raced a revoke (acceptable — the revoked key will not be used again).
|
||||
|
||||
Forward path: file-locking (`flock(2)`) is reserved if a future Phase introduces multi-writer scenarios (e.g., a setup wizard process running alongside the server). With multi-writer, §6.3's read-before-write still holds the revoke-dominates-touch contract; file-locking only adds defense-in-depth against rare time-of-check-time-of-use windows where two processes both re-read a non-revoked manifest, then both write back with the touch path silently dropping a concurrent in-flight revoke from a third writer.
|
||||
|
||||
---
|
||||
|
||||
## 7. Owner / guest / anonymous gating
|
||||
|
||||
### 7.1 The three identity classes
|
||||
|
||||
| Class | Source | Cache namespace | `/health` visibility | `X-OLP-Fallback-Detail` visibility | `/v1/chat/completions` |
|
||||
|---|---|---|---|---|---|
|
||||
| **owner** | Valid OLP key with `owner_tier: "owner"` | per-key (`<key-id>`) | full per-provider details | yes (header emitted) | yes |
|
||||
| **guest** | Valid OLP key with `owner_tier: "guest"` | per-key (`<key-id>`) | trimmed (`{ status, version }` only) | no (header suppressed) | yes (scoped by `providers_enabled`) |
|
||||
| **anonymous** | No `Authorization` / `x-api-key` header, AND `config.json auth.allow_anonymous: true` | `__anonymous__` (shared) | trimmed (`{ status, version }` only) | no (header suppressed) | yes |
|
||||
|
||||
When `auth.allow_anonymous: false` (default) and no key is presented, all routes return `401 auth_required`.
|
||||
|
||||
### 7.2 Configuration
|
||||
|
||||
`~/.olp/config.json` gains an `auth` block:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"allow_anonymous": false,
|
||||
"owner_only_endpoints": ["/health", "/v0/management/quota"],
|
||||
"fallback_detail_header_policy": "owner_only"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **`allow_anonymous`** — default `false`. When `true`, requests without a key are accepted and namespaced under the legacy `__anonymous__` cache keyId.
|
||||
- **`owner_only_endpoints`** — list of HTTP paths returning trimmed payloads to non-owner identities. `/health` is the canonical example.
|
||||
- **`fallback_detail_header_policy`** — `"owner_only"` (default) emits `X-OLP-Fallback-Detail` only to owner tier. `"all"` reverts to v0.1.1 ungated behaviour. `"none"` suppresses unconditionally. The policy is the v0.1.1 → v0.2.0 migration knob for operators who want to delay re-gating.
|
||||
|
||||
### 7.3 Environment-based behaviour is rejected
|
||||
|
||||
Phase 2 deliberately does NOT auto-detect "dev" vs "production" via `NODE_ENV`, `hostname`, port, or any other heuristic. The rule is: `config.json auth.allow_anonymous` is the truth, and the operator sets it explicitly. Behavioural divergence on environment heuristics is a known source of "it works locally" security incidents and is out of scope by design.
|
||||
|
||||
---
|
||||
|
||||
## 8. Audit ndjson schema
|
||||
|
||||
One JSON object per line (newline-terminated, UTF-8), written by the per-request audit-append path (§ 6.2).
|
||||
|
||||
```json
|
||||
{
|
||||
"ts": "<ISO-8601 UTC>",
|
||||
"key_id": "<key-id>" | "__anonymous__" | "__env_owner__",
|
||||
"owner_tier": "owner" | "guest" | "anonymous",
|
||||
"method": "POST" | "GET" | ...,
|
||||
"path": "/v1/chat/completions" | "/v1/models" | ...,
|
||||
"provider": "<provider-key>" | null,
|
||||
"model": "<requested-model>" | null,
|
||||
"status_code": 200 | 401 | 503 | ...,
|
||||
"latency_ms": <int>,
|
||||
"cache_status": "hit" | "miss" | "bypass" | null,
|
||||
"fallback_hops": <int>,
|
||||
"tried_providers": ["<provider-key>", ...],
|
||||
"error_code": null | "<ProviderError code>",
|
||||
"ir_request_hash": "<short hex>" | null,
|
||||
"chain_id": "<correlator>" | null
|
||||
}
|
||||
```
|
||||
|
||||
Field origin:
|
||||
|
||||
- `ts` / `key_id` / `owner_tier` — set by the auth middleware.
|
||||
- `method` / `path` / `status_code` / `latency_ms` — set by the request handler.
|
||||
- `provider` / `model` / `cache_status` / `fallback_hops` / `tried_providers` / `error_code` — sourced from the existing D28 per-hop log fields (no new computation; same shapes the structured log already exposes).
|
||||
- `ir_request_hash` / `chain_id` — sourced from D28 fields directly; enable join across audit, structured log, and the `X-OLP-Fallback-Detail` tuple.
|
||||
|
||||
**No PII.** Audit deliberately captures NO request body, NO response body, NO IR-message content. Hash + shape only. This is a personal/family deployment property; do not relax without a separate ADR amendment.
|
||||
|
||||
**`tried_providers` semantics (clarification, D53 / 2026-05-25).** The field captures the list of providers the server **actually dispatched a spawn against** for this request. A provider that was configured in the chain but filtered out by `providers_enabled` gating (resulting in 403 `key_no_provider_access`) is NOT included — the key didn't try the provider, the gate did. On the 403 path `tried_providers` is the empty array. The configured-but-blocked chain providers appear in the human-readable error message returned to the client but are intentionally NOT surfaced in the audit event, so downstream queries like "which providers did key X actually call" stay accurate. This semantic was implicit in the D45 implementation (where the field was set to the original chain on 403, misrepresenting "tried"); D53 corrects the implementation + amends this section to spell out the intent.
|
||||
|
||||
**Rotation.** Phase 2 does NOT rotate `audit.ndjson`. Rotation policy ships in Phase 3 — daily rotation via `lib/audit.mjs` `_maybeRotateAudit` synchronous trigger on first append after UTC date change + optional `bin/olp-audit-rotate.mjs` external cron. See ADR 0008 § 5.
|
||||
|
||||
---
|
||||
|
||||
## 9. Bootstrap & recovery
|
||||
|
||||
### 9.1 Minimal keygen command surface
|
||||
|
||||
Phase 2 MUST ship at least one executable entry that:
|
||||
|
||||
1. Generates an opaque OLP token (§ 5 format).
|
||||
2. Computes its SHA-256 hash.
|
||||
3. Writes a `keys/<key-id>/manifest.json` per § 4 with `owner_tier: "owner"` (first key) or as specified by flag.
|
||||
4. Prints the plaintext token to stdout **exactly once**. The token is otherwise never logged.
|
||||
5. Returns non-zero on any failure (manifest path conflict, filesystem permission, etc.).
|
||||
|
||||
The concrete shape — `npx olp keygen --owner`, `node bin/keygen.mjs --owner`, `node lib/keys/cli.mjs keygen --owner`, etc. — is an implementation choice and lands at D44 or D45. ADR 0007 does not pin the shape; it pins the requirement that the surface exists and is reproducible without manual file editing.
|
||||
|
||||
### 9.2 First-run flow
|
||||
|
||||
When `~/.olp/keys/` is empty AND `auth.allow_anonymous: false` (defaults), the server refuses to start `/v1/chat/completions` requests with a clear `401 no_keys_configured` until the operator runs the keygen command. The server itself does NOT auto-generate a key on first run — explicit operator action is required so the plaintext-once contract (§ 9.1 step 4) is honored on a terminal the operator can see.
|
||||
|
||||
When `~/.olp/keys/` is empty AND `auth.allow_anonymous: true`, the server starts normally and serves all requests under `__anonymous__`. Useful for dev / single-user-no-multi-tenancy deployments.
|
||||
|
||||
### 9.3 Owner key loss / rotation
|
||||
|
||||
If the operator loses their owner token, recovery is `<keygen-command> --owner --force`:
|
||||
|
||||
1. Generate a fresh owner key (new `<key-id>`, new plaintext).
|
||||
2. Mark all existing `owner_tier: "owner"` keys' `revoked_at` to current timestamp. (Existing guest keys are not affected.)
|
||||
3. Print the new plaintext once.
|
||||
|
||||
The old token is permanently invalid after revocation; the manifest stays on disk for audit attribution.
|
||||
|
||||
### 9.4 `OLP_OWNER_TOKEN` environment override
|
||||
|
||||
For headless / CI / containerized deployments, the env var `OLP_OWNER_TOKEN` is honored:
|
||||
|
||||
- Server startup reads `OLP_OWNER_TOKEN`. If set, the value is treated as a synthetic owner identity with stable `key_id: "__env_owner__"`.
|
||||
- The plaintext token is NEVER logged, NEVER written to manifest, NEVER written to audit. The raw token leaves the env var and the request `Authorization` header only.
|
||||
- Cache namespacing uses `__env_owner__` as the `keyId`, isolating env-owner traffic from filesystem-owner traffic.
|
||||
- Audit attribution uses `key_id: "__env_owner__"` and `owner_tier: "owner"`.
|
||||
- Server startup logs warn `non_persistent_owner_token` with no token material, alerting the operator that the env-owner identity will disappear on restart unless re-set.
|
||||
|
||||
Filesystem-stored owner keys (from § 9.1/9.2) continue to validate independently when `OLP_OWNER_TOKEN` is set; the env-owner is an additive credential, not a replacement.
|
||||
|
||||
**Token-collision policy.** Hash-collision between an `OLP_OWNER_TOKEN` plaintext and a filesystem-stored key's plaintext is undefined behaviour at Phase 2 (cache namespacing would diverge silently between `__env_owner__` and the filesystem `<key-id>`, while audit attribution would split). Operators MUST NOT reuse the same plaintext token across both surfaces. A future Phase MAY add a collision-detection startup check; not in Phase 2 scope.
|
||||
|
||||
---
|
||||
|
||||
## 10. Acceptance criteria
|
||||
|
||||
Implementation D-days (D44+) MUST land tests covering:
|
||||
|
||||
1. **Per-key cache isolation** — Two keys A and B with identical request payloads do NOT share cache. `cache_status` is `miss` for both first calls and `hit` for the second call from the SAME key only.
|
||||
2. **Anonymous prod-default off** — With `auth.allow_anonymous: false` (no override), a request without a key receives `401 auth_required`; the audit event is recorded with `key_id: "__anonymous__"` and `status_code: 401`.
|
||||
3. **Anonymous dev-mode on** — With `auth.allow_anonymous: true`, the same request succeeds with `keyId="__anonymous__"`.
|
||||
4. **Owner-vs-guest /health gating (with default `auth.owner_only_endpoints` config)** — Owner key sees the full per-provider `providers` map in `/health`; guest key + anonymous see only `{ status, version }`. Test rephrases if the operator's `owner_only_endpoints` config does not include `/health` (test must assert the same gating predicate the config produces, not a hardcoded trimmed payload shape).
|
||||
5. **Owner-vs-guest X-OLP-Fallback-Detail gating** — Same response payload for both owner and guest; header present for owner only.
|
||||
6. **Key revocation** — After `revoke`, subsequent requests with that token return `401 key_revoked` within the next request (no caching of validation).
|
||||
7. **Manifest atomicity + revoke-dominates-touch (§ 6.3, § 6.4)** — Concurrent `revoke` + `touchLastUsed` writes do not corrupt the manifest AND revoke always survives. Test: spawn two writers racing on the same key (revoke vs `touchLastUsed`) under three orderings — revoke-then-touch, touch-then-revoke, and interleaved (touch reads pre-revoke snapshot, then revoke writes, then touch attempts write). For all three orderings, assert: (a) final file parses as valid JSON; (b) `revoked_at` is non-null and equals the revoke writer's timestamp; (c) `last_used_at` may have either writer's value. The test FAILS if any interleaving produces `revoked_at: null` after the revoke writer completed. This pins the §6.3 read-before-write discipline.
|
||||
8. **Audit ndjson round-trip** — Every line in `audit.ndjson` parses as valid JSON; every required field present; PII fields (message content, response content) absent.
|
||||
9. **Bootstrap keygen surface** — The minimal keygen command (whatever shape D44 chooses) runs end-to-end without manual file editing, produces a working owner key, and prints the plaintext exactly once.
|
||||
10. **`OLP_OWNER_TOKEN` env override** — With the env var set, a request bearing the env token validates as `keyId="__env_owner__"` with `owner_tier="owner"`; the raw token does NOT appear in any log line, audit event, or stack trace.
|
||||
11. **`providers_enabled` scope enforcement** — A guest key with `providers_enabled: ["anthropic"]` requesting `model` that routes to `openai` receives `403 key_no_provider_access` and an audit event with the rejection reason.
|
||||
|
||||
---
|
||||
|
||||
## 11. Node baseline / storage portability
|
||||
|
||||
Option 2 (filesystem-only) was chosen at v0.2.0 over Option 1 (direct port of OCP's SQLite-backed `keys.mjs`) because of a runtime-baseline mismatch, not a critique of SQLite or of OCP's design.
|
||||
|
||||
Evidence:
|
||||
|
||||
- OLP `package.json` declares `engines.node` `">=18"` (file line 11).
|
||||
- CI test matrix in `.github/workflows/test.yml` runs Node 20 and 24 (file line 13).
|
||||
- `node:sqlite` was added in Node **v22.5.0**; v22.12 still required the `--experimental-sqlite` runtime flag to import; current Node API docs mark the module as **Release Candidate** (post-experimental but pre-stable). Source: https://nodejs.org/api/sqlite.html (retrieved during D43-B drafting 2026-05-25).
|
||||
|
||||
Adopting `node:sqlite` at v0.2.0 would require, in this order:
|
||||
|
||||
1. Raise `engines.node` to a version where the API is at minimum non-flag-gated. Per Node's release-history docs — v22.5.0 added the API behind `--experimental-sqlite` (source: https://nodejs.org/download/release/v22.12.0/docs/api/sqlite.html confirms v22.12 still required the flag); the module moved past flag-gating in **v22.13.0 (LTS line)** and **v23.4.0 (current line)**; the API entered **Release Candidate at v25.7.0** per current docs (https://nodejs.org/api/sqlite.html). The minimum non-flag-gated baseline for `engines.node` is therefore `>=22.13.0` (or `>=23.4.0` on the non-LTS path). A stable (post-RC) baseline is TBD pending future Node releases beyond v25.x.
|
||||
2. Update the CI test matrix to drop Node 20 (or move the SQLite-using code behind a runtime feature check that exercises both code paths in CI).
|
||||
3. Accept Release-Candidate API stability risk in the project's storage layer for the period until the API moves to stable.
|
||||
|
||||
These three are achievable but are not zero-cost and have second-order effects (e.g., existing Node 20 deployments by family clients break on upgrade). Phase 2 does not undertake them; § 13 documents the forward path.
|
||||
|
||||
**Decision posture statement.** "SQLite is good; the runtime baseline says not yet."
|
||||
|
||||
---
|
||||
|
||||
## 12. Out of scope (Phase 3+)
|
||||
|
||||
The following are deliberately deferred from Phase 2 and tracked elsewhere:
|
||||
|
||||
- **Dashboard (`dashboard.html`)** — owner-only multi-provider quota / fallback / cache-hit-rate panels. Deferred to **Phase 3**. (Was originally bundled into "Phase 6" in the pre-v0.1.1 README phase plan; the post-D43-A plan re-aligned this to Phase 3.)
|
||||
- **Quota enforcement (`manifest.quota` non-null shapes)** — manifest schema reserves the field; semantics + enforcement land in a Phase 3 ADR amendment.
|
||||
- **Audit query layer / rotation** — `audit.ndjson` is append-only at Phase 2; rotation policy + indexed query lands with Dashboard work (Phase 3).
|
||||
- **Per-key per-provider auth artifact mapping** — Phase 2 uses the global `~/.olp/providers/<name>/` artifacts for all keys. Per-key override (e.g., two OLP keys each authenticated to a different OpenAI Codex account) is a Phase 3+ concern; the spec § 4.5 phrasing "Multi-key support per provider" anticipates this without locking the design.
|
||||
- **Audit memory buffer on append failure** — see § 6.2 note; deliberate forward-path-only.
|
||||
- **File-locking (`flock(2)`)** — see § 6.4 note.
|
||||
|
||||
---
|
||||
|
||||
## 13. Future forward — Option 3 migration (Phase 3+)
|
||||
|
||||
When Dashboard / SQL-aggregate quota / >5 users / multi-second audit-query workload arrives, OLP's storage layer migrates to a **hybrid** model that retains manifest as the declarative SPOT and adds a SQLite-indexed query mirror.
|
||||
|
||||
Required preconditions BEFORE any migration commit:
|
||||
|
||||
1. A separate prior PR raises `engines.node` and updates the CI matrix per § 11. This PR ships independently of any storage change.
|
||||
2. An ADR amendment to this file documents the migration trigger (which of the criteria above fired) and the schema mapping from manifest → SQLite rows.
|
||||
3. The migration code is a one-shot sync that reads every existing manifest, replays the audit log, populates SQLite from scratch, then begins dual-writing. Manifest writes remain authoritative; SQLite is rebuildable from manifest + audit at any time.
|
||||
|
||||
The migration is one-way (additive — SQLite gets added; manifest stays). Reverting from hybrid to manifest-only is supported by stopping SQLite writes and deleting the DB file.
|
||||
|
||||
**Forward-path audit memory buffer.** If audit append failures become non-rare (operational hint: `audit_append_dropped` count exceeds threshold in /health), Phase 3+ may add an in-process bounded buffer that flushes opportunistically. The buffer's design (size cap, flush interval, persistence on shutdown) is out of scope for Phase 2 and is a separate ADR amendment.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- Closes the long-standing `lib/keys.mjs` 📋-Planned gap in AGENTS.md / README.md / v1x-roadmap.md.
|
||||
- Lets D40 `X-OLP-Fallback-Detail` re-gate per its v0.1 deferral note.
|
||||
- Lets README's long-standing claim "/health is owner-only" become factually true.
|
||||
- Per-key cache namespacing becomes observable behaviour (was a latent affordance only).
|
||||
- Family members can each have their own OLP key without sharing cache state.
|
||||
- Audit trail per request enables troubleshooting questions ("did my call hit cache?", "which key triggered the fallback to mistral?") without inspecting logs.
|
||||
|
||||
**Negative / trade-offs:**
|
||||
|
||||
- Filesystem audit is O(N) for any aggregate query — acceptable until Phase 3 Dashboard work.
|
||||
- Manifest atomicity at multi-writer scale is not bulletproof — see § 6.4; mitigated by the single-process Phase 2 deployment model.
|
||||
- The plaintext-once contract puts UX burden on the keygen command output — operators must capture the token immediately on creation; lost = revoke + regenerate.
|
||||
- Existing OCP users migrating will need new OLP keys (OCP's SQLite-backed keys are not portable to OLP's manifest layout — § 9 "Migration from OCP" in `scripts/migrate-from-ocp.mjs` 📋 Phase 7 may add a one-shot translator; not in Phase 2 scope).
|
||||
|
||||
**Reversibility:**
|
||||
|
||||
- Migration to Option 3 hybrid (§ 13) is supported and explicitly planned.
|
||||
- Reverting Phase 2 entirely would require restoring the `__anonymous__` hardcoding in `server.mjs` and removing the auth middleware. The decision is reversible but no concrete trigger has been imagined; the decision is treated as durable.
|
||||
|
||||
---
|
||||
|
||||
## Authority citations
|
||||
|
||||
- **OLP v0.1 spec § 4.5** (planning authority for `~/.olp/` layout in § 3) — at `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations.
|
||||
- **OCP `keys.mjs`** (prior-art reference for opaque-key + per-key isolation model) — at `~/ocp/keys.mjs` on the maintainer's workstation; OCP v3.13.0 production.
|
||||
- **Phase 2 kickoff handoff** (decision provenance for Option 2 + opaque + four amendments) — `~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` committed in `cc-rules` `d9da966`.
|
||||
- **Node `node:sqlite` documentation** (rejection rationale for Option 1 in § 11) — https://nodejs.org/api/sqlite.html (retrieved 2026-05-25).
|
||||
- **`lib/cache/store.mjs:77-79, :287`** (proof that per-keyId namespace + singleflight composition are wired and ready to receive a real `keyId`).
|
||||
- **`server.mjs:502, :531`** (the two hardcoded `'__anonymous__'` call sites Phase 2 implementation replaces).
|
||||
- **`server.mjs:392, :1072, :1101`** (the three call sites Phase 2 implementation gates: `/health` handler entry and the two `X-OLP-Fallback-Detail` header-write paths).
|
||||
- **ADR 0004 Amendment 5** (D40 ungated header + Phase 2 re-gating deferral) — `docs/adr/0004-fallback-engine.md`.
|
||||
- **CLAUDE.md `release_kit.phase_rolling_mode` `current_pre_release_identifier`** = `"0.2.0-phase2"` — confirms this ADR lands in the Phase 2 sprint.
|
||||
@@ -0,0 +1,372 @@
|
||||
# ADR 0008 — Dashboard + Audit Query Layer (Phase 3)
|
||||
|
||||
- **Date:** 2026-05-25
|
||||
- **Status:** Accepted (D48, design-only — implementation D-days D49–D54 follow; Phase 3 close = v0.3.0)
|
||||
- **Authors:** project maintainer (with AI drafting assistance)
|
||||
- **Related:**
|
||||
- OLP v0.1 spec § 4.6 (Dashboard requirements — port from OCP with multi-provider support) and § 4.7 (observability endpoints)
|
||||
- ADR 0007 § 12 (Phase 3+ out-of-scope: Dashboard, audit query layer, rotation) — this ADR opens those deferrals
|
||||
- ADR 0007 § 13 (Option 3 hybrid migration to SQLite) — explicitly **NOT** triggered by Phase 3; in-memory ndjson scan is the v0.3.0 query model
|
||||
- ADR 0007 § 7 (Identity classes) — Dashboard auth gating reuses owner-vs-non-owner pattern (Dashboard is owner-only)
|
||||
- ADR 0007 § 8 (Audit ndjson schema) — the data source the query layer reads
|
||||
- ADR 0004 Amendment 2 (soft triggers deferred to v1.x) — quota panel sources from `provider.quotaStatus()` which is a contract method; per-provider returns what it can or `null`
|
||||
- D45 reviewer P2 deferral on `tried_providers` semantics — addressed in this Phase as D53 (separate D-day; not in ADR 0008 scope)
|
||||
- **Phase 3 kickoff authority:** maintainer "go" + standing-autopilot grant (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a` — the grant explicitly excludes Phase 3+ as needing new authorization; the "go" supplied that)
|
||||
- **Lanes pinned by maintainer 2026-05-25 (Phase 3 kickoff brief):**
|
||||
- Lane 1 Dashboard tech stack: **A** — static HTML + vanilla JS + fetch (no build step; matches OLP "no bundler" ethos)
|
||||
- Lane 2 Audit query model: **A** — in-memory scan of audit ndjson per request (O(N) per query; family-scale acceptable; SQLite deferred to Option 3 trigger per ADR 0007 § 13)
|
||||
- Lane 3 Audit rotation: **B** — daily rotation, files named `audit-YYYY-MM-DD.ndjson` (UTC date)
|
||||
- Lane 4 Refresh: **A** — page poll every 30s (no SSE infra introduction)
|
||||
- Lane 5 Dashboard scope: **B** — full per spec § 4.6 (quota + per-provider counts/cache/fallback last 24h + multi-provider spend trend last 30d + top fallback chains by trigger count)
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
OLP v0.2.0 ships per-key audit ndjson at `~/.olp/logs/audit.ndjson` (ADR 0007 § 8) but provides no aggregate query surface or visualization. The audit file grows unbounded, and operators must `tail`/`grep` to observe basic facts ("which provider served the most requests today", "what's my cache hit rate", "how often did the chain fall back to OpenAI"). Phase 3 closes this gap with:
|
||||
|
||||
1. **`lib/audit-query.mjs`** — an in-memory aggregator that scans `~/.olp/logs/audit-*.ndjson` files in a configurable time window and returns shaped summaries.
|
||||
2. **`server.mjs` `/v0/management/*` endpoints** — three owner-only JSON endpoints exposing the aggregate data: `/v0/management/dashboard-data`, `/v0/management/quota`, `/cache/stats`.
|
||||
3. **`dashboard.html`** — a single static HTML file served from `/dashboard` (owner-only) that fetches the JSON endpoints, renders 4 panels, and polls every 30s.
|
||||
4. **Daily audit rotation** — at UTC midnight (or on first append after a UTC-date change), the live `audit.ndjson` is renamed to `audit-YYYY-MM-DD.ndjson` and a fresh `audit.ndjson` opens. Cross-file queries handle the rolling 30-day window.
|
||||
|
||||
Phase 3 deliberately **does not** add a build step, a database, or per-key UI write surface. The first three are out of scope (Option 3 hybrid is § 13's forward path; SQLite has a Node-baseline blocker per § 11). The last is a security surface that warrants a separate review pass (Phase 4+).
|
||||
|
||||
Phase 3 is the natural home for OCP's `dashboard.html` port (v0.1 spec § 4.6 — "Port OCP's `dashboard.html` with multi-provider support"). OCP's dashboard was single-provider; OLP's is multi-provider, which is the substantive change. The HTML structure is otherwise lifted.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
The five lanes above are normative. The deviation lattice they sit in:
|
||||
|
||||
| Lane | Pinned | Rejected (why) |
|
||||
|---|---|---|
|
||||
| **1. Tech stack** | Static HTML + vanilla JS + fetch | SSR (Node template literals) — adds server-side render path; CSP harder. SPA — adds build step, violates ethos. |
|
||||
| **2. Query model** | In-memory scan of `audit-*.ndjson` per request | SQLite indexed mirror — touches ADR 0007 § 13 migration → engines bump prerequisite. In-memory rolling aggregate — complex (per-write incremental + window expiry), correctness risk. |
|
||||
| **3. Rotation** | Daily UTC rotation (`audit-YYYY-MM-DD.ndjson`) | No rotation — single file grows unbounded at family scale ~10–100 lines/day but a year is ~10–50k lines, still ok but no natural query unit. Size-based (100MB / keep 5) — equivalent complexity, query range less intuitive. |
|
||||
| **4. Refresh** | Page poll every 30s | SSE push — adds server-side subscriber state; not justified at family scale. Static-at-load — UX too poor. |
|
||||
| **5. Dashboard scope** | Full per spec § 4.6 | Minimal (quota + cache + fallback only) — spec is already drafted; full is ~1 D-day more for trend + top-chains panels. Plus key-mgmt UI — security surface delta, Phase 4+. |
|
||||
|
||||
**Phase 3 does not** introduce: a database, a build step, an SPA framework, SSE for dashboard, or web-side key management. Each is a future-phase concern (Option 3 hybrid; SSE for dashboard if poll latency becomes pain; key-mgmt UI after a security review pass).
|
||||
|
||||
---
|
||||
|
||||
## 3. Storage layout (`~/.olp/logs/`)
|
||||
|
||||
```
|
||||
~/.olp/logs/
|
||||
audit.ndjson — live append target (Phase 2 D45)
|
||||
audit-2026-05-24.ndjson — yesterday (after rotation)
|
||||
audit-2026-05-23.ndjson
|
||||
audit-2026-05-22.ndjson
|
||||
...
|
||||
```
|
||||
|
||||
Files are append-only (no in-place edits). Rotation atomically renames the live file and opens a fresh one. All files have mode 0600; the `logs/` directory is 0700.
|
||||
|
||||
**Retention policy at v0.3.0:** unbounded by default (operator manages disk). A Phase 3+ amendment may add automatic retention (`olp_audit_max_days` config) once an observed operational need exists.
|
||||
|
||||
---
|
||||
|
||||
## 4. Audit query layer (`lib/audit-query.mjs`)
|
||||
|
||||
A new module that reads the rotated + live audit files in a date range and returns aggregate summaries. Per-call O(N) where N = total lines in the date range (family scale: thousands per day = trivial).
|
||||
|
||||
### 4.1 Public API
|
||||
|
||||
```js
|
||||
// Read all audit lines in [startMs, endMs); returns iterator of parsed events.
|
||||
// Skips malformed lines (logs warn) so a corrupted day doesn't kill the query.
|
||||
export function* readAuditWindow({ startMs, endMs, olpHome }): Iterator<AuditEvent>;
|
||||
|
||||
// Aggregate request shape over a window. Returns:
|
||||
// {
|
||||
// window: { startMs, endMs },
|
||||
// request_count, status_2xx, status_4xx, status_5xx,
|
||||
// by_provider: { [providerKey]: { count, cache_hit, cache_miss, cache_bypass, fallback_count } },
|
||||
// by_owner_tier: { owner: N, guest: N, anonymous: N },
|
||||
// by_path: { '/v1/chat/completions': N, '/v1/models': N },
|
||||
// median_latency_ms, p95_latency_ms,
|
||||
// }
|
||||
export function aggregateRequests({ windowMs, olpHome }): RequestAggregate;
|
||||
|
||||
// Top-N fallback chains by trigger count in window. Returns sorted array:
|
||||
// [{ chain: ['anthropic', 'openai'], count: 42, first_seen, last_seen }, ...]
|
||||
export function topFallbackChains({ windowMs, limit, olpHome }): FallbackChainSummary[];
|
||||
|
||||
// Daily series of request_count + latency_median over N days. Returns sorted array:
|
||||
// [{ date: '2026-05-22', request_count, median_latency_ms, by_provider }, ...]
|
||||
export function spendTrendDaily({ days, olpHome }): DailySpendEntry[];
|
||||
|
||||
// Cache hit rate snapshot (in-memory cacheStore stats + audit-derived numerator).
|
||||
// Differs from /cache/stats: that returns the live in-memory CacheStore stats;
|
||||
// this is the audit-side derived rate over the window.
|
||||
export function cacheHitRateWindow({ windowMs, olpHome }): CacheHitRateSummary;
|
||||
```
|
||||
|
||||
### 4.2 Window semantics
|
||||
|
||||
`windowMs` is a duration ending at "now"; `[now - windowMs, now)`. The implementation walks files whose date overlaps that range: today's `audit.ndjson` always; `audit-YYYY-MM-DD.ndjson` for each prior date in range. A line is included only if its `ts` (ISO-8601) falls in the window.
|
||||
|
||||
For the 30-day spend trend, `windowMs = 30 * 86400 * 1000`. The implementation buckets per UTC day and returns one entry per day, including days with zero requests (sparse-fill).
|
||||
|
||||
### 4.3 PII discipline
|
||||
|
||||
Per ADR 0007 § 8, audit events contain no message content, no response content, no raw tokens. The query layer relays only the schema fields. It MUST NOT introduce derived fields that reveal content (e.g., "first 50 chars of prompt").
|
||||
|
||||
### 4.4 Error handling
|
||||
|
||||
- Missing file → empty iteration (not an error).
|
||||
- Malformed JSON line → log warn `audit_query_skip_malformed` + skip; continue.
|
||||
- File-read error (EACCES, etc.) → throw to caller; the dashboard endpoint surfaces 500 with diagnostic message.
|
||||
|
||||
---
|
||||
|
||||
## 5. Audit rotation
|
||||
|
||||
### 5.1 Trigger
|
||||
|
||||
Rotation fires on the **first append after a UTC date change**. Implementation lives in `lib/audit.mjs` (extended at D49). On each `appendAuditEvent` call:
|
||||
|
||||
1. Compute `today = new Date().toISOString().slice(0, 10)` (e.g., `'2026-05-25'`).
|
||||
2. Read a module-scoped `_currentDate` cached at startup.
|
||||
3. If `today !== _currentDate` AND `audit.ndjson` exists AND it is non-empty:
|
||||
- Rename `audit.ndjson` → `audit-${_currentDate}.ndjson` (the previous day's date).
|
||||
- Set `_currentDate = today`.
|
||||
- Continue with the append (new `audit.ndjson` opens via append-create).
|
||||
|
||||
The check is per-call (microsecond cost). The rename is the only filesystem heavy op and fires once per UTC day.
|
||||
|
||||
### 5.2 External-cron alternative (`bin/olp-audit-rotate.mjs`)
|
||||
|
||||
An auxiliary script is shipped at D52 for operators who prefer cron-driven rotation (e.g., to rotate exactly at 00:00:00 UTC rather than "first request after midnight"). The script does the same rename + state-bump logic but can be invoked from a host cron / launchd job. The in-server check remains as a safety net; both can coexist.
|
||||
|
||||
### 5.3 Concurrent-rotation safety
|
||||
|
||||
In-process: the rotation logic is wrapped in a per-process lock (`Map<key='audit-rotate', Promise>`) so two concurrent `appendAuditEvent` calls don't both attempt the rename. External cron + in-server check: the in-server check sees the rename has already happened (file with today's date already exists if cron beat it); the no-op fallback is "if `audit.ndjson` exists, append; else create + append" — POSIX semantics.
|
||||
|
||||
### 5.4 Renamed-file query path
|
||||
|
||||
The query layer (§ 4) walks `audit-${date}.ndjson` files for any date in the window. Today's file is always `audit.ndjson` (not renamed yet); yesterday + prior are date-suffixed.
|
||||
|
||||
---
|
||||
|
||||
## 6. Dashboard panels (per spec § 4.6, Lane 5 = B full)
|
||||
|
||||
`dashboard.html` is a single static file served from `/dashboard`. Renders 4 panels in a 2×2 grid:
|
||||
|
||||
### 6.1 Panel 1 — Per-provider quota / credit pool
|
||||
|
||||
For each loaded provider, calls `provider.quotaStatus()` (ADR 0002 Provider contract). Returns whatever the provider can report (e.g., Anthropic Plan limits remaining, Codex credit pool balance) OR `null` (provider opts out — Phase 2 mistral has no quota API).
|
||||
|
||||
Each row shows:
|
||||
- Provider key + display name
|
||||
- Quota remaining / quota total (or "n/a" if null)
|
||||
- Last poll timestamp
|
||||
|
||||
### 6.2 Panel 2 — Per-provider request count + cache hit rate + fallback rate (last 24h)
|
||||
|
||||
Uses `aggregateRequests({ windowMs: 86400 * 1000 })`. One row per provider showing:
|
||||
- Request count (total served by that provider, regardless of chain position)
|
||||
- Cache hit rate (% of requests where `cache_status === 'hit'`)
|
||||
- Fallback rate (% of requests where `fallback_hops > 0`)
|
||||
- 5xx error rate (% of requests where `status_code >= 500`)
|
||||
|
||||
### 6.3 Panel 3 — Multi-provider unified spend trend (last 30 days)
|
||||
|
||||
Uses `spendTrendDaily({ days: 30 })`. Shows a sparkline-style chart (vanilla SVG, no library) with:
|
||||
- X axis: 30 daily buckets
|
||||
- Y axis: request count per day (stacked by provider color)
|
||||
- Hover tooltip: per-day breakdown by provider
|
||||
|
||||
Note: "spend trend" is the spec's term — at v0.3.0 we don't have provider-side cost integration (Anthropic Plan is flat-rate per Anthropic 2026-06-15 split per the learning memory). So "spend" is proxied by request count. A future ADR may add cost weights per provider when commercial cost-tracking lands.
|
||||
|
||||
### 6.4 Panel 4 — Top fallback chains by trigger count
|
||||
|
||||
Uses `topFallbackChains({ windowMs: 86400 * 1000, limit: 10 })`. Lists top 10 chains:
|
||||
- Chain shape (e.g., `anthropic → openai`)
|
||||
- Trigger count
|
||||
- First / last seen timestamps
|
||||
|
||||
### 6.5 Refresh model (Lane 4 = A)
|
||||
|
||||
The dashboard sets a 30s `setInterval` that calls `fetch('/v0/management/dashboard-data')` + updates DOM in place (no full reload). Initial fetch on page load. The interval pauses when the page is hidden (via `document.visibilityState` listener) to avoid useless background polls.
|
||||
|
||||
### 6.6 Localhost-bound by default
|
||||
|
||||
The dashboard is served from the existing OLP HTTP port (default 3456) which is already bound to `127.0.0.1` per `server.mjs` startup (`server.listen(PORT, '127.0.0.1', ...)`). No additional binding logic. Remote operators access via SSH tunnel; ADR 0007 § 7 owner-only auth provides the per-request gate.
|
||||
|
||||
---
|
||||
|
||||
## 7. Server endpoints (D50)
|
||||
|
||||
All endpoints are owner-only per ADR 0007 § 7 (owner-tier validation through `authenticate`). Non-owner identities get 401 / 403 per existing patterns; anonymous (when `allow_anonymous: true`) gets 401 (these are management endpoints, not user-facing).
|
||||
|
||||
### 7.1 `GET /dashboard`
|
||||
|
||||
Serves `dashboard.html`. Owner-only gated. Content-Type `text/html; charset=utf-8`. Static file read once at server startup + cached in memory (small, no need to re-read per request).
|
||||
|
||||
### 7.2 `GET /v0/management/dashboard-data`
|
||||
|
||||
Returns the JSON payload the dashboard's 30s poll consumes. Shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"generated_at": "<ISO-8601>",
|
||||
"window_24h": <RequestAggregate from §4.1>,
|
||||
"quota": [
|
||||
{ "provider": "anthropic", "quota_remaining": 1234, "quota_total": 5000, "polled_at": "<ISO-8601>" },
|
||||
{ "provider": "openai", "quota_remaining": null }
|
||||
],
|
||||
"spend_trend_30d": <DailySpendEntry[] from §4.1>,
|
||||
"top_fallback_chains_24h": <FallbackChainSummary[] from §4.1>,
|
||||
"cache_stats": <stats from server.mjs cacheStore.stats() — global aggregate>
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 `GET /v0/management/quota`
|
||||
|
||||
Returns just the quota array (subset of dashboard-data; useful for scripted monitoring).
|
||||
|
||||
### 7.4 `GET /cache/stats`
|
||||
|
||||
Returns the live in-memory `cacheStore.stats()` shape. Planning authority is **OLP v0.1 spec § 4.6** (which names `/cache/stats` explicitly); ADR 0005's `Consequences/Mitigations` paragraph (~ line 279) references it as the monitoring surface for per-`(provider, model)` cache hit-rate breakdown.
|
||||
|
||||
**Shape gap to resolve at D50.** The current `cacheStore.stats()` in `lib/cache/store.mjs:320-350` returns `{ hits, misses, size, inflightCount }` — global aggregate only, no per-`(provider, model)` breakdown. If D50 reveals the shape is insufficient for Panel 2 (per-provider 24h cache hit rate, currently sourced from `aggregateRequests` audit-side rather than `cacheStore.stats`), the dashboard endpoint is satisfied. If a future panel needs the per-`(provider, model)` breakdown that spec § 4.6 implies, D50 amends the store shape + an ADR 0005 amendment fires at that time. Phase 3 acceptance criteria do not require the breakdown.
|
||||
|
||||
### 7.5 Audit on management endpoints
|
||||
|
||||
All four endpoints append an audit row via the existing `appendAuditEvent` pattern. Path values are `/dashboard` / `/v0/management/dashboard-data` / `/v0/management/quota` / `/cache/stats`. The 30s poll generates 2880 dashboard rows per day per owner — manageable at family scale, but noted as a knob (a future amendment may suppress audit for these paths if they become noise-dominant).
|
||||
|
||||
---
|
||||
|
||||
## 8. Auth gating
|
||||
|
||||
Reuses ADR 0007 § 7 owner-vs-non-owner model + introduces a second gating mode.
|
||||
|
||||
**Two gating modes (this ADR formalizes the distinction):**
|
||||
|
||||
- **`owner_only_trim`** (Phase 2 / D46 model) — non-owner identities receive a 200 response with a trimmed payload (e.g., `/health` returns `{ ok, version }` only). Used when the endpoint has a baseline payload that is safe to share with all identities and an enriched payload only for owners.
|
||||
- **`owner_only_block`** (Phase 3 / D48 new) — non-owner identities receive `401 invalid_or_revoked_key` (or `401 auth_required` if no token). Used when the entire payload is sensitive and there is no safe baseline to share (Dashboard quota stats, fallback chains by trigger, etc. all reveal operational behaviour that should not leak to non-owner identities).
|
||||
|
||||
The four new endpoints (`/dashboard`, `/v0/management/dashboard-data`, `/v0/management/quota`, `/cache/stats`) are `owner_only_block`. `/health` remains `owner_only_trim`.
|
||||
|
||||
The owner_only_endpoints config gains four entries; the gating-mode distinction is implementation-side (the handler decides whether to trim or block based on the endpoint). Server startup defaults `owner_only_endpoints` to include `/health` + the four new ones (Phase 3 default; operator can opt-out per-endpoint via config). Pre-Phase-3 deployments with `owner_only_endpoints: ['/health']` continue to work — the new endpoints will 401 for non-owner under that legacy config because the handler is `owner_only_block`-mode regardless of the config list (the config controls /health's trim/full toggle only; the management endpoints are not opt-out-able to a non-401 response).
|
||||
|
||||
`401` shapes match Phase 2 / D45 pattern: JSON `{ error: { message, type } }` with `type: 'auth_required'` or `'invalid_or_revoked_key'`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Failure modes + graceful degradation
|
||||
|
||||
| Failure | Behavior |
|
||||
|---|---|
|
||||
| `audit.ndjson` absent (fresh install) | Empty arrays in all aggregates; dashboard shows "No requests in window" panels |
|
||||
| `audit-YYYY-MM-DD.ndjson` corrupted (one bad line) | Skip line + log warn; continue; dashboard rendering unaffected |
|
||||
| Provider `quotaStatus()` throws | Panel shows that row as `quota: "error"`; other providers' rows render normally |
|
||||
| Dashboard `/v0/management/dashboard-data` query >5s | Dashboard JS shows "Loading…" with a timeout; second poll attempts after 30s |
|
||||
| `audit.ndjson` rotation fails (rename EACCES) | `appendAuditEvent` warn `audit_rotate_failed` + continues appending to the un-rotated file; next call retries the rotation |
|
||||
| File handle limit hit during 30-day query (many files open) | Query reads one file at a time (no parallel reads); never opens >2 simultaneously |
|
||||
|
||||
The dashboard degrades visibly (per-panel error states) rather than failing whole-page.
|
||||
|
||||
---
|
||||
|
||||
## 10. Acceptance criteria
|
||||
|
||||
Implementation D-days (D49+) MUST land tests covering:
|
||||
|
||||
1. **`readAuditWindow`** correctly iterates events from today's `audit.ndjson` + N prior rotated files within the window.
|
||||
2. **`readAuditWindow`** skips malformed lines without throwing; logs warn for each.
|
||||
3. **`aggregateRequests`** correctly counts by provider + cache_status + owner_tier + path; correctly computes median + p95 latency.
|
||||
4. **`topFallbackChains`** returns sorted by count descending; ties broken by first-seen timestamp ascending.
|
||||
5. **`spendTrendDaily`** sparse-fills zero-request days; window respects UTC day boundaries.
|
||||
6. **Daily rotation** — writing past UTC midnight renames `audit.ndjson` → `audit-<yesterday>.ndjson` and continues appending to a fresh `audit.ndjson`.
|
||||
7. **Cross-file query** — a 30-day window with mixed rotated files returns correctly merged results.
|
||||
8. **Concurrent rotation safety** — N concurrent `appendAuditEvent` calls during a UTC date change result in exactly one rename + all lines append to the correct file.
|
||||
9. **`GET /dashboard`** returns 200 HTML to owner; 401 to non-owner. This includes the case where `allow_anonymous: true` AND no Authorization header is presented: the authenticate middleware produces an anonymous identity, the `owner_only_block` mode then rejects with 401 (per § 8 — anonymous is non-owner; management endpoints block, do not trim). When `allow_anonymous: false` + no header, 401 fires earlier at the authenticate middleware itself. Test must cover both cases.
|
||||
10. **`GET /v0/management/dashboard-data`** returns 200 JSON to owner with all required fields populated.
|
||||
11. **`GET /cache/stats`** returns 200 JSON to owner with the live in-memory cache stats shape.
|
||||
12. **Dashboard HTML smoke** — fetched via test http client + parsed → has the 4 panel containers + 30s poll script; no JS console errors when loaded in a real browser (manual or playwright; manual is acceptable at Phase 3).
|
||||
13. **Audit on management endpoints** — calling `/v0/management/dashboard-data` appends an audit row with `path: '/v0/management/dashboard-data'` and `status_code: 200`.
|
||||
14. **Graceful degradation** — when a provider's `quotaStatus()` throws, the dashboard endpoint still returns 200 with that provider's quota row showing `"quota_remaining": null` and an error indicator.
|
||||
15. **PII guard** — every aggregate query function asserts at the test level that returned data does NOT include any message content; the `prompt`/`messages`/`response`/`content` fields MUST NEVER appear in any output shape.
|
||||
|
||||
---
|
||||
|
||||
## 11. Forward path (Phase 4+)
|
||||
|
||||
Items deliberately deferred:
|
||||
|
||||
- **SQLite migration (Option 3 hybrid)** — trigger: query latency >2s on a typical owner session, OR Dashboard usage scales beyond family (>5 owners polling). Preconditions per ADR 0007 § 13: engines bump + CI matrix change as a separate prior PR.
|
||||
- **SSE push for dashboard live updates** — trigger: 30s poll feels stale, OR operator wants real-time view of streaming requests. Reuses existing streaming infra from ADR 0005 Amendment 8 (v1.x streaming SF when it ships).
|
||||
- **Key-mgmt UI from dashboard** — owner can create/revoke/edit keys from the web UI rather than CLI. Out of Phase 3 because (a) it adds a write surface to the dashboard requiring careful CSRF handling, (b) security review of the auth flow is non-trivial, (c) the CLI surface from D47 covers the same use cases.
|
||||
- **Cost weights per provider** — once provider-side cost tracking is feasible, "spend trend" can show actual dollars. At v0.3.0 it's a request-count proxy.
|
||||
- **Audit retention / max-days policy** — currently unbounded; operator manages disk. A Phase 3+ amendment adds `audit_max_days` config when an operational need emerges.
|
||||
- **Per-key dashboard views** — owner sees aggregate; per-key drill-down is a future amendment.
|
||||
|
||||
---
|
||||
|
||||
## 12. Out of scope (explicitly NOT in Phase 3)
|
||||
|
||||
- Per-key per-provider auth artifact mapping (ADR 0007 § 12; Phase 4+).
|
||||
- `tried_providers` schema semantics fix on `key_no_provider_access` 403 — D45 reviewer P2 deferral. Tracked as a Phase 3 implementation D-day (D53) but NOT part of ADR 0008; documented in ADR 0004 amendment or ADR 0007 § 8 amendment at D53.
|
||||
- All ADR 0007 § 12 deferrals other than Dashboard + audit query layer + rotation.
|
||||
- Externally-visible Dashboard (anything bound to 0.0.0.0 / public). Operator SSH-tunnels.
|
||||
|
||||
---
|
||||
|
||||
## 13. Phase 3 sprint shape
|
||||
|
||||
| D-day | Deliverable | Type |
|
||||
|---|---|---|
|
||||
| **D48** | This ADR (0008 draft) | ADR-only |
|
||||
| **D49** | `lib/audit-query.mjs` + Suite 23 unit tests | impl |
|
||||
| **D50** | `server.mjs` `/v0/management/*` endpoints + `/dashboard` route + Suite 24 HTTP tests | impl |
|
||||
| **D51** | `dashboard.html` + render JS + 30s poll | impl |
|
||||
| **D52** | Audit daily rotation (`lib/audit.mjs` extension + `bin/olp-audit-rotate.mjs` + Suite 25 rotation tests) | impl |
|
||||
| **D53** | `tried_providers` schema fix (D45 P2 deferral; small) | impl |
|
||||
| **D54** | E2E browser smoke (manual or playwright) + AGENTS / README polish | tests + docs |
|
||||
| **D55** | Phase 3 close → v0.3.0 (release-kit PR per `phase_close_trigger`) | release |
|
||||
|
||||
Each D-day = implementor + fresh-context opus reviewer per Iron Rule 10. Estimated wall-clock: similar to Phase 2 cadence (1 intense session per D-day under standing autopilot).
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- Operators get an at-a-glance view of OLP's behaviour (was a tail/grep exercise pre-Phase-3).
|
||||
- Audit layer becomes queryable, not just append-only; `lib/audit-query.mjs` is reusable for future CLI tools (`olp-audit search` etc.).
|
||||
- Daily rotation bounds per-file size + creates a natural archival unit.
|
||||
- Owner-only gating reuses Phase 2 auth model (no new auth surface).
|
||||
- v0.1 spec § 4.6 Dashboard requirements are met without introducing a build step / database / framework.
|
||||
|
||||
**Negative / trade-offs:**
|
||||
|
||||
- In-memory ndjson scan is O(N) per query; if audit grows to millions of lines (single-host years), the 30-day query becomes slow. Mitigation: ADR 0007 § 13 Option 3 hybrid is the documented next step; trigger is observed slowness.
|
||||
- 30s poll generates baseline traffic when dashboard is open (2880 management requests/day per owner). Not a real cost but worth observing.
|
||||
- Audit rotation is "first append after UTC midnight" which means a server with zero requests overnight rotates lazily (first request of the new day triggers it). External cron at D52 covers the strict-midnight case.
|
||||
- No automatic audit retention. A multi-year-running server accumulates files; operator manages.
|
||||
|
||||
**Reversibility:**
|
||||
|
||||
- Dashboard is a static file + 4 endpoints. Removable in a future revert PR if Phase 3 retrospectively proves unwanted.
|
||||
- Audit rotation is additive — disabling reverts to single-file behaviour without code change (operator never invokes the cron + the in-server rotation can be guarded by a config flag).
|
||||
- The `lib/audit-query.mjs` module is consumed by Dashboard endpoints + can be used standalone; removing it requires unrelated endpoint surgery.
|
||||
|
||||
---
|
||||
|
||||
## Authority citations
|
||||
|
||||
- **OLP v0.1 spec § 4.6 + § 4.7** (Dashboard + observability endpoints) — at `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations.
|
||||
- **OCP `dashboard.html`** (prior-art reference for the multi-panel HTML structure) — at `~/ocp/dashboard.html` on the maintainer's workstation; OCP production reference.
|
||||
- **ADR 0007 §§ 7 / 8 / 12 / 13** (owner-gating model; audit ndjson schema; Phase 3 scope opening; SQLite forward path).
|
||||
- **ADR 0002** (Provider contract — `quotaStatus` method that Panel 1 consumes).
|
||||
- **OLP v0.1 spec § 4.6** (planning authority for `/cache/stats` endpoint name + Dashboard requirements). ADR 0005's `Consequences/Mitigations` paragraph references the endpoint as the monitoring surface for per-`(provider, model)` cache hit-rate breakdown; that breakdown is a Phase 4+ amendment trigger if needed (see § 7.4 above).
|
||||
- **ADR 0004 Amendment 5** (D40 X-OLP-Fallback-Detail — top-fallback-chains panel data shape lineage).
|
||||
- **Standing-autopilot grant** (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a`) — Phase 3 kickoff via maintainer "go" + lane pin.
|
||||
- **Phase 2 kickoff handoff pattern** (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`) — this ADR follows the same structure.
|
||||
- **CLAUDE.md `release_kit.phase_rolling_mode current_phase: Phase 3`** — confirms this ADR lands in the Phase 3 sprint.
|
||||
@@ -0,0 +1,197 @@
|
||||
# ADR 0009 — Anthropic Interactive-Mode Path (Placeholder)
|
||||
|
||||
- **Date:** 2026-05-25
|
||||
- **Status:** Draft (Placeholder — blocked on OCP ADR 0007 P0 experiment outcome; no implementation D-day scheduled until P0 lands)
|
||||
- **Authors:** project maintainer (with AI advisory drafting)
|
||||
- **Related:**
|
||||
- **OCP ADR 0007** (Interactive-Mode Execution Pool, stream-json) — at `~/ocp/docs/adr/0007-interactive-mode-pool.md` on the maintainer's workstation. Pin reference at the time of this writing: OCP ADR 0007 is Draft status pending the same P0 outcome.
|
||||
- OLP ADR 0001 (Project Founding) — establishes the 2026-06-15 Anthropic billing-split trigger that motivated OLP's multi-provider posture in the first place.
|
||||
- OLP ADR 0006 (Provider Inclusion / Risk Tier Framework) — anthropic is currently a Tier-D Candidate; this ADR amends the operational shape of that plugin if/when P0 succeeds.
|
||||
- OLP ADR 0007 (Multi-Key Auth) — Phase 2 design; per-key cache + audit layer that any future interactive-mode implementation must continue to satisfy.
|
||||
- OLP ADR 0008 (Dashboard + Audit Query) — Phase 3 design; any interactive-mode change must not regress the Dashboard's per-provider observability fields.
|
||||
- **Standing autopilot grant note:** Phase 4 is a "new authorization required" scope per `~/.cc-rules/memory/auto/standing_autopilot_phase_2.md`. This placeholder ADR is recorded NOT as implementation work but as the maintainer's "do not forget this when planning Phase 4" anchor. No implementation D-day is scheduled until P0 lands AND maintainer issues a Phase 4 "go" specific to this ADR.
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The triggering external work
|
||||
|
||||
OCP shipped ADR 0007 (`docs/adr/0007-interactive-mode-pool.md` in `dtzp555-max/ocp`) on 2026-05-25, draft status. The ADR designs a dual-path execution model for the post-2026-06-15 Anthropic billing split:
|
||||
|
||||
- **Current `claude -p` path**: programmatic billing → Agent SDK $100/month credit pool (~20–50 heavy coding sessions/month).
|
||||
- **Proposed interactive-mode path**: spawn Claude without `-p`, communicate via either (Transport A) piped NDJSON over stdio or (Transport B) `node-pty` PTY — possibly classified as interactive billing → subscription pool.
|
||||
|
||||
The OCP team accepted the *concept* but rejected an external contributor's PR #101 implementation (tmux + hook-file polling + `--dangerously-skip-permissions`) on alignment + security grounds, then drafted ADR 0007 as the clean redesign.
|
||||
|
||||
### 1.2 Why this is OLP's concern
|
||||
|
||||
OLP's founding premise (ADR 0001) was that OCP would become uneconomical post-2026-06-15, motivating a multi-provider hedge. OLP's `lib/providers/anthropic.mjs` today uses the same `claude -p` invocation OCP uses → same billing consequence post-2026-06-15.
|
||||
|
||||
If OCP's ADR 0007 P0 experiment confirms that an interactive-mode spawn (Transport A or B) bills against subscription rather than Agent SDK credit, the implementation pattern is directly portable to OLP's anthropic provider plugin. OLP would inherit the same billing benefit without needing to commission an independent P0.
|
||||
|
||||
If P0 fails for both transports, OLP's anthropic provider remains stuck on `-p` post-June-15; the multi-provider routing (OpenAI Codex, Mistral) becomes the operational mitigation, exactly per OLP's original founding logic.
|
||||
|
||||
### 1.3 The unverified premise (binding caveat)
|
||||
|
||||
Per OCP ADR 0007 § "Unverified Premise":
|
||||
|
||||
> "TTY detection matters. Local testing (Claude Code 2.1.150) shows: in a real TTY, `claude` without `-p` enters the TUI and does not emit NDJSON. With piped stdin/stdout (`child_process.spawn`), it emits NDJSON even without `-p`. This means Anthropic could use `isTTY` as the billing signal, not the `-p` flag."
|
||||
|
||||
OLP cannot independently confirm or refute this prior to 2026-06-15 — Anthropic's billing pool signaling is not exposed on any observable surface until the billing split goes live. **Any OLP implementation that bets on Transport A (stdio pipe) without P0 confirmation risks burning real Agent SDK credit on every Anthropic request.**
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
**Option 3 — Wait for OCP ADR 0007 P0 experiment outcome, then port the validated approach.**
|
||||
|
||||
Rationale:
|
||||
|
||||
- **Avoid duplicated P0 risk.** Both OCP and OLP would run the same experiment against the same Anthropic billing pool. OCP is already designed to run it; OLP riding their result is a free observation.
|
||||
- **Lower decision-tree noise.** P0 has three outcomes (Transport A wins / Transport B wins / both fail). OLP's right answer differs per outcome; making the decision before the data is speculation.
|
||||
- **No code is wasted.** OLP currently routes anthropic via `claude -p`, which works (just expensive post-June-15). The cost during the wait window is bounded by the Agent SDK $100/month credit + OLP's family-scale request volume.
|
||||
|
||||
What "wait" means concretely:
|
||||
|
||||
1. **No code change to `lib/providers/anthropic.mjs`** until OCP ADR 0007 transitions from Draft → Accepted (which requires P0 success per OCP ADR 0007 § "Status").
|
||||
2. **No Phase 4 D-day scheduled for this scope** until that transition AND maintainer issues an explicit Phase 4 "go" naming this ADR.
|
||||
3. **This placeholder ADR stays Draft** until either OCP P0 lands AND OLP decides to port, OR OCP P0 fails decisively AND OLP marks this ADR Rejected with a "shelved per upstream P0 failure" note.
|
||||
|
||||
---
|
||||
|
||||
## 3. P0 outcome → OLP action decision tree
|
||||
|
||||
Recorded here so a future Phase 4 brief can act mechanically once OCP P0 lands.
|
||||
|
||||
```
|
||||
OCP ADR 0007 P0 result
|
||||
│
|
||||
├─ Transport A (stdio pipe) confirmed interactive-billing
|
||||
│ → OLP Option 1 OR Option 2 (see § 4); maintainer decides.
|
||||
│ Likely Option 1: port the lib/interactive-pool.mjs +
|
||||
│ billing-router.mjs pattern into lib/providers/anthropic.mjs.
|
||||
│ Updates ADR 0006 to spell out the new spawn mode.
|
||||
│
|
||||
├─ Transport B (PTY) confirmed; Transport A fails
|
||||
│ → OLP Option 1 with PTY adapter; node-pty dependency added
|
||||
│ under engines-bump scrutiny (this triggers a separate prior
|
||||
│ PR per ADR 0007 § 11-like discipline: native addon adds
|
||||
│ CI matrix work).
|
||||
│
|
||||
├─ Both transports billed as programmatic
|
||||
│ → OLP marks this ADR Rejected. Anthropic provider stays on
|
||||
│ `claude -p`. Operational mitigation: family-scale users
|
||||
│ either (a) accept the Agent SDK $100 cap, (b) bring their
|
||||
│ own API key (BYOK env path is already there), or (c) shift
|
||||
│ volume to other providers (Codex / Mistral) via OLP's
|
||||
│ existing fallback chain.
|
||||
│
|
||||
└─ P0 results unobservable (billing signals not exposed)
|
||||
→ Continue waiting. Re-evaluate one billing cycle (30 days)
|
||||
post-2026-06-15. OLP Anthropic provider remains on `-p`
|
||||
path during the wait; users see Agent SDK credit consumption
|
||||
as the cost signal.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation lanes (to be selected when P0 lands)
|
||||
|
||||
This section is informational only. No lane is selected at placeholder time.
|
||||
|
||||
### Option 1 — OLP parallel implementation
|
||||
|
||||
OLP's `lib/providers/anthropic.mjs` reimplements OCP's interactive pool natively. Replaces the current `claude -p` spawn with a pool-managed warm process + adapter selected per P0 outcome.
|
||||
|
||||
- **Pros:** OLP self-contained; no runtime dependency on OCP being installed.
|
||||
- **Cons:** Duplicates substantial logic (pool lifecycle, transport adapter, crash backoff DEGRADED, permission auto-response). Two codebases drift over time.
|
||||
|
||||
### Option 2 — OLP chains OCP as backend
|
||||
|
||||
OLP's `lib/providers/anthropic.mjs` invokes OCP (via its existing HTTP entry surface, or via a future direct-spawn API) rather than spawning `claude` directly. OLP becomes a multi-provider layer ON TOP OF OCP for the Anthropic provider; other providers (Codex, Mistral) continue to be direct.
|
||||
|
||||
- **Pros:** Zero duplication; OLP benefits from OCP's P0-validated work automatically. Architectural separation: OCP owns Claude execution, OLP owns multi-provider routing.
|
||||
- **Cons:** OLP gains a runtime dependency on OCP being installed + running. Double caching (OCP cache + OLP cache; cache key composition needs to avoid stampede). OCP's HTTP shim is OpenAI-spec-compatible but adds an extra hop's latency. OCP failure modes propagate.
|
||||
|
||||
### Option 3 — Both (default to OCP backend if available, fallback to local pool)
|
||||
|
||||
A hybrid: OLP detects OCP installed locally, prefers chaining; otherwise falls back to the parallel implementation. Most defensive but most complex.
|
||||
|
||||
**Default at placeholder time:** Option 1 is the simpler ship if P0 transports prove out. Option 2 is the cleaner architecture but adds operational coupling. Maintainer decides at P0-resolution time.
|
||||
|
||||
---
|
||||
|
||||
## 5. Risk assessment (placeholder snapshot)
|
||||
|
||||
| Risk | Likelihood (now) | Impact | Mitigation pending P0 |
|
||||
|---|---|---|---|
|
||||
| OLP forgets this ADR exists | Medium (multi-month wait) | High (would mean OLP misses the post-June-15 window) | This ADR + cc-rules memory `~/.cc-rules/memory/learnings/ocp_adr_0007_interactive_mode_pool.md` |
|
||||
| OCP ADR 0007 P0 fails entirely | Medium | High for OLP Anthropic users (Agent SDK $100 cap binds) | OLP's multi-provider fallback (Codex/Mistral) already shipped as Phase 1 work; users have a path |
|
||||
| OCP ADR 0007 ships incomplete (interim) | Medium | Medium (OLP can't reliably port) | Wait for OCP to mark Accepted; don't port from Draft |
|
||||
| Anthropic policy changes mid-wait | Medium | Depends — could obsolete the whole approach | Re-read OCP ADR 0007 + this ADR before any Phase 4 anthropic work; no decisions on stale information |
|
||||
|
||||
---
|
||||
|
||||
## 6. Out of scope (explicitly NOT in this ADR)
|
||||
|
||||
- **Any code change.** This is a placeholder + decision-tree record only.
|
||||
- **OCP P0 design.** That work is OCP's responsibility per OCP ADR 0007 § "Implementation phases".
|
||||
- **A new OCP-OLP integration protocol.** If Option 2 is selected at P0-resolution time, the integration shape is a separate ADR.
|
||||
- **Engines-bump for node-pty.** Only relevant if P0 picks Transport B and Option 1 is selected. Then it lands as a separate prior PR per the ADR 0007 § 11 pattern.
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase 4 priority interaction
|
||||
|
||||
This ADR is recorded BEFORE Phase 4 implementation scope is finalized. Phase 4 currently lists (per OLP v0.3.0 CHANGELOG):
|
||||
|
||||
- Per-key per-provider auth artifact mapping (ADR 0007 § 12 deferral)
|
||||
- Audit retention policies (ADR 0008 § 11 deferral)
|
||||
- SQLite hybrid migration (ADR 0007 § 13 trigger)
|
||||
- Provider-cost weights for spend trend (ADR 0008 § 11 deferral)
|
||||
|
||||
If OCP P0 succeeds, **the interactive-mode port likely jumps to the top of Phase 4** (highest user impact: keeps OLP Anthropic users on subscription billing). The other items remain Phase 4 but reorder downstream.
|
||||
|
||||
If OCP P0 fails, **this ADR is shelved** and Phase 4 ordering is unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- OLP retains a documented anchor for the interactive-mode option without committing implementation effort prematurely.
|
||||
- Future Phase 4 planning has a structured decision tree, not a vague "we should look at OCP someday".
|
||||
- Cross-machine + cross-session memory (cc-rules) ensures the dependency is visible to any future session reading the OLP project context.
|
||||
|
||||
**Negative:**
|
||||
|
||||
- During the wait window (now → P0 outcome ≥ 2026-07-15), OLP Anthropic users consume Agent SDK credit post-2026-06-15. Bounded by family-scale request volume but a real operational cost.
|
||||
- Some risk that "wait" turns into "forget" if multiple unrelated Phase 4 priorities crowd the agenda. Mitigated by this ADR + the cc-rules memory pointer.
|
||||
|
||||
**Reversibility:**
|
||||
|
||||
- This is a placeholder. Either P0 result transitions it (Accepted → port, Rejected → shelve) cleanly. The placeholder itself doesn't lock OLP into anything.
|
||||
|
||||
---
|
||||
|
||||
## Authority citations
|
||||
|
||||
- **OCP ADR 0007** at `~/ocp/docs/adr/0007-interactive-mode-pool.md` (maintainer workstation). Project repo: `dtzp555-max/ocp`.
|
||||
- **PR #101** to `dtzp555-max/ocp` — external contributor's tmux-based prototype that triggered the OCP ADR 0007 redesign.
|
||||
- **Anthropic 2026-06-15 billing-split announcement** — see `~/.cc-rules/memory/learnings/anthropic_claude_code_billing_split_2026_06_15.md`.
|
||||
- **OLP ADR 0001** (Project Founding) — establishes the original billing-split → multi-provider motivation.
|
||||
- **OLP ADR 0006** (Provider Inclusion + Risk Tier Framework) — the anthropic plugin's tier classification + the surface this ADR would amend.
|
||||
- **OLP ADR 0007** (Multi-Key Auth, Phase 2) — per-key audit + cache layer that must continue to work across any anthropic execution-mode change.
|
||||
- **OLP ADR 0008** (Dashboard + Audit Query, Phase 3) — Dashboard per-provider fields must continue to populate.
|
||||
- **CLAUDE.md `release_kit.phase_rolling_mode`** — current_phase: Phase 4 (post-v0.3.0); this ADR explicitly does NOT consume a Phase 4 D-day until P0 lands.
|
||||
- **Standing autopilot grant** (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a`) — Phase 4+ requires new authorization; this placeholder is a decision-tree pre-record, not Phase 4 implementation.
|
||||
|
||||
---
|
||||
|
||||
## Status transitions (recorded for clarity)
|
||||
|
||||
- 2026-05-25 — Created as Draft (Placeholder). OCP ADR 0007 also Draft.
|
||||
- _(future)_ — If OCP ADR 0007 → Accepted with a confirmed transport: this ADR moves to "Pending Phase 4 implementation D-day", maintainer decides Option 1 / 2 / 3 + lane.
|
||||
- _(future)_ — If OCP ADR 0007 → Rejected: this ADR moves to "Shelved (upstream P0 failure)" with a note explaining the fallback (multi-provider routing already covers).
|
||||
@@ -20,6 +20,9 @@ New ADRs increment from the highest existing number. Filenames are `NNNN-<short-
|
||||
| [0004](0004-fallback-engine.md) | Fallback Engine Semantics & Safety | Trigger taxonomy (Hard / Soft / Deterministic-deferred / Cost-aware-deferred), idempotent-failure safety (first-chunk rule), chain advancement one-at-a-time, observability headers. |
|
||||
| [0005](0005-cache-cross-provider.md) | Cache Layer Cross-Provider Design | Cache key composition over `(provider, model, messages, …)`, per-model isolation, D1+D2+D3+D4 port from OCP v3.13.0, cross-provider fallback cache behaviour (correct miss). |
|
||||
| [0006](0006-provider-inclusion.md) | Provider Inclusion / Exclusion + Risk-Tier Framework | The 4-tier classification (A excluded by default / B explicit consent / C opt-in / D eligible-for-default-enabled), Candidate-vs-Enabled distinction, current v0.1 candidate inventory (0 Enabled), Antigravity exclusion rationale (named prohibition + no cost advantage + reinstatement friction; pending primary-source pin), consent UX, future provider addition procedure. |
|
||||
| [0007](0007-multi-key-auth.md) | Multi-Key Auth (`lib/keys.mjs`) | Phase 2 design ADR (D43-B, 2026-05-25). Option 2 (filesystem manifest at `~/.olp/keys/<key-id>/manifest.json`) + opaque `olp_<32-byte>` token + SHA-256 hash. Owner / guest / anonymous tier gating with explicit `config.json auth.allow_anonymous` (default false). Bootstrap keygen command surface + `OLP_OWNER_TOKEN` env override with stable synthetic `key_id`. Audit ndjson append-only at `~/.olp/logs/audit.ndjson`, warn+1-retry on append failure. Rejects direct SQLite port at v0.2.0 due to Node baseline (`engines >=18` + CI 20/24 vs `node:sqlite` added 22.5.0 / RC); Option 3 hybrid documented as forward path when Phase 3+ Dashboard / SQL-aggregate quota arrives. |
|
||||
| [0008](0008-dashboard-and-audit-query.md) | Dashboard + Audit Query Layer | Phase 3 design ADR (D48, 2026-05-25). Static HTML dashboard + vanilla JS + fetch (no build step). In-memory ndjson scan for aggregate queries (O(N) per call; family-scale acceptable; defers SQLite migration to Option 3 hybrid trigger). Daily audit rotation `audit-YYYY-MM-DD.ndjson` on first append after UTC midnight; cross-file query layer for rolling 30-day windows. Owner-only gating on `/dashboard` + 3 `/v0/management/*` JSON endpoints reusing ADR 0007 § 7 auth model. 30s page poll (no SSE infra). Panels: per-provider quota / 24h request+cache+fallback / 30d spend trend / top-N fallback chains per spec § 4.6. Opens ADR 0007 § 12 Phase 3 deferral (Dashboard + audit query + rotation). |
|
||||
| [0009](0009-interactive-mode-path-placeholder.md) | Anthropic Interactive-Mode Path (Placeholder) | Placeholder ADR (2026-05-25, Draft) — blocked on OCP ADR 0007 P0 experiment outcome. Records the maintainer's "wait + port" decision: do NOT independently implement; ride OCP's P0 result. If P0 confirms Transport A (stdio NDJSON) or B (PTY) bills as subscription rather than Agent SDK credit, port to OLP `lib/providers/anthropic.mjs` (Option 1 parallel impl, or Option 2 OCP-as-backend; decision deferred to P0-resolution time). If P0 fails on both, shelve. No Phase 4 D-day scheduled until P0 lands AND maintainer issues explicit "go" naming this ADR. |
|
||||
|
||||
## When to write a new ADR
|
||||
|
||||
|
||||
+31
-25
@@ -8,35 +8,40 @@
|
||||
3. **Where** does the work live in the tree today (file + anchor).
|
||||
4. **When** does it need to land (trigger: load profile, security event, governance amendment).
|
||||
|
||||
**Reading order for a v1.x sprint kickoff.** Items #1–#3 are the most architecturally consequential and should be designed in dependency order: #2 (multi-key auth) blocks header gating in #1 and observability ownership in #4. #1 (streaming SF) blocks #5 (soft trigger reactivation) only if soft triggers are wired on streaming requests.
|
||||
**Reading order for a v1.x sprint kickoff.** As of 2026-05-25, #1 (streaming SF, D57+D58) and #2 (multi-key auth, Phase 2) are CLOSED, and #4 and #7 closed in D56. Remaining v1.x scope: #3 (soft trigger reactivation), #5 (provider cacheKeyFields mask), #6 (streaming SPAWN_FAILED salvage — unbundled from #1 at #1 close). All three remaining items have explicit "trigger to start" gates that have not fired.
|
||||
|
||||
---
|
||||
|
||||
## #1 — Streaming-path singleflight + TOCTOU close
|
||||
## #1 — Streaming-path singleflight + TOCTOU close — ✅ **SHIPPED (D57 + D58, 2026-05-25)**
|
||||
|
||||
- **What.** `cacheStore.getOrComputeStreaming(keyId, cacheKey, sourceFactory)` API replacing the current `peek + spawn` pattern in `server.mjs`. Per-(keyId, cacheKey) inflight Map with tee fan-out, bounded per-client backpressure queues, late-joiner replay buffer, AbortController propagation on all-disconnect.
|
||||
- **Why deferred.** Personal/family-scale single-tenant load — N concurrent identical streaming requests is an edge case that has not been reported. Each concurrent caller receives the correct response; the waste is N CLI processes instead of one.
|
||||
- **Design ADR (ratified).** [`docs/adr/0005-cache-cross-provider.md` Amendment 8](./adr/0005-cache-cross-provider.md) — full design including the inflight Map shape, tee policy, late-joiner replay, backpressure cap, D38 semaphore coordination, abort policy, cache TTL race handling, observability event set, and X-OLP-Streaming-Inflight header. Implementation acceptance criteria are in Amendment 8 §13.
|
||||
- **Tracking issue.** GitHub issue [#16](https://github.com/dtzp555-max/olp/issues/16) — STAYS OPEN as v1.x tracker. Sibling: the closed-but-not-implemented Amendment 6 deferral (D34 F1).
|
||||
- **Code anchors today.**
|
||||
- `server.mjs` lines ~782 (`preCheckHit = await cacheStore.peek(...)`) and ~811–817 (streaming branch entry) — these are the lines the new API replaces.
|
||||
- `lib/cache/store.mjs` `getOrCompute` — sibling API; the new one mirrors its shape on the streaming path.
|
||||
- **Trigger to start.** Any of: (a) report of N>1 concurrent identical streaming requests in the wild, (b) v1.x sprint planning kickoff with the maintainer explicitly opening this scope, (c) downstream feature requiring tee-streaming primitive (e.g., browser-side observer attaching to an existing stream).
|
||||
- **Estimated effort.** Design ADR ratified (Amendment 8) = 30 min done. Implementation = 200–400 lines + 15-20 tests + fresh-context reviewer pass. ~3-4 hours of subagent runtime with full Iron Rule 10 discipline.
|
||||
- **Status.** Closed. Trigger (b) fired 2026-05-25 — maintainer "go" after v0.3.1. Shipped across three D-days:
|
||||
- **D57** (PR #36) — cache layer: `cacheStore.getOrComputeStreaming(keyId, cacheKey, sourceFactory, opts) → { stream, isFirst, role }` with `_streamingInflight` Map, tee fan-out, late-joiner replay buffer, per-client backpressure (`PER_CLIENT_QUEUE_CAP=1MB`), replay cap (`ACCUMULATED_REPLAY_CAP=10MB`), AbortController propagation, synchronous Map check+insert (closes TOCTOU). Suite 27 = 12 unit tests.
|
||||
- **D58** (PR #37) — server.mjs wiring: streaming branch swap; `tryAcquireSpawn`/`releaseSpawn` moved inside `sourceFactory` closure (D38 §7 coordination); `CONCURRENCY_LIMIT` fallthrough preserved; `X-OLP-Streaming-Inflight: source | attached` header; `cache_status: 'streaming_attached'` audit value + audit-query gauge reconciliation; `res.on('close') → stream.return()` for client disconnect; D16 truncated-not-cached invariant preserved via `cacheStore.delete` on stop-less exhaustion. Suite 28 = 8 HTTP integration tests.
|
||||
- **D59** (this commit) — docs polish: README known-limitations entry inverted; this roadmap entry closed; issue #16 closed.
|
||||
- **Design authority.** [`docs/adr/0005-cache-cross-provider.md` Amendment 8](./adr/0005-cache-cross-provider.md) — implemented per spec §§1–14 across D57+D58.
|
||||
- **Tracking issue.** GitHub issue [#16](https://github.com/dtzp555-max/olp/issues/16) — CLOSED at D59 with refs to D57+D58 PRs.
|
||||
- **Final test count delta.** 603 (v0.3.1) → 623 (v0.3.2/v0.4.0). +20 tests across the SF arc.
|
||||
- **Deferred sub-items** (left here as future-work pointers, NOT blocking #1 closure):
|
||||
- `X-OLP-Streaming-Inflight: solo` value not emitted on the wire (Amendment 8 §11). It's observable only post-stream via the `streaming_inflight_source_done` log event's `attached_count: 0`. Future ADR amendment may expose via HTTP trailer.
|
||||
- `streaming_inflight_join` log event from `_attachClient` cache-layer path (carries no provider/model context). D58 emits the event from the server-layer wrapper instead; cache-layer emission would need a provider/model plumb (TODO marker at `lib/cache/store.mjs:~620`).
|
||||
- `isFirst` field returned by `getOrComputeStreaming` is currently unused by server.mjs (`role` supersedes). Could be removed in a future cache-layer API cleanup.
|
||||
|
||||
## #2 — Multi-key auth (`lib/keys.mjs`)
|
||||
## #2 — Multi-key auth (`lib/keys.mjs`) — **PHASE 2 ACTIVE (no longer deferred)**
|
||||
|
||||
- **What.** Per-API-key identity, namespace scoping for the cache, ownership tier (owner vs guest) for header gating, and audit log of which key issued which request.
|
||||
- **Why deferred.** Phase 1 ships single-tenant — the cache layer carries `keyId='__anonymous__'` (D5). No real user identity is needed for personal/family use today.
|
||||
- **Design ADR (NOT YET RATIFIED).** No design ADR exists yet. v1.x sprint must produce one before implementation.
|
||||
- **Tracking.** Not a GitHub issue (no governance event filed for it). Tracked here + in `AGENTS.md § Key files to know` (`lib/keys.mjs` marked 📋 Planned).
|
||||
- **Blocks.**
|
||||
- `X-OLP-Fallback-Detail` owner-only gating (D40 / ADR 0004 Amendment 5 — currently ungated).
|
||||
- `/health` per-key visibility (currently anonymous-only).
|
||||
- **Code anchors today.**
|
||||
- `lib/cache/store.mjs` per-keyId namespace Map — the data model is already keyed by `keyId`; only the keyId source is hardcoded.
|
||||
- `server.mjs` request handlers — the `keyId='__anonymous__'` constant needs to be replaced by a header/token lookup.
|
||||
- **Trigger to start.** First multi-user deployment of OLP (e.g., maintainer + spouse + child accessing the same instance with separate identities).
|
||||
- **Status.** Phase 2 active as of 2026-05-25. Design ratified at D43-B. This entry stays for cross-reference but is no longer a v1.x deferral; implementation D-days D44+ execute within Phase 2.
|
||||
- **What.** Per-API-key identity, namespace scoping for the cache, ownership tier (owner vs guest) for header gating, and audit log of which key issued which request. Detailed scope in ADR 0007.
|
||||
- **Design ADR (ratified).** [`docs/adr/0007-multi-key-auth.md`](./adr/0007-multi-key-auth.md) — Option 2 (filesystem manifest) + opaque token, with explicit forward path to Option 3 hybrid (SQLite-indexed mirror) when Phase 3+ Dashboard / SQL-aggregate quota work justifies. Migratable, manifest-as-SPOT.
|
||||
- **Tracking.** Not a GitHub issue. Tracked here + via ADR 0007 acceptance criteria (§ 10) which drive the D44+ test surface.
|
||||
- **Resolves.**
|
||||
- `X-OLP-Fallback-Detail` owner-only gating (D40 / ADR 0004 Amendment 5 — currently ungated; Phase 2 re-gates per ADR 0007 § 7).
|
||||
- `/health` per-key visibility (currently anonymous-only — owner / guest / anonymous tiers per ADR 0007 § 7).
|
||||
- **Code anchors today (unchanged at ADR ratification; replaced by D44+ implementation).**
|
||||
- `lib/cache/store.mjs:77-79` per-keyId namespace Map — wire is in place.
|
||||
- `lib/cache/store.mjs:287` singleflight composition `${keyId}:${cacheKey}` — wire is in place.
|
||||
- `server.mjs:502, :531` — the two `keyId='__anonymous__'` call sites to replace.
|
||||
- `server.mjs:392` — `/health` handler entry (Phase 2 gate).
|
||||
- `server.mjs:1072, :1101` — `X-OLP-Fallback-Detail` header-write paths (Phase 2 gate).
|
||||
- **Trigger (already fired).** Maintainer opened Phase 2 sprint 2026-05-25.
|
||||
|
||||
## #3 — Soft trigger reactivation (ADR 0004 Amendment 2)
|
||||
|
||||
@@ -78,9 +83,10 @@
|
||||
|
||||
- **What.** Currently the streaming branch does NOT participate in D16 salvage (the salvage-on-SPAWN_FAILED + chunks pattern that the buffered path uses). Streaming SPAWN_FAILED mid-stream → the truncation marker (D35 #10) fires, but no salvage logic captures partial chunks for downstream cache reuse.
|
||||
- **Why deferred.** Less impactful than #1 — at most one client benefits per spawn event, and the buffered path already provides salvage for the bulk of requests. Streaming is the minority path.
|
||||
- **Design ADR.** Not yet ratified. Coordinated with #1 because the tee architecture changes the salvage semantics (multiple clients may want different finish_reason interpretations on source-mid-stream-failure).
|
||||
- **Status update post-#1 close (2026-05-25).** #1 was originally bundled with #6 in the design ADR (Amendment 8). The tee architecture as implemented does NOT carry salvage semantics — D57's tee writes `accumulatedChunks` to cache only on normal source completion (stop chunk seen); on SPAWN_FAILED mid-stream the cache layer rejects all clients with the error and does NOT persist partial chunks. D58 preserves D16's truncated-not-cached invariant via server-layer `cacheStore.delete` on stop-less exhaustion. #6 therefore remains independently deferrable.
|
||||
- **Design ADR.** Not yet ratified. The unbundling from #1 means #6 now needs its own ADR amendment when triggered.
|
||||
- **Tracking.** Not a GitHub issue. Tracked here.
|
||||
- **Trigger to start.** Bundled with #1 implementation work (the inflight tee architecture changes the salvage semantics, so designing them together is cheaper than serializing).
|
||||
- **Trigger to start.** First report of streaming-path SPAWN_FAILED mid-stream where partial-chunk salvage would have helped a downstream caller. Practically unlikely at family scale.
|
||||
|
||||
## #7 — AUTH_MISSING tuple path test coverage (D40 follow-up)
|
||||
|
||||
|
||||
@@ -0,0 +1,503 @@
|
||||
/**
|
||||
* lib/audit-query.mjs — OLP audit ndjson aggregate query layer (Phase 3 / D49)
|
||||
*
|
||||
* Authority: ADR 0008 § 4 (query API surface) + § 5 (rotation file naming) +
|
||||
* § 3 (storage layout). Reads `~/.olp/logs/audit.ndjson` (live) +
|
||||
* `audit-YYYY-MM-DD.ndjson` (rotated dailies) and returns aggregate
|
||||
* summaries shaped for the Dashboard endpoints (D50).
|
||||
*
|
||||
* Query model (ADR 0008 Lane 2 = A): in-memory scan per request. O(N) where
|
||||
* N = total lines in the date range. Family-scale acceptable; SQLite hybrid
|
||||
* (ADR 0007 § 13) is the documented forward path when N+queries get slow.
|
||||
*
|
||||
* PII discipline (ADR 0007 § 8 + ADR 0008 § 4.3): event shape is hash + shape
|
||||
* only — no message content, no response content, no raw tokens. This module
|
||||
* MUST NOT introduce derived fields that reveal content. Every aggregate
|
||||
* function asserts the input event has the expected shape but does NOT inspect
|
||||
* or relay message bodies.
|
||||
*
|
||||
* What is NOT in this module (intentional split):
|
||||
* - Daily rotation trigger (D52, lib/audit.mjs extension)
|
||||
* - Server endpoints that consume these queries (D50, server.mjs)
|
||||
* - Dashboard HTML / DOM render (D51, dashboard.html)
|
||||
*/
|
||||
|
||||
import { readFileSync, readdirSync, existsSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
// ── Constants ─────────────────────────────────────────────────────────────
|
||||
|
||||
const DEFAULT_OLP_HOME = join(homedir(), '.olp');
|
||||
const OLP_HOME_ENV = 'OLP_HOME';
|
||||
const LIVE_AUDIT_FILE = 'audit.ndjson';
|
||||
const ROTATED_FILE_PATTERN = /^audit-(\d{4}-\d{2}-\d{2})\.ndjson$/;
|
||||
|
||||
// ── Path helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
function _resolveOlpHome(opts) {
|
||||
if (opts?.olpHome) return opts.olpHome;
|
||||
if (process.env[OLP_HOME_ENV]) return process.env[OLP_HOME_ENV];
|
||||
return DEFAULT_OLP_HOME;
|
||||
}
|
||||
|
||||
function _logsDir(opts) {
|
||||
return join(_resolveOlpHome(opts), 'logs');
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the UTC-date string (YYYY-MM-DD) for an ISO-8601 timestamp.
|
||||
*/
|
||||
function _utcDateString(isoTs) {
|
||||
if (typeof isoTs !== 'string' || isoTs.length < 10) return null;
|
||||
return isoTs.slice(0, 10);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the UTC-date string for an epoch-ms.
|
||||
*/
|
||||
function _utcDateFromMs(ms) {
|
||||
return new Date(ms).toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
/**
|
||||
* Inclusive range of UTC date strings from startDate to endDate (both
|
||||
* YYYY-MM-DD). Returns the list in ascending order. Safe for spans up to
|
||||
* several years (no upper bound enforced — caller's responsibility).
|
||||
*/
|
||||
function _dateRange(startDate, endDate) {
|
||||
const dates = [];
|
||||
const cur = new Date(`${startDate}T00:00:00Z`);
|
||||
const end = new Date(`${endDate}T00:00:00Z`);
|
||||
while (cur <= end) {
|
||||
dates.push(cur.toISOString().slice(0, 10));
|
||||
cur.setUTCDate(cur.getUTCDate() + 1);
|
||||
}
|
||||
return dates;
|
||||
}
|
||||
|
||||
// ── File enumeration ──────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Discover audit files in the logs directory. Returns a Map from
|
||||
* date-string ('YYYY-MM-DD' or 'live' for the un-rotated file) to absolute
|
||||
* file path. The 'live' entry is `audit.ndjson` if present; date-string
|
||||
* entries are the rotated daily files matching `audit-YYYY-MM-DD.ndjson`.
|
||||
*
|
||||
* Returns an empty Map if the logs directory does not exist or is empty.
|
||||
* Caller responsible for date filtering.
|
||||
*
|
||||
* @param {object} [opts] - { olpHome }
|
||||
* @returns {Map<string, string>} date-string → absolute file path
|
||||
*/
|
||||
export function discoverAuditFiles(opts = {}) {
|
||||
const dir = _logsDir(opts);
|
||||
const out = new Map();
|
||||
if (!existsSync(dir)) return out;
|
||||
let entries;
|
||||
try { entries = readdirSync(dir); } catch { return out; }
|
||||
for (const name of entries) {
|
||||
if (name === LIVE_AUDIT_FILE) {
|
||||
out.set('live', join(dir, name));
|
||||
continue;
|
||||
}
|
||||
const m = ROTATED_FILE_PATTERN.exec(name);
|
||||
if (m) {
|
||||
out.set(m[1], join(dir, name));
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// ── Line-level read + parse ───────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Parse a single ndjson line. Returns the event object on success, or
|
||||
* null on parse error. Caller logs warn for null returns.
|
||||
*/
|
||||
function _parseLine(line) {
|
||||
if (!line) return null;
|
||||
try {
|
||||
const obj = JSON.parse(line);
|
||||
if (typeof obj !== 'object' || obj === null) return null;
|
||||
return obj;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Read all events from a single file, skipping malformed lines.
|
||||
* Logs warn (via logEvent override or console) for each malformed line so
|
||||
* a corrupted day doesn't kill the query.
|
||||
*
|
||||
* @param {string} path
|
||||
* @param {(level: string, event: string, data?: object) => void} [logEvent]
|
||||
* @returns {Array<object>} parsed events
|
||||
*/
|
||||
function _readFileEvents(path, logEvent) {
|
||||
let raw;
|
||||
try {
|
||||
raw = readFileSync(path, 'utf-8');
|
||||
} catch (err) {
|
||||
// Re-throw read errors (EACCES, ENOENT during race) so the dashboard
|
||||
// endpoint surfaces 500 with diagnostic per ADR 0008 § 4.4.
|
||||
throw new Error(`audit_query_read_failed: ${path}: ${err?.message ?? err}`);
|
||||
}
|
||||
const lines = raw.split('\n');
|
||||
const events = [];
|
||||
let skipped = 0;
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i].trim();
|
||||
if (!line) continue;
|
||||
const ev = _parseLine(line);
|
||||
if (ev === null) {
|
||||
skipped++;
|
||||
continue;
|
||||
}
|
||||
events.push(ev);
|
||||
}
|
||||
if (skipped > 0 && logEvent) {
|
||||
logEvent('warn', 'audit_query_skip_malformed', { path, skipped });
|
||||
}
|
||||
return events;
|
||||
}
|
||||
|
||||
// ── Public API ────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Iterate all audit events in [startMs, endMs). Walks the rotated daily
|
||||
* files whose date overlaps the range + today's live audit.ndjson. Within
|
||||
* each file, includes only events whose `ts` falls in the window.
|
||||
*
|
||||
* Per ADR 0008 § 4.2: window semantics are half-open [start, end).
|
||||
*
|
||||
* @param {object} args
|
||||
* @param {number} args.startMs - epoch-ms inclusive lower bound
|
||||
* @param {number} args.endMs - epoch-ms exclusive upper bound
|
||||
* @param {string} [args.olpHome]
|
||||
* @param {(level: string, event: string, data?: object) => void} [args.logEvent]
|
||||
* @yields {object} parsed audit event
|
||||
*/
|
||||
export function* readAuditWindow({ startMs, endMs, olpHome, logEvent } = {}) {
|
||||
if (typeof startMs !== 'number' || typeof endMs !== 'number') {
|
||||
throw new Error('readAuditWindow: startMs and endMs (numbers) are required');
|
||||
}
|
||||
if (endMs <= startMs) return; // empty window
|
||||
|
||||
const files = discoverAuditFiles({ olpHome });
|
||||
if (files.size === 0) return;
|
||||
|
||||
// Walk all dates in [startMs, endMs) plus the live file (today).
|
||||
const startDate = _utcDateFromMs(startMs);
|
||||
const endDate = _utcDateFromMs(endMs - 1); // endMs is exclusive
|
||||
const dateList = _dateRange(startDate, endDate);
|
||||
|
||||
for (const date of dateList) {
|
||||
const path = files.get(date);
|
||||
if (!path) continue;
|
||||
const events = _readFileEvents(path, logEvent);
|
||||
for (const ev of events) {
|
||||
const tsStr = ev.ts;
|
||||
if (typeof tsStr !== 'string') continue;
|
||||
const tsMs = Date.parse(tsStr);
|
||||
if (Number.isNaN(tsMs)) continue;
|
||||
if (tsMs >= startMs && tsMs < endMs) yield ev;
|
||||
}
|
||||
}
|
||||
|
||||
// Live file (today) — always check; date may overlap window's end.
|
||||
const livePath = files.get('live');
|
||||
if (livePath) {
|
||||
const events = _readFileEvents(livePath, logEvent);
|
||||
for (const ev of events) {
|
||||
const tsStr = ev.ts;
|
||||
if (typeof tsStr !== 'string') continue;
|
||||
const tsMs = Date.parse(tsStr);
|
||||
if (Number.isNaN(tsMs)) continue;
|
||||
if (tsMs >= startMs && tsMs < endMs) yield ev;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Aggregate request shape over a rolling window ending at "now".
|
||||
*
|
||||
* Returns:
|
||||
* {
|
||||
* window: { startMs, endMs },
|
||||
* request_count, status_2xx, status_4xx, status_5xx,
|
||||
* by_provider: { [providerKey]: { count, cache_hit, cache_miss, cache_bypass, cache_streaming_attached, fallback_count } },
|
||||
* by_owner_tier: { owner: N, guest: N, anonymous: N },
|
||||
* by_path: { '/v1/chat/completions': N, '/v1/models': N, ... },
|
||||
* median_latency_ms, p95_latency_ms,
|
||||
* }
|
||||
*
|
||||
* Per ADR 0008 § 4.1 + § 4.3 PII discipline: aggregates count + categorical
|
||||
* breakdowns only, NEVER message content.
|
||||
*
|
||||
* @param {object} args
|
||||
* @param {number} args.windowMs - duration in ms; window = [now - windowMs, now)
|
||||
* @param {string} [args.olpHome]
|
||||
* @param {(level, event, data?) => void} [args.logEvent]
|
||||
* @param {() => number} [args._nowFn] - injectable for testing
|
||||
*/
|
||||
export function aggregateRequests({ windowMs, olpHome, logEvent, _nowFn } = {}) {
|
||||
if (typeof windowMs !== 'number' || windowMs <= 0) {
|
||||
throw new Error('aggregateRequests: windowMs (positive number) is required');
|
||||
}
|
||||
const now = (_nowFn ?? Date.now)();
|
||||
const startMs = now - windowMs;
|
||||
const endMs = now;
|
||||
|
||||
const result = {
|
||||
window: { startMs, endMs },
|
||||
request_count: 0,
|
||||
status_2xx: 0,
|
||||
status_4xx: 0,
|
||||
status_5xx: 0,
|
||||
by_provider: {},
|
||||
by_owner_tier: { owner: 0, guest: 0, anonymous: 0 },
|
||||
by_path: {},
|
||||
median_latency_ms: 0,
|
||||
p95_latency_ms: 0,
|
||||
};
|
||||
const latencies = [];
|
||||
|
||||
for (const ev of readAuditWindow({ startMs, endMs, olpHome, logEvent })) {
|
||||
result.request_count++;
|
||||
|
||||
// Status code bucket
|
||||
const sc = typeof ev.status_code === 'number' ? ev.status_code : 0;
|
||||
if (sc >= 200 && sc < 300) result.status_2xx++;
|
||||
else if (sc >= 400 && sc < 500) result.status_4xx++;
|
||||
else if (sc >= 500) result.status_5xx++;
|
||||
|
||||
// By provider
|
||||
if (typeof ev.provider === 'string' && ev.provider.length > 0) {
|
||||
const p = result.by_provider[ev.provider] ??= {
|
||||
count: 0, cache_hit: 0, cache_miss: 0, cache_bypass: 0, cache_streaming_attached: 0, fallback_count: 0,
|
||||
};
|
||||
p.count++;
|
||||
if (ev.cache_status === 'hit') p.cache_hit++;
|
||||
else if (ev.cache_status === 'miss') p.cache_miss++;
|
||||
else if (ev.cache_status === 'bypass') p.cache_bypass++;
|
||||
// D58 — ADR 0005 Amendment 8 §11 + lib/audit.mjs cache_status enum: streaming
|
||||
// singleflight joiners (attached) share the source spawn but did not hit a
|
||||
// cache. Tracked separately so `count` and `cache_hit + cache_miss +
|
||||
// cache_bypass + cache_streaming_attached` reconcile.
|
||||
else if (ev.cache_status === 'streaming_attached') p.cache_streaming_attached++;
|
||||
if (typeof ev.fallback_hops === 'number' && ev.fallback_hops > 0) p.fallback_count++;
|
||||
}
|
||||
|
||||
// By owner tier
|
||||
if (ev.owner_tier === 'owner') result.by_owner_tier.owner++;
|
||||
else if (ev.owner_tier === 'guest') result.by_owner_tier.guest++;
|
||||
else result.by_owner_tier.anonymous++;
|
||||
|
||||
// By path
|
||||
if (typeof ev.path === 'string' && ev.path.length > 0) {
|
||||
result.by_path[ev.path] = (result.by_path[ev.path] ?? 0) + 1;
|
||||
}
|
||||
|
||||
// Latency
|
||||
if (typeof ev.latency_ms === 'number' && ev.latency_ms >= 0) {
|
||||
latencies.push(ev.latency_ms);
|
||||
}
|
||||
}
|
||||
|
||||
// Median + p95 over sorted latencies
|
||||
if (latencies.length > 0) {
|
||||
latencies.sort((a, b) => a - b);
|
||||
const midIdx = Math.floor(latencies.length / 2);
|
||||
result.median_latency_ms = latencies.length % 2 === 0
|
||||
? Math.round((latencies[midIdx - 1] + latencies[midIdx]) / 2)
|
||||
: latencies[midIdx];
|
||||
const p95Idx = Math.min(latencies.length - 1, Math.floor(latencies.length * 0.95));
|
||||
result.p95_latency_ms = latencies[p95Idx];
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Top-N fallback chains by trigger count in window. A "chain" is the
|
||||
* `tried_providers` array from an event with fallback_hops > 0. Returns
|
||||
* sorted array descending by count; ties broken by earliest first_seen.
|
||||
*
|
||||
* [{ chain: ['anthropic', 'openai'], count: 42, first_seen, last_seen }, ...]
|
||||
*
|
||||
* @param {object} args
|
||||
* @param {number} args.windowMs
|
||||
* @param {number} [args.limit=10]
|
||||
* @param {string} [args.olpHome]
|
||||
* @param {(level, event, data?) => void} [args.logEvent]
|
||||
* @param {() => number} [args._nowFn]
|
||||
*/
|
||||
export function topFallbackChains({ windowMs, limit = 10, olpHome, logEvent, _nowFn } = {}) {
|
||||
if (typeof windowMs !== 'number' || windowMs <= 0) {
|
||||
throw new Error('topFallbackChains: windowMs (positive number) is required');
|
||||
}
|
||||
const now = (_nowFn ?? Date.now)();
|
||||
const startMs = now - windowMs;
|
||||
const endMs = now;
|
||||
|
||||
// Map chain-key (joined string) → aggregate
|
||||
const chains = new Map();
|
||||
for (const ev of readAuditWindow({ startMs, endMs, olpHome, logEvent })) {
|
||||
if (typeof ev.fallback_hops !== 'number' || ev.fallback_hops <= 0) continue;
|
||||
if (!Array.isArray(ev.tried_providers) || ev.tried_providers.length < 2) continue;
|
||||
const key = ev.tried_providers.join('→');
|
||||
const entry = chains.get(key);
|
||||
const ts = typeof ev.ts === 'string' ? ev.ts : null;
|
||||
if (entry === undefined) {
|
||||
chains.set(key, {
|
||||
chain: [...ev.tried_providers],
|
||||
count: 1,
|
||||
first_seen: ts,
|
||||
last_seen: ts,
|
||||
});
|
||||
} else {
|
||||
entry.count++;
|
||||
if (ts && (!entry.first_seen || ts < entry.first_seen)) entry.first_seen = ts;
|
||||
if (ts && (!entry.last_seen || ts > entry.last_seen)) entry.last_seen = ts;
|
||||
}
|
||||
}
|
||||
|
||||
// Sort desc by count, ascending by first_seen on ties
|
||||
const arr = [...chains.values()];
|
||||
arr.sort((a, b) => {
|
||||
if (b.count !== a.count) return b.count - a.count;
|
||||
if (a.first_seen && b.first_seen) return a.first_seen < b.first_seen ? -1 : a.first_seen > b.first_seen ? 1 : 0;
|
||||
return 0;
|
||||
});
|
||||
return arr.slice(0, limit);
|
||||
}
|
||||
|
||||
/**
|
||||
* Daily series of request_count + median latency_ms + by_provider over N
|
||||
* UTC days ending today. Sparse-fills zero-request days. Returns ascending
|
||||
* by date:
|
||||
*
|
||||
* [{ date: '2026-05-22', request_count, median_latency_ms, by_provider }, ...]
|
||||
*
|
||||
* by_provider is { [providerKey]: count } per day.
|
||||
*
|
||||
* @param {object} args
|
||||
* @param {number} args.days
|
||||
* @param {string} [args.olpHome]
|
||||
* @param {(level, event, data?) => void} [args.logEvent]
|
||||
* @param {() => number} [args._nowFn]
|
||||
*/
|
||||
export function spendTrendDaily({ days, olpHome, logEvent, _nowFn } = {}) {
|
||||
if (typeof days !== 'number' || days <= 0) {
|
||||
throw new Error('spendTrendDaily: days (positive number) is required');
|
||||
}
|
||||
const now = (_nowFn ?? Date.now)();
|
||||
|
||||
// Compute the N UTC dates ending today (inclusive). Semantics: "last N
|
||||
// calendar dates ending today" — NOT "events within a rolling N*86400-ms
|
||||
// window ago" (the latter would span N+1 distinct UTC dates and produce
|
||||
// off-by-one buckets at non-midnight call times).
|
||||
const dates = [];
|
||||
for (let i = days - 1; i >= 0; i--) {
|
||||
dates.push(_utcDateFromMs(now - i * 86400 * 1000));
|
||||
}
|
||||
// Window covers the start of the first date through "now" so readAuditWindow
|
||||
// sees every event whose ts falls in any of the N dates' UTC days.
|
||||
const startMs = Date.parse(`${dates[0]}T00:00:00Z`);
|
||||
const endMs = now;
|
||||
|
||||
// Bucket by UTC date
|
||||
const buckets = new Map();
|
||||
for (const ev of readAuditWindow({ startMs, endMs, olpHome, logEvent })) {
|
||||
const date = _utcDateString(ev.ts);
|
||||
if (!date) continue;
|
||||
const b = buckets.get(date) ?? { request_count: 0, latencies: [], by_provider: {} };
|
||||
b.request_count++;
|
||||
if (typeof ev.latency_ms === 'number') b.latencies.push(ev.latency_ms);
|
||||
if (typeof ev.provider === 'string' && ev.provider.length > 0) {
|
||||
b.by_provider[ev.provider] = (b.by_provider[ev.provider] ?? 0) + 1;
|
||||
}
|
||||
buckets.set(date, b);
|
||||
}
|
||||
|
||||
// Sparse-fill using the precomputed dates list (preserves ascending order)
|
||||
return dates.map(date => {
|
||||
const b = buckets.get(date);
|
||||
if (b) {
|
||||
b.latencies.sort((a, b) => a - b);
|
||||
const midIdx = Math.floor(b.latencies.length / 2);
|
||||
const median = b.latencies.length === 0 ? 0
|
||||
: b.latencies.length % 2 === 0
|
||||
? Math.round((b.latencies[midIdx - 1] + b.latencies[midIdx]) / 2)
|
||||
: b.latencies[midIdx];
|
||||
return {
|
||||
date,
|
||||
request_count: b.request_count,
|
||||
median_latency_ms: median,
|
||||
by_provider: b.by_provider,
|
||||
};
|
||||
}
|
||||
return { date, request_count: 0, median_latency_ms: 0, by_provider: {} };
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Audit-derived cache hit rate over the window. Differs from
|
||||
* `cacheStore.stats()` in server.mjs: that is the live in-process counter;
|
||||
* this is the audit-side rate scoped to the rolling window.
|
||||
*
|
||||
* { window: { startMs, endMs }, total, hit, miss, bypass, streaming_attached, hit_rate, by_provider }
|
||||
*
|
||||
* `streaming_attached` (D58, ADR 0005 Amendment 8 §11): D58 streaming
|
||||
* singleflight joiners did not hit a literal cache, so they are excluded
|
||||
* from both numerator AND denominator of `hit_rate`. Tracked separately
|
||||
* so the count reconciles with `total = hit + miss + bypass + streaming_attached`.
|
||||
*
|
||||
* @param {object} args
|
||||
* @param {number} args.windowMs
|
||||
* @param {string} [args.olpHome]
|
||||
* @param {(level, event, data?) => void} [args.logEvent]
|
||||
* @param {() => number} [args._nowFn]
|
||||
*/
|
||||
export function cacheHitRateWindow({ windowMs, olpHome, logEvent, _nowFn } = {}) {
|
||||
if (typeof windowMs !== 'number' || windowMs <= 0) {
|
||||
throw new Error('cacheHitRateWindow: windowMs (positive number) is required');
|
||||
}
|
||||
const now = (_nowFn ?? Date.now)();
|
||||
const startMs = now - windowMs;
|
||||
const endMs = now;
|
||||
|
||||
let total = 0, hit = 0, miss = 0, bypass = 0, streaming_attached = 0;
|
||||
const by_provider = {};
|
||||
|
||||
for (const ev of readAuditWindow({ startMs, endMs, olpHome, logEvent })) {
|
||||
if (ev.cache_status === null || ev.cache_status === undefined) continue;
|
||||
total++;
|
||||
const p = typeof ev.provider === 'string' && ev.provider.length > 0 ? ev.provider : '__unknown__';
|
||||
const pe = by_provider[p] ??= { total: 0, hit: 0, miss: 0, bypass: 0, streaming_attached: 0, hit_rate: 0 };
|
||||
pe.total++;
|
||||
if (ev.cache_status === 'hit') { hit++; pe.hit++; }
|
||||
else if (ev.cache_status === 'miss') { miss++; pe.miss++; }
|
||||
else if (ev.cache_status === 'bypass') { bypass++; pe.bypass++; }
|
||||
// D58 — ADR 0005 Amendment 8 §11: streaming singleflight joiners.
|
||||
// Excluded from hit_rate numerator + denominator (they did not hit a
|
||||
// literal cache); tracked so `total` reconciles.
|
||||
else if (ev.cache_status === 'streaming_attached') { streaming_attached++; pe.streaming_attached++; }
|
||||
}
|
||||
|
||||
// Compute hit_rate per provider + overall (excludes bypass from denominator
|
||||
// since bypass-by-cache_control is intentional non-cacheable, not a cache miss).
|
||||
for (const p of Object.values(by_provider)) {
|
||||
const denom = p.hit + p.miss;
|
||||
p.hit_rate = denom > 0 ? p.hit / denom : 0;
|
||||
}
|
||||
const overallDenom = hit + miss;
|
||||
const hit_rate = overallDenom > 0 ? hit / overallDenom : 0;
|
||||
|
||||
return {
|
||||
window: { startMs, endMs },
|
||||
total, hit, miss, bypass, streaming_attached, hit_rate, by_provider,
|
||||
};
|
||||
}
|
||||
+296
@@ -0,0 +1,296 @@
|
||||
/**
|
||||
* lib/audit.mjs — OLP audit ndjson append (Phase 2 / D45)
|
||||
*
|
||||
* Authority: ADR 0007 § 6.2 (audit append semantics) + § 8 (event schema).
|
||||
*
|
||||
* Behaviour:
|
||||
* - One JSON event per line; newline-terminated; UTF-8.
|
||||
* - Append to ~/.olp/logs/audit.ndjson (chmod 0600 file, 0700 dir).
|
||||
* - On append failure: log a warn ('audit_append_failed_once') + retry
|
||||
* once synchronously.
|
||||
* - On second-failure: increment per-process drop counter + log warn
|
||||
* ('audit_append_dropped'); NEVER throw to the caller (audit is
|
||||
* observability, not authorization). Per § 6.2.
|
||||
* - No memory buffer at Phase 2 (forward-path note in ADR § 13).
|
||||
*
|
||||
* Atomicity note: Node's `fs.appendFileSync` opens with O_APPEND which is
|
||||
* POSIX-atomic for writes <= PIPE_BUF (typically 4096 bytes). Our event
|
||||
* payloads (§ 8 schema with hash + shape fields, no PII / no message
|
||||
* content) are well under that limit, so concurrent in-process appends
|
||||
* are line-atomic without explicit locking.
|
||||
*
|
||||
* No PII: § 8 explicitly excludes request body, response body, and IR
|
||||
* message content. Hash + shape only.
|
||||
*/
|
||||
|
||||
import { appendFileSync, mkdirSync, chmodSync, renameSync, existsSync, statSync, readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
const DEFAULT_OLP_HOME = join(homedir(), '.olp');
|
||||
const OLP_HOME_ENV = 'OLP_HOME';
|
||||
const RETRY_COUNT = 1; // § 6.2: warn + 1 retry
|
||||
const LIVE_AUDIT_FILE = 'audit.ndjson';
|
||||
const ROTATED_FILE_PREFIX = 'audit-';
|
||||
const ROTATED_FILE_SUFFIX = '.ndjson';
|
||||
|
||||
let _dropCounter = 0;
|
||||
let _rotateCounter = 0; // observability + test assertion target
|
||||
let _rotateFailCounter = 0;
|
||||
// Module-cached "last UTC date we saw at append time" so we don't read
|
||||
// disk metadata on every append just to check for rotation.
|
||||
let _lastSeenUtcDate = _utcDateNow();
|
||||
|
||||
/**
|
||||
* Resolve OLP home dir (matches lib/keys.mjs precedence): opts.olpHome →
|
||||
* process.env.OLP_HOME → ~/.olp. Resolved per call so tests setting the
|
||||
* env mid-run take effect.
|
||||
*/
|
||||
function _resolveOlpHome(opts) {
|
||||
if (opts?.olpHome) return opts.olpHome;
|
||||
if (process.env[OLP_HOME_ENV]) return process.env[OLP_HOME_ENV];
|
||||
return DEFAULT_OLP_HOME;
|
||||
}
|
||||
|
||||
/**
|
||||
* Current UTC date as YYYY-MM-DD. Module-private; reused by rotation logic.
|
||||
*/
|
||||
function _utcDateNow() {
|
||||
return new Date().toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the first event's `ts` from the live audit file to discover the
|
||||
* date it was opened on (for stale-cache recovery when the process is
|
||||
* restarted and the in-memory `_lastSeenUtcDate` doesn't match). Returns
|
||||
* the YYYY-MM-DD string, or null if the file is missing / empty /
|
||||
* malformed.
|
||||
*/
|
||||
function _firstEventDateInLiveFile(livePath) {
|
||||
try {
|
||||
if (!existsSync(livePath)) return null;
|
||||
// Read the file + slice off the first ndjson line. For audit ndjson the
|
||||
// first line is at most a few hundred bytes; this is fine for the rare
|
||||
// "process restart with a stale live file" recovery path. (Family-scale
|
||||
// single-file audit is bounded; multi-MB scans are not a real concern
|
||||
// until Phase 4+ when Option 3 SQLite migration would kick in anyway.)
|
||||
const raw = readFileSync(livePath, 'utf-8');
|
||||
const nl = raw.indexOf('\n');
|
||||
const firstLine = nl === -1 ? raw : raw.slice(0, nl);
|
||||
if (!firstLine) return null;
|
||||
const obj = JSON.parse(firstLine);
|
||||
if (typeof obj?.ts !== 'string') return null;
|
||||
return obj.ts.slice(0, 10);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Rotate the live audit file (if any) to its UTC-date suffix. Idempotent:
|
||||
* if a rotated file with that name already exists (e.g., cron beat us to
|
||||
* it), this skips the rename.
|
||||
*
|
||||
* Per ADR 0008 § 5.1 + § 5.3. SYNCHRONOUS so callers (appendAuditEvent +
|
||||
* external cron) can rely on it completing before the next IO operation.
|
||||
* Sync rotation eliminates the race that an async wrapper would create
|
||||
* between the date-change-detection and the append (where the append could
|
||||
* land in the old un-rotated file).
|
||||
*
|
||||
* Concurrent in-process invocations: Node's single-threaded event loop
|
||||
* serializes synchronous calls within a tick. Cross-tick concurrency
|
||||
* uses the `_lastSeenUtcDate` cache as the gate — once set, subsequent
|
||||
* appends short-circuit the rotation check.
|
||||
*
|
||||
* @param {object} args - { olpHome, logEvent, _nowFn (test injection) }
|
||||
* @returns {{ rotated: boolean, fromPath?: string, toPath?: string, dateUsed?: string }}
|
||||
*/
|
||||
export function _maybeRotateAudit(args = {}) {
|
||||
const olpHome = _resolveOlpHome(args);
|
||||
const logEvent = args.logEvent ?? ((level, ev, data) => {
|
||||
const entry = { ts: new Date().toISOString(), level, event: ev, ...(data ?? {}) };
|
||||
process.stderr.write(JSON.stringify(entry) + '\n');
|
||||
});
|
||||
const nowFn = args._nowFn ?? (() => new Date());
|
||||
|
||||
const logsDir = join(olpHome, 'logs');
|
||||
const livePath = join(logsDir, LIVE_AUDIT_FILE);
|
||||
if (!existsSync(livePath)) {
|
||||
// No live file yet (first append ever); no rotation needed.
|
||||
_lastSeenUtcDate = nowFn().toISOString().slice(0, 10);
|
||||
return { rotated: false };
|
||||
}
|
||||
// Determine the "date the live file holds" — use the first event's ts.
|
||||
// Fall back to file mtime if events absent (corrupt / empty file edge).
|
||||
let fileDate = _firstEventDateInLiveFile(livePath);
|
||||
if (fileDate === null) {
|
||||
try {
|
||||
fileDate = statSync(livePath).mtime.toISOString().slice(0, 10);
|
||||
} catch {
|
||||
return { rotated: false };
|
||||
}
|
||||
}
|
||||
const today = nowFn().toISOString().slice(0, 10);
|
||||
if (fileDate === today) {
|
||||
_lastSeenUtcDate = today;
|
||||
return { rotated: false };
|
||||
}
|
||||
|
||||
// Rotate: rename live → audit-<fileDate>.ndjson.
|
||||
const rotatedName = `${ROTATED_FILE_PREFIX}${fileDate}${ROTATED_FILE_SUFFIX}`;
|
||||
const rotatedPath = join(logsDir, rotatedName);
|
||||
if (existsSync(rotatedPath)) {
|
||||
// Cron or another writer beat us; the live file holding fileDate's
|
||||
// events must be merged manually. Per ADR 0008 § 5.3 we log + skip.
|
||||
logEvent('warn', 'audit_rotate_target_exists', {
|
||||
livePath, rotatedPath,
|
||||
message: 'rotation target exists — concurrent rotator beat in-process check; manual merge required if events overlap',
|
||||
});
|
||||
_lastSeenUtcDate = today;
|
||||
return { rotated: false };
|
||||
}
|
||||
try {
|
||||
renameSync(livePath, rotatedPath);
|
||||
_rotateCounter++;
|
||||
_lastSeenUtcDate = today;
|
||||
logEvent('info', 'audit_rotated', { fromPath: livePath, toPath: rotatedPath, dateUsed: fileDate });
|
||||
return { rotated: true, fromPath: livePath, toPath: rotatedPath, dateUsed: fileDate };
|
||||
} catch (err) {
|
||||
_rotateFailCounter++;
|
||||
logEvent('warn', 'audit_rotate_failed', {
|
||||
livePath, rotatedPath,
|
||||
error: err?.message ?? String(err),
|
||||
});
|
||||
// Don't update _lastSeenUtcDate so the next append retries.
|
||||
return { rotated: false };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Append a single audit event to ~/.olp/logs/audit.ndjson.
|
||||
*
|
||||
* @param {object} event - § 8 schema fields (ts, key_id, owner_tier,
|
||||
* method, path, provider, model, status_code, latency_ms, cache_status,
|
||||
* fallback_hops, tried_providers, error_code, ir_request_hash, chain_id).
|
||||
* Caller is responsible for populating fields; missing fields are
|
||||
* serialized as undefined → omitted by JSON.stringify.
|
||||
*
|
||||
* cache_status enum (free-form string; not schema-validated at append):
|
||||
* 'hit' — served from cache (buffered-replay or streaming
|
||||
* cache_hit role from ADR 0005 Amendment 8 §1).
|
||||
* 'miss' — buffered or streaming source path; provider
|
||||
* spawn fired for this request.
|
||||
* 'bypass' — D2 cache_control bypass (no cache read/write).
|
||||
* 'streaming_attached' — D58 / ADR 0005 Amendment 8 §11: client joined
|
||||
* an in-flight streaming source spawn from
|
||||
* another caller; this request did NOT spawn a
|
||||
* provider but also did NOT hit the cache (the
|
||||
* cache was empty at the inflight Map check).
|
||||
* null — pre-chain error paths (the cache layer was
|
||||
* never consulted; e.g. 401, 415, 400 IR).
|
||||
* @param {object} [opts]
|
||||
* @param {string} [opts.olpHome] - test override; defaults to ~/.olp
|
||||
* @param {(level: string, event: string, data?: object) => void} [opts.logEvent]
|
||||
* - injectable structured logger; defaults to console.warn with JSON line
|
||||
*/
|
||||
export function appendAuditEvent(event, opts = {}) {
|
||||
const olpHome = _resolveOlpHome(opts);
|
||||
const logsDir = join(olpHome, 'logs');
|
||||
const path = join(logsDir, LIVE_AUDIT_FILE);
|
||||
const line = JSON.stringify(event) + '\n';
|
||||
const logEvent = opts.logEvent ?? ((level, ev, data) => {
|
||||
const entry = { ts: new Date().toISOString(), level, event: ev, ...(data ?? {}) };
|
||||
process.stderr.write(JSON.stringify(entry) + '\n');
|
||||
});
|
||||
|
||||
// D52: cheap fast-path date check. If the module-cached date matches the
|
||||
// current UTC date, skip the rotation probe entirely (no disk I/O). If
|
||||
// the date has changed, synchronously rotate BEFORE the append so the
|
||||
// append lands in the (post-rotation) new live file rather than the
|
||||
// about-to-rotate-away old one.
|
||||
// Per ADR 0008 § 5.1: rotation fires "on the first append after a UTC
|
||||
// date change." Synchronous rotation ensures no append straddles the
|
||||
// boundary — old-date events land in the rotated file; new-date events
|
||||
// land in the fresh live file. The cache flip happens INSIDE
|
||||
// _maybeRotateAudit so concurrent in-process re-triggers short-circuit.
|
||||
const today = _utcDateNow();
|
||||
if (today !== _lastSeenUtcDate) {
|
||||
_maybeRotateAudit({ olpHome, logEvent });
|
||||
}
|
||||
|
||||
for (let attempt = 0; attempt <= RETRY_COUNT; attempt++) {
|
||||
try {
|
||||
mkdirSync(logsDir, { recursive: true, mode: 0o700 });
|
||||
// Tighten dir mode in case it already existed with broader permissions.
|
||||
try { chmodSync(logsDir, 0o700); } catch { /* tolerate EPERM */ }
|
||||
appendFileSync(path, line, { mode: 0o600 });
|
||||
return;
|
||||
} catch (err) {
|
||||
if (attempt < RETRY_COUNT) {
|
||||
logEvent('warn', 'audit_append_failed_once', {
|
||||
path,
|
||||
error: err?.message ?? String(err),
|
||||
});
|
||||
continue;
|
||||
}
|
||||
_dropCounter++;
|
||||
logEvent('warn', 'audit_append_dropped', {
|
||||
path,
|
||||
error: err?.message ?? String(err),
|
||||
drop_count: _dropCounter,
|
||||
});
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-process count of audit events dropped due to repeated append failure.
|
||||
* Useful for /health observability surface (D46).
|
||||
*/
|
||||
export function getAuditDropCount() {
|
||||
return _dropCounter;
|
||||
}
|
||||
|
||||
/**
|
||||
* Test-only: reset the drop counter to zero. Suite 20 uses this between
|
||||
* cases to assert independent failure-handling counts.
|
||||
*/
|
||||
export function __resetAuditDropCount() {
|
||||
_dropCounter = 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-process count of successful rotations performed. Test + future
|
||||
* observability surface.
|
||||
*/
|
||||
export function getAuditRotateCount() {
|
||||
return _rotateCounter;
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-process count of failed rotation attempts (rename threw, target
|
||||
* existed, etc.). Test + future observability surface.
|
||||
*/
|
||||
export function getAuditRotateFailCount() {
|
||||
return _rotateFailCounter;
|
||||
}
|
||||
|
||||
/**
|
||||
* Test-only: reset the rotation counters + the in-process "last seen UTC
|
||||
* date" cache so each test exercises a fresh code path.
|
||||
*/
|
||||
export function __resetAuditRotateState() {
|
||||
_rotateCounter = 0;
|
||||
_rotateFailCounter = 0;
|
||||
_lastSeenUtcDate = _utcDateNow();
|
||||
}
|
||||
|
||||
/**
|
||||
* Test-only: force the cached "last seen UTC date" to a specific value
|
||||
* so the next appendAuditEvent observes a date change and triggers
|
||||
* rotation deterministically.
|
||||
*/
|
||||
export function __setLastSeenUtcDateForTesting(dateStr) {
|
||||
_lastSeenUtcDate = dateStr;
|
||||
}
|
||||
Vendored
+582
-9
@@ -51,6 +51,75 @@
|
||||
* @property {number} inflightCount
|
||||
*/
|
||||
|
||||
// ── D57 — ADR 0005 Amendment 8 streaming-singleflight shapes ──────────────
|
||||
|
||||
/**
|
||||
* @typedef {Object} StreamingInflightEntry
|
||||
* @property {string} compositeKey - `${keyId}\0${cacheKey}`
|
||||
* @property {AsyncIterator<*>|null} source - underlying source iterator (null while factory pending)
|
||||
* @property {AbortController} sourceAbortController - propagates "all clients gone" to the source
|
||||
* @property {Array<*>} accumulatedChunks - late-joiner replay buffer (bounded by §10)
|
||||
* @property {number} accumulatedByteSize - running byte size of accumulatedChunks
|
||||
* @property {boolean} accumulatedReplayCapExceeded - true once §10 cap hit; cache write will skip
|
||||
* @property {Set<AttachedClient>} attachedClients - all live clients tee'ing this source
|
||||
* @property {boolean} factoryPending - true while sourceFactory() is awaited
|
||||
* @property {Array<{ resolve: function, reject: function }>} pendingJoiners - late joiners arriving during factoryPending
|
||||
* @property {boolean} sourceDone - source iterator exhausted normally
|
||||
* @property {Error|null} sourceError - non-null if source threw
|
||||
* @property {boolean} sourceAborted - true if AbortController fired
|
||||
* @property {number} ttlMs - TTL to use when writing the completed accumulated chunks to cache
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {Object} AttachedClient
|
||||
* @property {string} id - request id / correlator
|
||||
* @property {Array<*>} queue - per-client tee buffer
|
||||
* @property {number} queueByteSize - running byte size sum
|
||||
* @property {boolean} yieldedAccumulated - true after late-joiner replay drained
|
||||
* @property {boolean} done - terminal sentinel hit
|
||||
* @property {boolean} backpressured - true once STREAM_BACKPRESSURE terminator scheduled
|
||||
* @property {Error|null} error - non-null if source threw or replay-drain over-cap
|
||||
* @property {((chunk: { value: *, done: boolean }) => void)|null} resolveNext - pending pull promise resolver
|
||||
* @property {((err: Error) => void)|null} rejectNext - pending pull promise rejecter
|
||||
*/
|
||||
|
||||
// ADR 0005 Amendment 8 §14 — implementation defaults. Per-call overrides flow
|
||||
// via the `opts` argument to getOrComputeStreaming (used by tests to exercise
|
||||
// caps cheaply without producing megabytes of fixture data).
|
||||
export const PER_CLIENT_QUEUE_CAP_DEFAULT = 1 * 1024 * 1024;
|
||||
export const ACCUMULATED_REPLAY_CAP_DEFAULT = 10 * 1024 * 1024;
|
||||
|
||||
/**
|
||||
* Returns an approximate byte size for a chunk. The tee + cap math uses
|
||||
* JSON.stringify length as the serialization yardstick (matches the cache
|
||||
* store's existing size accounting via Buffer.byteLength(JSON.stringify(...))).
|
||||
* Non-stringifiable values (circular, etc.) fall back to 0 — the tee continues
|
||||
* but the size accounting under-estimates that chunk. In practice IR chunks
|
||||
* are always JSON-safe.
|
||||
*
|
||||
* @param {*} chunk
|
||||
* @returns {number}
|
||||
*/
|
||||
function _chunkByteSize(chunk) {
|
||||
try {
|
||||
return Buffer.byteLength(JSON.stringify(chunk) ?? '', 'utf8');
|
||||
} catch {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Synthesises a STREAM_BACKPRESSURE terminator stream (ADR 0005 Amendment 8 §8):
|
||||
* yields `{ type: 'stop', finish_reason: 'length' }` then a `[DONE]` sentinel
|
||||
* then ends. Used both for late-joiner-too-late and per-client overflow paths.
|
||||
*
|
||||
* @returns {AsyncGenerator<*>}
|
||||
*/
|
||||
async function* _backpressureTerminator() {
|
||||
yield { type: 'stop', finish_reason: 'length' };
|
||||
yield '[DONE]';
|
||||
}
|
||||
|
||||
// ── CacheStore ────────────────────────────────────────────────────────────
|
||||
|
||||
export class CacheStore {
|
||||
@@ -82,6 +151,14 @@ export class CacheStore {
|
||||
/** @type {Map<string, Promise<*>>} */
|
||||
this._inflight = new Map();
|
||||
|
||||
// D57 — ADR 0005 Amendment 8: streaming singleflight per-(keyId,cacheKey)
|
||||
// inflight Map. Composite key uses `\0` separator per §2 (avoids colliding
|
||||
// with keyId or cacheKey content). The check + insert against this Map is
|
||||
// synchronous in getOrComputeStreaming (no `await` between read & write),
|
||||
// mirroring D38 `tryAcquireSpawn` atomicity.
|
||||
/** @type {Map<string, StreamingInflightEntry>} */
|
||||
this._streamingInflight = new Map();
|
||||
|
||||
// Stats per keyId
|
||||
/** @type {Map<string, { hits: number, misses: number }>} */
|
||||
this._stats = new Map();
|
||||
@@ -266,13 +343,10 @@ export class CacheStore {
|
||||
* @param {number} [ttlMs]
|
||||
* @returns {Promise<*>}
|
||||
*
|
||||
* TODO(v1.x — ADR 0005 Amendment 8 / issue #16): add a sibling
|
||||
* `getOrComputeStreaming(keyId, cacheKey, sourceFactory)` for the streaming
|
||||
* path. This API handles buffered responses only; the streaming branch in
|
||||
* server.mjs currently uses a peek+spawn pattern with a TOCTOU window.
|
||||
* The streaming sibling will mirror this method's shape but with a tee
|
||||
* fan-out and per-client backpressure queues. See docs/v1x-roadmap.md #1
|
||||
* for the design contract and acceptance criteria.
|
||||
* D57 — ADR 0005 Amendment 8 / issue #16 resolved at the cache layer:
|
||||
* the sibling `getOrComputeStreaming` method below provides tee-fan-out +
|
||||
* per-client backpressure for the streaming path. Server-side wiring lands
|
||||
* separately in D58.
|
||||
*/
|
||||
async getOrCompute(keyId, cacheKey, computeFn, ttlMs) {
|
||||
// 1. Cache hit — return immediately, no singleflight overhead
|
||||
@@ -311,6 +385,493 @@ export class CacheStore {
|
||||
return computePromise;
|
||||
}
|
||||
|
||||
/**
|
||||
* D57 — ADR 0005 Amendment 8 (issue #16): streaming singleflight + tee-fan-out.
|
||||
*
|
||||
* Streaming-path sibling of `getOrCompute`. Coordinates concurrent identical
|
||||
* streaming requests so only one source spawn occurs, all attached clients
|
||||
* receive identical chunk sequences in order, late joiners are replayed from
|
||||
* an accumulated buffer, slow clients are disconnected with a synthetic
|
||||
* STREAM_BACKPRESSURE terminator instead of stalling the source, and the
|
||||
* source is aborted when all clients disconnect.
|
||||
*
|
||||
* The Map check + insert against `_streamingInflight` is synchronous — no
|
||||
* `await` between read and write — matching the D38 `tryAcquireSpawn`
|
||||
* atomicity invariant and collapsing the original TOCTOU window in
|
||||
* `server.mjs:782` (peek + spawn). See §1 + §6.
|
||||
*
|
||||
* Three outcomes (Amendment 8 §1):
|
||||
* - **cache_hit**: cached entry exists and is alive → returns
|
||||
* `{ stream: <async iterator over cached chunks>, isFirst: false,
|
||||
* role: 'cache_hit' }`. No spawn. `hits` incremented.
|
||||
* - **attached**: inflight entry exists in `_streamingInflight` → attaches
|
||||
* a new AttachedClient. Late-joiner replay (§5) drains accumulated
|
||||
* chunks synchronously; if drain would exceed `perClientQueueCap` the
|
||||
* client receives a STREAM_BACKPRESSURE synthesised stream instead.
|
||||
* `isFirst: false`, `role: 'attached'`. `hits` incremented (sharing a
|
||||
* spawn is functionally a "cache-like" benefit; documented choice).
|
||||
* - **source**: no cache hit, no inflight entry → the cache layer takes
|
||||
* the inflight lock synchronously (placeholder entry inserted), then
|
||||
* `await sourceFactory()`. If the factory throws (e.g.
|
||||
* CONCURRENCY_LIMIT) the placeholder is removed and the error
|
||||
* propagates. On success the source is wired up, the tee task starts,
|
||||
* `isFirst: true`, `role: 'source'`. `misses` incremented.
|
||||
*
|
||||
* **`role` enum** (returned at attach-time):
|
||||
* - `source` — first caller; entry created. Lifetime-end may upgrade to
|
||||
* `solo` (no joiners ever attached) at the server (D58); the cache
|
||||
* layer reports `source` at attach-time and does not flip mid-stream.
|
||||
* - `attached` — joined an existing inflight entry.
|
||||
* - `cache_hit` — served from cache; no entry created.
|
||||
*
|
||||
* **Amendment 8 §11 header values**: the X-OLP-Streaming-Inflight header
|
||||
* (D58) uses `source | attached | solo`. The cache layer's `cache_hit` is
|
||||
* the "served from cache without inflight" case; D58 chooses whether to
|
||||
* emit `solo` or omit the header for that path. The cache layer reports
|
||||
* `cache_hit` as a distinct role so the server can disambiguate.
|
||||
*
|
||||
* **§14 defaults**: `PER_CLIENT_QUEUE_CAP = 1 MB`, `ACCUMULATED_REPLAY_CAP
|
||||
* = 10 MB`. Both overridable via `opts` for cheap test exercise of the cap
|
||||
* paths.
|
||||
*
|
||||
* @param {string} keyId
|
||||
* @param {string} cacheKey
|
||||
* @param {() => Promise<AsyncIterator<*>>|AsyncIterator<*>} sourceFactory
|
||||
* Invoked exactly once per inflight lifetime (only on first caller).
|
||||
* Returns the source async iterator. May throw (e.g. CONCURRENCY_LIMIT
|
||||
* from `tryAcquireSpawn`); on throw, the inflight entry is removed and
|
||||
* the error propagates to the first caller. Late joiners that attached
|
||||
* while the factory was pending are rejected with the same error.
|
||||
* @param {object} [opts]
|
||||
* @param {string} [opts.clientId] - correlator id (defaults to incrementing counter)
|
||||
* @param {number} [opts.ttlMs] - TTL for completed accumulated-chunks cache write
|
||||
* @param {number} [opts.perClientQueueCap] - override §14 default (1 MB)
|
||||
* @param {number} [opts.accumulatedReplayCap] - override §14 default (10 MB)
|
||||
* @returns {Promise<{ stream: AsyncGenerator<*>, isFirst: boolean, role: 'source'|'attached'|'cache_hit' }>}
|
||||
*/
|
||||
async getOrComputeStreaming(keyId, cacheKey, sourceFactory, opts = {}) {
|
||||
const compositeKey = `${keyId}\0${cacheKey}`;
|
||||
const perClientQueueCap = opts.perClientQueueCap ?? PER_CLIENT_QUEUE_CAP_DEFAULT;
|
||||
const accumulatedReplayCap = opts.accumulatedReplayCap ?? ACCUMULATED_REPLAY_CAP_DEFAULT;
|
||||
const ttlMs = opts.ttlMs;
|
||||
const clientId = opts.clientId ?? `c-${this._nowFn()}-${Math.floor(Math.random() * 1e9).toString(36)}`;
|
||||
|
||||
// ── (A) Inflight Map check FIRST (Amendment 8 §6 — TTL race) ───────────
|
||||
// Late joiners that arrive after a cache entry has expired but during an
|
||||
// active source spawn must still attach via the inflight Map rather than
|
||||
// re-spawn. The synchronous Map.get + (if hit) Map preservation here
|
||||
// satisfies the no-`await`-between-check-and-decision invariant.
|
||||
const inflightEntry = this._streamingInflight.get(compositeKey);
|
||||
if (inflightEntry) {
|
||||
// Hits-as-share decision (documented at method header): sharing a spawn
|
||||
// is a cache-like benefit; increment hits for consistency with
|
||||
// cache_hit accounting and to expose the singleflight win in stats().
|
||||
this._getStats(keyId).hits++;
|
||||
const stream = this._attachClient(inflightEntry, {
|
||||
clientId,
|
||||
perClientQueueCap,
|
||||
});
|
||||
return { stream, isFirst: false, role: 'attached' };
|
||||
}
|
||||
|
||||
// ── (B) Cache hit check (no inflight) ──────────────────────────────────
|
||||
// Replays cached chunks via a synthetic async iterator. No source spawn.
|
||||
const ns = this._getNamespace(keyId);
|
||||
const existing = ns.get(cacheKey);
|
||||
if (existing && this._isAlive(existing)) {
|
||||
this._getStats(keyId).hits++;
|
||||
const cachedChunks = Array.isArray(existing.value) ? existing.value : [existing.value];
|
||||
const stream = (async function* cacheReplay() {
|
||||
for (const chunk of cachedChunks) {
|
||||
yield chunk;
|
||||
}
|
||||
})();
|
||||
return { stream, isFirst: false, role: 'cache_hit' };
|
||||
}
|
||||
|
||||
// ── (C) Miss + no inflight: take the lock synchronously, then await ───
|
||||
// The placeholder entry is inserted BEFORE invoking sourceFactory so that
|
||||
// late joiners arriving while the factory is awaited see the inflight
|
||||
// entry and attach (they're parked in `pendingJoiners` until the factory
|
||||
// resolves or rejects). If the factory throws, the placeholder is
|
||||
// removed and the error propagates to the first caller AND all parked
|
||||
// joiners. This preserves the §1 invariant: the Map insert is atomic
|
||||
// from later joiners' perspective.
|
||||
const entry = /** @type {StreamingInflightEntry} */ ({
|
||||
compositeKey,
|
||||
source: null,
|
||||
sourceAbortController: new AbortController(),
|
||||
accumulatedChunks: [],
|
||||
accumulatedByteSize: 0,
|
||||
accumulatedReplayCapExceeded: false,
|
||||
attachedClients: new Set(),
|
||||
factoryPending: true,
|
||||
pendingJoiners: [],
|
||||
sourceDone: false,
|
||||
sourceError: null,
|
||||
sourceAborted: false,
|
||||
ttlMs,
|
||||
});
|
||||
this._streamingInflight.set(compositeKey, entry);
|
||||
this._getStats(keyId).misses++;
|
||||
|
||||
// Attach the first caller synchronously so any subsequent joiners during
|
||||
// the factory await see the same set/topology as the first caller.
|
||||
const firstStream = this._attachClient(entry, {
|
||||
clientId,
|
||||
perClientQueueCap,
|
||||
});
|
||||
|
||||
let sourceIter;
|
||||
try {
|
||||
const factoryResult = sourceFactory();
|
||||
sourceIter = factoryResult && typeof factoryResult.then === 'function'
|
||||
? await factoryResult
|
||||
: factoryResult;
|
||||
} catch (err) {
|
||||
// Factory rejected — remove placeholder and reject first caller + any
|
||||
// late joiners that arrived during the await.
|
||||
this._streamingInflight.delete(compositeKey);
|
||||
for (const client of entry.attachedClients) {
|
||||
if (client.rejectNext) {
|
||||
client.rejectNext(err);
|
||||
client.resolveNext = null;
|
||||
client.rejectNext = null;
|
||||
}
|
||||
client.error = err;
|
||||
client.done = true;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
|
||||
entry.source = sourceIter;
|
||||
entry.factoryPending = false;
|
||||
|
||||
// Kick off the tee task. It runs detached; lifetime is bounded by the
|
||||
// source iterator's completion / error / abort.
|
||||
this._teeStreamingSource(keyId, cacheKey, entry, {
|
||||
accumulatedReplayCap,
|
||||
});
|
||||
|
||||
return { stream: firstStream, isFirst: true, role: 'source' };
|
||||
}
|
||||
|
||||
/**
|
||||
* D57 — ADR 0005 Amendment 8 §3 + §5: attach a new client to an inflight
|
||||
* entry. Synchronously drains the accumulated replay buffer into the
|
||||
* client's queue (§5). If the drain would exceed `perClientQueueCap`, the
|
||||
* client receives a STREAM_BACKPRESSURE synthesised stream INSTEAD of the
|
||||
* normal tee — the source continues for the other clients.
|
||||
*
|
||||
* Returns the async iterator the caller will consume.
|
||||
*
|
||||
* @private
|
||||
*/
|
||||
_attachClient(entry, { clientId, perClientQueueCap }) {
|
||||
// Late-joiner replay drain cap check (§5 + §10): a late joiner cannot
|
||||
// catch up if either
|
||||
// (a) the accumulated buffer alone would overflow the per-client cap
|
||||
// (burst > PER_CLIENT_QUEUE_CAP), or
|
||||
// (b) the replay buffer is already truncated (§10 cap was hit and
|
||||
// further source chunks were not appended to accumulatedChunks),
|
||||
// so even a successful drain would give the joiner a partial view
|
||||
// that disagrees with later live chunks.
|
||||
// Either condition → STREAM_BACKPRESSURE synthetic terminator. The
|
||||
// source / other clients are unaffected.
|
||||
if (
|
||||
entry.accumulatedByteSize > perClientQueueCap
|
||||
|| entry.accumulatedReplayCapExceeded
|
||||
) {
|
||||
this._warnFn('stream_backpressure_disconnect', {
|
||||
client_id: clientId,
|
||||
queue_byte_size: entry.accumulatedByteSize,
|
||||
per_client_cap: perClientQueueCap,
|
||||
composite_key: entry.compositeKey,
|
||||
reason: entry.accumulatedReplayCapExceeded
|
||||
? 'replay_cap_truncated'
|
||||
: 'replay_drain_over_cap',
|
||||
});
|
||||
return _backpressureTerminator();
|
||||
}
|
||||
|
||||
/** @type {AttachedClient} */
|
||||
const client = {
|
||||
id: clientId,
|
||||
queue: [],
|
||||
queueByteSize: 0,
|
||||
yieldedAccumulated: false,
|
||||
done: false,
|
||||
backpressured: false,
|
||||
error: null,
|
||||
resolveNext: null,
|
||||
rejectNext: null,
|
||||
// Per-client cap is captured here so the tee task can apply it
|
||||
// without re-plumbing opts; documented as an internal field.
|
||||
__perClientQueueCap__: perClientQueueCap,
|
||||
};
|
||||
|
||||
// Synchronous replay drain — push every accumulated chunk into the
|
||||
// client's queue at attach-time. From this point on the tee task pushes
|
||||
// live chunks.
|
||||
for (const chunk of entry.accumulatedChunks) {
|
||||
client.queue.push(chunk);
|
||||
client.queueByteSize += _chunkByteSize(chunk);
|
||||
}
|
||||
client.yieldedAccumulated = true;
|
||||
entry.attachedClients.add(client);
|
||||
|
||||
// TODO(D58 — ADR 0005 Amendment 8 §11): emit `streaming_inflight_join`
|
||||
// event from the server-layer wrapper, which has provider/model context.
|
||||
// Cache layer alone does not have provider/model identity (sourceFactory
|
||||
// is a closure), so the join event lives at the consumer of `role:
|
||||
// 'attached'` in server.mjs. D57 reviewer P2-3 follow-up.
|
||||
|
||||
// If source already completed before this attach (last-second join)
|
||||
// mark the client as terminal-after-drain so the iterator returns
|
||||
// cleanly once the replay queue is drained.
|
||||
if (entry.sourceDone) {
|
||||
client.done = true;
|
||||
} else if (entry.sourceError) {
|
||||
client.error = entry.sourceError;
|
||||
client.done = true;
|
||||
}
|
||||
|
||||
// Per-client AbortController for client-side cancellation (HTTP close).
|
||||
// The async iterator's return() removes the client from attachedClients;
|
||||
// if the entry's attachedClients size hits zero, the tee task aborts the
|
||||
// source. The teardown logic lives in the iterator below.
|
||||
const store = this;
|
||||
const iterator = (async function* clientStream() {
|
||||
try {
|
||||
while (true) {
|
||||
// Drain queue chunks first.
|
||||
if (client.queue.length > 0) {
|
||||
const next = client.queue.shift();
|
||||
client.queueByteSize -= _chunkByteSize(next);
|
||||
yield next;
|
||||
continue;
|
||||
}
|
||||
// Backpressure-terminated client: yield the synthetic terminator.
|
||||
if (client.backpressured) {
|
||||
yield { type: 'stop', finish_reason: 'length' };
|
||||
yield '[DONE]';
|
||||
client.done = true;
|
||||
return;
|
||||
}
|
||||
// Source already errored.
|
||||
if (client.error) {
|
||||
throw client.error;
|
||||
}
|
||||
// Source already completed and no more queued chunks.
|
||||
if (client.done) {
|
||||
return;
|
||||
}
|
||||
// Block until the tee task pushes the next chunk (or signals
|
||||
// source-done / source-error / backpressure).
|
||||
await new Promise((resolve, reject) => {
|
||||
client.resolveNext = resolve;
|
||||
client.rejectNext = reject;
|
||||
});
|
||||
client.resolveNext = null;
|
||||
client.rejectNext = null;
|
||||
}
|
||||
} finally {
|
||||
// Iterator return() fired (HTTP close, break, or normal return) —
|
||||
// remove client and possibly trigger source abort.
|
||||
if (entry.attachedClients.has(client)) {
|
||||
entry.attachedClients.delete(client);
|
||||
}
|
||||
// If we're the last client AND the source is still running, fire
|
||||
// the AbortController so the source iterator's return() / cleanup
|
||||
// can reap any underlying resources.
|
||||
if (
|
||||
entry.attachedClients.size === 0
|
||||
&& !entry.sourceDone
|
||||
&& !entry.sourceError
|
||||
&& !entry.sourceAborted
|
||||
&& !entry.factoryPending
|
||||
) {
|
||||
entry.sourceAborted = true;
|
||||
try {
|
||||
entry.sourceAbortController.abort();
|
||||
} catch {
|
||||
// best-effort
|
||||
}
|
||||
// Tee task observes attachedClients.size === 0 + sourceAborted on
|
||||
// its next loop iteration and exits without a cache write.
|
||||
store._streamingInflight.delete(entry.compositeKey);
|
||||
store._warnFn('streaming_inflight_abort', {
|
||||
composite_key: entry.compositeKey,
|
||||
accumulated_chunk_count: entry.accumulatedChunks.length,
|
||||
});
|
||||
}
|
||||
}
|
||||
})();
|
||||
|
||||
return iterator;
|
||||
}
|
||||
|
||||
/**
|
||||
* D57 — ADR 0005 Amendment 8 §4: tee fan-out task. One reader pulls from
|
||||
* `entry.source`; on each chunk, pushes to `accumulatedChunks` (bounded by
|
||||
* §10) and to every attached client's queue (per-client cap from §8).
|
||||
*
|
||||
* On source completion: writes accumulated chunks to cache if (a) cap not
|
||||
* exceeded and (b) `set()`'s own `maxEntryBytes` cap admits it. Resolves
|
||||
* all clients to drain-out state. Removes entry.
|
||||
*
|
||||
* On source error: rejects all clients via their `rejectNext`. No cache
|
||||
* write. Removes entry.
|
||||
*
|
||||
* Source-abort short-circuit: if `attachedClients.size === 0` after a push,
|
||||
* fires `sourceAbortController.abort()`, exits without cache write.
|
||||
*
|
||||
* @private
|
||||
*/
|
||||
_teeStreamingSource(keyId, cacheKey, entry, { accumulatedReplayCap }) {
|
||||
const store = this;
|
||||
(async () => {
|
||||
try {
|
||||
for (;;) {
|
||||
// Pre-check: if all clients have already gone away before we even
|
||||
// pull the next chunk, abort the source and bail out. (The
|
||||
// per-client iterator's finally-block sets sourceAborted=true and
|
||||
// removes the entry; we just need to stop pulling.)
|
||||
if (entry.attachedClients.size === 0 && !entry.factoryPending) {
|
||||
if (!entry.sourceAborted) {
|
||||
entry.sourceAborted = true;
|
||||
try { entry.sourceAbortController.abort(); } catch { /* best-effort */ }
|
||||
}
|
||||
// Try to call return() on the source so the underlying generator
|
||||
// cleans up. Best-effort; not all iterators implement it.
|
||||
try {
|
||||
if (entry.source && typeof entry.source.return === 'function') {
|
||||
await entry.source.return();
|
||||
}
|
||||
} catch { /* best-effort */ }
|
||||
return;
|
||||
}
|
||||
|
||||
const result = await entry.source.next();
|
||||
if (result.done) break;
|
||||
const chunk = result.value;
|
||||
const size = _chunkByteSize(chunk);
|
||||
|
||||
// §10 — replay buffer cap. Past the cap we stop accumulating (so
|
||||
// future late joiners can still see the chunks they need to
|
||||
// catch up to live), but we mark the entry not-cacheable so the
|
||||
// §4 completion path skips the cache write.
|
||||
if (!entry.accumulatedReplayCapExceeded) {
|
||||
if (entry.accumulatedByteSize + size > accumulatedReplayCap) {
|
||||
entry.accumulatedReplayCapExceeded = true;
|
||||
store._warnFn('streaming_inflight_replay_cap_exceeded', {
|
||||
composite_key: entry.compositeKey,
|
||||
accumulated_byte_size: entry.accumulatedByteSize,
|
||||
chunk_size: size,
|
||||
accumulated_replay_cap: accumulatedReplayCap,
|
||||
});
|
||||
// Continue accumulating up to this chunk so existing late
|
||||
// joiners' drain decision was based on the size they saw at
|
||||
// attach-time. We do NOT push this chunk to accumulatedChunks
|
||||
// (it would corrupt the "<= cap at attach-time" invariant for
|
||||
// future joiners). Future joiners arriving past this point
|
||||
// see accumulatedByteSize already > cap and get the
|
||||
// backpressure terminator at attach-time per §5.
|
||||
} else {
|
||||
entry.accumulatedChunks.push(chunk);
|
||||
entry.accumulatedByteSize += size;
|
||||
}
|
||||
}
|
||||
|
||||
// Fan out to each client synchronously (no await inside the for-
|
||||
// each-client loop). Disconnecting a client is mutation-during-
|
||||
// iteration; we snapshot the set first.
|
||||
const clientsSnapshot = [...entry.attachedClients];
|
||||
for (const client of clientsSnapshot) {
|
||||
// Per-client backpressure (§8). If the push would exceed the
|
||||
// per-client cap, disconnect this client only.
|
||||
if (client.queueByteSize + size > client.__perClientQueueCap__) {
|
||||
client.backpressured = true;
|
||||
store._warnFn('stream_backpressure_disconnect', {
|
||||
client_id: client.id,
|
||||
queue_byte_size: client.queueByteSize,
|
||||
per_client_cap: client.__perClientQueueCap__,
|
||||
composite_key: entry.compositeKey,
|
||||
reason: 'queue_overflow',
|
||||
});
|
||||
// Remove from set so future fan-out skips this client.
|
||||
entry.attachedClients.delete(client);
|
||||
// Wake the client's pull-promise so it can yield the synthetic
|
||||
// STREAM_BACKPRESSURE terminator.
|
||||
if (client.resolveNext) {
|
||||
const r = client.resolveNext;
|
||||
client.resolveNext = null;
|
||||
client.rejectNext = null;
|
||||
r({ value: undefined, done: false });
|
||||
}
|
||||
continue;
|
||||
}
|
||||
client.queue.push(chunk);
|
||||
client.queueByteSize += size;
|
||||
if (client.resolveNext) {
|
||||
const r = client.resolveNext;
|
||||
client.resolveNext = null;
|
||||
client.rejectNext = null;
|
||||
r({ value: undefined, done: false });
|
||||
}
|
||||
}
|
||||
|
||||
// If the fan-out emptied the attached set (all over-cap), the
|
||||
// top-of-loop pre-check will fire on the next iteration and abort.
|
||||
}
|
||||
|
||||
// Source iterator returned normally.
|
||||
entry.sourceDone = true;
|
||||
const cacheWritten =
|
||||
!entry.accumulatedReplayCapExceeded
|
||||
&& entry.accumulatedChunks.length > 0;
|
||||
if (cacheWritten) {
|
||||
// ADR 0005 Amendment 8 §4: write accumulated chunks to cache via
|
||||
// the standard set() path (which itself applies the D23
|
||||
// maxEntryBytes cap — separate from the §10 replay cap).
|
||||
await store.set(keyId, cacheKey, entry.accumulatedChunks, entry.ttlMs);
|
||||
}
|
||||
store._warnFn('streaming_inflight_source_done', {
|
||||
composite_key: entry.compositeKey,
|
||||
attached_count: entry.attachedClients.size,
|
||||
accumulated_chunk_count: entry.accumulatedChunks.length,
|
||||
cache_written: cacheWritten,
|
||||
});
|
||||
// Wake every remaining attached client so they drain their queue and
|
||||
// observe `done = true`.
|
||||
for (const client of [...entry.attachedClients]) {
|
||||
client.done = true;
|
||||
if (client.resolveNext) {
|
||||
const r = client.resolveNext;
|
||||
client.resolveNext = null;
|
||||
client.rejectNext = null;
|
||||
r({ value: undefined, done: true });
|
||||
}
|
||||
}
|
||||
store._streamingInflight.delete(entry.compositeKey);
|
||||
} catch (err) {
|
||||
// Source threw mid-stream. Reject every attached client.
|
||||
entry.sourceError = err;
|
||||
for (const client of [...entry.attachedClients]) {
|
||||
client.error = err;
|
||||
client.done = true;
|
||||
if (client.rejectNext) {
|
||||
const rej = client.rejectNext;
|
||||
client.resolveNext = null;
|
||||
client.rejectNext = null;
|
||||
rej(err);
|
||||
}
|
||||
}
|
||||
store._streamingInflight.delete(entry.compositeKey);
|
||||
}
|
||||
})();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns stats for a specific keyId, or aggregate stats across all keyIds.
|
||||
*
|
||||
@@ -322,11 +883,14 @@ export class CacheStore {
|
||||
const s = this._stats.get(keyId) ?? { hits: 0, misses: 0 };
|
||||
const ns = this._store.get(keyId);
|
||||
const size = ns ? ns.size : 0;
|
||||
// D57 — ADR 0005 Amendment 8 §1: inflightCount aggregates both the
|
||||
// buffered-path singleflight Map and the streaming-path inflight Map
|
||||
// so stats() reflects all active dedup-coordination entries.
|
||||
return {
|
||||
hits: s.hits,
|
||||
misses: s.misses,
|
||||
size,
|
||||
inflightCount: this._inflight.size,
|
||||
inflightCount: this._inflight.size + this._streamingInflight.size,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -345,7 +909,8 @@ export class CacheStore {
|
||||
hits: totalHits,
|
||||
misses: totalMisses,
|
||||
size: totalSize,
|
||||
inflightCount: this._inflight.size,
|
||||
// D57 — see per-keyId branch above; streaming entries counted alongside buffered.
|
||||
inflightCount: this._inflight.size + this._streamingInflight.size,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -397,10 +962,18 @@ export class CacheStore {
|
||||
this._inflight.delete(k);
|
||||
}
|
||||
}
|
||||
// D57 — also clear streaming inflight entries scoped to this keyId.
|
||||
// Composite key uses `\0` separator (see _streamingInflight init).
|
||||
for (const k of this._streamingInflight.keys()) {
|
||||
if (k.startsWith(`${keyId}\0`)) {
|
||||
this._streamingInflight.delete(k);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
this._store.clear();
|
||||
this._stats.clear();
|
||||
this._inflight.clear();
|
||||
this._streamingInflight.clear();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+522
@@ -0,0 +1,522 @@
|
||||
/**
|
||||
* lib/keys.mjs — OLP multi-key auth (Phase 2 / D44 core)
|
||||
*
|
||||
* Authority: ADR 0007 (multi-key auth). Read that ADR before modifying.
|
||||
*
|
||||
* This module implements the identity / lifecycle layer for OLP API keys:
|
||||
* - Opaque token generation (§ 5)
|
||||
* - Manifest read + atomic write (§ 6.1)
|
||||
* - Per-key in-process write-lock (§ 6.4)
|
||||
* - touchLastUsed read-modify-write with revoke preservation (§ 6.3)
|
||||
* - validateKey lookup with NO validation cache (§ 6.3.5) — manifests are
|
||||
* read on every authenticated request
|
||||
* - Env override (OLP_OWNER_TOKEN → __env_owner__) per § 9.4
|
||||
* - Anonymous escape-hatch identity per § 7
|
||||
*
|
||||
* What is NOT in this module (intentional split):
|
||||
* - audit ndjson append (§ 6.2) — request-layer concern; D45 (server.mjs glue)
|
||||
* - keygen CLI bootstrap surface (§ 9.1) — D45+ (separate command entry)
|
||||
* - server.mjs integration (replace '__anonymous__' constants) — D45
|
||||
* - owner-vs-guest /health + X-OLP-Fallback-Detail gating — D46
|
||||
*
|
||||
* The module is filesystem-only at v0.2.0. The future Option-3 SQLite-indexed
|
||||
* mirror (ADR 0007 § 13) is invisible from this module's API — when added, the
|
||||
* SQLite write happens inside writeManifestAtomic / revokeKey and the module's
|
||||
* public surface is unchanged.
|
||||
*/
|
||||
|
||||
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
|
||||
import {
|
||||
readFileSync, writeFileSync, openSync, fsyncSync, closeSync,
|
||||
renameSync, readdirSync, mkdirSync, chmodSync, existsSync,
|
||||
} from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
// ── Constants ─────────────────────────────────────────────────────────────
|
||||
|
||||
export const SCHEMA_VERSION = 1;
|
||||
export const TOKEN_PREFIX = 'olp_';
|
||||
export const TOKEN_RANDOM_BYTES = 32; // 256 bits entropy
|
||||
export const KEY_ID_RANDOM_BYTES = 6; // 8 base64url chars
|
||||
|
||||
export const ANONYMOUS_KEY_ID = '__anonymous__';
|
||||
export const ENV_OWNER_KEY_ID = '__env_owner__';
|
||||
export const ENV_OWNER_VAR = 'OLP_OWNER_TOKEN';
|
||||
|
||||
const DEFAULT_OLP_HOME = join(homedir(), '.olp');
|
||||
export const OLP_HOME_ENV = 'OLP_HOME';
|
||||
|
||||
/**
|
||||
* Resolve the OLP home directory. Precedence:
|
||||
* 1. `opts.olpHome` (explicit caller override — tests, CLI flags)
|
||||
* 2. `process.env.OLP_HOME` (operator / CI env override)
|
||||
* 3. `~/.olp` (default per ADR 0007 § 3)
|
||||
* Resolved dynamically per call so tests setting OLP_HOME mid-run take effect.
|
||||
*/
|
||||
function _resolveOlpHome(opts) {
|
||||
if (opts?.olpHome) return opts.olpHome;
|
||||
if (process.env[OLP_HOME_ENV]) return process.env[OLP_HOME_ENV];
|
||||
return DEFAULT_OLP_HOME;
|
||||
}
|
||||
|
||||
// ── Internal state ────────────────────────────────────────────────────────
|
||||
|
||||
// Per-key in-process write-lock chain (§ 6.4). Map<key-id, Promise>.
|
||||
// Each entry is the tail of the promise chain for that key-id; serialized
|
||||
// access via _withKeyLock.
|
||||
const _writeLocks = new Map();
|
||||
|
||||
// Test hook: injected pause between touchLastUsed's read and write phases.
|
||||
// Used by acceptance criterion #7 to deterministically reproduce the
|
||||
// interleaved revoke-during-touch race. Default no-op.
|
||||
let _touchInterleaveHook = async () => {};
|
||||
|
||||
// ── Path helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
function _olpHome(opts) { return _resolveOlpHome(opts); }
|
||||
function _keysDir(opts) { return join(_olpHome(opts), 'keys'); }
|
||||
function _keyDir(id, opts) { return join(_keysDir(opts), id); }
|
||||
function _manifestPath(id, opts) { return join(_keyDir(id, opts), 'manifest.json'); }
|
||||
|
||||
// ── Crypto helpers ────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Generate an opaque OLP token per § 5: `olp_<32-byte base64url>`.
|
||||
* Total length 47 chars (4 prefix + 43 base64url).
|
||||
*/
|
||||
export function generateToken() {
|
||||
return TOKEN_PREFIX + randomBytes(TOKEN_RANDOM_BYTES).toString('base64url');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate a key-id per § 3: lowercase alphanumeric + hyphen + underscore.
|
||||
* 8 base64url chars from 6 random bytes; lowercased.
|
||||
*/
|
||||
export function generateKeyId() {
|
||||
return randomBytes(KEY_ID_RANDOM_BYTES).toString('base64url').toLowerCase();
|
||||
}
|
||||
|
||||
/**
|
||||
* SHA-256 of the full token string (prefix included), hex-lowercase.
|
||||
* Matches § 5 hash spec.
|
||||
*/
|
||||
export function hashToken(plaintextToken) {
|
||||
return createHash('sha256').update(plaintextToken).digest('hex');
|
||||
}
|
||||
|
||||
/**
|
||||
* Constant-time comparison of two hex-encoded hashes.
|
||||
* Returns false on length mismatch (rather than throwing).
|
||||
*/
|
||||
function _safeHexCompare(a, b) {
|
||||
if (typeof a !== 'string' || typeof b !== 'string') return false;
|
||||
if (a.length !== b.length) return false;
|
||||
const bufA = Buffer.from(a, 'hex');
|
||||
const bufB = Buffer.from(b, 'hex');
|
||||
if (bufA.length !== bufB.length) return false;
|
||||
return timingSafeEqual(bufA, bufB);
|
||||
}
|
||||
|
||||
// ── Manifest schema validation (§ 4) ──────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Validates a parsed manifest object against the § 4 schema.
|
||||
* Throws Error('manifest_invalid: <reason>') on schema violations.
|
||||
* Unknown fields are tolerated (forward-compat).
|
||||
*/
|
||||
export function validateManifest(obj) {
|
||||
if (typeof obj !== 'object' || obj === null) {
|
||||
throw new Error('manifest_invalid: not an object');
|
||||
}
|
||||
if (obj.schema_version !== SCHEMA_VERSION) {
|
||||
throw new Error(`manifest_invalid: unrecognized schema_version ${obj.schema_version}`);
|
||||
}
|
||||
for (const field of ['id', 'name', 'token_hash', 'token_hash_algo', 'owner_tier', 'providers_enabled', 'created_at']) {
|
||||
if (obj[field] === undefined) {
|
||||
throw new Error(`manifest_invalid: missing required field "${field}"`);
|
||||
}
|
||||
}
|
||||
if (obj.token_hash_algo !== 'sha256') {
|
||||
throw new Error(`manifest_invalid: unsupported token_hash_algo "${obj.token_hash_algo}"`);
|
||||
}
|
||||
if (!['owner', 'guest'].includes(obj.owner_tier)) {
|
||||
throw new Error(`manifest_invalid: owner_tier must be "owner" or "guest", got "${obj.owner_tier}"`);
|
||||
}
|
||||
if (!(obj.providers_enabled === '*' || Array.isArray(obj.providers_enabled))) {
|
||||
throw new Error('manifest_invalid: providers_enabled must be "*" or array');
|
||||
}
|
||||
return obj;
|
||||
}
|
||||
|
||||
// ── Manifest IO (§ 6.1) ───────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Read manifest for a key-id. Returns parsed object or null if file absent.
|
||||
* Throws on JSON parse error or schema violation.
|
||||
*/
|
||||
export function readManifest(id, opts = {}) {
|
||||
const path = _manifestPath(id, opts);
|
||||
if (!existsSync(path)) return null;
|
||||
const raw = readFileSync(path, 'utf-8');
|
||||
const obj = JSON.parse(raw);
|
||||
if (obj.id !== id) {
|
||||
throw new Error(`manifest_id_mismatch: directory "${id}" contains manifest with id "${obj.id}"`);
|
||||
}
|
||||
return validateManifest(obj);
|
||||
}
|
||||
|
||||
/**
|
||||
* Atomic manifest write per § 6.1: tmpfile + fsync + rename, 0600 file / 0700 dir.
|
||||
* Caller MUST hold the per-key write-lock (§ 6.4) when invoking this for
|
||||
* lifecycle events. Lock acquisition is the caller's responsibility because
|
||||
* createKey allocates a new key-id (no existing lock yet) while revoke /
|
||||
* touchLastUsed operate on an existing key-id.
|
||||
*/
|
||||
export function writeManifestAtomic(id, manifest, opts = {}) {
|
||||
if (manifest.id !== id) {
|
||||
throw new Error(`writeManifestAtomic: manifest.id "${manifest.id}" mismatches id arg "${id}"`);
|
||||
}
|
||||
validateManifest(manifest);
|
||||
|
||||
const dir = _keyDir(id, opts);
|
||||
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
||||
try { chmodSync(dir, 0o700); } catch { /* tolerate EPERM on pre-existing dir */ }
|
||||
|
||||
const finalPath = _manifestPath(id, opts);
|
||||
const tmpPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
|
||||
const serialized = JSON.stringify(manifest, null, 2) + '\n';
|
||||
|
||||
const fd = openSync(tmpPath, 'w', 0o600);
|
||||
try {
|
||||
writeFileSync(fd, serialized);
|
||||
fsyncSync(fd);
|
||||
} finally {
|
||||
closeSync(fd);
|
||||
}
|
||||
renameSync(tmpPath, finalPath);
|
||||
// § 6.1 step 5: enforce 0600 even if umask interfered.
|
||||
try { chmodSync(finalPath, 0o600); } catch { /* tolerate EPERM */ }
|
||||
}
|
||||
|
||||
// ── Per-key write lock (§ 6.4) ────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Serialize concurrent in-process writes against the same key-id.
|
||||
* Returns the value produced by fn(); awaits prior queued work first.
|
||||
*
|
||||
* Lock-map semantics: each caller stores its own `next` promise as the
|
||||
* Map tail. New callers chain off the stored tail (`get(id)` returns the
|
||||
* current tail = prior caller's next). On finally, we compare-and-delete
|
||||
* the tail by identity — if no one queued after us, the Map still points
|
||||
* at our `next` and we clean up; if a later caller chained, the Map points
|
||||
* at their `next` and we leave it alone.
|
||||
*
|
||||
* (D44 fold-in correctness fix: prior version stored
|
||||
* `prev.then(() => next)`, a derived promise that never matched the
|
||||
* cleanup-identity check, leaving stale Map entries per unique key-id.
|
||||
* Storing `next` directly fixes the cleanup; tested by 19u-extra.)
|
||||
*/
|
||||
async function _withKeyLock(id, fn) {
|
||||
const prev = _writeLocks.get(id) ?? Promise.resolve();
|
||||
let release;
|
||||
const next = new Promise(r => { release = r; });
|
||||
_writeLocks.set(id, next);
|
||||
|
||||
try {
|
||||
await prev;
|
||||
return await fn();
|
||||
} finally {
|
||||
release();
|
||||
if (_writeLocks.get(id) === next) _writeLocks.delete(id);
|
||||
}
|
||||
}
|
||||
|
||||
// ── Public API ────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Create a new OLP key. Generates a fresh opaque token (returned in
|
||||
* plaintext exactly once) and writes the manifest atomically.
|
||||
*
|
||||
* @param {object} args
|
||||
* @param {string} args.name - human label (required, non-empty)
|
||||
* @param {'owner'|'guest'} [args.owner_tier='guest']
|
||||
* @param {string[]|'*'} [args.providers_enabled='*']
|
||||
* @param {string} [args.notes='']
|
||||
* @param {string} [args.olpHome] - test override; defaults to ~/.olp
|
||||
* @returns {{ id: string, plaintext_token: string, manifest: object }}
|
||||
* The plaintext_token MUST be displayed to the operator exactly once and
|
||||
* never logged. The manifest contains only the hash.
|
||||
*/
|
||||
export function createKey(args = {}) {
|
||||
const { name, owner_tier = 'guest', providers_enabled = '*', notes = '', olpHome } = args;
|
||||
if (typeof name !== 'string' || name.length === 0) {
|
||||
throw new Error('createKey: name is required (non-empty string)');
|
||||
}
|
||||
if (!['owner', 'guest'].includes(owner_tier)) {
|
||||
throw new Error(`createKey: owner_tier must be "owner" or "guest", got "${owner_tier}"`);
|
||||
}
|
||||
if (!(providers_enabled === '*' || Array.isArray(providers_enabled))) {
|
||||
throw new Error('createKey: providers_enabled must be "*" or string array');
|
||||
}
|
||||
|
||||
const id = generateKeyId();
|
||||
const plaintext_token = generateToken();
|
||||
const manifest = {
|
||||
schema_version: SCHEMA_VERSION,
|
||||
id,
|
||||
name,
|
||||
token_hash: hashToken(plaintext_token),
|
||||
token_hash_algo: 'sha256',
|
||||
owner_tier,
|
||||
providers_enabled,
|
||||
quota: null,
|
||||
created_at: new Date().toISOString(),
|
||||
revoked_at: null,
|
||||
last_used_at: null,
|
||||
notes,
|
||||
};
|
||||
writeManifestAtomic(id, manifest, { olpHome });
|
||||
return { id, plaintext_token, manifest };
|
||||
}
|
||||
|
||||
/**
|
||||
* List all keys. Returns array of manifest objects with `token_hash` redacted
|
||||
* (kept on disk; omitted from list output per common operational hygiene —
|
||||
* the hash itself is non-secret but listing it bulk-reads adds nothing).
|
||||
*
|
||||
* Skips manifests that fail schema validation; would log warn in real impl.
|
||||
*
|
||||
* @returns {Array<object>} possibly empty
|
||||
*/
|
||||
export function listKeys(opts = {}) {
|
||||
const dir = _keysDir(opts);
|
||||
if (!existsSync(dir)) return [];
|
||||
const entries = readdirSync(dir);
|
||||
const out = [];
|
||||
for (const id of entries) {
|
||||
if (id.startsWith('.')) continue;
|
||||
try {
|
||||
const m = readManifest(id, opts);
|
||||
if (m === null) continue;
|
||||
// Redact token_hash from list output (keep on disk).
|
||||
const { token_hash, ...rest } = m;
|
||||
out.push(rest);
|
||||
} catch {
|
||||
// Skip invalid manifest; production impl would log warn.
|
||||
continue;
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Revoke a key by id. Sets revoked_at to current ISO timestamp.
|
||||
* Idempotent: revoking an already-revoked key returns true without rewriting.
|
||||
* Returns false if the key-id does not exist on disk.
|
||||
*/
|
||||
export async function revokeKey(args = {}) {
|
||||
const { id, olpHome } = args;
|
||||
if (!id || typeof id !== 'string') throw new Error('revokeKey: id required');
|
||||
return _withKeyLock(id, async () => {
|
||||
const m = readManifest(id, { olpHome });
|
||||
if (m === null) return false;
|
||||
if (m.revoked_at !== null) return true; // already revoked; no-op
|
||||
m.revoked_at = new Date().toISOString();
|
||||
writeManifestAtomic(id, m, { olpHome });
|
||||
return true;
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a plaintext token. Returns an identity object on success, null
|
||||
* on any failure (missing token, no match, revoked, manifest invalid).
|
||||
*
|
||||
* Resolution order:
|
||||
* 1. If plaintext === process.env.OLP_OWNER_TOKEN → synthetic env-owner identity.
|
||||
* 2. If !plaintext and allowAnonymous → anonymous identity.
|
||||
* 3. Else hash plaintext, scan ~/.olp/keys/ for a manifest with matching hash.
|
||||
* Revoked manifests return null (caller produces 401 key_revoked).
|
||||
*
|
||||
* § 6.3.5: this function MUST hit the manifest filesystem on every call
|
||||
* (no in-process validation cache at Phase 2).
|
||||
*
|
||||
* @param {string|null} plaintextToken
|
||||
* @param {object} [opts]
|
||||
* @param {boolean} [opts.allowAnonymous=false] - server reads config and passes through
|
||||
* @param {string} [opts.olpHome]
|
||||
* @returns {{ id, owner_tier, providers_enabled, source }|null}
|
||||
*/
|
||||
export function validateKey(plaintextToken, opts = {}) {
|
||||
const { allowAnonymous = false, olpHome } = opts;
|
||||
|
||||
// Defensive: non-string truthy inputs (number, object, etc.) return null
|
||||
// rather than throwing in hashToken. Matches missing-token semantics.
|
||||
// (D44 fold-in P2 #2: prior version threw TypeError on validateKey({}) /
|
||||
// validateKey(42) by reaching createHash().update(<non-string>).)
|
||||
if (plaintextToken != null && typeof plaintextToken !== 'string') return null;
|
||||
|
||||
// 1. Env owner override (§ 9.4)
|
||||
const envToken = process.env[ENV_OWNER_VAR];
|
||||
if (envToken && plaintextToken && _safeHexCompare(hashToken(plaintextToken), hashToken(envToken))) {
|
||||
return {
|
||||
id: ENV_OWNER_KEY_ID,
|
||||
owner_tier: 'owner',
|
||||
providers_enabled: '*',
|
||||
source: 'env',
|
||||
};
|
||||
}
|
||||
|
||||
// 2. Anonymous fallback (§ 7)
|
||||
if (!plaintextToken) {
|
||||
if (allowAnonymous) {
|
||||
return {
|
||||
id: ANONYMOUS_KEY_ID,
|
||||
owner_tier: 'anonymous',
|
||||
providers_enabled: '*',
|
||||
source: 'anonymous',
|
||||
};
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// 3. Filesystem manifest lookup (§ 6.3.5 — every request, no cache)
|
||||
const dir = _keysDir({ olpHome });
|
||||
if (!existsSync(dir)) return null;
|
||||
const hash = hashToken(plaintextToken);
|
||||
let entries;
|
||||
try { entries = readdirSync(dir); } catch { return null; }
|
||||
|
||||
for (const id of entries) {
|
||||
if (id.startsWith('.')) continue;
|
||||
let m;
|
||||
try { m = readManifest(id, { olpHome }); } catch { continue; }
|
||||
if (m === null) continue;
|
||||
if (!_safeHexCompare(m.token_hash, hash)) continue;
|
||||
if (m.revoked_at !== null) return null; // revoked → caller produces 401
|
||||
return {
|
||||
id: m.id,
|
||||
owner_tier: m.owner_tier,
|
||||
providers_enabled: m.providers_enabled,
|
||||
source: 'filesystem',
|
||||
};
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Update last_used_at lazily after a successful request. Per § 6.3:
|
||||
* 1. Re-read latest manifest from disk inside the per-key write-lock.
|
||||
* 2. If revoked_at is non-null in fresh read → NO-OP (preserve revocation).
|
||||
* 3. Otherwise merge new last_used_at preserving all other fields.
|
||||
*
|
||||
* Best-effort: any error is logged via console.warn and swallowed; this
|
||||
* function never throws (§ 6.3 "Failure logs warn and does NOT fail the
|
||||
* request").
|
||||
*
|
||||
* Anonymous + env-owner identities have no manifest → no-op silently.
|
||||
*/
|
||||
export async function touchLastUsed(id, opts = {}) {
|
||||
if (id === ANONYMOUS_KEY_ID || id === ENV_OWNER_KEY_ID) return;
|
||||
|
||||
try {
|
||||
await _withKeyLock(id, async () => {
|
||||
// Test hook fires BEFORE the read so race tests can deterministically
|
||||
// inject an external revoke that the read must observe. In production
|
||||
// the hook is a no-op; the read is the only filesystem access and
|
||||
// happens inside the per-key write-lock.
|
||||
await _touchInterleaveHook(id, opts);
|
||||
// § 6.3 step 1: re-read latest manifest inside the lock.
|
||||
const fresh = readManifest(id, opts);
|
||||
if (fresh === null) return; // key removed from disk
|
||||
// § 6.3 step 2: NO-OP if revoked.
|
||||
if (fresh.revoked_at !== null) return;
|
||||
// § 6.3 step 3: merge last_used_at preserving all other fields.
|
||||
fresh.last_used_at = new Date().toISOString();
|
||||
writeManifestAtomic(id, fresh, opts);
|
||||
});
|
||||
} catch (err) {
|
||||
// § 6.3 best-effort: warn, never throw.
|
||||
console.warn(JSON.stringify({
|
||||
event: 'last_used_update_failed',
|
||||
id,
|
||||
error: err?.message ?? String(err),
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
// ── Auth config loader (§ 7.2) ────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Read the `auth` block from ~/.olp/config.json. All fields defaulted
|
||||
* so partial / absent config is safe.
|
||||
*
|
||||
* Defaults per ADR § 7.2:
|
||||
* - allow_anonymous: false (production-off default)
|
||||
* - owner_only_endpoints: ['/health'] (D46 consumes; D45 only loads)
|
||||
* - fallback_detail_header_policy: 'owner_only' (D46 consumes; D45 only loads)
|
||||
*
|
||||
* Returns the auth config object. Never throws — missing file / parse
|
||||
* error / missing `auth` key all fall back to defaults.
|
||||
*
|
||||
* @param {object} [opts]
|
||||
* @param {string} [opts.olpHome] - test override; defaults to ~/.olp
|
||||
* @returns {{ allow_anonymous: boolean, owner_only_endpoints: string[], fallback_detail_header_policy: 'owner_only'|'all'|'none' }}
|
||||
*/
|
||||
export function loadAuthConfigSync(opts = {}) {
|
||||
const olpHome = _resolveOlpHome(opts);
|
||||
const path = join(olpHome, 'config.json');
|
||||
const DEFAULTS = {
|
||||
allow_anonymous: false,
|
||||
owner_only_endpoints: ['/health'],
|
||||
fallback_detail_header_policy: 'owner_only',
|
||||
};
|
||||
if (!existsSync(path)) return { ...DEFAULTS };
|
||||
try {
|
||||
const raw = readFileSync(path, 'utf-8');
|
||||
const cfg = JSON.parse(raw);
|
||||
const auth = (cfg && typeof cfg === 'object' && cfg.auth && typeof cfg.auth === 'object')
|
||||
? cfg.auth
|
||||
: {};
|
||||
return {
|
||||
allow_anonymous: typeof auth.allow_anonymous === 'boolean' ? auth.allow_anonymous : DEFAULTS.allow_anonymous,
|
||||
owner_only_endpoints: Array.isArray(auth.owner_only_endpoints) ? auth.owner_only_endpoints : DEFAULTS.owner_only_endpoints,
|
||||
fallback_detail_header_policy: ['owner_only', 'all', 'none'].includes(auth.fallback_detail_header_policy)
|
||||
? auth.fallback_detail_header_policy
|
||||
: DEFAULTS.fallback_detail_header_policy,
|
||||
};
|
||||
} catch {
|
||||
// Malformed JSON / unreadable file → safe defaults
|
||||
return { ...DEFAULTS };
|
||||
}
|
||||
}
|
||||
|
||||
// ── Test-only hooks ───────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Test-only: install a hook called inside touchLastUsed between the
|
||||
* read-phase and write-phase. Used to deterministically reproduce the
|
||||
* interleaved-revoke race (acceptance criterion #7).
|
||||
*
|
||||
* Pass null to reset to no-op.
|
||||
*/
|
||||
export function __setTouchInterleaveHook(hookOrNull) {
|
||||
_touchInterleaveHook = hookOrNull ?? (async () => {});
|
||||
}
|
||||
|
||||
/**
|
||||
* Test-only: clear all in-process write-locks. Useful for test cleanup
|
||||
* to avoid lock state leaking across tests.
|
||||
*/
|
||||
export function __resetWriteLocks() {
|
||||
_writeLocks.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Test-only: report the current size of the in-process write-lock Map.
|
||||
* Used by Suite 19 to verify lock cleanup fires (D44 fold-in P2 #1
|
||||
* regression test — Map must shrink to 0 after all queued callers finish).
|
||||
*/
|
||||
export function __writeLockSize() {
|
||||
return _writeLocks.size;
|
||||
}
|
||||
@@ -162,6 +162,15 @@ export const PROVIDER_ERROR_CODES = /** @type {const} */ ([
|
||||
'SPAWN_FAILED',
|
||||
'SPAWN_TIMEOUT', // ADR 0004 § Trigger taxonomy bullet 4: spawn timeout is a hard trigger
|
||||
'CONCURRENCY_LIMIT', // ADR 0002 Amendment 6 / ADR 0004 Amendment 4 (D38, issue #1)
|
||||
/* ADR 0005 Amendment 8 §8 (D57): per-client streaming queue overflow.
|
||||
* NOT a hard trigger — the source spawned successfully and other attached
|
||||
* clients continue to receive chunks; only this client's queue exceeded
|
||||
* PER_CLIENT_QUEUE_CAP. The affected client receives a synthetic
|
||||
* { type: 'stop', finish_reason: 'length' } + [DONE] terminator.
|
||||
* D58 wires server-side header/log surface; HARD_TRIGGER_CODES in
|
||||
* lib/fallback/engine.mjs is a whitelist so absence here gives the
|
||||
* correct default (no fallback advancement). */
|
||||
'STREAM_BACKPRESSURE',
|
||||
]);
|
||||
|
||||
export class ProviderError extends Error {
|
||||
|
||||
+8
-2
@@ -1,12 +1,18 @@
|
||||
{
|
||||
"name": "olp",
|
||||
"version": "0.1.1",
|
||||
"version": "0.3.2",
|
||||
"description": "Personal multi-provider LLM proxy. Successor to OCP. One HTTP endpoint, multiple subscriptions behind it, automatic routing + fallback + caching.",
|
||||
"type": "module",
|
||||
"main": "server.mjs",
|
||||
"bin": {
|
||||
"olp-keys": "./bin/olp-keys.mjs",
|
||||
"olp-audit-rotate": "./bin/olp-audit-rotate.mjs"
|
||||
},
|
||||
"scripts": {
|
||||
"start": "node server.mjs",
|
||||
"test": "node test-features.mjs"
|
||||
"test": "node test-features.mjs",
|
||||
"olp-keys": "node bin/olp-keys.mjs",
|
||||
"olp-audit-rotate": "node bin/olp-audit-rotate.mjs"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
|
||||
+791
-176
File diff suppressed because it is too large
Load Diff
+3446
-2
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user