# AGENTS.md — OpenVibe.Zone

## Project overview

OpenVibe.Zone (`https://openvibe.zone`) provides private S3-compatible storage **zones** for OpenVibe
projects: one named object zone per project environment (sandbox or production), reached by any S3 tool
at `https://s3.openvibe.media` (path style; `https://s3.openvibe.network` is the same surface behind
Cloudflare). The design is ADR-031. Zone owns the zone record and control API; **Media owns everything
inside a zone**.

- **Entry:** `server/index.js`; app `server/app.js`; port `5050`, service id `zone`.
- **API:** `server/http/api.js` (`/api/v1`), `events.js` (`/internal/events`, v2-signed,
  loopback-only), `pages.js` (console + docs), `discovery.js`, `principal.js`, `caller-limits.js`.
- **Domain:** `server/zone/` — `zones.js` (records, names, revisions, provisioning, deletion, the job),
  `usage.js` (Media's hourly rollups, kept and summed), `clients.js` (Media provision/report/keys and
  Network roles/projects), `media-limits.js`.
- **Pages:** `server/render/` (`layout.js`, `html.js`, `markdown.js`, `short.js`); CSS in `public/css`.
  Console changes are same-origin forms; no SPA.
- **Secrets:** an access key's secret is shown once and never stored here (Media keeps it encrypted).

## Owns, does not own

Owns the zone record: its name (never reused), environment, state, description, per-zone quota; the
control API and console; its metered usage as Media reports it (`zone_usage`); the resource index/control
views. Tables in `ov_zone` (migrations below).

Does not own: **Media owns the objects, bytes, replicas, S3/native data APIs, access keys, quota
enforcement, usage counting and the one deletion path.** Zone never lists keys, never holds bytes and
never counts. Identity/projects are Network's; the price comparison is Host's.

## Capabilities and API

Base `https://openvibe.zone/api/v1` (and `https://api.openvibe.zone/api/v1`). A caller is either a
developer app of the project with the route's capability for audience `openvibe.zone` (a sandbox app
reaches only the sandbox), or a project member (any role reads; admins/owners change).

| Route | Capability |
|---|---|
| `POST /projects/:project_id/zones` (Idempotency-Key) | `zone.zone.create` |
| `GET /projects/:project_id/zones` | `zone.zone.list` |
| `GET /zones/:zone_id` | `zone.zone.read` |
| `PATCH /zones/:zone_id` | `zone.zone.manage` |
| `DELETE /zones/:zone_id?recursive=true` | `zone.zone.delete` |
| `GET /zones/:zone_id/usage` | `zone.usage.read` |
| `GET /resources`, `/resources/:ovrn` | `zone.resource.read` (first-party) |
| `POST /resources/control` | `zone.resource.control` (first-party) |

Grants Zone holds: `media.zone.provision` and `media.access_key.manage` (audience `openvibe.media`),
`network.project.member.read`, and `events.subscription.manage` (the `media.usage.recorded`
subscription). SDK `openvibe-sdk/zone` is the client surface.

## Database and migrations

PostgreSQL `ov_zone` through `openvibe-sdk/db` (PgBouncer for the app, owner role for migrations):
`0001` initial, `0002` usage, `0003` telemetry, `0004` account data, `0005`–`0007` sharing/defaults.
Applied at boot; never edit a migration that has run. Telemetry is aggregated by route template,
method and status class (never raw URL), with 14-day retention; `/shared`, static assets, health,
readiness and `/metrics` are not counted.

## Auth and security

Network RS256 JWTs (JWKS) for apps/members; `/internal/events` answers only on loopback (nginx 404s
it), requires a valid v2 signature (`ZONE_EVENTS_SECRET`) and refuses a request through a proxy. Every
console change is a same-origin form; only a project's admins and owners change zones and keys. Media's
S3 answers are `private, no-store` with CDN no-store, so no edge keeps them. Never log or store an
access-key secret; no shared loopback key exists (tested by grep and at runtime). Account export/
deletion covers every table with a person column or exempts it with a reason.

## Deploy

`sudo ovhost deploy zone`: unit `openvibe-zone.service` on `127.0.0.1:5050`, database `ov_zone`, env
`/etc/openvibe/zone.env` (with `EVENTS_URL` and `ZONE_EVENTS_SECRET` for the usage subscription), nginx
`deploy/nginx/openvibe.zone.conf` on openvibe.zone's own certificate; migrations run at boot. Rollback
with `sudo ovhost rollback zone --to <sha>`.

## Commands and tests

```bash
npm ci
npm run dev                  # http://127.0.0.1:5050
npm test                     # every test/*.test.js, temp PGlite + mock Network
npm test -- login            # only matching files
npm run test:pg              # the same on PostgreSQL
```

`test/run.js` uses `openvibe-shared/test-runner`; temp PGlite and an in-process Network mock, never the
network. Coverage includes zone names/revisions/provisioning/deletion, usage rollups, app vs member
authorization, the S3 surface/limits, nginx auth limits, the no-internal-key and secrets checks,
session/redirect security, account data and the pages.

## Conventions and pitfalls

- CommonJS, 4-space indent, single quotes, semicolons; problem+json errors; escaped HTML.
- **Zone is metadata only.** Do not add an object list, byte store, replica, key listing or a second
  delete path — that is Media's, and a duplicate would drift. Operations call Media with Zone's own
  grants.
- **A zone name is never reused**, even after deletion; a rename does not change the S3 bucket identity.
- **The secret is shown once.** A key response may carry it that one time; never persist, log or
  re-render it. Media holds the encrypted key.
- **Idempotency:** create carries `Idempotency-Key`; a retry must return the same zone, not a second one.
- **Sandbox apps reach only the sandbox**, and only their project; a member check is Network's answer,
  never a client claim.
- **The usage is Media's:** keep the `media.usage.recorded` rollups and sum them; never estimate or
  count a byte locally.
- **No SQL migration may block a rollback**, and one with a person column must be covered by account
  data or exempted in `server/account-data.js` with a reason.