[integrations] REST API gateway

[alanshurafa]

Summary

Deno/Supabase Edge Function providing a REST API for non-MCP clients — 15 endpoints over thoughts, ingestion, and search.

Hardened per Wave 2.5 review:

• String IDs — all thought IDs parsed, validated, and forwarded as strings (not `Number()`-coerced). Prevents silent row-identity corruption when IDs cross 2^53 or migrations preserve historical BIGINT values.
• Robust upsert response parsing — `extractThoughtId()` helper handles scalar, `{id}`, `{thought_id}`, array-wrapped, and null-returning shapes. No more 500 on a legitimate response.
• Timing-safe auth — `timingSafeEqual()` XOR-accumulator for `x-brain-key` comparison. Early return on missing key; `.trim()` handles copy-paste whitespace.
• CORS allowlist — `CORS_ALLOWED_ORIGINS` env (comma-separated). Legacy default `*` preserved for backward compat, but README documents the risk for production.
• Per-key rate limiting — 100 req/min default (`RATE_LIMIT_PER_MIN` env). SHA-256-hashed keys so logs never leak the raw key. In-memory bucket with `Retry-After` response.
• Ingest proxy hardening — 60s `AbortController` timeout, 1 MB body cap, distinguishes 502 (unreachable), 504 (timeout), invalid-JSON vs forwarded-JSON responses.
• Sort-column allowlist — rejects arbitrary column names; prevents schema enumeration and ordering by heavy/PII columns.
• Error opacity — top-level catch returns `{error:"internal_error", code:"GENERIC", error_id:}` and logs full error server-side with the same UUID. No PostgREST constraint names or data values leak to callers.
• Sensitivity re-detection on update — `handleUpdateThought` runs `detectSensitivity` + escalation-only `resolveSensitivityTier`. A standard thought rewritten to contain a credit card can no longer stay `standard`.

Why

The stock MCP server is fine for AI clients, but dashboards, scripts, and webhooks need HTTP. This gateway mirrors the core MCP's capture/search/list/update surface over REST with the same auth model (`x-brain-key`) — so any client that can do HTTPS + headers can talk to an Open Brain.

Replaces the content from the closed PR #45 bundle with the Wave 2.5 security hardening pass incorporated.

Test plan

• POST `/capture` with valid key — thought created, ID returned as string
• POST `/capture` with wrong key — 401 returned in constant time (no timing-based key-length leak)
• Flood 150 requests in 60s with same key — verify 101st gets 429 + `Retry-After`
• GET `/thoughts?sort=embedding` — verify 400 (sort column not in allowlist)
• GET `/thoughts?sort=created_at` — verify 200 + sorted results
• POST `/update` changing content to include `4111-1111-1111-1111` on a `standard` thought — verify tier escalates to `personal` or `restricted`
• Unset `CORS_ALLOWED_ORIGINS` → verify `*` still honored with README warning
• Set `CORS_ALLOWED_ORIGINS="https://app.example.com"\` → verify other origins rejected
• `deno check index.ts` + `_shared/*.ts`

[alanshurafa]

Conflicts with main. This is tied to the design discussion in #192; I'll rebase once there's a direction there.

[alanshurafa]

Rebased onto main — conflicts cleared. The only conflict was a stray repo-wide markdown-lint commit on this branch that collided with main's own lint cleanup; I dropped that commit. The branch's actual changes are untouched. Now mergeable.

[alanshurafa]

Both #201 and #202 are single-tenant, shared-key gateways over a service-role backend (RLS bypassed by design). Both now use constant-time key comparison, env-only secrets, and header-only auth — I dropped the ?key= query param from #201 (it leaked the key into access logs) to match #202. Both READMEs now document the trust model explicitly: single-tenant by design, high-entropy key required (rate limiting is best-effort), and the service-role/RLS-bypass boundary. The auth surface is sound for the intended self-hosted use — ready for your review whenever.

[justfinethanku]

Audited for maintainer merge lane: branch is mergeable, Alan already documented the single-tenant trust model clearly, local passes, and I added the standard Community Contribution badge plus creator credit to the README so the contribution convention is preserved.

[justfinethanku]

Audited for the maintainer merge lane: the branch is mergeable, Alan already documented the single-tenant trust model clearly, local Deno type-checking for integrations/rest-api passes, and I added the standard Community Contribution badge plus creator credit to the README so the contribution convention is preserved.