mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-19 09:45:07 +00:00
40064955ab
* feat+test+docs: 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 ADR § 10 acceptance criteria #1 (per-key cache isolation), #2 (anonymous prod-default off), #3 (anonymous dev-mode on), #6 (post-revoke 401 within next request — full coverage with D45), #8 (audit ndjson round-trip), #10 (OLP_OWNER_TOKEN env override — full server-side coverage), #11 (providers_enabled 403 scope). Owner-vs-guest gating for /health + X-OLP-Fallback-Detail (criteria #4, #5) remains in D46 scope. NEW lib/audit.mjs (~110 lines): - appendAuditEvent(event, opts): one JSON event per line to ~/.olp/logs/audit.ndjson (file 0600, dir 0700). § 6.2 retry: warn + 1 retry; per-process drop counter + warn on second failure; NEVER throws. Per-call OLP_HOME env resolution (matches lib/keys.mjs). - getAuditDropCount(): for future /health surface. lib/keys.mjs extended: - loadAuthConfigSync({ olpHome }): reads auth block from ~/.olp/config.json with ADR § 7.2 defaults (allow_anonymous: false, owner_only_endpoints: ['/health'], fallback_detail_header_policy: 'owner_only'). Never throws; missing file / malformed JSON falls back to defaults. - _resolveOlpHome(opts): precedence opts.olpHome → process.env.OLP_HOME → ~/.olp. Per-call resolution so tests + operator deployments can redirect without code edits. server.mjs auth middleware integration: - extractToken(req): parses Authorization Bearer / x-api-key. - authenticate(req): validateKey + 401 paths (auth_required vs invalid_or_revoked_key). - isProviderEnabled(olpIdentity, providerKey): '*' = all; else array allowlist. - _authConfig loaded at startup; warn auth_allow_anonymous_enabled when true. Test seams __setAuthConfig / __resetAuthConfig. - handleChatCompletions + handleModels both gated by authenticate at top. Audit ctx built throughout; res.on('finish') appends row + fires touchLastUsed async. - IDENTITY-VS-CREDENTIALS SEPARATION: olpIdentity (new validated identity) 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+ per ADR § 12. - handleChatCompletions chain filtered by isProviderEnabled; empty result returns 403 key_no_provider_access. - keyId = olpIdentity.keyId (replacing hardcoded '__anonymous__'). - Audit captures fields throughout: post-auth, post-IR, post-chain (success or exhausted). Status + latency populated on res.on('finish'). TESTS — Suite 20, +15 (499 → 514): 20a-d: header parsing + valid key happy paths (Bearer / x-api-key / invalid → 401) 20e: revoked key 401 (criterion #6 end-to-end) 20f: OLP_OWNER_TOKEN env override returns 200 (criterion #10 full) 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 (criterion #1 end-to-end) 20j + 20j-401: audit.ndjson written with § 8 schema fields + PII guard; 401 path also appends (criterion #8) 20k: filesystem key last_used_at populated post-request (D45 touch wire) 20l + 20l-200: /v1/models also enforces auth TEST-MODE SETUP (test-features.mjs): - process.env.OLP_HOME = mkdtempSync(...) at module load so audit + key writes don't pollute ~/.olp/. - __setAuthConfig({ allow_anonymous: true }) after server.mjs imports so pre-D45 HTTP integration tests (Suite 18 etc.) continue to pass. - Suite 20 explicitly overrides __setAuthConfig per-case to exercise production-default-off coverage. DOCUMENTATION: - AGENTS.md: lib/keys.mjs 🟡 marker updated + NEW lib/audit.mjs entry; 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 (OLP_HOME, OLP_OWNER_TOKEN) and auth config block surfaced. - CHANGELOG.md: D45 entry under Unreleased per release_kit overlay phase_rolling_mode discipline. AUTHORITY: - ADR 0007 (multi-key auth — §§ 5/6.2/7/9.4 implementation contracts + § 10 criteria #1/#2/#3/#6/#8/#10/#11 covered). - 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). Verified: 514/514 pass via npm test (no regression in 499 existing tests; 15 new Suite 20 tests all green). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix+test+docs: D45 fold-in — CI fail recovery + opus reviewer P1/P2/P3 Fresh-context opus reviewer (PR #21) returned APPROVE_WITH_MINOR with 4 findings; CI Node 24 separately reported 9 Suite 20 failures (all 200-expecting tests). Root cause of CI: Suite 20 setup did not stub CLAUDE_CODE_OAUTH_TOKEN before mock spawn, so anthropic.mjs AUTH_MISSING pre-check fired and tests 502'd. (Local Node 22 had the env from the maintainer's claude install — masked the gap.) CI FIX — Suite 20 OAuth env stub Added ensureSuite20FakeOAuth / restoreSuite20OAuth helpers in makeSuite20Server / teardownSuite20. Matches the existing pattern in Suite 9 line ~2154 (test-fake-oauth-token-for-cache-tests). P1 — Real-streaming path audit fidelity Single-hop streaming success (server.mjs ~L1050, the most common deployed shape) did not populate auditCtx.provider / tried_providers / cache_status. Audit rows for streaming requests carried provider: null. Fixed by stamping these at the top of the streaming branch 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: streaming request 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 test-features.mjs module load left /var/folders/.../olp-test-home-* leak per npm test run. Fixed by process.on('exit', () => rmSync(_GLOBAL_TEST_OLP_HOME)). Best-effort; swallows errors so exit handler never throws. P3 — handleModels 401 lacks OLP diagnostic headers handleChatCompletions 401 passes olpErrorHeaders({ startMs }); handleModels 401 did not. Aligned. DEFERRED — P2 tried_providers semantics on 403 Reviewer noted that key_no_provider_access 403 stamps original chain in tried_providers, but the field name implies hops actually dispatched. Either ADR § 8 amendment or D46+ semantic fix. Marked in CHANGELOG; not in this fold-in scope. Test count: 514 → 515 (+1 streaming-audit regression test 20j-stream; 14 existing Suite 20 tests still pass). Verified locally via npm test. CI Node 24 recovery via the OAuth env stub. Authority: PR #21 fresh-context opus reviewer findings; CI Node 24 run 26382758946 failure logs; CLAUDE.md release_kit overlay phase_rolling_mode — under Unreleased. 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>
8.5 KiB
8.5 KiB
Inherits: @~/.cc-rules/AGENTS.md
OLP — Open LLM Proxy — Agent Guidelines
Scope: the dtzp555-max/olp repository.
Audience: any AI coding agent (Claude Code / Cursor / OpenCode / Copilot / Codex / Gemini) touching OLP source.
What this project is
OLP (Open LLM Proxy) is a personal- and family-scale multi-provider LLM proxy. It exposes a single OpenAI-compatible HTTP endpoint (/v1/chat/completions) and routes each request to one of N provider plugins, each of which spawns the corresponding provider CLI (e.g. claude -p, codex exec --json, vibe --prompt). An IR (Intermediate Representation) normalizes between the entry surface and each provider's native shape. Intelligent fallback chains advance one provider at a time on configured triggers; content-addressed caching minimizes quota consumption.
OLP supersedes OCP (Open Claude Proxy) as of v1.0. The trigger was the 2026-05-14 Anthropic announcement (effective 2026-06-15) splitting CLI/Agent SDK traffic out of the Pro/Max subscription pool — OCP's foundational assumption ("subscription = unlimited within rate limits") broke for Anthropic on that date. Spreading risk across multiple providers is the structural response.
OLP is not a commercial multi-tenant SaaS, not an enterprise gateway competing with LiteLLM/OpenCode/CLIProxyAPI on breadth, not a model-capability router ("route to the smartest model"), and not a conversation-state store (clients manage their own state). See ALIGNMENT.md Core Principle and docs/adr/0001-project-founding.md.
Runtime: Node.js (ESM, .mjs throughout). No build step. No bundler. server.mjs is the single executable entrypoint. The architecture is spawn-binary: OLP spawns the real provider CLI for every uncached request.
Stack
- Node.js >=18, native ESM modules
http/httpsbuilt-ins for the proxy core (no Express, no Fastify)models-registry.jsonas the single source of truth for(provider, model) → metadatamappings (analogous to OCP'smodels.json; SPOT discipline will be codified in a Phase 1 ADR — OLP ADR 0003 is currently the IR design, not the SPOT codification)- GitHub Actions for CI (
alignment.yml,release.yml,test.yml) ghCLI assumed for PR creation and release automation- No TypeScript. No test framework beyond
test-features.mjs(run vianpm test; CI workflow.github/workflows/test.yml). Keep dependencies minimal.
Key files to know
server.mjs— HTTP listener, entry surface (/v1/chat/completions,/health,/v1/models, etc.), plugin loader, request dispatch. Governed byALIGNMENT.md.lib/providers/— per-provider plugins. Each file (anthropic.mjs,openai.mjs,mistral.mjs, …) implements the Provider contract documented in ADR 0002.lib/ir/— Intermediate Representation definition + serializers. Governed by ADR 0003.lib/cache/— content-addressed cache layer (per-key isolation,cache_controlbypass, 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, identity layer. Carries OCP's per-key isolation model into OLP. 🟡 Phase 2 — D44 core + D45 server integration shipped (validateKey is invoked on every /v1/ request; chain filtered by providers_enabled; touchLastUsed fires post-response). Remaining: D46 owner-vs-guest /health + X-OLP-Fallback-Detail gating; keygen CLI bootstrap surface (D46+).*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).dashboard.html— owner-only multi-provider dashboard (quota panels, fallback rate, cache hit rate). 📋 Planned (Phase 6) — not yet authored.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 indocs/adr/README.mdbefore 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_kitoverlay (Iron Rule 5.5).
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 (specific components landed; others scheduled). For the full status table see README.md § "Implementation status". The shipped set as of D45 is: server.mjs (with Phase 2 auth middleware + audit wire), 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), models-registry.json, test-features.mjs (Suites 19 + 20). Phase 2 in progress: D46 owner gating for /health + X-OLP-Fallback-Detail; keygen CLI bootstrap surface; Phase 2 close → v0.2.0.
Project-specific constraints
ALIGNMENT.mdis binding. Any PR touching a provider plugin, the entry surface, or the IR must cite the relevant authority (provider CLI documentation / OpenAI spec URL / ADR number) in the commit body and PR description. SeeCLAUDE.md§ "Hard requirements for plugin / server.mjs changes" andALIGNMENT.mdRules 1, 2, 5.- Alignment CI is not suppressible. The
alignment.ymlworkflow greps for known-hallucinated tokens (currently carrying OCP'sapi.anthropic.com/api/oauth/usageas a transitive guardrail) and runs per-provider sanity checks. Adding new blacklist tokens is done via PR amendment toalignment.yml; removing entries requires anALIGNMENT.mdamendment PR. - No self-approval. Implementation author cannot merge their own PR (Iron Rule 10). A fresh-context reviewer must open the cited authority and confirm in the review comment.
models-registry.jsonis the only place to add/edit(provider, model)metadata. Do not touch hardcoded model maps inserver.mjs,lib/providers/*.mjs, orsetup.mjs(📋setup.mjsis planned, not yet authored). The OLP ADR that codifies this SPOT discipline lands in Phase 1 (OCP's ADR 0003 —models.jsonSPOT — is the precedent; OLP needs its own SPOT ADR because the registry shape differs).- Provider plugins follow the contract in ADR 0002. A new provider plugin must implement every method on the Provider contract (
name,displayName,models,auth,spawn,estimateCost,quotaStatus,healthCheck,hints). Partial implementations are unalignable perALIGNMENT.mdRule 4. - No anti-fingerprinting. OLP is honest about spawning the real CLI. If a provider detects subscription-spawn proxying and bans it, the response is to drop the provider per ADR 0006, not to mask the spawn.
- No conversation state. OLP is a stateless proxy. Memory / continuity is the client's responsibility (see ADR 0001 § Non-mission).
Release protocol
OLP follows the machine-readable release_kit: overlay in CLAUDE.md (Iron Rule 5.5). Before any version bump or tag push, re-read that YAML block and walk every item in new_feature_doc_expectations and bootstrap_quirk_policy. Tag push triggers .github/workflows/release.yml, which creates the GitHub Release automatically — do not create the release manually.
Version is sourced from package.json; changelog from CHANGELOG.md; user-facing docs from README.md. The Supported Providers table in README.md is sourced from models-registry.json per the overlay; do not hand-edit it out of sync.
Handoff expectations
A fresh session picking up OLP work should read, in order:
- This file (
AGENTS.md). ALIGNMENT.md— constitution; non-optional.CLAUDE.md— tool-specific instructions andrelease_kitoverlay.docs/adr/— most recent ADRs first; they explain why the current structure exists. Founding ADRs 0001–0006 are the OLP-bootstrap set.~/.cc-rules/memory/projects/olp_v0_1_spec.md— the v0.1 spec (authoritative for OLP scope until v1.0 ships).~/.cc-rules/memory/auto/MEMORY.md— cross-machine memory index.
Only after these should the session touch code.
Authors: project maintainer (with AI drafting assistance).