# Account, Integrations & Security — Spec

**Status:** Draft roadmap · **Date:** 2026-07-18 · **Owner:** Ryan
**Scope:** The full account/security/integrations vision for Oracle Lattice OS —
real profile settings, notifications, sign-in security, device tracking, and the
linked-accounts engine (Google, Discord, YouTube, Twitch, Facebook, email, RSS)
that syncs external services into the ecosystem so AI helpers can act on them in
one place.

This is a **multi-phase platform track**, not one edit. Each external provider
needs its own OAuth app (you register it; I wire it), and each sync is its own
connector + background job. This doc is the plan + exactly what you provide.

---

## 0. What shipped already (this pass)

- **Notification bell** in the top bar — desktop (left of the chat icon) and mobile
  (next to the Oracle symbol), with an unread badge and a panel. The **feed
  content** (mentions/replies/follows) is Phase 2 below; the bell + `setNotifCount(n)`
  hook are live now.
- Per-category Settings with a left sub-nav (Account, Subscription, Internet & Data,
  Ecosystem, Agents, Appearance, Privacy, General).

---

## 1. Profile (Account → Profile)

Real, saveable profile. Ships against the existing `/api/me/profile`.

- **Display name** — the name shown on posts, comments, and everywhere. Editable,
  but **rate-limited to 5 changes per rolling 30 days** (server tracks
  `nameChanges: [{ts}]`; UI shows "N of 5 changes left this month"). The `@handle`
  underneath is **immutable** (identity anchor; changing it would break mentions).
- Fields: pronouns, location, bio, interests, avatar (upload or KAI avatar).
- **Server work:** add `name` + `nameChanges` to the user record; new
  `POST /api/me/name { name }` that enforces the 5/30-day cap and propagates the
  new name to the display layer (posts/comments read the live user record, so this
  is mostly a write + cache-bust).

## 2. Notifications (bell feed)

- **Server:** a per-user notification store (`state/social/notifs/<userId>.jsonl`)
  written when someone **@mentions** you, **replies**, **reacts**, **follows**, or
  DMs you. Endpoints: `GET /api/me/notifs` (list + unread count),
  `POST /api/me/notifs/seen`.
- **Client:** the bell's panel renders the list; `setNotifCount()` drives the badge;
  poll on the existing cadence. Mentions are detected server-side by scanning
  new posts/comments/messages for `@handle`.
- **@mention** anywhere (post, comment, channel, DM) → a notification + optional
  browser notification (reuses the notification system already built for DMs).

## 3. Sign-in & Security (Account → Sign-in & Security)

Only security lives here (nothing bleeds in from other tabs).

- **Password**: set/change (hashed with the existing sha256+salt scheme).
- **Two-factor (2FA)**:
  - **TOTP** (Google Authenticator / Authy) — standard `otpauth://` secret + QR;
    server verifies the 6-digit code. This is the portable option.
  - **"Sign in with Google"** — optional: OAuth so a Google account *is* the second
    factor. Requires a Google OAuth app (Phase 4). A **new/never-seen device** is
    challenged **once**; after you approve it, the device is **trusted** and skips
    2FA next time (see §4).
- **Trusted devices**: a signed device token stored in the browser + server list;
  2FA only fires on an unrecognized device.

## 4. Sessions & Devices (Account → Sessions & Devices)

Show every active/recent login so you can confirm it was you.

- Per session: **device** (parsed from User-Agent — browser, OS, mobile/desktop),
  **login time**, **last active**, **device ID** (stable per-browser token),
  **IP address**, **approx location** (geo-IP), and a **VPN/proxy flag**.
- **IP / VPN detection** needs an IP-intelligence lookup (e.g. ipinfo/ipapi/
  ipqualityscore). That's an external API + key — one of the few things here that
  costs a call per new IP. Cached per IP.
- Actions: **"This is me"** (trust) / **"Sign out this session"** / **"Sign out all
  others"**.
- **Server:** the `sessions` Map already exists; extend each session with
  `{ua, ip, deviceId, createdAt, lastActive, geo, vpn}` and add
  `GET /api/me/sessions`, `POST /api/me/sessions/revoke`.

## 5. Linked Accounts / Integrations engine (Account → Linked Accounts)

The big one. A generic OAuth + sync framework; each provider is a plugin with a
**setup wizard** in this menu. Every provider needs **its own OAuth app** you
register (client id/secret → `.env`), just like the Drive setup.

Framework:
- `state/integrations/<userId>.json` — per-user link status + tokens (encrypted).
- `POST /api/integrations/<provider>/connect` → OAuth start (wizard).
- OAuth callback → store refresh token.
- Per-provider **sync worker** on a schedule; results flow into the ecosystem.

Providers (ranked by value / effort):

1. **Google** *(high value)* — sign-in + Google services. Once linked, the in-app
   **Web browser** uses your Google session (so Gmail/Drive/YouTube open logged in
   as the account you authorized). Also powers Google-based 2FA. Scopes: openid,
   email, profile (+ optional service scopes). *You provide: Google OAuth app.*
2. **Discord** *(high value)* — sync your servers. New **"Discord Servers"** section
   in the Messages area showing your servers → categories → channels, so you use
   Discord **through** Oracle: read, post, get updates. Config panel for which
   servers/channels to mirror. *You provide: Discord OAuth app + bot for the
   servers you want to bridge.*
3. **YouTube** *(high value)* — sync your **Shorts**/uploads into the Oracle
   **Shorts feed**, each rendered with a small **source badge** ("via YouTube
   (Google)"). *You provide: YouTube Data API (part of the Google app).*
4. **RSS** *(low effort, no OAuth)* — subscribe to any feed; new items appear as
   posts/notifications with a source badge. Good first sync to prove the pipeline.
5. **Twitch** — stream status + clips into the feed. *You provide: Twitch app.*
6. **Facebook / Instagram** — cross-post + import. *You provide: Meta app (their
   review is the slowest — plan for it).*
7. **Email** — connect a mailbox (IMAP/Gmail API) so AI helpers can triage/summarize
   in a workspace. *You provide: app password or Gmail API scope.*

**Source badges:** every synced item carries `{source:'youtube'|'rss'|…, url}` and
renders a small metadata chip so users always see where content came from.

## 6. Ecosystem hub (the vision)

Once providers are linked, the **Agents/workspace** area becomes the single place
where your AI helpers act across everything: summarize a Discord channel, draft a
YouTube Short description, triage email, post an RSS item to the feed — all keyed
to **your** real identity (from the isolation fix) and stored in **your** Drive
folder (from the storage spec). This is where "one area to do what the user wants"
comes together.

---

## 7. Phased rollout

- **Phase 1 — Account core (no external deps):** display-name 5/30 limit + real
  profile save; Sessions & Devices from UA + IP (VPN flag deferred to §4 API);
  notifications store + bell feed + @mention detection. *All buildable now.*
- **Phase 2 — RSS + notifications feed:** prove the sync pipeline with RSS (no
  OAuth), wire the bell to real notifications.
- **Phase 3 — Security:** TOTP 2FA + trusted devices.
- **Phase 4 — Google:** OAuth app → sign-in, browser session, 2FA option.
- **Phase 5 — Discord:** OAuth + bot → "Discord Servers" section + sync.
- **Phase 6 — YouTube → Shorts:** feed sync with source badges.
- **Phase 7 — Twitch / Facebook / Email:** as provider apps are approved.

## 8. What I need from you (per provider)

For each of Google, Discord, YouTube, Twitch, Facebook: create the provider's OAuth
app, add the redirect URI I give you, and hand me the **client id + secret** (into
`.env`, never printed). RSS and TOTP need nothing from you. IP/VPN detection needs
one IP-intelligence API key.

## 9. Open decisions

1. Which providers to prioritize after Phase 1? (I recommend RSS → Google →
   Discord → YouTube.)
2. Name-change limit: 5 per 30 days — confirm the number.
3. IP-intelligence provider for VPN detection (ipinfo vs ipqualityscore vs skip).
4. 2FA: TOTP first, Google-as-2FA later — OK?

Once you pick the Phase-1 scope and confirm the name-change number, I'll build
Phase 1 end-to-end (it needs nothing external).