**Genre**: engineering annex (non-UX). Port-plan for v2's encrypted credential vault, which is the foundation any v4 surface adapter (`@cocottetech/@platform/codebase/@features/{bookings,content}-*/adapter/`) depends on. Discovered via 2026-05-18 audit of v2 (`docs/quinn-my/credentials.md` + `codebase/@features/my/backend-api/src/`).
- **Encryption**: AES-256-GCM, 96-bit IV + 16-byte auth tag + ciphertext, stored as colon-delimited hex blob. Per-row IV (no nonce reuse).
- **Key sources** (priority): (1) session-key from custodian SSE flow (production); (2) `CREDENTIALS_ENCRYPTION_KEY` env var (dev fallback).
- **Custodian flow**: `black` subscribes to `GET /internal/key-events` (SSE), receives `{sessionId, nonce}` on user login, POSTs the DEK back via `/internal/key-delivery`. Server stores the key in process memory only; restart clears all session keys.
- **Categories**: static taxonomy in `categories-data.ts` — 7 categories (`escorting`, `screening`, `content`, `reviews`, `socials`, `messaging`, `travel`) with platform-keyword inference.
- **Inference**: on create/update/import — `inferPlatformLink(platform, url)` matches against a platforms registry; `inferCategory()` assigns one of the 7 categories.
- **Bulk import**: Firefox CSV-export-compatible POST `/api/credentials/import` — Quinn drops `about:logins` export into the system.
- **API**: standard CRUD (`GET / POST / PUT / DELETE` on `/api/credentials`); `GET /api/credentials/categories` for the static taxonomy.
Source files (apricot-authoritative; local Mac is divergent but readable):
Every surface adapter Cocotte runs (`bookings-tryst`, `content-onlyfans`, `bookings-hotels`, screening lookups, etc.) needs Quinn's per-platform login. v4 cannot ship its first surface action without the vault. Reinventing this is wasteful; v2's implementation is mature and battle-tested by Quinn's daily use.
The **container-based surface adapter** ([_engineering-surface-adapter-container.md](./_engineering-surface-adapter-container.md)) is the primary consumer — it requests one-shot decrypted credentials at action-start, performs a real login through Playwright, and discards the decrypted blob from process memory when the action completes. Credentials are never written to container disk and never logged.
## Port verdict
**PORT** — full lift, with v4 adjustments:
1.**Multi-tenancy**: v2 is single-Quinn; v4 must scope every `credentials` row by `user_id` (+ optional `org_id`). Add to the schema; enforce via RLS.
2.**PostgreSQL not SQLite**: target is `platform.db` (Postgres 16). Migrate schema with the same column shape; use `BYTEA` instead of `TEXT` for encrypted fields if cleaner, otherwise keep hex-string form for compatibility.
3.**NestJS not Bun/Hono**: rewrite the routes module as a NestJS controller + service. Logic ports verbatim — encryption math is unchanged.
4.**Custodian stays on black**: the SSE-key-delivery flow is correct as-is. The custodian process running on black continues to be the source of truth; v4's `platform.api` becomes the SSE subscriber endpoint (replacing v2's `my.transquinnftw.com/api/credentials`).
5.**Categories taxonomy is canonical**: import `categories-data.ts` verbatim into v4 (it informs [O surfaces roster](./O-surfaces-roster.brief.md) categories N1–N9). v4's brief O is the *UX-facing* presentation; this taxonomy is the *engineering* mapping.
| Categories source | `@platform/codebase/@packages/credentials-shared/src/categories.ts` (shared, imported by both platform-api and the surface adapters in `@features/{bookings,content}-*/adapter/`) |
| Adapter consumer pattern | `@cocottetech/@platform/codebase/@features/bookings-tryst/adapter/{login,bump}/lib/credentials.ts` — fetches via `platform-api` + decrypts at point-of-use |
Write `0003_credentials_vault.sql`. The v4 schema **extends v2's** by adding `auth_mode` to support both cookie-paste and full-credentials paths per [_engineering-surface-adapter-container.md](./_engineering-surface-adapter-container.md):
```sql
CREATE TYPE credential_platform_type AS ENUM ('escort', 'content', 'screening', 'reviews', 'socials', 'messaging', 'travel', 'other');
CREATE TYPE credential_auth_mode AS ENUM ('cookie', 'credentials');
auth_mode credential_auth_mode NOT NULL DEFAULT 'credentials',
-- credentials-mode fields (NULL when auth_mode='cookie')
username TEXT,
password_enc TEXT,
totp_secret_enc TEXT,
-- cookie-mode fields (NULL when auth_mode='credentials')
cookie_blob_enc TEXT,
-- shared
note TEXT,
sort_order INT NOT NULL,
is_archived BOOLEAN NOT NULL DEFAULT FALSE, -- mode-switch keeps prior auth for revert
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CHECK (
(auth_mode = 'credentials' AND username IS NOT NULL AND password_enc IS NOT NULL AND cookie_blob_enc IS NULL)
OR
(auth_mode = 'cookie' AND cookie_blob_enc IS NOT NULL AND password_enc IS NULL)
)
);
-- Unique key allows two rows per (user, platform, username) when one is archived
CREATE UNIQUE INDEX idx_credentials_platform_username_active
ON credentials(user_id, lower(platform), lower(username))
WHERE NOT is_archived;
ALTER TABLE credentials ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON credentials ...;
```
Mode-switching (Quinn changes from cookie to full creds or vice-versa) flips `is_archived=TRUE` on the prior row and inserts a new active row. The archive lets Quinn revert without re-entering. Brief V data-export includes both active + archived auth-state.
### Step 2 — port the cipher utility
TypeScript port of v2's `cipher.ts` — AES-256-GCM with the same blob format. Heavy testing against v2's stored values to verify byte-perfect output (if data is migrated rather than re-encrypted).
### Step 3 — NestJS controller + service
Mirrors v2's route handlers; CRUD + import + categories endpoints. Same auth model (session + key required for read/write of decrypted values).
Lift `categories-data.ts` into `@platform/codebase/@packages/credentials-shared/`; consumed by both `platform-api` and adapter actions. Ensures O surfaces roster matches the vault's category enum.
- POSTs `{platform: 'tryst', username: <Quinn's>}` to platform-api `/api/credentials/lookup`.
- Decrypts via session key.
- Returns `{username, password, totp_secret}` to the caller.
### Step 7 — data migration
One-time script that reads v2's SQLite DB + decrypts using v2's session-key flow + re-encrypts under v4's keys + inserts into platform.db. Quinn's credentials carry forward.
## Dependencies on prior work
-`0001_tenancy_and_content.sql` already creates `users` + `orgs` tables; this migration extends with `credentials`.
- The custodian process on black is part of v4's infrastructure; either reuse v2's binary or fork it.
-`@platform/codebase/@features/platform-api/` NestJS scaffold (per P0.3) needs to exist before this work starts.
## Open questions
- **Cross-org credential sharing** (Demimonde back-office holds credentials; Sansonnet has its own)? Per [brand-family memory](./O-surfaces-roster.brief.md) — Demimonde is back-office for the Cocotte umbrella, so credentials live under Demimonde Org ownership with the Cocotte talent as user_owner. Sansonnet is separately-held; its own Org owns its credentials. Schema supports both via `(user_id, org_id?)`.
- **TOTP secret as one-shot vs persistent**? Currently persistent in v2 (Cocotte computes TOTP on each lookup). For high-security platforms, may want to require Quinn-side approval per-use. Defer.
- **Per-surface auth-rotation cadence** — some platforms invalidate cookies after N days. Cocotte should track last-validated timestamp + re-prompt Quinn when stale. Defer to a future schema iteration.
## Out of scope
- The custodian binary itself (black-side; pre-existing).
