AkurAI-Drive / AGENTS.md

Latest change 01b0c3e49ec2c526bbda745999ffed8ebfa8b8ee - docs: reference the access code by env var, not literal by olibuijr

# AGENTS.md — AkurAI Drive

A private, Iceland-hosted file cloud, part of the AkurAI platform. Live at
**https://akurai-drive.olibuijr.com** (EC2 `mail.olibuijr.com` / 3.94.46.219).

## Two components

**1. Marketing site (`site/`)** — branded landing + onboarding, served by the
**AkurAI-Framework** single binary (`akurai serve --dir site/frontend`):
```
akurai-ec2 deploy-binary akurai-drive <akurai-musl-bin> 8095 ~/Projects/AkurAI-Drive/site
```
- `site/frontend/index.html` — the whole landing (self-contained native-ESM, no build):
  hero, features, how-it-works, pricing, security band. Every CTA → `/auth/login`.
- Built from the already-compiled framework binary; **do NOT modify
  `~/Projects/AkurAI-Framework`** (another session owns it via `fw-*` worktrees).

**2. Backend API (`backend/`)** — `akurai-drive-api`, a Rust/axum service that mirrors
`~/Projects/akurai-idp` (axum + rusqlite + musl). Deployed by `backend/deploy.sh`:
systemd `akurai-drive-api.service` (User=drive), `127.0.0.1:8096`, env in
`/etc/akurai-drive-api.env`, DB `/data/akurai-drive/drive.sqlite`.
- `GET /auth/login` → sets a `drive_oauth_state` cookie, 302 to the IDP `/authorize`.
- `GET /auth/callback` → state check, exchanges the code at the IDP over **localhost
  http (`127.0.0.1:3500`, no TLS)** with `client_secret_basic`, calls `/userinfo`,
  creates a `drive_session`, 302 to `/app`.
- `GET /auth/logout`, `GET /api/me` (identity + `is_admin` = groups ∋ `drive-admins`),
  `GET /api/storage` (session-scoped bucket list).
- `POST /api/storage` — **the gate**: requires header `X-Drive-Access-Code` ==
  `DRIVE_ACCESS_CODE` (else 403), then a valid session (else 401), then provisions a
  real bucket via `aws s3api create-bucket` (`<prefix>-<slug(org)>-<6hex>`), records it.
- `GET /app` → the logged-in dashboard (`static/app.html`, `include_str!`); 302 to
  `/auth/login` without a session.

## Routing (nginx vhost on the box)
`/auth/*`, `/api/me`, `/api/storage`, `/app`, `/healthz` → backend `:8096`; everything
else (`/`, static) → framework `:8095`. The default-server catch-all (`000-default-https`)
returns a clean 404 for unmatched hosts.

## The gate
The early-access code is enforced **in the backend** via the `DRIVE_ACCESS_CODE` env var.
Its value lives ONLY in `/etc/akurai-drive-api.env` on the box — never committed here,
never in the frontend (the user types it into the create-storage form). Change it = edit
the env file + `systemctl restart akurai-drive-api`.

## Auth / AWS
OIDC client `AkurAI Drive` (`client_id 7d0d50e0…`), admin = IDP group `drive-admins`.
S3 via a scoped IAM user `akurai-drive-s3` (create/delete + objects on `akurai-drive-*`
only), keys in the backend env. AWS CLI v2 is installed on the box.

## Conventions
- `data/` and `target/` are gitignored. Verify deploys with
  `curl --resolve akurai-drive.olibuijr.com:443:3.94.46.219 …`.
- See memory `akurai-drive-project`, `idp-location-ec2`, `aws-ec2-ops`.

## Next
Files plane: browser ↔ S3 direct via SigV4 **presigned URLs** (server signs only —
HMAC-SHA256 — bytes never touch the box); a file-manager UI on `/app`; per-tenant bucket
policy/CORS; remove the early-access gate for GA.