cbfb187d16
- POST /api/fenjaops/invites on server.js (requireAuth+requireAdmin). Ignores any is_admin field in the body — always stores 0. Records the acting admin's email in invited_by so the audit trail shows who added whom (CLI adds still record "cli"). - admin/index.html: new "Invite a new user" form panel at the top (email + optional first name). - admin/admin.js: wires the form submit to the POST, shows inline success/error, refreshes the tables on success. - admin/admin.css: form styling matching the existing paper/ink palette; mobile stacks. - Docs: CLAUDE.md, PROJECT.md, OPERATIONS.md, CHECKLIST.md, README.md all updated. New non-negotiable property in PROJECT.md: no web endpoint can set is_admin=1 or delete an invite — promotion + removal stay on bin/invite.js. New CHECKLIST.md section H2 covers the page's gating, the invite form, and an escalation-path audit. Admin promotion and invite deletion remain CLI-only so a compromised admin session cannot escalate or evict. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
155 lines
9 KiB
Markdown
155 lines
9 KiB
Markdown
# project-bifrost
|
|
|
|
Invite-only frontdoor and editorial timeline for Fenja AI. Self-hosted on a single VPS.
|
|
|
|
> **New here (human or AI)?** Read this file top to bottom before making changes. It is the shortest path to understanding what exists and why.
|
|
|
|
---
|
|
|
|
## What it is
|
|
|
|
Two surfaces on one domain (`project-bifrost.fenja.ai`):
|
|
|
|
1. **Entrance** — email form. If the email is on the invite list, a session cookie is issued immediately and the welcome step appears. Shown to any logged-out visitor.
|
|
2. **Timeline** — an editorial scroll through 12 headlines about digital sovereignty, ending in a pivot to how Fenja AI addresses it. Shown to logged-in users at the same URL; includes a globe, an overview (Project Bifrost scenes), and an archive.
|
|
|
|
The root URL `/` is context-aware: unauthenticated → entrance, authenticated → timeline.
|
|
|
|
## Stack
|
|
|
|
- **Runtime** — Node 20+, Express 4
|
|
- **Storage** — SQLite via `better-sqlite3 12.x` (single file on disk, WAL mode)
|
|
- **Web server** — Nginx reverse-proxying to `127.0.0.1:3000`
|
|
- **TLS** — Let's Encrypt via certbot
|
|
- **Process supervisor** — systemd (`fenja.service`)
|
|
- **Runs as** — unprivileged `fenja` user on the VPS
|
|
|
|
## Repo layout
|
|
|
|
```
|
|
.
|
|
├── server.js Entry. Binds 127.0.0.1:3000. Routing + CSP + logging.
|
|
├── src/
|
|
│ ├── auth.js /auth/* endpoints: login, logout, me
|
|
│ ├── db.js SQLite init, schema, prepared statements, cleanup timer
|
|
│ ├── middleware.js rateLimit() + requireAuth()
|
|
│ └── sessions.js Cookie issue/clear, opaque session IDs
|
|
├── public/ Served to anyone (ungated)
|
|
│ ├── entrance.html The login page
|
|
│ └── entrance.js Two-step form behaviour
|
|
├── protected/ Served only with valid session cookie
|
|
│ ├── index.html The timeline (authed home page)
|
|
│ ├── timeline.js Timeline scroll/globe/archive logic
|
|
│ ├── archive.html Legacy deep-link placeholder
|
|
│ ├── archive.js Logout button
|
|
│ ├── fenja/
|
|
│ │ ├── colors_and_type.css
|
|
│ │ └── fonts/ Manrope + Newsreader variable fonts
|
|
│ └── vendor/ d3-array, d3-geo, topojson-client, countries-110m.json
|
|
├── admin/ Hidden admin UI (served at /fenjaops behind requireAuth+requireAdmin)
|
|
│ ├── index.html Stats, invite list, join log, + "Invite a new user" form
|
|
│ ├── admin.css
|
|
│ └── admin.js
|
|
├── bin/
|
|
│ ├── invite.js CLI: add/remove/list invites; admin add/remove/list
|
|
│ └── joins.js CLI: read the Join-CTA click log (list/summary/for/stats)
|
|
├── deploy/
|
|
│ ├── fenja.service systemd unit
|
|
│ └── nginx.conf Nginx server block
|
|
├── data/ SQLite lives here (gitignored)
|
|
├── PROJECT.md This file
|
|
├── OPERATIONS.md Day-to-day ops: invites, deploys, backups
|
|
├── INSTALL.md One-time server setup
|
|
└── CHECKLIST.md Manual test checklist after any change
|
|
```
|
|
|
|
## How auth works
|
|
|
|
The site is invite-list-only. The invite list IS the authentication factor — a person who knows an invited email can log in as them. The site exposes only marketing/preview content, so this is acceptable by design. If a user needs to be kicked out, remove their invite AND delete their session rows (see OPERATIONS.md).
|
|
|
|
1. User POSTs `{ email }` to `/auth/login`. Server:
|
|
- Rate-limits per IP (30/hour)
|
|
- Validates the email format. If not on the invite list, returns `403 {error: "not_invited"}`.
|
|
- On success, issues a session row (opaque 256-bit random ID) and sets `HttpOnly; Secure; SameSite=Lax` cookie. Returns `200 {ok: true, firstName}`.
|
|
2. Subsequent requests to `/`, `/timeline`, `/vendor/*`, etc. hit `requireAuth` middleware which looks up the session by cookie ID in SQLite. No JWT; revocation is a `DELETE`.
|
|
3. `GET /auth/me` returns `{ email, firstName }` for the current session (or 401). The frontend uses it on load to pick which entrance step to show.
|
|
4. Logout POSTs to `/auth/logout`, which deletes the session row and clears the cookie.
|
|
|
|
There are **no one-time codes, no pepper, and no SMTP** in this version. The entire mail stack and code-based verification path were removed.
|
|
|
|
## Non-negotiable properties
|
|
|
|
These things define the security model. Breaking any of them is a regression even if tests pass.
|
|
|
|
- **Protected HTML is never accessible without a valid session cookie.** `requireAuth` runs *before* `express.static`; the file is never read off disk for unauthenticated requests.
|
|
- **The session cookie is always `HttpOnly`, `Secure`, `SameSite=Lax`.** (`Secure` is conditional on `NODE_ENV=production` to allow local dev over HTTP — this env var must be set in `/etc/fenja/env` on the VPS.)
|
|
- **No inline `<script>` in any HTML** — CSP is strict (`script-src 'self'`). All JS is in separate files.
|
|
- **Node binds to `127.0.0.1` only.** Nginx is the single ingress.
|
|
- **`/etc/fenja/env` is minimal** (`PORT`, `PUBLIC_ORIGIN`, `NODE_ENV`), owned `root:fenja` mode 640, never in `/opt/fenja/`. Adding secrets back is a security review.
|
|
- **No web endpoint can set `is_admin=1` or delete an invite.** The admin page exposes `POST /api/fenjaops/invites` for creating *non-admin* invites only — the handler ignores any `is_admin` field in the body and always stores `0`. Admin promotion (`setInviteAdmin`) and invite deletion (`deleteInvite`) are reachable only via `bin/invite.js` on the VPS. This means a compromised admin session can grow the invite list but cannot escalate anyone (including themselves) or evict existing users.
|
|
|
|
If a change forces one of these to move, it's not a local change — it's a security review.
|
|
|
|
## Things that are easy to change
|
|
|
|
Everything above the auth layer is flexible:
|
|
|
|
- Content of any page in `public/` or `protected/` (copy, layout, visuals)
|
|
- Adding new protected pages (drop file in `protected/`, it's automatically gated)
|
|
- Adding new public pages (drop file in `public/`, it's automatically available)
|
|
- Tweaking the timeline (data, accents, animations)
|
|
- Fonts, colors, type scale (`protected/fenja/colors_and_type.css`)
|
|
- Error copy, confirmation copy, empty states
|
|
- Adding new `/auth/*` endpoints for e.g. invite management (but keep the invariants above)
|
|
|
|
## What's where at runtime (on the VPS)
|
|
|
|
```
|
|
/opt/fenja/ code (owned by fenja:fenja)
|
|
/opt/fenja/data/ SQLite + nightly backups
|
|
/etc/fenja/env secrets (root:fenja, 640)
|
|
/etc/systemd/system/fenja.service
|
|
/etc/nginx/sites-enabled/project-bifrost
|
|
/etc/letsencrypt/live/project-bifrost.fenja.ai/
|
|
/etc/cron.d/fenja-backup
|
|
```
|
|
|
|
## For AI agents working on this project
|
|
|
|
**Start by reading this file, then the specific file(s) you're being asked to modify. Do not skim.**
|
|
|
|
Good rules of thumb:
|
|
|
|
- **Content/layout/visual changes** — almost always local to one file in `public/` or `protected/`. Safe to iterate freely.
|
|
- **Adding a new page** — drop it in the right directory, done. Gating is automatic via the directory.
|
|
- **Changes touching `src/`, `server.js`, `deploy/`, or session/cookie behaviour** — read the "Non-negotiable properties" above first. If your change would violate any of them, stop and ask the human.
|
|
- **Changes to `package.json`, `deploy/`, `.env.example`** — operational surface area. Flag explicitly in the change summary and have the human redeploy.
|
|
- **Never commit secrets, `.env` files, `data/*.sqlite`, or anything the `.gitignore` excludes.**
|
|
- **When finished**, walk through `CHECKLIST.md` mentally: which items does this change plausibly affect? If any, say so in the summary so the human knows what to spot-check.
|
|
- **If unsure whether a change is safe, ask.** The codebase is small; the cost of a clarifying question is tiny compared to the cost of a silent regression.
|
|
|
|
## Current status
|
|
|
|
Live at `https://project-bifrost.fenja.ai/`. Backups and uptime monitoring configured. Production running, invites being handled manually via SSH.
|
|
|
|
## Tracking: Join-CTA clicks
|
|
|
|
The final "Join Project Bifrost" CTA records every press into `bifrost_joins`. Schema:
|
|
|
|
```
|
|
bifrost_joins(id INTEGER PK AUTOINCREMENT,
|
|
email TEXT NOT NULL,
|
|
clicked_at INTEGER NOT NULL,
|
|
session_id TEXT)
|
|
```
|
|
|
|
One row per click — if a user presses the button multiple times, you get multiple rows, so per-user history is preserved. Writes happen via `POST /api/bifrost-join` (behind `requireAuth`, reads `req.session.email`). Reads happen via `bin/joins.js` (see OPERATIONS.md).
|
|
|
|
## Things not yet done
|
|
|
|
Rough list of things that exist as possibilities, not commitments:
|
|
|
|
- Admin UI for the remaining invite operations (remove, rename, admin grant/revoke). Currently only *adding* non-admin invites is possible from the page; everything else stays on `bin/invite.js`.
|
|
- Rate-limit headers returned to the client (`Retry-After`) instead of bare 429s
|
|
- Session list view so users can see/revoke their own active sessions
|
|
- Second gated surface (docs? notes? unclear)
|