@velora-cms/server 0.11.0

package/dist/auth/rate-limit.js

@@ -0,0 +1,283 @@
+import { hashApiKey, isApiKeyHashValid } from "./api-keys.js";
+import { parseWindow } from "./route-rate-limits.js";
+// Same structural rule as the jwt: lane below applies here too: a rate-
+// limit bucket key must derive from something the caller cannot freely
+// mint. `vk_<random-hex>` is trivially self-mintable (it's just the
+// KEY_PREFIX plus 32 random bytes — see generateApiKey), so bucketing on
+// an unresolved token's hash would let an anonymous caller on a `public`
+// route rotate the random suffix every request, minting a fresh key:
+// bucket (its own 100/window allowance) each time — unbounded in
+// aggregate, and never rejected, since a public route never calls
+// requireApiKey. So a presented vk_ token must actually resolve to a
+// live (unrevoked) key before it earns the key: lane; anything else
+// falls back to the capped ip: lane, exactly like the jwt: lane's
+// unverifiable-token case.
+//
+// Resolving means a DB lookup (isApiKeyHashValid, the exact same query
+// requireApiKey itself uses — see api-keys.ts's findLiveApiKeyByHash).
+// So results are cached in-process, keyed by hash, for a short TTL: a
+// real key's positive result is cached too, which is what lets the
+// honest hot path — repeat calls presenting the SAME real key — mostly
+// avoid the DB. The TTL is also why a freshly-revoked key can keep
+// earning its own bucket for up to apiKeyCacheTtlMs() after revocation —
+// that does NOT grant access; requireApiKey re-checks the DB (no caching
+// there) on every request and rejects it immediately regardless of what
+// bucket the rate limiter put it in.
+//
+// IMPORTANT: this cache does NOT and cannot make a rotating-token flood
+// free. Every distinct fake vk_ token is a distinct hash, so it's a
+// guaranteed cache MISS — one DB query and, previously, one new map
+// entry, every single time, for the flood's whole duration; a positive
+// cache only pays off when a hash repeats. So a hard size ceiling
+// (MAX_API_KEY_CACHE_ENTRIES / apiKeyCacheMaxEntries() below) bounds the
+// map's memory regardless of hit rate: once at the cap, a cache MISS's
+// result is still computed and returned (the request still gets an
+// answer — a busy but correctly-behaving cache is never a reason to
+// misclassify a token), it's just not inserted, so the map can't be
+// forced to grow past the cap by an attacker who never repeats a token.
+// That does mean a sustained flood past the cap still costs one DB query
+// per request forever — the cap protects memory, not query volume; query
+// volume protection would need a different mechanism (e.g. IP-scoped
+// throttling ahead of this lookup), which is out of scope here.
+//
+// Both knobs are env-configurable and evaluated per-cache-write
+// (parsePositiveInt below, same "defensive parse, not frozen at
+// module-import time" shape as configuredMax/configuredIpMax further
+// down this file) — mainly so a test can force small values and assert
+// deterministically, rather than racing real time or filling thousands
+// of real entries.
+function apiKeyCacheTtlMs() {
+    return parsePositiveInt(process.env.VELORA_RATE_LIMIT_KEY_CACHE_TTL_MS, 30_000);
+}
+function apiKeyCacheMaxEntries() {
+    return parsePositiveInt(process.env.VELORA_RATE_LIMIT_KEY_CACHE_MAX_ENTRIES, 5_000);
+}
+const apiKeyValidityCache = new Map();
+// Opportunistic eviction (called on every cache write, not on a timer):
+// a bounded cache doesn't need a background sweep if every insert first
+// clears out anything that's already expired, so the map never holds
+// more live entries than "distinct hashes seen within the last TTL
+// window" — which keeps a MODERATE, mostly-repeating flow of traffic
+// from growing this map forever. It does NOT bound a flood of
+// never-repeating fake tokens within a single TTL window (nothing in
+// that flood expires until the TTL elapses) — that's what the hard size
+// cap above is for; the two mechanisms cover different failure shapes.
+function pruneExpiredApiKeyCacheEntries(now) {
+    for (const [hash, entry] of apiKeyValidityCache) {
+        if (entry.expiresAt <= now) {
+            apiKeyValidityCache.delete(hash);
+        }
+    }
+}
+// Test-only accessor (no production caller) so a test can pin "the cache
+// never grows past its configured cap" without reaching into
+// module-private state via a hack.
+export function apiKeyValidityCacheSizeForTests() {
+    return apiKeyValidityCache.size;
+}
+async function isVkTokenValid(token) {
+    const hash = hashApiKey(token);
+    const now = Date.now();
+    const cached = apiKeyValidityCache.get(hash);
+    if (cached && cached.expiresAt > now) {
+        return { hash, valid: cached.valid };
+    }
+    let valid;
+    try {
+        valid = await isApiKeyHashValid(hash);
+    }
+    catch {
+        // Fail safe, symmetric with the jwt: branch's catch below: a DB
+        // error here (down, pool exhausted — plausibly BY a flood the cache
+        // above is trying to blunt) must not propagate out of keyGenerator —
+        // this runs as an onRequest hook ahead of EVERY request through
+        // either rate-limited scope, including public plugin routes that may
+        // not touch the DB at all, so an uncaught throw here would 500 all
+        // of them. An unresolved-on-error token is treated exactly like an
+        // unresolved-on-miss token: capped ip: lane, never key:. Deliberately
+        // NOT cached — a transient outage isn't "this key is invalid," and
+        // caching a false negative would keep rejecting a real key for the
+        // whole TTL after the DB recovers.
+        return { hash, valid: false };
+    }
+    pruneExpiredApiKeyCacheEntries(now);
+    if (apiKeyValidityCache.size < apiKeyCacheMaxEntries()) {
+        apiKeyValidityCache.set(hash, { valid, expiresAt: now + apiKeyCacheTtlMs() });
+    }
+    return { hash, valid };
+}
+// Per-API-key rate limiting for the external surface (Session 108),
+// extended to three lanes by Session 160's public access tier. The bucket
+// key is derived from what the request actually presents:
+//   - a `vk_` bearer token that RESOLVES to a real, non-revoked key (see
+//     isVkTokenValid above) -> `key:<hash>` — a real external API-key
+//     caller. An unresolved vk_-prefixed token (unknown or revoked) is
+//     never trusted with this lane — see the comment above the cache.
+//   - any OTHER bearer token that SIGNATURE-VERIFIES as a real session JWT
+//     -> `jwt:<sub>` — a logged-in admin/editor session hitting a
+//     pluginApiRoutes catch-all, bucketed per user id (not per token
+//     string, so a token refresh doesn't mint a fresh bucket). jwtVerify()
+//     only proves a valid SESSION, not an admin role — role gating is
+//     requireAdmin's job, later; this lane exists for "not anonymous,"
+//     not "is an admin." This has to be its own lane, not folded into
+//     `ip:`, because S108's design is "admin traffic is not rate-limited"
+//     — if it shared the anonymous IP lane, every admin behind one office
+//     IP/NAT would share one small budget.
+//   - anything else (no bearer token, an unresolved vk_ token, or a
+//     bearer token that is neither `vk_`-prefixed nor a verifiable JWT —
+//     garbage, expired, forged) -> `ip:${request.ip}`. This is the
+//     security-critical branch: this function runs as `keyGenerator`, an
+//     onRequest hook that fires BEFORE requireAdmin/requireApiKey ever run
+//     (dispatch order in plugin-api-routes.ts resolves the route and its
+//     access level only after the rate limiter has already picked a
+//     bucket). If an unresolved/unverified bearer token were trusted
+//     enough to land in key: or jwt:, an anonymous caller hitting a
+//     `public` route with an arbitrary `Authorization` header would buy
+//     one of the higher-ceiling lanes and defeat the whole point of
+//     capping ip: — so a token must actually resolve/verify before
+//     anything is trusted as non-anonymous; any failure (or no token at
+//     all) falls back to the capped, anonymous ip: lane.
+//
+// Async because both isVkTokenValid (a DB lookup on cache miss) and
+// request.jwtVerify() are async; @fastify/rate-limit awaits keyGenerator
+// (its own index.js does `await params.keyGenerator(req)`), so this is a
+// supported shape, not a workaround.
+export async function rateLimitKey(request) {
+    const header = request.headers.authorization;
+    if (header?.startsWith("Bearer ")) {
+        const token = header.slice("Bearer ".length).trim();
+        if (token.startsWith("vk_")) {
+            const { hash, valid } = await isVkTokenValid(token);
+            if (valid) {
+                return `key:${hash}`;
+            }
+            return `ip:${request.ip}`;
+        }
+        try {
+            await request.jwtVerify();
+            // S160 final-fix, finding 7: jwtVerify() only proves the SIGNATURE is
+            // valid, not that the payload carries a usable `sub` — a verified
+            // token with no sub (or an empty one) would otherwise produce the
+            // literal key `jwt:undefined`, which rateLimitConfig.max grants
+            // Number.MAX_SAFE_INTEGER: the one remaining place in this lane
+            // logic where the unlimited bucket was reachable without the thing
+            // that's supposed to earn it. Access tokens always carry `sub`
+            // today, so this is a guard against a future/malformed token, not a
+            // live gap — but it's the same class of bug this file's rateLimitKey
+            // comment above already documents fixing twice for the vk_ lane.
+            const sub = request.user?.sub;
+            if (typeof sub === "string" && sub.length > 0) {
+                return `jwt:${sub}`;
+            }
+            // No usable sub — fall through to the capped ip: lane below, same as
+            // an unverifiable token.
+        }
+        catch {
+            // Unverifiable bearer token (garbage, expired, forged, wrong
+            // secret) — never trusted as a session; falls through to the
+            // capped anonymous lane below, same as presenting no token at all.
+        }
+    }
+    return `ip:${request.ip}`;
+}
+// max/timeWindow are env-configurable so an operator can tune them without
+// a code change; the defaults are a sane external-API baseline. `max` is a
+// function (the plugin's supported `(req, key) => number` form) rather than
+// a top-level `Number(process.env...)` computed once at module-import time,
+// so the value reflects the env at the moment each request is checked —
+// this module is statically imported (via app.ts) well before a test's
+// `beforeAll` gets a chance to override the env var, so a plain constant
+// would freeze in the default forever. `timeWindow` stays a plain string:
+// the plugin's function form for it must return a number of milliseconds,
+// not a duration string, and no test needs to override the window. Do NOT
+// restructure it into a function to "match" `max` — that's a deliberate,
+// documented asymmetry, not an oversight.
+//
+// Parsed defensively: an empty-string env var Numbers to 0 and a typo
+// Numbers to NaN, and this lane (like the ip: lane below) now gates real
+// traffic where a silently-adopted 0 is an outage, not a config no-op — so
+// anything that doesn't parse to a positive finite number falls back to
+// the default instead of being trusted verbatim.
+function parsePositiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+// S162 second-review fix: `timeWindow` below was still a bare `?? "1
+// minute"` — the same defect `parseWindow` (route-rate-limits.ts) was
+// written to prevent, left out of the first fix wave despite that wave's
+// own commit title ("Defend rate-limit *_WINDOW env vars the same way
+// *_MAX already is"). This is the LARGEST blast radius of any `timeWindow`
+// in the system: it's the default for every scope that doesn't override it
+// — auth (besides login), docs, plugin-api-routes, and public-api — so a
+// blank or unparseable VELORA_RATE_LIMIT_WINDOW here would 500 most of the
+// API, not just one family.
+//
+// Exported and factored out of the object literal below (rather than
+// inlined as `parseWindow(process.env.VELORA_RATE_LIMIT_WINDOW, "1
+// minute")` directly) so a test can exercise the exact parse logic
+// `rateLimitConfig.timeWindow` is built from without re-importing this
+// whole module — this module is statically imported by app.ts and pulls in
+// api-keys.ts -> db/prisma.ts, which opens a real Prisma client at
+// top-level `await`; re-importing it via vi.resetModules() to test a
+// different env value would mean standing up a second live client
+// mid-suite, which is worse than the thing being tested.
+export function resolveGlobalTimeWindow(value) {
+    return parseWindow(value, "1 minute");
+}
+function configuredMax() {
+    return parsePositiveInt(process.env.VELORA_RATE_LIMIT_MAX, 100);
+}
+// Same env-configurable, evaluated-per-request shape as configuredMax()
+// above, and for the same reason — this module is statically imported
+// well before a test's beforeAll gets a chance to override the env var.
+function configuredIpMax() {
+    return parsePositiveInt(process.env.VELORA_RATE_LIMIT_IP_MAX, 60);
+}
+export const rateLimitConfig = {
+    // Three lanes, three ceilings — rateLimitKey's doc comment explains why
+    // each bucket exists; this is why each gets the ceiling it gets:
+    //   - `key:` (a vk_ token that actually RESOLVED to a real, non-revoked
+    //     key — see isVkTokenValid) — configuredMax(), the original Session
+    //     108 external-API budget. An unresolved vk_-shaped token never
+    //     reaches this lane, so this ceiling can't be bought by minting
+    //     arbitrary vk_-prefixed strings.
+    //   - `jwt:` (a signature-verified session, bucketed per user id) — left
+    //     effectively unlimited, preserving S108's recorded intent
+    //     ("admin-session traffic is not rate-limited"). It got its own lane
+    //     specifically so it would NOT inherit the ip: ceiling below — and
+    //     rateLimitKey only ever mints a jwt: bucket after request.jwtVerify()
+    //     actually succeeds, never on the mere presence of a bearer token, so
+    //     this ceiling can't be bought with a forged/garbage header. (This
+    //     lane is about "logged in," not "admin" — role gating still happens
+    //     downstream in requireAdmin.)
+    //   - `ip:` (no credentials at all, an unresolved/unknown/revoked vk_
+    //     token, or a bearer token that failed verification) —
+    //     configuredIpMax(). Used to be effectively unlimited too, back when
+    //     un-keyed traffic could only ever BE an admin session hitting a
+    //     pluginApiRoutes catch-all with no vk_ bearer token. Session 160's
+    //     "public" access tier broke that premise: genuinely anonymous,
+    //     un-credentialed browser traffic (e.g. a contact-form submission)
+    //     now lands here too, so this lane gets a real, deliberately
+    //     tighter ceiling instead.
+    max: (_req, key) => {
+        if (key.startsWith("key:"))
+            return configuredMax();
+        if (key.startsWith("jwt:"))
+            return Number.MAX_SAFE_INTEGER;
+        return configuredIpMax();
+    },
+    timeWindow: resolveGlobalTimeWindow(process.env.VELORA_RATE_LIMIT_WINDOW),
+    keyGenerator: rateLimitKey,
+    // Return the codebase's uniform { message } error body (ApiErrorSchema
+    // shape) instead of the plugin's default; Retry-After is set by the
+    // plugin automatically. The plugin `throw`s whatever this returns
+    // (index.js: `throw params.errorResponseBuilder(req, respCtx)`) and
+    // Fastify's default error handler replies using `error.statusCode`, so
+    // `statusCode` must be carried through on the returned object — without
+    // it every rate-limited request would 500 instead of 429 (or 403 for a
+    // ban, hence reusing context.statusCode rather than hardcoding 429).
+    errorResponseBuilder: (_request, context) => ({
+        statusCode: context.statusCode,
+        message: `Rate limit exceeded, retry in ${context.after}`,
+    }),
+};

package/dist/auth/require-auth.d.ts

@@ -0,0 +1,4 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import "./jwt-payload.js";
+export declare function requireAuth(request: FastifyRequest, reply: FastifyReply): Promise<void>;
+export declare function requireAdmin(request: FastifyRequest, reply: FastifyReply): Promise<void>;

package/dist/auth/require-auth.js

@@ -0,0 +1,28 @@
+import "./jwt-payload.js";
+// onRequest hook, not preHandler: Fastify validates the body before
+// preHandler runs, so a preHandler auth check would answer unauthenticated
+// requests with validation 400s instead of a 401.
+export async function requireAuth(request, reply) {
+    try {
+        await request.jwtVerify();
+    }
+    catch {
+        await reply.code(401).send({ message: "Authentication required" });
+    }
+}
+// Role gate on top of requireAuth. The role rides in the JWT — good for
+// 15 minutes (the access token TTL), so a demotion takes effect on the
+// next token refresh, not instantly. Acceptable for v0.1; revisit if
+// instant revocation ever matters.
+export async function requireAdmin(request, reply) {
+    try {
+        await request.jwtVerify();
+    }
+    catch {
+        await reply.code(401).send({ message: "Authentication required" });
+        return;
+    }
+    if (request.user.role !== "admin") {
+        await reply.code(403).send({ message: "Admin role required" });
+    }
+}

package/dist/auth/route-rate-limits.d.ts

@@ -0,0 +1,31 @@
+import type { FastifyRequest } from "fastify";
+export declare function parseWindow(value: string | undefined, fallback: string): string;
+export declare const LOGIN_RATE_LIMIT: {
+    max: () => number;
+    timeWindow: () => string;
+};
+export declare const SETUP_RATE_LIMIT: {
+    max: () => number;
+    timeWindow: () => string;
+};
+export declare const DOCS_RATE_LIMIT: {
+    max: () => number;
+    timeWindow: () => string;
+};
+export declare const ADMIN_RATE_LIMIT: {
+    max: () => number;
+    timeWindow: () => string;
+};
+export declare function ipOnlyKeyGenerator(request: FastifyRequest): Promise<string>;
+export declare function ipOnlyRateLimitConfig(): {
+    max: number;
+    timeWindow: string;
+    keyGenerator: typeof ipOnlyKeyGenerator;
+    errorResponseBuilder: (request: FastifyRequest, context: {
+        after: string;
+        statusCode: number;
+    }) => {
+        statusCode: number;
+        message: string;
+    };
+};

package/dist/auth/route-rate-limits.js

@@ -0,0 +1,155 @@
+import { parse as parseMs } from "@lukeed/ms";
+// S162: per-family ceilings for the public route families that had none.
+// The shared three-lane rateLimitConfig (auth/rate-limit.ts) stays the
+// default for everything else; these are overrides for routes whose
+// economics differ from a generic API call.
+//
+// Same "parse at call time, not at import time" shape as rate-limit.ts's
+// configuredMax/configuredIpMax, and for the same reason: this module is
+// statically imported well before a test's beforeAll can set an env var,
+// so a plain constant would freeze the default in forever.
+function parsePositiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+// S162 final review, I3: `max` was defended by parsePositiveInt above, but
+// every `timeWindow` read was a bare `?? "fallback"`, and `??` does not
+// catch the empty string. @fastify/rate-limit hands whatever string this
+// returns straight to @lukeed/ms's own `parse()` (mergeParams takes the
+// `typeof === 'string'` branch without re-checking it parses), and an
+// unparseable value (blank, a typo, anything parse() can't match) becomes
+// `undefined` — which applyRateLimit then calls as a function, OUTSIDE its
+// try/catch, 500ing the whole scope. A blank
+// VELORA_RATE_LIMIT_LOGIN_WINDOW would mean nobody can log in, silently.
+// Running the candidate through the SAME parser @fastify/rate-limit will
+// use (rather than guessing at what looks like a duration) is what makes
+// this defensible: anything parse() can't turn into a positive number of
+// milliseconds falls back, exactly like a bad `max` value does above.
+// Exported so rate-limit.ts's shared, three-lane rateLimitConfig can defend
+// its own `timeWindow` (the biggest blast radius of all — it governs the
+// auth, docs, plugin-api-routes and public-api scopes) with the exact same
+// parser, rather than duplicating this logic or leaving it undefended.
+export function parseWindow(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = parseMs(value);
+    return typeof parsed === "number" && parsed > 0 ? value : fallback;
+}
+// Deliberately the tightest ceiling in the system. POST /api/auth/login is
+// unauthenticated and password-guessing is exactly what it invites.
+export const LOGIN_RATE_LIMIT = {
+    max: () => parsePositiveInt(process.env.VELORA_RATE_LIMIT_LOGIN, 10),
+    timeWindow: () => parseWindow(process.env.VELORA_RATE_LIMIT_LOGIN_WINDOW, "15 minutes"),
+};
+// Runs once per install, and 409s outright on an already-configured
+// instance (S151). The ceiling makes the pre-configuration window
+// uninteresting to probe.
+export const SETUP_RATE_LIMIT = {
+    max: () => parsePositiveInt(process.env.VELORA_RATE_LIMIT_SETUP, 5),
+    timeWindow: () => parseWindow(process.env.VELORA_RATE_LIMIT_SETUP_WINDOW, "1 hour"),
+};
+// Static-ish reads. Generous, but not unbounded.
+export const DOCS_RATE_LIMIT = {
+    max: () => parsePositiveInt(process.env.VELORA_RATE_LIMIT_DOCS, 120),
+    timeWindow: () => parseWindow(process.env.VELORA_RATE_LIMIT_DOCS_WINDOW, "1 minute"),
+};
+// The admin SPA's static bundle at /velora (S184) — same reasoning and
+// defaults as the docs bundle above. admin-static.ts applies this lane
+// PLUGIN-LEVEL (the limiter registered on its encapsulated scope with
+// these values), because @fastify/static's generated asset routes carry
+// no per-route config slot — so EVERYTHING under /velora, hashed assets
+// included, buckets on this lane, per IP. Do not "restore" per-route
+// config there: it cannot reach the asset routes and would silently drop
+// them to the generic IP lane (a cold SPA load could 429 the login).
+export const ADMIN_RATE_LIMIT = {
+    max: () => parsePositiveInt(process.env.VELORA_RATE_LIMIT_ADMIN, 120),
+    timeWindow: () => parseWindow(process.env.VELORA_RATE_LIMIT_ADMIN_WINDOW, "1 minute"),
+};
+// The shared rateLimitKey puts a VERIFIED JWT into the jwt: lane, which is
+// Number.MAX_SAFE_INTEGER — effectively unlimited. Login must never inherit
+// that, or anyone holding one valid session could brute-force passwords
+// without limit simply by attaching their own token. So login buckets on IP
+// and nothing else.
+//
+// And on IP ONLY — never the submitted email. A per-email bucket would let
+// an attacker distinguish real accounts from fake ones by watching which
+// addresses start returning 429, turning the limiter itself into an
+// account-existence oracle. Same discipline as S160's honeypot: the
+// observable response must not vary with whether the subject exists.
+//
+// Shared beyond login as of S162's I6 fix: the setup scope (setup.ts)
+// reuses this same generator for the same reason — no API keys or JWT
+// sessions exist to lane there either, so IP-alone is the only sound key.
+// The key prefix dropped "login-" accordingly now that it's not login-
+// specific.
+//
+// That change means this generator now mints the literal string `ip:<addr>`
+// for both login and setup — the same literal rate-limit.ts's own
+// three-lane rateLimitKey mints for its unauthenticated fallback lane. That
+// collision is safe, not accidental-looking-safe: `@fastify/rate-limit`
+// registers a fresh `LocalStore` per scope it's registered on
+// (`LocalStore.child()`), so a bucket key is only ever compared against
+// other keys within the SAME scope's store. Login (auth.ts) and setup
+// (setup.ts) are different registered scopes from each other and from
+// every other route family, so two identical `ip:1.2.3.4` strings in
+// different scopes address entirely separate maps — same key text, disjoint
+// storage, no shared budget.
+export async function ipOnlyKeyGenerator(request) {
+    return `ip:${request.ip}`;
+}
+// S162 final review, I6: setup.ts used to register the full three-lane
+// rateLimitConfig (auth/rate-limit.ts) for its scope, which imports
+// auth/api-keys.ts, which imports db/prisma.ts — a module with a
+// top-level `await loadPrismaClient(...)`. That drags Prisma into the
+// setup-only boot path (setup-app.ts's buildSetupOnlyApp), which is
+// documented as never touching it, and which runs precisely when no
+// database is configured yet — so an unconfigured VELORA_PRISMA_CLIENT_DIR
+// pointing at a not-yet-generated client would throw at import time and
+// prevent that boot path from starting at all.
+//
+// Setup has no API keys and no JWT sessions to lane in the first place —
+// the three-lane generator buys it nothing. This is the plain IP-keyed
+// equivalent, kept in this file (not auth/rate-limit.ts) so importing it
+// can never pull Prisma in transitively.
+// S165 audit fix: unlike LOGIN/SETUP/DOCS_RATE_LIMIT above, this config isn't
+// dereferenced by a caller that calls `.timeWindow()` before handing a value
+// to the plugin — setup.ts registers the WHOLE object directly as
+// `@fastify/rate-limit`'s plugin options. That plugin's `timeWindow` option
+// only accepts a plain string/number, or a function called as
+// `timeWindow(req, key)` that itself must RETURN a number of milliseconds
+// (see rateLimitConfig's own comment in rate-limit.ts for the full type). A
+// zero-argument function returning a duration STRING — what this used to be
+// — is neither: tsc rejects the assignment, and at runtime the plugin would
+// take the function branch, call it as `timeWindow(req, key)`, and get
+// `"1 minute"` back where it expects a number.
+//
+// Turned into a builder, called at the exact point of registration
+// (setup.ts's `ipOnlyRateLimitConfig()`), so the env is still read at
+// registration time rather than frozen at this module's import — this
+// module is statically imported well before a test's beforeEach can set an
+// env var, same reasoning as parsePositiveInt's own comment above. Both
+// fields are now plain values (a number and a string, both parsed exactly
+// once per call) because nothing downstream needs to defer past that one
+// read: `max`'s only reason to be a function elsewhere in this file is so a
+// caller can re-invoke it at its own use site, and nothing calls this
+// builder's returned `max` more than once per registration either.
+export function ipOnlyRateLimitConfig() {
+    return {
+        max: parsePositiveInt(process.env.VELORA_RATE_LIMIT_IP_MAX, 60),
+        // S162 second-review fix, preserved through the S165 reshape: this was
+        // once a bare `?? "1 minute"`, the exact bug parseWindow (above) exists
+        // to prevent. A blank VELORA_RATE_LIMIT_WINDOW would 500 every route in
+        // the setup scope (/api/setup/status, /api/setup/complete), the one
+        // boot path with no other way in on a fresh install.
+        timeWindow: parseWindow(process.env.VELORA_RATE_LIMIT_WINDOW, "1 minute"),
+        keyGenerator: ipOnlyKeyGenerator,
+        // Same error-response contract as auth/rate-limit.ts's rateLimitConfig
+        // (statusCode carried through so Fastify's default error handler
+        // answers 429 instead of 500 — see that file's comment) — duplicated
+        // rather than imported, for the same Prisma-avoidance reason as above.
+        errorResponseBuilder: (_request, context) => ({
+            statusCode: context.statusCode,
+            message: `Rate limit exceeded, retry in ${context.after}`,
+        }),
+    };
+}

package/dist/auth/tokens.d.ts

@@ -0,0 +1,15 @@
+export declare const ACCESS_TOKEN_TTL = "15m";
+export declare const REFRESH_TOKEN_TTL_DAYS = 30;
+export declare const REFRESH_COOKIE_NAME = "velora_refresh";
+export declare function refreshCookieOptions(): {
+    httpOnly: true;
+    secure: boolean;
+    sameSite: "lax";
+    path: string;
+    maxAge: number;
+};
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, passwordHash: string): Promise<boolean>;
+export declare function generateRefreshToken(): string;
+export declare function hashRefreshToken(token: string): string;
+export declare function refreshTokenExpiryDate(): Date;

package/dist/auth/tokens.js

@@ -0,0 +1,38 @@
+import { randomBytes, createHash } from "node:crypto";
+import bcrypt from "bcrypt";
+const BCRYPT_SALT_ROUNDS = 12;
+export const ACCESS_TOKEN_TTL = "15m";
+export const REFRESH_TOKEN_TTL_DAYS = 30;
+export const REFRESH_COOKIE_NAME = "velora_refresh";
+// httpOnly so the refresh token is never reachable from JS (removes the
+// XSS-theft risk the old in-memory-only approach was accepting); scoped to
+// the auth path only, since no other route needs it; sameSite: 'lax' is
+// enough CSRF protection here — it isn't sent on cross-site POSTs, only on
+// top-level GET navigations, and every route that reads it is a POST.
+export function refreshCookieOptions() {
+    return {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === "production",
+        sameSite: "lax",
+        path: "/api/auth",
+        maxAge: REFRESH_TOKEN_TTL_DAYS * 24 * 60 * 60,
+    };
+}
+export function hashPassword(password) {
+    return bcrypt.hash(password, BCRYPT_SALT_ROUNDS);
+}
+export function verifyPassword(password, passwordHash) {
+    return bcrypt.compare(password, passwordHash);
+}
+// Refresh tokens are high-entropy random values, not user-chosen secrets,
+// so a fast hash is appropriate here — unlike passwords, there's no
+// dictionary/brute-force risk to slow down with bcrypt.
+export function generateRefreshToken() {
+    return randomBytes(32).toString("hex");
+}
+export function hashRefreshToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+export function refreshTokenExpiryDate() {
+    return new Date(Date.now() + REFRESH_TOKEN_TTL_DAYS * 24 * 60 * 60 * 1000);
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./index.js";

package/dist/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The `velora-server` command: identical to `node dist/index.js` — index.js
+// is the boot entry (env load → client self-heal → core migrations → mode
+// → app). Kept as a wrapper so the boot file stays importable-free of
+// shebang concerns.
+import "./index.js";

package/dist/boot/core-migration-gate.d.ts

@@ -0,0 +1,12 @@
+import type { BootMode } from "./resolve-boot-mode.js";
+export type CoreMigrationGate = {
+    action: "refuse";
+    message: string;
+} | {
+    action: "log";
+    message: string;
+} | {
+    action: "none";
+};
+export type CoreMigrationPhase = "client-generation" | "core-migrations";
+export declare function judgeCoreMigrationFailure(error: unknown, mode: BootMode, phase: CoreMigrationPhase): CoreMigrationGate;

package/dist/boot/core-migration-gate.js

@@ -0,0 +1,52 @@
+// Two independent phrasings per phase, matched to how each already reads
+// in its sentence: the refuse message says "Refusing to start: <refuse
+// clause> against DATABASE_URL (…)"; the log message is its own sentence,
+// "<log clause> (…) — continuing into setup." Keeping them as separate
+// strings (rather than deriving one from the other) avoids grammar that
+// only happens to work for one phase.
+const PHASE_WORDING = {
+    "client-generation": {
+        refuseClause: "Prisma client generation failed",
+        logClause: "Prisma client generation did not succeed yet",
+    },
+    "core-migrations": {
+        refuseClause: "core migrations could not run",
+        logClause: "Core migrations did not run yet",
+    },
+};
+// The actual decision: given whatever error (if any) was captured while
+// preparing the Prisma-owned schema, and the boot mode that was
+// subsequently resolved, what should index.ts do about it?
+//
+// "full" means DATABASE_URL is configured AND an admin already exists —
+// this is the one mode where a broken/un-migrated schema must not be
+// allowed to boot silently, so it ALWAYS refuses on any error. This is the
+// never-boot-un-migrated invariant, and core-migration-gate.test.ts pins
+// it: no future edit here may make "full" tolerate an error, no matter
+// what phase or error shape is added later.
+//
+// The setup-* modes never refuse — a missing table or missing database is
+// the expected reason they were selected in the first place (see
+// resolve-boot-mode.ts's own header) — they get at most one quiet log
+// line, not a raw stack.
+//
+// No captured error at all (the normal case — self-heal and migrations
+// both succeeded, or index.ts never even attempted them because
+// DATABASE_URL was unset) means there is nothing to decide: "none".
+export function judgeCoreMigrationFailure(error, mode, phase) {
+    if (error === undefined)
+        return { action: "none" };
+    const causeMessage = error instanceof Error ? error.message : String(error);
+    const wording = PHASE_WORDING[phase];
+    if (mode === "full") {
+        return {
+            action: "refuse",
+            message: `Refusing to start: ${wording.refuseClause} against DATABASE_URL (${causeMessage}). ` +
+                "Fix the database (or unset DATABASE_URL to re-enter setup) and start again.",
+        };
+    }
+    return {
+        action: "log",
+        message: `${wording.logClause} (${causeMessage}) — continuing into setup.`,
+    };
+}

package/dist/boot/resolve-boot-mode.d.ts

@@ -0,0 +1,6 @@
+export type BootMode = "setup-full" | "setup-admin-only" | "full";
+export declare const ADMIN_PROBE_TIMEOUT_MS = 10000;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+export declare function resolveBootMode(env: NodeJS.ProcessEnv, countAdmins: () => Promise<number>): Promise<BootMode>;
+export declare function describeDatabaseUrlShape(url: string | undefined): string;
+export declare function countAdminUsers(): Promise<number>;