customer-presentation/PROJECT.md

# 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
├── bin/
│   ├── invite.js          CLI: add/remove/list invites
│   └── 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.

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 managing invites without SSH
- Rate-limit headers returned to the client (`Retry-After`) instead of bare 429s
- A proper "resend code" link on the code screen after 30s
- Session list view so users can see/revoke their own active sessions
- Second gated surface (docs? notes? unclear)
- Email templates with proper HTML (currently plain text, which is fine for deliverability)