AGENTS.md

AGENTS.md — OpenVibe.Cam

Project overview

The camera app, the private wall for cameras you own, and the API Live's cam button calls. A photo or
a still is saved to OpenVibe.Pics (the MediaHub); Cam keeps the link, the filter label and the
caption, never the bytes. A camera is private to its owner, and a viewer sees it only while the
grant the owner gave is active and not revoked. Node.js/Express, PostgreSQL, CommonJS, no build step.

• Origin https://openvibe.cam, port 5160, service id cam, env prefix CAM, unit
  openvibe-cam.service, release root /opt/openvibe.cam.
• v1 is written and tested ([STATUS.json](STATUS.json)); the README records that it is not deployed by
  the change that added it.

What it owns

• cam_cameras (cam_ + ULID, owner usr_…, source browser|phone|pi|ip, status, Live stream id
  unique per owner, slot, note) and cam_grants (cmg_, one canonical viewer subject, expiry,
  revocation); cam_photos, cam_stills; account-data receipts and telemetry. All in
  [migrations/0001_initial.sql](migrations/0001_initial.sql).
• There is no image/blob/byte column anywhere. The pics_slug and links are the picture's address
  in Pics; Cam and its database cannot serve the bytes.
• The capture app (browser preview, timer, 3-shot burst, grid, on-device colour/light/softness), the
  private wall /w/:id, /my, /my/cameras/:id, the still /s/:id and the <ov-camera> element.
• Revocable viewer grants: @username resolved through Network (identity.subject.resolve), a
  subject id accepted without it, default 7 days and at most 90, a re-grant extends instead of making a
  second grant, revocation writes a timestamp checked on every read.
• The Live cam button: POST /api/v1/stills fetches Media's public GET /live/:slot/frame.jpg
  (only image/jpeg accepted), uploads it to Pics as the person and returns the still plus the exact
  line Live posts.

Not owned: identity (Network), the live frame (Media), the picture bytes and their visibility
(Pics/MediaHub), the stream (Live), Studio (the edit link points at openvibe.studio).

Who calls it, and whom it calls

• Callers: people in the browser; OpenVibe.Live's cam button (POST /api/v1/stills with the
  viewer's own token); any site embedding <ov-camera>.
• Depends on:
• Network — sign-in (OAuth client cam, PKCE S256, cookies cam_at/cam_rt/cam_oauth),
  JWKS, token exchange/refresh/revoke, account export/deletion, identity.subject.resolve.
• Media — the public live frame (OV_MEDIA_URL, GET /live/:sel/frame.jpg?w=640).
• Live — GET /api/streams/:id to check a paired stream is on the owner's channel
  (live.stream.read).
• Pics / MediaHub — POST /api/v1/images, called with the person's own Network token
  (pics.image.upload); Cam never holds a service token for Pics, and MediaHub refuses one there.
• Events — account deliveries; PostgreSQL (DATABASE_URL, owner DATABASE_DIRECT_URL for
  migrations); Valkey optional.

Repository map

• Entry: [server/index.js](server/index.js) — createApp(), listen, key warm-up, graceful stop.
• App: [server/app.js](server/app.js) — helmet/CSP, /auth, /internal/events, /shared,
  /api/v1, pages (/, /app, /my, /w/:id, /s/:id, /developers), machine endpoints.
• Config/db: [server/config.js](server/config.js), [server/db.js](server/db.js).
• Domain: [server/cameras.js](server/cameras.js) (cameras, grants, photos, stills),
  [server/store.js](server/store.js), [server/upstreams.js](server/upstreams.js) (Media/Live/Pics),
  [server/events/pipeline.js](server/events/pipeline.js).
• HTTP: [server/http/api.js](server/http/api.js), pages.js, principal.js, discovery.js,
  openapi-routes.js, router.js; views in [server/views/index.js](server/views/index.js).
• Auth: [server/auth/sso.js](server/auth/sso.js), [server/auth/keys.js](server/auth/keys.js).
• Browser: [public/js/developers.js](public/js/developers.js) and the camera pages/view strings;
  the filter runs on a canvas in the person's browser.
• Proof seed: [scripts/seed-proof.js](scripts/seed-proof.js).
• Deploy: [deploy/systemd/openvibe-cam.service](deploy/systemd/openvibe-cam.service),
  [deploy/nginx/openvibe.cam.conf](deploy/nginx/openvibe.cam.conf) (TLS, www→apex, /auth/me and
  /my/ rate-limited, /internal and /metrics 404, 16 MB body cap).

Commands

npm install
npm run dev                # NODE_ENV=development node server/index.js
npm start                  # node server/index.js, http://127.0.0.1:5160
npm test                   # test/run.js, PGlite, mock Network + Media/Live/Pics fixtures
OV_ALLOW_SUITE=1 npm test  # the README's guarded form
npm run test:pg            # same on PostgreSQL (CAM_TEST_STORE=pg)
npm test -- cameras        # filter by file name; --strict makes a skip fail
npm run seed:proof         # CAM_PROOF_OWNER=usr_… CAM_PROOF_VIEWER=usr_… node scripts/seed-proof.js
ov test                    # the harness's sharded run of what the change reaches

Database and migrations

Cam's own PostgreSQL database on the host's data role (DATABASE_URL through PgBouncer; owner
DATABASE_DIRECT_URL for migrations; PGlite under CAM_PGLITE_DIR in development). Migrations are
migrations/NNNN_*.sql, applied at boot; never edit an applied one, add a new number. Constraints are
part of the privacy model (one unrevoked grant per camera+viewer, owner/stream uniqueness) — do not
drop or relax them for a feature.

Auth and privacy

• People sign in with Network SSO. The API takes the signed-in person's token; POST /api/v1/stills
  forwards the viewer's own token to Pics; there is no Cam service-to-Pics credential.
• A wall is for its owner and an active, unrevoked, unexpired grantee — staff have no bypass
  (404 for everyone else, including admins).
• A grant is one canonical subject with an expiry; revocation is immediate on the next read. @username
  resolution is Network's; a subject id works when Network is not reachable.
• The <ov-camera> element holds no session and uploads nothing unless the site asks; the camera is
  a browser API, not a server capture.
• Account export/deletion go through /internal/events with this service's own client token.

Frontend loading model

Server-rendered pages and plain browser JavaScript; the filter, timer, burst and grid run in the
person's browser on a canvas — the server never applies an effect and does no image analysis. The
embeddable <ov-camera> is one script from https://openvibe.cam/embed/ov-camera.js; there is no SPA,
bundler or transpiler. openvibe-shared supplies the Frame/legal/SEO and /shared/* from the pinned
node_modules. CSP is in [server/app.js](server/app.js).

Deploy

Unit [deploy/systemd/openvibe-cam.service](deploy/systemd/openvibe-cam.service) runs
/opt/openvibe.cam/server/index.js on 127.0.0.1:5160, env /etc/openvibe/cam.env; vhost
[deploy/nginx/openvibe.cam.conf](deploy/nginx/openvibe.cam.conf). The README does not record an
ovhost deploy cam command and says this release is not deployed — use the host's own service
installer, and do not claim the domain is live until the owner's launch step runs.

Tests

npm test runs each test/*.test.js in its own process (90 s) with a temp PGlite, a mock Network and
a Media/Live/Pics fixture server. It covers the migration and its constraints; pairing and stream
ownership; grants (username resolution, extension, revocation, expiry, no staff bypass); the still's
Media→Pics path and refusals; photo upload and limits; pages/cache headers; sign-in; account
export/deletion; and the home page must not put any camera or grant on the public page. ov test runs
the same.

Conventions

• CommonJS, 4-space indent, single quotes, semicolons; factories with injectable config/store/clock/
  fetch/log; rendering in server/render/ and server/views/.
• IDs are prefixed ULIDs (cam_, cmg_, cmp_, cms_); timestamps are the store's clock.
• Errors are small JSON problems or 404s; never reveal that a camera exists to someone without a grant.
• No secret in a log, a response or the database; Pics' slugs are not secrets but are not enumerable.

Pitfalls

• No bytes in Cam. Do not add an image/blob column or proxy the picture: Pics owns the bytes and
  its own visibility; Cam stores only the slug and links.
• No face recognition, no server-side filter, no image analysis. The README's promise is part of
  the product; a "smart" server feature breaks it.
• The wall is private even from staff. A grant is the only door (besides the owner); a 404, not a
  403, is the answer.
• Only image/jpeg from Media's frame is accepted for a still; do not accept arbitrary content
  types or arbitrary URLs.
• Check stream ownership through Live's public API before pairing a stream; the slot defaults to
  the stream's managed slot.
• Grants have a maximum of 90 days; a re-grant extends the active row, never duplicates it.
• The Live cam button must use the viewer's token to upload to Pics; a service token is refused
  by MediaHub and would attribute the still to Cam.
• A photo of someone else's Pics object is 404 in Studio, not a redirect or a preview.

Documentation

• [README.md](README.md) — purpose, the tables, API, Live cam button, <ov-camera>, pages, proof,
  run/test and deploy files.
• [STATUS.json](STATUS.json) — what works and what does not.
• OpenVibe.Contracts holds the cam.* capability shapes; Pics/Media own the image contract.