# Google Drive as Server Cloud Storage — Spec **Status:** Draft — Phase 0 helper shipped ( ools/oracle-discord/drive-oauth-setup.mjs) · **Date:** 2026-07-17 · **Owner:** Ryan **Goal:** Use the dedicated Google account's 5TB Drive as the server's cloud storage backend — per-user workspace files, message attachments, and per-user memory `.md` files — with storage quotas enforced per paid tier. --- ## 1. Summary The KAI server (`command-center-server.mjs`) gains a **Drive storage module** that stores each user's files in their own folder inside the 5TB Drive, tracks how many bytes each user has used, and refuses uploads that would exceed the user's tier limit. Files are addressed by the **real user id** from the identity isolation fix (v9.10 / 2026-07-17), so storage is correctly attributed per user. This is additive. Nothing about the existing engine, Discord fleet, or dashboard changes except new `/api/storage/*` endpoints and a new server module. --- ## 2. Account & auth model (the decision that drives everything) The 5TB lives on a **dedicated account you created for this**. That's the clean case: the server can act fully *as* that account with no risk to a personal identity. **Chosen path: OAuth2 with a stored refresh token, scope `drive.file`.** Ranked, with why: 1. **OAuth2 refresh token, `drive.file` scope — RECOMMENDED (high confidence).** The server authenticates as the dedicated account and can create/read/manage *only the files it creates* (`drive.file` = least privilege; it cannot see anything else in that Drive). Files count against the account's 5TB. One-time consent → long-lived refresh token stored in `.env`. 2. **OAuth2 with full `drive` scope — works, not recommended.** Broader access than needed. Only use if we later need to read files the server did not create. 3. **Service account + Shared Drive — only if this becomes a Workspace account.** Personal Gmail accounts cannot host Shared Drives, so this is off the table for the current dedicated Gmail. If you later move to Google Workspace, this becomes the cleanest option (no refresh-token maintenance). 4. **Plain service account (no shared drive) — RULED OUT.** A service account has its own ~15GB quota and separate billing; files it creates do **not** draw from the 5TB. This is the common trap. 5. **`GOOGLE_API_KEY` / Vertex ADC (already in `.env`) — RULED OUT for storage.** Neither carries a Drive scope; they cannot access Drive user storage. --- ## 3. One-time setup (YOU do this — I cannot log into your Google account) This is the only part I can't do for you: creating the credential and doing the consent both require signing into the dedicated Google account. Steps: 1. **Enable the API.** Google Cloud Console → the existing project (the one in `ANTIGRAV_PROJECT`) → *APIs & Services → Library* → search **Google Drive API** → **Enable**. (Reusing your Antigravity project is fine.) 2. **OAuth consent screen.** *APIs & Services → OAuth consent screen* → set it to **External**, add the dedicated account's email as a **Test user** (so it works without Google verification), add scope `.../auth/drive.file`. 3. **Create credentials.** *Credentials → Create credentials → OAuth client ID → Application type: Desktop app.* Download the JSON — it contains `client_id` and `client_secret`. 4. **Get a refresh token (one time).** I'll ship a tiny helper script `tools/oracle-discord/drive-oauth-setup.mjs`. You run it once: - It prints a Google URL. Open it, sign in **as the dedicated account**, approve. - Google redirects with a `code`; the script exchanges it for a **refresh token** and prints it. - `access_type=offline` + `prompt=consent` are set so a refresh token is actually returned. 5. **Paste 3 values into `.env`** (see §4). Done — the server can now use the 5TB. > Security: the refresh token is a long-lived secret. It lives only in > `tools/oracle-discord/.env` (same as every other secret) — never printed, > committed, or echoed. --- ## 4. New `.env` keys ``` GDRIVE_CLIENT_ID= GDRIVE_CLIENT_SECRET= GDRIVE_REFRESH_TOKEN= GDRIVE_ROOT_FOLDER_NAME=KAI-Server # optional; default "KAI-Server" GDRIVE_ENABLED=1 # kill-switch: 0 = disable cleanly ``` No new secrets are needed beyond these three real ones. --- ## 5. Server storage module — `tools/oracle-discord/storage/drive.mjs` Uses the `googleapis` npm package (add to `package.json`). Singleton Drive client built from the refresh token; token auto-refreshes in memory. Drive layout: ``` KAI-Server/ (root app folder, id cached) users/ / (one folder per real user id) workspace/ (Builder+ workspace files) attachments/ (message/DM attachments) memory/ (per-user .md memory files — task #20) ``` Functions (all async, all keyed by the caller's real `userId`): - `ensureUserFolder(userId, sub)` → folderId (creates lazily, caches id). - `uploadFile(userId, sub, name, buffer, mime)` → `{fileId, size, webViewLink}`. - `downloadFile(fileId, userId)` → stream (verifies the file is under the user's folder before serving — no cross-user reads). - `listFiles(userId, sub)` → `[{id,name,size,modifiedTime}]`. - `deleteFile(fileId, userId)` → moves to trash (never hard-delete). - `userUsageBytes(userId)` → summed size of the user's subtree (cached ~60s). - `accountQuota()` → `about.get({fields:'storageQuota'})` → `{limit,usage}` for the whole 5TB (ops dashboard). Design notes: - **`drive.file` scope** means the module only ever sees its own files — safe. - **Ownership check on every read/delete**: resolve the file's parents and confirm it's inside `users//`. This is the storage-side equivalent of the identity isolation fix — a user can never fetch another user's file id. --- ## 6. Per-tier quota model Drive has no native per-subfolder quota, so the **server enforces it**: before an upload, `userUsageBytes(userId) + incoming.size` must be ≤ the user's tier limit. Usage is also cached in the user record for fast reads. Proposed starting limits (adjust — see §10; total must fit inside 5TB): | Tier | Storage/user | Notes | |-------------|--------------|----------------------------------------| | Free | 1 GB | attachments (no full workspace folder) | | Explorer | 5 GB | paid tools + browser | | Creator | 25 GB | workspace files | | Builder | 75 GB | + Antigravity coding workspace | | Team | 150 GB | Roundtable + Full Fleet | | Enterprise | 1 TB | baseline; config can raise | Capacity math: 5TB = ~5,000 GB. Mixed tiers leave comfortable headroom for a few hundred paid users; the ops dashboard shows total 5TB usage via `accountQuota()` so you see the ceiling coming. Enforcement returns HTTP 413 `{ok:false,error:'quota_exceeded',limit,used}` so the UI can show "You're out of space — upgrade your tier." Tier limits live in one server constant (`TIER_STORAGE_BYTES`) next to the existing plan/credits config, so they're one edit to tune. --- ## 7. New API endpoints (all behind `currentContentUser` → real user only) ``` POST /api/storage/upload (multipart or base64) → {fileId,size,link} GET /api/storage/list?sub= → user's files in a subfolder GET /api/storage/file?id= → download (ownership-checked) POST /api/storage/delete {fileId} → trash GET /api/storage/usage → {used, limit, tier, pct} GET /api/storage/account (owner/admin only) → whole-5TB usage ``` These reuse the same auth wall and per-user identity as the DM/receipt work. --- ## 8. Consumers to wire (after the module lands) 1. **Message / DM attachments** — the "Photo" button and DM images upload to `attachments/`, store the returned link in the post/message record. 2. **Per-user memory `.md`** (task #20) — write/read the user's memory file in `memory/`, with the local device copy as the fast cache and Drive as backup. 3. **Builder-tier workspace** — the Antigravity workspace files for Builder users live in `workspace/` (ties into the "Builder tier → Antigravity session" request). --- ## 9. Rollout phases - **Phase 0 (you):** §3 setup → 3 `.env` values. ~15 min. - **Phase 1:** `drive.mjs` module + `npm i googleapis` + a self-test that uploads and deletes a 1KB probe file. Verifiable in isolation, touches nothing else. - **Phase 2:** `/api/storage/*` endpoints + `TIER_STORAGE_BYTES` + quota gate. - **Phase 3:** wire attachments. - **Phase 4:** wire per-user memory + Builder workspace. - Each phase is independently shippable and reversible via `GDRIVE_ENABLED=0`. --- ## 10. Risks / gotchas (honest list) - **Refresh-token expiry.** For an app in "Testing" on the consent screen, refresh tokens can expire after 7 days. **Fix:** move the consent screen to "In production" (no Google verification needed for `drive.file` with a single known user) — then the refresh token is long-lived. I'll flag this in the setup steps so you don't get surprised in a week. - **Quota accounting drift.** Summing file sizes can drift if files are added out of band. **Mitigation:** periodic reconcile against Drive's actual per-folder listing; usage cache TTL ~60s. - **Rate limits.** Drive API has per-project quotas (generous, but real). Batch and cache; don't poll usage on every request (cache it). - **Large uploads.** Use resumable uploads for files > ~5MB (the module handles this). - **Single point of storage.** Everything rides one Drive account; if that account is locked, storage is unavailable. Acceptable for now; note it for scale. - **Not a CDN.** Serving files through the server proxies bytes. Fine for attachments; if you later want fast public media, add signed Drive links or a real object store (R2/S3) — but 5TB Drive is a great start. --- ## 11. Open decisions for you 1. **Tier storage sizes** — accept the §6 table or give me your numbers. 2. **`drive.file` vs full `drive` scope** — recommend `drive.file` (least privilege). Confirm. 3. **Attachment size cap per upload** (e.g., 25MB Free → 250MB Builder?). 4. **When to move the OAuth consent screen to "production"** (do it during setup to avoid the 7-day token expiry — recommended). Once you've done Phase 0 and answered §11, I'll build Phase 1 and give you the probe-file test to confirm the 5TB is live before wiring anything else.