C-292 Phase 3 OAA KV Read Split

[kaizencycle]

Summary

Phase 3 hardens OAA sovereign memory reads by splitting public summary reads from private raw reads.

The previous broad read path could expose raw memory entries publicly:

GET /api/oaa/kv?prefix=

This PR keeps a public metadata surface, but gates raw memory payloads behind scoped read auth.

What changed

• Added lib/http/auth.ts

  • Shared read-auth helper for OAA service reads.
  • Supports token normalization: whitespace, quotes, and Bearer prefix.
  • Supports Authorization: Bearer, x-oaa-read-token, x-oaa-service-token, and x-agent-service-token.
  • Fails closed if no read token is configured for private reads.

• Updated pages/api/oaa/kv.ts

  • Public GET now returns sanitized summary metadata only.
  • Private raw GET requires private=true or raw=true plus read auth.
  • Private reads require a scoped prefix of at least 3 characters.
  • Unscoped private reads require explicit OAA_ALLOW_UNSCOPED_PRIVATE_READS=true.
  • Public reads capped at 25 rows.
  • Private reads capped at 100 rows.

• Added docs/security/C292_PHASE3_OAA_KV_READ_SPLIT.md.

Public mode

GET /api/oaa/kv?prefix=<optional>&limit=<1-25>

Returns only:

type, hash, previous_hash, ts, agent, cycle, intent, key

Private mode

GET /api/oaa/kv?private=true&prefix=<required>&limit=<1-100>

Requires read auth.

Files changed

• lib/http/auth.ts
• pages/api/oaa/kv.ts
• docs/security/C292_PHASE3_OAA_KV_READ_SPLIT.md

Merge readiness

• Branch is 3 commits ahead of main, 0 behind.
• No schema changes.
• No new dependencies.

Canon

Public reads show proof metadata.
Private reads require authorization.
Sovereign memory must not leak raw payloads.

We heal as we walk.