feat+test+docs: D50 — server.mjs management endpoints (Phase 3 dashboard wire-up) (#27)

* feat+test+docs: 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: GET /dashboard Serves dashboard.html (text/html). D50 stub explains state + lists backing endpoints. D51 replaces with full UI. GET /v0/management/dashboard-data Full aggregate per § 7.2: { generated_at, window_24h, cache_hit_24h, quota, spend_trend_30d, top_fallback_chains_24h, cache_stats } GET /v0/management/quota Quota subset only (per-provider provider.quotaStatus + error capture per § 9 graceful degradation). GET /cache/stats Live in-memory cacheStore.stats() with generated_at wrapper. HELPER: _runOwnerOnlyManagementEndpoint(req, res, method, path, inner) Factors common auth + audit ctx + owner-block + res.on('finish') wire. inner is async (req, res, olpIdentity, auditCtx) → void. Eliminates 4× boilerplate. OWNER_ONLY_BLOCK MODE (ADR 0008 § 8 D48-fold-in): authenticate → if owner_tier !== '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 (Suite 24c). Allow_anonymous: false + no header → 401 auth_required at middleware (Suite 24d). 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 D50 state, lists backing endpoints with curl example. Cached in memory at first /dashboard request via _loadDashboardHtml with module-scope _dashboardHtmlCache; falls back to in-memory stub if file missing (defensive for test imports from non-repo cwd). AUDIT ON MANAGEMENT ENDPOINTS (ADR 0008 § 7.5): Every management request appends audit row including 401 paths (verified by Suite 24j). Touch wire skips anonymous + env-owner identities (matches Phase 2 pattern). TESTS — Suite 24, +11 (571 → 582): 24a-d: /dashboard owner_only_block matrix (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 § 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 shape 24h-401: cache/stats guest → 401 24i: successful dashboard-data appends audit row with status 200 + key_id + correct path 24j: 401 (guest blocked) dashboard-data appends audit row with error_code: 'owner_required' + owner_tier: 'guest' DOCUMENTATION: - AGENTS.md: dashboard.html new entry (D50 placeholder); lib/audit- query.mjs marker note unchanged. - CHANGELOG.md: D50 entry under Unreleased per release_kit overlay. NOT IN D50 scope: - Full dashboard UI (D51 — replaces dashboard.html with the real 4-panel layout + 30s poll JS) - Daily audit rotation (D52) - tried_providers schema fix (D53) - Phase 3 close (D55; v0.3.0; maintainer-triggered) Test count: 571 → 582 (+11). Verified locally via npm test. AUTHORITY: - ADR 0008 § 7 (endpoint definitions) + § 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 source of truth). - CLAUDE.md release_kit overlay phase_rolling_mode — under Unreleased. - Standing autopilot grant. ALIGNMENT.md scope check: this PR adds 4 new entry-surface endpoints under owner-only_block gating + a new lib/audit-query consumer surface. Per Rule 5: management endpoints are owner-only operational surface, not OpenAI-spec-compatible — they exist outside the /v1/chat/completions + /v1/models spec scope. No provider plugin / IR change. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: D50 fold-in — AGENTS.md dashboard.html duplicate (opus P3) Fresh-context opus reviewer (PR #27) flagged a duplicate dashboard.html entry: my D50 addition was added directly above a stale "Planned (Phase 6) — not yet authored" line that should have been removed. The file contradicted itself. Fix: merge into single entry — keep the original line phrasing and attach the D50 status update. No code change, no test change. Authority: PR #27 fresh-context opus reviewer P3 finding. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-19 09:45:07 +00:00 · 2026-05-25 16:02:47 +10:00
parent 686794e316
commit f9f2eaa059
5 changed files with 529 additions and 1 deletions
@@ -41,7 +41,7 @@ Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mj
 - `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. **🟡 D45 — appendAuditEvent + getAuditDropCount shipped. Fires per /v1/chat/completions + /v1/models request including 401/403/5xx paths. Warn+1-retry on append failure; no memory buffer at Phase 2 (forward path).** **D52 will extend with daily rotation per ADR 0008 § 5.**
 - `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 (quota panels, fallback rate, cache hit rate). **📋 Planned (Phase 6) — not yet authored.**
+- `dashboard.html` — owner-only multi-provider dashboard (quota panels, fallback rate, cache hit rate). **🟡 D50 — placeholder stub shipped at repo root + `/dashboard` route in server.mjs serves it owner-only_block. D51 lands the full multi-panel UI (quota + 24h request stats + 30d spend trend + top fallback chains) per ADR 0008 § 6.**
 - `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.