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)