irdb/doc/frontend-development.md

Building a new frontend

Audience: anyone tasked with rewriting the UI in Vue, building a Tauri desktop app, or a mobile client. Read this before touching any code.

Read this first

The api's contract is stable. The PHP+Twig UI is replaceable. You can throw out the entire ui/ directory and replace it with a Next.js app, a Vue SPA, a Tauri desktop, or a SwiftUI client without the api caring at all — provided the new frontend respects the authentication model.

What's stable, in order of importance:

1. /api/v1/* paths and shapes, as documented in OpenAPI (/api/v1/openapi.yaml).
2. Token kinds (reporter, consumer, admin, service).
3. RBAC roles (viewer, operator, admin).
4. The impersonation pattern: service token + X-Acting-User-Id.
5. The users shape and oidc_role_mappings semantics.

What's not stable (and you shouldn't depend on):

• Template names under ui/resources/views/.
• UI route paths under /app/*.
• Internal class names, file layout, migrations of UI-only state.
• The /internal/jobs/* surface — scheduler-only, not in OpenAPI.

The full stable-vs-replaceable table is in architecture.md.

Three integration patterns

(a) BFF replacement — drop-in for the current PHP UI

Easiest path. A new server process holds the service token, manages browser sessions, and forwards each request to the api with the two-header pattern. Works for SSR-style frontends (Next.js, Nuxt, Rails, Django, Phoenix).

What the BFF owns:

• The OIDC redirect / callback flow (PKCE).
• Browser sessions (any backend; the current PHP UI uses file-backed, but Redis or a signed cookie store works).
• A local-admin form (optional).
• HTML rendering or hydration of an SPA shell.
• CSRF for its own forms.

What the BFF does not own:

• Business logic. Scoring, RBAC, decay all live in the api.
• Database access. The BFF holds zero persistent state of its own.
• The decision of "who is this user". The api answers that via /api/v1/auth/users/upsert-oidc and /api/v1/auth/users/upsert-local.

Pseudocode for the three critical bits in a Node/Express BFF:

// 1. Validate an OIDC ID token; upsert via the api.
app.get('/oidc/callback', async (req, res) => {
    const tokens = await exchangeCode(req.query.code, req.session.pkceVerifier);
    const id = await validateIdToken(tokens.id_token, oidcConfig);

    const user = await fetch(`${API_BASE}/api/v1/auth/users/upsert-oidc`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${UI_SERVICE_TOKEN}`,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            subject: id.sub,
            email: id.email,
            display_name: id.name,
            groups: id.groups ?? [],
        }),
    }).then(r => r.json());

    if (user.role === null) {
        return res.redirect('/no-access');
    }

    req.session.regenerate();          // defeat fixation
    req.session.user_id = user.id;
    req.session.role = user.role;
    res.redirect('/app/dashboard');
});

// 2. The two-header pattern, applied to every admin call.
async function callApi(req, path, init = {}) {
    const headers = new Headers(init.headers);
    headers.set('Authorization', `Bearer ${UI_SERVICE_TOKEN}`);
    if (req.session.user_id) {
        headers.set('X-Acting-User-Id', String(req.session.user_id));
    }
    return fetch(`${API_BASE}${path}`, { ...init, headers });
}

// 3. A typical handler: BFF is a pure proxy with HTML rendering on top.
app.get('/app/ips', async (req, res) => {
    const data = await callApi(req, `/api/v1/admin/ips?${req.query}`)
        .then(r => r.json());
    res.render('ips', { user: req.session, data });
});

That's the pattern in 30 lines. The current PHP UI is the same shape, just longer because it does form rendering and CSRF too.

(b) SPA + thin BFF

Browser SPA (Vue / React / Svelte) for rendering; a thin BFF for auth only. The BFF mints short-lived signed cookies the SPA presents on each request to the api. The SPA itself never sees the service token.

When to choose this:

• You want the snappy navigation and component reuse of an SPA.
• Your auth is OIDC and you don't want to put OIDC logic in the browser.
• You're OK with one server process whose only job is auth.

When not to choose this:

• You want a thinner stack — pattern (a) does the same job with one process and one render path.

Trade-offs to think through:

• The BFF still needs CSRF / cross-site protections for the cookie.
• Bearer-style headers between SPA and BFF are easier than cookies if you'll terminate at a single hostname.
• The SPA can call the api directly, with the BFF's signed token acting as a translation layer that converts cookie → service token
  • impersonation header.

(c) Direct API access (native / mobile / SPA without BFF)

This is what you'd want for a desktop client (Tauri, Electron) or a mobile app where there's no server. The user authenticates against the api directly, and the api issues a user-bound token that the client carries.

This needs api work first. The user-token issuance flow doesn't exist today. See auth-flows.md for the sketched extension point — the recommended shape is a new /api/v1/auth/oauth/* group that mints kind=user tokens after an OIDC pass-through or device-code flow.

Don't try to give the SPA a service token. The service token can impersonate any user; if it leaks to a browser or a native binary, your audit trail becomes worthless and an attacker has full admin without ever touching a real account.

Minimum API surface

A fully-featured frontend uses about 25 endpoints. Checklist (canonical shapes are in OpenAPI):

Identity

• GET /api/v1/admin/me
• POST /api/v1/auth/users/upsert-oidc (BFF)
• POST /api/v1/auth/users/upsert-local (BFF, only if local admin enabled)

IPs

• GET /api/v1/admin/ips
• GET /api/v1/admin/ips/countries
• GET /api/v1/admin/ips/{ip}

Stats

• GET /api/v1/admin/stats/dashboard

Manual blocks / allowlist

• GET / POST /api/v1/admin/manual-blocks
• GET / DELETE /api/v1/admin/manual-blocks/{id}
• GET / POST /api/v1/admin/allowlist
• GET / DELETE /api/v1/admin/allowlist/{id}

Reporters / consumers / tokens

• GET / POST /api/v1/admin/reporters (and /{id} PATCH/DELETE)
• GET / POST /api/v1/admin/consumers (and /{id} PATCH/DELETE)
• GET / POST /api/v1/admin/tokens (and /{id} DELETE)

Categories / policies

• GET / POST / PATCH / DELETE /api/v1/admin/categories[/{id}]
• GET / POST / PATCH / DELETE /api/v1/admin/policies[/{id}]
• GET /api/v1/admin/policies/{id}/preview

Audit / settings

• GET /api/v1/admin/audit-log
• GET /api/v1/admin/jobs/status
• POST /api/v1/admin/jobs/trigger/{name}
• GET /api/v1/admin/config

A simpler "viewer-only" frontend can skip every write endpoint. The api enforces RBAC server-side, so a frontend that hides the buttons is doing cosmetic work — the api will reject unauthorized calls regardless.

CORS

For BFF patterns (a) — server-to-server calls — CORS doesn't apply.

For SPA patterns (b) and (c) — browser-direct calls to the api — configure the api with the right UI_ORIGIN:

# api .env
UI_ORIGIN=https://reputation.example.com

The api emits Access-Control-Allow-Origin: <UI_ORIGIN>, Access-Control-Allow-Credentials: true, and includes X-Acting-User-Id in the allow-list. Multiple origins aren't supported in v1; if you need that, deploy multiple api replicas with different UI_ORIGIN values, or front them with a reverse proxy that adjusts the header.

Local development

Spin up only the api and a fresh SQLite, point your frontend dev server at it:

docker compose up -d migrate api
# api is now reachable at http://localhost:8081

# Generate an admin token to bypass the BFF locally:
docker compose exec -T api php bin/console auth:create-token \
    --kind=admin --role=admin --quiet
# Use this in your frontend's dev server as IRDB_API_TOKEN.

# Run your frontend dev server:
API_BASE_URL=http://localhost:8081 npm run dev

For SPA-with-BFF patterns, run the BFF as a separate process. For direct-API patterns (when that's built), point the OIDC redirect URI at your dev frontend's URL.

Migration path

To swap the current UI with a new one without downtime:

1. Build the new container image; expose it on a different port.
2. Stand it up alongside ui in compose with its own healthcheck.
3. At the reverse proxy / DNS level, switch the hostname (reputation.example.com) from old → new.
4. Once the new UI is verified, scale the old one to zero or remove it from compose.

The api doesn't notice. Sessions belong to whichever UI the user hits, so users will be asked to log in again on the new UI — that's the only externally-visible side-effect of the swap.

What NOT to do

• Don't replicate business logic in the frontend. Scoring, decay, RBAC checks, manual-block CIDR containment — all of that lives in the api. The frontend just renders what the api returns and forwards what the user types.
• Don't store user data in the frontend's storage. The session knows user_id, display_name, role. Anything else (their manual-block list, their allowlist) is the api's data; ask for it on each render.
• Don't bypass the service-token pattern by giving the SPA the service token directly. Pattern (c) needs the user-token flow built first; pattern (b) needs a BFF that mints short-lived cookies. Both are above zero work — but skipping that work means the audit trail no longer attributes actions to humans.
• Don't rely on UI route paths or template names. The current /app/* paths exist because the PHP UI happens to use them. A Vue SPA might use /dashboard, /ips, etc.; both are fine.
• Don't add custom auth headers. The api accepts exactly Authorization: Bearer … and (for service tokens) X-Acting-User-Id: …. Anything else is ignored.
• Don't try to talk to /internal/jobs/* from the frontend. Those routes are RFC1918 + loopback bound and authenticated with the internal job token. They will return 404 from any external-looking IP. The public path for triggering a job is POST /api/v1/admin/jobs/trigger/{name}.

See also

• api-overview.md — base URL, auth summary, conventions, worked curl examples.
• auth-flows.md — every auth path in detail; the future user-token sketch is here.
• architecture.md — system overview, container topology, stable-vs-replaceable surfaces.
• /api/docs — interactive OpenAPI viewer.