bincio-wiki/docs/architecture/auth.md

Authentication & Invites

Shared database

BincioWiki shares its user database with bincio_activity. Both services read from and write to the same SQLite file at /var/bincio/data/instance.db. There is no separate user store for the wiki.

The relevant tables:

users

CREATE TABLE users (
    handle          TEXT PRIMARY KEY,
    display_name    TEXT NOT NULL DEFAULT '',
    password_hash   TEXT NOT NULL,
    is_admin        INTEGER NOT NULL DEFAULT 0,
    created_at      INTEGER NOT NULL,
    wiki_access     INTEGER NOT NULL DEFAULT 1,
    activity_access INTEGER NOT NULL DEFAULT 0
);

wiki_access = 1 grants access to BincioWiki. activity_access = 1 grants access to BincioActivity. The two flags are independent; a user can have one, both, or neither.

sessions

CREATE TABLE sessions (
    token       TEXT PRIMARY KEY,
    handle      TEXT NOT NULL REFERENCES users(handle) ON DELETE CASCADE,
    created_at  INTEGER NOT NULL,
    expires_at  INTEGER NOT NULL
);

Sessions expire after 30 days. The cookie is bincio_session, HTTP-only, SameSite=Lax, domain .bincio.org (shared across all subdomains).

invites

CREATE TABLE invites (
    code            TEXT PRIMARY KEY,
    created_by      TEXT NOT NULL REFERENCES users(handle) ON DELETE CASCADE,
    used_by         TEXT REFERENCES users(handle) ON DELETE SET NULL,
    created_at      INTEGER NOT NULL,
    used_at         INTEGER,
    grants_activity INTEGER NOT NULL DEFAULT 0,
    grants_wiki     INTEGER NOT NULL DEFAULT 0
);

Wiki invites are created with grants_wiki = 1, grants_activity = 0. The grants_wiki column was added by a migration in edit/server.py (_migrate_db() runs at sidecar startup).

Session flow

POST /api/auth/login  →  bcrypt.checkpw  →  INSERT sessions  →  Set-Cookie: bincio_session
GET  /api/me          →  SELECT sessions JOIN users  →  200 + user JSON  |  401
POST /api/auth/logout →  DELETE sessions  →  Clear cookie

Every protected Astro page calls GET /api/me on load via inline JavaScript. A 401 or 403 response triggers an immediate window.location.replace('/login/').

Security model

This is client-side enforcement only. The static HTML is served publicly by nginx without any HTTP-level authentication. A user without JavaScript, or one who crafts direct HTTP requests, can read the raw HTML.

This is an intentional, documented tradeoff. The content is community memories (cycling routes, gear notes, trip reports) — not financial or medical data. The goal is keeping search engine crawlers and casual visitors out, not resisting determined attackers. All members of the community are trusted.

For future pages that require stricter enforcement, the architecture supports adding an Astro SSR mode with server-side cookie validation before any HTML is rendered. This would require migrating from output: "static" to output: "server".

Invite system

Creating an invite

Any wiki user can generate an invite link from /invites/. The sidecar creates a single-use token:

POST /api/invites
→ { "code": "abc123def456ghi7" }

The invite URL is https://wiki.bincio.org/join/?code=<token>.

Registration

The invitee visits the URL and fills in a handle, optional display name, and password. On submit:

POST /api/auth/register
{ code, handle, display_name, password }

The sidecar:

1. Validates the code exists and used_by is null.
2. Checks grants_wiki = 1.
3. Validates the handle (lowercase, 2–20 chars, [a-z][a-z0-9_-]{1,19}).
4. Validates password length ≥ 8 characters.
5. Checks handle uniqueness.
6. Inserts the user (wiki_access=1, activity_access=0) and marks the invite as used — in a single transaction.
7. Creates a session and sets the cookie. The user is immediately logged in.

Revoking an invite

A user can revoke any of their own unused invites via the /invites/ page. Used invites cannot be revoked.

User limits

The settings table stores a max_wiki_users value (currently 100). The /api/auth/register endpoint reads this value and rejects registration if the current wiki user count has reached the limit.

SELECT value FROM settings WHERE key = 'max_wiki_users';
-- 100