AkurAI-Drive / AGENTS.md

Latest change 8a258c11b4a4bce887befe7c4878a267865b3a5d - AkurAI Drive: branded landing + onboarding + gated storage creation 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).

## What this is

The product surface for AkurAI Drive: a branded marketing + onboarding site and the
storage-provisioning flow. Auth is **AkurAI IDP** (OIDC), identity surfaced via the
`groups` claim (`drive-admins` = admin). Files are intended to stream **browser ↔ S3**
via signed URLs (data plane separate from the app plane) — see the project memory.

## How it's served (no custom binary yet)

The site is a `site/` directory served by the **AkurAI-Framework** single binary
(`akurai serve --dir site/frontend`), deployed with the `akurai-ec2` ops CLI:

```
akurai-ec2 deploy-binary akurai-drive <akurai-musl-bin> 8095 ~/Projects/AkurAI-Drive/site
```

- `site/frontend/index.html` — the whole branded landing + onboarding (self-contained,
  no build step; native-ESM `<script type=module>`; SSO sign-in link + create-storage modal).
- `site/backend/collections.toml` — defines the `storage` collection; the framework
  auto-generates its REST API at `/api/collections/storage/records`.

## The storage gate (IMPORTANT — server-side, in nginx)

The framework auto-API is **public and unvalidated** (it has no auth, no validation
rules, no hooks). So the early-access guardrail is enforced at the **edge, in nginx**,
NOT in this repo:

- The create-storage form sends the access code as header `X-Drive-Access-Code` and the
  `{org,email,plan}` body to **`POST /api/storage`**.
- nginx (vhost `/etc/nginx/sites-available/akurai-drive.olibuijr.com` on the box):
  - `map $http_x_drive_access_code $drive_denied` → 0 only when the code matches.
  - `location = /api/storage` → `if ($drive_denied) { return 403 }` else `proxy_pass`
    to the framework's `/api/collections/storage/records`.
  - `location /api/collections` → `return 404` (the raw auto-API is blocked publicly so
    the gate can't be bypassed and the schema isn't advertised).
- **The code is the secret `REDACTED`, and it lives ONLY in the nginx vhost on the box.**
  It is never committed here and is not hardcoded in the frontend (the user types it).
  To change it, edit the `map` in the vhost and `nginx -t && systemctl reload nginx`.

This is a development guardrail. The real plan is a dedicated drive backend (OIDC RP
callback + S3 presigning + provisioning) — see the project memory `akurai-drive-project`.

## Conventions
- Do NOT modify `~/Projects/AkurAI-Framework` for drive features — another session owns
  it via `fw-*` worktrees. The drive composes the framework, it doesn't fork it.
- `data/` and `target/` are gitignored (runtime/build artifacts).
- Verify deploys with `curl --resolve akurai-drive.olibuijr.com:443:3.94.46.219 ...`.