# X2 — AI BYOK Proxy — Session Card

> Per-module session list for **X2 AI BYOK Proxy**. Read this alongside `docs/plan/13-execution-modules-and-sessions.md` (the execution framework this card implements), `docs/plan/10-security-integrations-b2b.md` (the authoritative BYOK/AI design), and `docs/plan/02-platform-divergences.md` §2.4 (divergence #4). This is a **planning artifact** — no production code, no invented constants.

## Purpose

X2 delivers the **Bring-Your-Own-Key (BYOK) AI layer**: users supply their own API key for one or more of four supported providers (OpenAI, Anthropic, Google, Apple Intelligence); the ToGO backend stores those keys **encrypted at rest**, and **all** AI calls are proxied **server-side** so no key ever reaches any client. The AI does **behavioral pattern analysis only** — never diagnosis, prescription, or drug-category guessing — and the mandatory **"Consult your doctor."** deferral is enforced deterministically **in the proxy layer, not left to the prompt**. Every client "AI settings" screen is a **pure passthrough form** to the backend: write-only key submission, no read-back, nothing stored locally. This module closes **divergence #4** (AI working on legacy iOS via Apple Intelligence, missing on Android) once the Android session lands, by turning "integrate AI" into "render a passthrough screen against a contract that already exists."

## Feature parameters relevant to this module (exact — do not invent)

These are the fixed facts this module builds against. No numeric engine constants apply to the AI proxy; the binding constraints are categorical/security rules.

- **Supported providers (enum):** `openai`, `anthropic`, `google`, `apple_intelligence`. This is the only provider set.
- **No key ever reaches a client.** Keys travel once (client → backend, authenticated HTTPS) and are never returned, cached, or transited by any client afterward.
- **No key read-back endpoint.** Clients may learn only *that* a key exists for a provider (status: exists / not set), never *what* it is. A masked hint is **PENDING DESIGN** (open question #8).
- **Encrypted at rest.** Keys are encrypted before persistence in PostgreSQL; decrypted only in server memory at the moment of an outbound provider call. **Encryption mechanism (application-level envelope encryption vs. external KMS) and the encryption-key rotation policy are an OPEN QUESTION** (doc 10 §6 #4) — do not pick one silently.
- **All AI calls proxied server-side.** No client constructs prompts, selects providers, or post-processes AI output. Client role is strictly: submit key (write-only) / send analysis request / render response.
- **Deterministic guardrail (Core Opinion 2).** Every AI output ends with **"Consult your doctor."**, appended/verified **in the proxy layer** (post-processing), independent of model obedience. The AI is strictly prohibited from **diagnosing, prescribing, or guessing drug categories**.
- **Categorical, not quantitative (Core Opinion 1).** The AI performs **no quantitative food deduction**; behavioral analysis runs over categorical protocol events only.
- **`ai_provider_keys` schema:** every column `NOT NULL` with a defined default (per the strict schema rule). Planning sketch (doc 10 §2.5): `provider text NOT NULL DEFAULT 'openai'` (enum-checked `openai|anthropic|google|apple_intelligence`), `encrypted_key bytea NOT NULL DEFAULT ''` (ciphertext only; plaintext never stored), `key_status text NOT NULL DEFAULT 'active'` (`active|revoked`), plus `id`/`user_id`/`created_at`/`updated_at`. One row per (user, provider); rotation-history retention is undecided.
- **API surface sketch (names are placeholders, finalized against the Phase 1 API-conventions doc):** `PUT /v1/ai/keys/{provider}` (submit/replace — returns no key material), `GET /v1/ai/keys` (list provider status — **never** returns material), `DELETE /v1/ai/keys/{provider}` (revoke), `POST /v1/ai/analyze` (behavioral analysis — returns analysis text only).

## Session table

One row per session. Surfaces follow the module order (`backend → web → chrome → apple → android → desktop`); **there is no `mcp` session** — the MCP surface holds no AI keys and no protocol/AI logic (doc 13 §5). Backend must land before any client session. Replace `<date>` (YYYY-MM-DD) and `NN` (zero-padded index) at session start.

| Session ID | Surface | Scope (what this one session builds) | Entry deps | Done criteria (doc 13 §5) | Plan docs to read |
|---|---|---|---|---|---|
| `S-<date>-X2-backend-NN` | backend | The `aiproxy` module/plugin: `ai_provider_keys` schema + migration; encrypt-at-rest write path; `PUT`/`GET`/`DELETE` key endpoints (write-only, status-only list, **no read-back**); `POST /v1/ai/analyze` proxy that builds the guardrail system prompt server-side, calls the user's configured provider, and **deterministically appends/verifies "Consult your doctor." in the proxy layer**; provider adapters (`openai`/`anthropic`/`google`/`apple_intelligence`) stubbed or wired per Phase-1 scope decision. | M0.1–M0.4 (kernel, TOGO auth + per-user `users` row, plugin framework, migration harness); **M1 backend exists** (X-modules land after M1 — doc 13 §4). | **Backend-engine template, adapted for a non-engine module:** module registered on the kernel; migration is expand-contract and **every column is NOT NULL with a default**; endpoints return computed state; **no endpoint returns key material** (verified); key is encrypted before persistence and decrypted only in-memory server-side; the `"Consult your doctor."` deferral is enforced in the proxy and covered by a unit test that passes **regardless of model output**; no diagnosis/prescription/drug-category output path exists; unit tests encode the provider enum + deferral literally; integration test vs. real Postgres (key write → rotate → revoke; no-readback; deferral append; cross-user isolation 404-not-403) passes; **no key material leaves the backend**. Record the encryption-mechanism choice as an open question if still unresolved. | 10 §2–§3 & §6; 04 §2 (`aiproxy` module) & §4–§5; 13 §5–§6; 01 (Core Opinions). |
| `S-<date>-X2-web-NN` | web | `/settings/ai` — the BYOK passthrough form: provider picker + key field; write-only submit to `PUT /v1/ai/keys/{provider}`; renders provider **status** from `GET /v1/ai/keys`; renders proxied analysis (incl. the server's "Consult your doctor." deferral) verbatim where surfaced. Never displays stored key material. | `S-<date>-X2-backend-NN` done; M0.5–M0.7 (web shell + typed API client, theme engine, i18n engine). | **Client-engine template, adapted for a settings passthrough:** screen renders server key-status and submits key intents only (write-only); **thin-client/SSOT audit passes** — no key persisted in browser storage, no AI-provider SDK/endpoint in client code, no prompt construction, no client-side deferral logic (the deferral is rendered from server output, not synthesized); both themes render per the strict color spec; Arabic RTL mirrors correctly; strings are ICU, none concatenated. Masked-hint treatment is **PENDING DESIGN**. | 05 §1 (constraints), §4 (API map), §9.3; 10 §2.3; 13 §5. |
| `S-<date>-X2-chrome-NN` | chrome | Options-page AI BYOK section: provider + key entry submitted write-only to the backend (`POST /ai/keys`); renders provider status; no AI calls originate in the extension. | `S-<date>-X2-backend-NN` done; Chrome extension shell + TOGO auth linkage (from M1 chrome). | Client template (as above). Additionally: **keys are never written to `chrome.storage`** (which is not encrypted at rest), never attached to any client-side call, never echoed; a **static scan proves zero AI keys/SDKs/provider endpoints** in the extension bundle; both themes + Arabic RTL + ICU strings. | 06 §1 (row 4), §3.2, §9.3, §11–§12; 10 §2.3; 13 §5. |
| `S-<date>-X2-apple-NN` | apple | Settings AI BYOK passthrough screen (iOS, shared with macOS): provider + key entry, write-only submit, status render, proxied-analysis render with the deferral verbatim. | `S-<date>-X2-backend-NN` done; Apple workspace + shared packages + TOGO auth session (from M1 apple / Apple scaffold). | Client template (as above). Additionally: **no provider key in Keychain, memory, or entitlements**; copy audit confirms no diagnostic/prescriptive phrasing and that AI-surface copy carries the "Consult your doctor." deferral; both themes + native RTL mirroring + ICU. **Apple Intelligence BYOK shape is an OPEN QUESTION** (doc 10 §6 #5, doc 07 OQ #8) — do **not** ship a client-side Apple Intelligence path that violates "no key on client / all calls proxied"; if the platform forces an exception, document it narrowly rather than implement silently. | 07 §1 (rows 3–4), §4 (AI row), §9 (audits), Open Questions #8; 10 §2.3 & §6 #5; 13 §5. |
| `S-<date>-X2-android-NN` | android | Settings AI BYOK passthrough screen (Kotlin/Compose): provider + key entry, write-only submit, status render, proxied-analysis render with the deferral. **Closes divergence #4** (AI missing on Android). | `S-<date>-X2-backend-NN` done; Android app shell + TOGO auth + `core/network` (from M1 android). | Client template (as above). Additionally, the **divergence-#4 closure criteria**: static scan shows **zero AI-provider SDKs/keys/endpoints in the client**; runtime shows AI features function **through the ToGO proxy only**; no key on device; both themes render **on physical device**; Arabic RTL mirrors; ICU strings. Whether Apple Intelligence is selectable from Android is an open question (doc 02 OQ #1) — render only what the backend offers. | 08 §1 (row 4), §4.3 (AI row), §10 (#4 closure), §11 acceptance; 02 §2.4; 10 §2.3; 13 §5. |
| `S-<date>-X2-desktop-NN` | desktop | Settings AI BYOK section reusing the shared web component: submit the key **once** over HTTPS, render status + proxied results. No key caching, no key display after entry. | `S-<date>-X2-backend-NN` done; Electron shell + shared React app + `packages/api-client` (from M1 desktop). | Client template (as above). Additionally: **no AI provider key in config, memory, the renderer, or the main process**; key submitted once and never displayed again; reuses the web `/settings/ai` component so both themes + RTL + ICU inherit from Phase 2; SSOT audit confirms `packages/api-client` holds no AI logic. | 09 (AI & BYOK section), §3 constraints; 05 §9.3 (shared component); 10 §2.3; 13 §5. |

## Notes & gotchas

- **Legacy precedent worth reusing (concept only, not code):** legacy iOS already had a working API-key **proxy** for AI via Apple Intelligence (divergence #4, ahead side). The greenfield design generalizes that proxy into the server-side `aiproxy` module so every client is a thin passthrough — reuse the *idea* of server-side proxying, port none of the legacy client-side AI code.
- **Divergence #4 is only closed by the Android session.** Backend + iOS parity is not the closure; the ledger entry for #4 flips only when `S-<date>-X2-android-NN` passes its acceptance (doc 02 §2.4, doc 08 §10).
- **Liabilities to avoid (hard rules):**
  - Never store, cache, echo, or log a provider key on any client — including `chrome.storage` (not encrypted at rest), Keychain, entitlements, `localStorage`, config files, the Electron renderer/main process, or memory beyond the single submit request.
  - **Never add a key read-back endpoint.** `GET /v1/ai/keys` returns status only.
  - Enforce **"Consult your doctor."** in the **proxy layer deterministically** — never rely on the model/prompt alone to produce it.
  - No client builds prompts, selects providers, or post-processes AI text; no client-side diagnosis/prescription/drug-category logic; no quantitative food modeling (Core Opinion 1).
  - **No `mcp` session for X2** — the MCP surface holds no AI keys and no AI logic (doc 13 §5).
- **PENDING DESIGN items** (do not invent; blocked on the Figma/design track):
  - Whether a **masked key hint** is shown at all in the AI settings screen (open question #8).
  - The **AI settings screen visuals per platform** — dark-glow / light-flat palette application and full RTL/Arabic mirroring (open question #9).
- **OPEN QUESTIONS to carry (undecided — surface in each session's handoff, do not resolve unilaterally):** key-encryption mechanism (app-level envelope vs. KMS) + encryption-key rotation (doc 10 §6 #4); **`aiproxy` Phase-1 scope — ship vs. reserve table + plugin slot only** (doc 04 §2); Apple Intelligence BYOK shape / possible narrow proxy exception (doc 10 §6 #5, doc 02 OQ #1); AI proxy audit logging & retention (doc 10 §6 #6); server-side output filtering beyond the mandatory deferral (doc 10 §6 #7).

## Handoff reminder

At the end of **every** X2 session, write **one `session-handoff` memory** to the `healthdebug` brain (retain the content in the doc 13 §6 structure, then `memory/edit` to attach metadata — `retain` cannot set metadata) with a unique `source_ref: handoff/X2-ai-byok/<surface>/<n>` (never reuse) and `metadata` `{ project: "healthdebug", category: "session-handoff", era: "greenfield", status: "current", surface: "<surface>", module: "X2", title: "Handoff <session-id>", tags: [...], next: "<module+surface>" }`. Then **update the single `build-ledger` memory** (`source_ref: build-ledger`, edited in place) so one recall shows the whole frontier and the recommended next session. Any new architectural decision or open question also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc. See doc 13 §6 and `docs/brain/BRAIN-INDEX.md`.