wood-fired-tasks 1.12.0

package/dist/api/plugins/auth/index.js

@@ -0,0 +1,300 @@
+import fp from 'fastify-plugin';
+import { parseApiKeyEntries, config, } from '../../../config/env.js';
+import { validateApiKeysForProduction } from './keys.js';
+import { logAuthFailure, } from '../../../services/auth-audit.js';
+import { tryAuth as tryPat } from './strategies/pat.js';
+import { tryAuth as trySession } from './strategies/session.js';
+import { tryAuth as tryLegacy, precomputeHashedEntries, } from './strategies/legacy.js';
+import { shouldTouchLastUsed } from '../../../services/pat-touch-debounce.js';
+/**
+ * Throws if `preHandler` has not run yet (or if `skipAuth` was set). Use in
+ * route handlers / tool helpers that need a non-null `request.user`. The
+ * type narrowing is the entire point — once `requireUser` returns, the
+ * caller has an `AuthenticatedUser` without further null checks.
+ *
+ * CR-01 (Phase 30 review) — belt-and-suspenders: check for BOTH `null`
+ * (the initialized default via `decorateRequest('user', null)`) AND
+ * `undefined` (the value the slot holds when the route was registered
+ * OUTSIDE any scope that ran the auth-chain plugin — e.g. a top-level
+ * device-flow route mounted as a sibling of the `/api/v1` scope). The
+ * scope-wiring fix in server.ts addresses the production wiring, but
+ * leaving the guard narrow would silently re-open the bug if a future
+ * refactor moved a sessionOnly route outside the chain again.
+ */
+export function requireUser(request) {
+    if (request.user === null || request.user === undefined) {
+        throw new Error('requireUser: request.user is null/undefined — auth preHandler did ' +
+            'not run, or the route is registered with config.skipAuth=true, ' +
+            'or the route is outside any scope that registered the auth chain.');
+    }
+    return request.user;
+}
+/**
+ * Apply a successful strategy outcome to the request: populate principal
+ * slots, then re-child the request logger so every subsequent
+ * `request.log.*()` call carries audit fields.
+ *
+ * `apiKeyLabel` is passed through into the bindings even on non-legacy paths
+ * (where it stays `undefined`). This matches the codebase precedent at
+ * the pre-split auth.ts:215-216 and the RESEARCH §8 pattern.
+ */
+function applyPrincipal(request, result, apiKeyLabel) {
+    request.user = result.user;
+    request.authMethod = result.authMethod;
+    request.tokenId = result.tokenId;
+    if (apiKeyLabel !== undefined) {
+        request.apiKeyLabel = apiKeyLabel;
+    }
+    request.log = request.log.child({
+        user_id: result.user.id,
+        token_id: result.tokenId,
+        auth_method: result.authMethod,
+        apiKeyLabel: request.apiKeyLabel,
+    });
+}
+/**
+ * Post-auth gate: if the matched route declares `config.sessionOnly: true`
+ * AND the active auth method is NOT 'session', return 403. This is the only
+ * place "PATs cannot mint PATs" is enforced — Plan 5 registers the
+ * `/me/tokens` routes with the flag set.
+ *
+ * Returns `true` when the gate fired and the reply has been sent; the caller
+ * MUST stop processing.
+ */
+function enforceSessionOnly(request, reply) {
+    if (request.routeOptions.config.sessionOnly === true &&
+        request.authMethod !== 'session') {
+        reply.code(403).send({
+            error: 'session_required',
+            message: 'This endpoint cannot be called with a Personal Access Token.',
+        });
+        return true;
+    }
+    return false;
+}
+/**
+ * Schedule the best-effort `last_used_at` update for a freshly-matched PAT.
+ *
+ * Plan 28-06 gates the write through the in-process debounce module
+ * (`pat-touch-debounce.ts`) so each token id triggers at most one SQL UPDATE
+ * per 10-minute window — satisfying REQUIREMENTS.md PAT-03's
+ * "≤ 1 write / 10 min / token" cap. No-op for non-PAT matches
+ * (tokenId === null) or when the gate returns `false` (recent write within
+ * window).
+ *
+ * better-sqlite3 is synchronous, so `touchLastUsed` returns `void` — wrap in
+ * try/catch (no `.catch(...)` on a void return). Errors are warn-logged but
+ * NEVER bubble up.
+ */
+function scheduleLastUsedTouch(fastify, tokenId, log) {
+    if (tokenId === null)
+        return;
+    if (!shouldTouchLastUsed(tokenId))
+        return;
+    setImmediate(() => {
+        try {
+            fastify.apiTokenRepository.touchLastUsed(tokenId);
+        }
+        catch (err) {
+            log.warn({ err, tokenId }, 'touchLastUsed failed');
+        }
+    });
+}
+/**
+ * Send a uniform 401 response after emitting the categorical audit log.
+ *
+ * Returns `void` so callers `return sendUnauthorized(...)` cleanly from the
+ * preHandler hook. The body is intentionally minimal — Threat T-28-04-02
+ * keeps `reasonCode` off the wire so callers can't probe distinct failure
+ * modes.
+ */
+function sendUnauthorized(request, reply, strategy, reasonCode) {
+    logAuthFailure(request.log, {
+        strategy,
+        reasonCode,
+        requestId: request.id,
+        peerIp: request.ip,
+    });
+    reply.code(401).send({
+        error: 'UNAUTHORIZED',
+        message: 'Authentication required',
+    });
+}
+/**
+ * Strategy chain threw (DB locked, connection lost, prepared-statement
+ * compile error from a runtime migration, etc.). Surface as a categorical
+ * 500 — explicitly NOT a 401, because pretending auth failed would
+ * mis-route operators and make a degraded DB indistinguishable from a
+ * brute-force probe. Two log lines:
+ *
+ *   1. `auth.error` (request.log.error) — carries the underlying `err`
+ *      object for postmortem.
+ *   2. `auth.failure` warn line via logAuthFailure — keeps the audit feed
+ *      aware that an authentication attempt did NOT succeed during the
+ *      outage window. Reuses the Phase 27 AuthFailureReason enum
+ *      ('unknown_token') so we don't widen the enum just to carry an
+ *      operational signal; the `auth.error` line above is where the
+ *      diagnostics live.
+ *
+ * Response body is `{ error: 'INTERNAL_ERROR' }` — no `reasonCode`, no
+ * stack, no token-shaped data. Threat T-28-04-02 still applies.
+ *
+ * WR-01 (Phase 28 review).
+ */
+function sendInternalError(request, reply, err) {
+    request.log.error({ err, requestId: request.id }, 'auth.error');
+    logAuthFailure(request.log, {
+        strategy: 'legacy',
+        reasonCode: 'unknown_token',
+        requestId: request.id,
+        peerIp: request.ip,
+    });
+    reply.code(500).send({ error: 'INTERNAL_ERROR' });
+}
+const authChainImpl = async (fastify) => {
+    // Parse and (in production) validate API_KEYS at register time so a
+    // misconfigured prod boot fails fast. Same fail-fast semantics as the
+    // pre-split plugin — `validateApiKeysForProduction` throws synchronously
+    // and Fastify bubbles the error up to createServer which closes the
+    // server and disposes the App (server.ts:345-363 catch).
+    const entries = parseApiKeyEntries(process.env.API_KEYS);
+    const keys = entries.map((e) => e.key);
+    if (process.env.NODE_ENV === 'production') {
+        validateApiKeysForProduction(keys);
+    }
+    else if (entries.length === 0) {
+        fastify.log.warn('No API keys configured in API_KEYS env var. All API requests will be rejected.');
+    }
+    const hashedEntries = precomputeHashedEntries(entries);
+    // Decorators MUST land before any route registers in this scope. The fp()
+    // wrap below lifts these into the parent scope so sibling /api/v1/* routes
+    // see populated slots after a successful preHandler run.
+    fastify.decorateRequest('user', null);
+    fastify.decorateRequest('authMethod', null);
+    fastify.decorateRequest('tokenId', null);
+    // MIGR-01 compat: `apiKeyLabel` decoration retained so existing
+    // routes/tests (events.ts SSE fingerprinting, auth-logging.test.ts) keep
+    // working. Default `undefined` matches the pre-split contract.
+    fastify.decorateRequest('apiKeyLabel', undefined);
+    const patDeps = {
+        apiTokenRepository: fastify.apiTokenRepository,
+        userRepository: fastify.userRepository,
+    };
+    fastify.addHook('preHandler', async (request, reply) => {
+        // 0. Route-level skipAuth opt-out (defined but unused in Phase 28 —
+        // Plan 4 ships the flag for future Phase 29 /auth/login etc.).
+        if (request.routeOptions.config.skipAuth === true) {
+            return;
+        }
+        // WR-01 (Phase 28 review) — wrap the entire chain walk so that a
+        // throwing strategy (e.g. `apiTokenRepository.findByHash` raising
+        // because the DB is locked) becomes a categorical 500 with an
+        // `auth.error` log AND an `auth.failure` audit line, rather than
+        // a generic Fastify 500 that the audit aggregator never sees. We
+        // deliberately do NOT downgrade to 401 — a degraded DB should not
+        // look like a brute-force probe.
+        try {
+            // 1. PAT
+            const patOutcome = await tryPat(request, patDeps);
+            if (patOutcome.kind === 'fail') {
+                return sendUnauthorized(request, reply, 'pat', patOutcome.reasonCode);
+            }
+            if (patOutcome.kind === 'match') {
+                applyPrincipal(request, patOutcome.result);
+                scheduleLastUsedTouch(fastify, patOutcome.result.tokenId, request.log);
+                if (enforceSessionOnly(request, reply))
+                    return;
+                return;
+            }
+            // 2. Session (Phase 29 — real implementation reads
+            // request.session.get('user') and re-validates against
+            // userRepository.findById; returns 'skip' when no session backend
+            // is registered (OIDC-disabled mode) so the legacy strategy still
+            // gets a chance.
+            const sessionOutcome = await trySession(request, {
+                userRepository: fastify.userRepository,
+            });
+            if (sessionOutcome.kind === 'fail') {
+                // Defensive — Phase 28 stub never returns fail. Keep the branch so
+                // Phase 29's swap doesn't need to add it.
+                return sendUnauthorized(request, reply, 'session', sessionOutcome.reasonCode);
+            }
+            if (sessionOutcome.kind === 'match') {
+                applyPrincipal(request, sessionOutcome.result);
+                if (enforceSessionOnly(request, reply))
+                    return;
+                return;
+            }
+            // 3. Legacy API_KEYS
+            const legacyOutcome = await tryLegacy(request, {
+                userRepository: fastify.userRepository,
+                hashedEntries,
+            });
+            if (legacyOutcome.kind === 'fail') {
+                return sendUnauthorized(request, reply, 'legacy', legacyOutcome.reasonCode);
+            }
+            if (legacyOutcome.kind === 'match') {
+                applyPrincipal(request, legacyOutcome.result, legacyOutcome.label);
+                // Plan 31-05 (MIGR-02): emit one warn log per legacy-authed request
+                // so operators can grep their log feed for sunset-readiness reporting
+                // (`event: 'legacy_auth_used'`). The onSend hook below stamps the
+                // RFC 8594 Deprecation/Sunset headers; this line is the canonical
+                // audit signal — the headers are advisory to the client, the log
+                // is the operator-side source of truth.
+                request.log.warn({
+                    event: 'legacy_auth_used',
+                    userId: legacyOutcome.result.user.id,
+                    apiKeyLabel: legacyOutcome.label,
+                    requestId: request.id,
+                    requestUrl: request.url,
+                    sunset: config.LEGACY_AUTH_SUNSET_DATE,
+                }, 'legacy_auth_used');
+                if (enforceSessionOnly(request, reply))
+                    return;
+                return;
+            }
+            // 4. Catch-all — no strategy saw a credential. Per Plan-04 Decision
+            // Q6, the audit log records `strategy: 'legacy', reasonCode:
+            // 'missing_credential'` so the failure mode matches the pre-split
+            // plugin's "missing X-API-Key" branch.
+            return sendUnauthorized(request, reply, 'legacy', 'missing_credential');
+        }
+        catch (err) {
+            return sendInternalError(request, reply, err);
+        }
+    });
+    // Plan 31-05 (MIGR-02): RFC 8594 Deprecation + Sunset response headers
+    // for every legacy-X-API-Key-authed request. Gated strictly on
+    // `request.authMethod === 'legacy'` so PAT, session, anonymous (skipAuth),
+    // and failed-auth responses NEVER carry the headers (Pitfall 4 in
+    // 31-RESEARCH §Common Pitfalls).
+    //
+    // Callback-style (4-arg) signature is used INTENTIONALLY rather than async
+    // — registering an async onSend hook inside this fp()-wrapped plugin
+    // delays `reply.sent` from becoming true synchronously when the preHandler
+    // calls `reply.send()` (e.g. from `enforceSessionOnly`'s 403). The
+    // me-tokens session-only tests then see the route handler run after the
+    // 403 reply was queued. The synchronous callback form keeps reply.send()
+    // synchronous, preserving the Phase 28 sessionOnly invariant.
+    fastify.addHook('onSend', (request, reply, payload, done) => {
+        if (request.authMethod === 'legacy') {
+            reply.header('Deprecation', 'true');
+            reply.header('Sunset', config.LEGACY_AUTH_SUNSET_DATE);
+        }
+        done(null, payload);
+    });
+};
+/**
+ * Wrap with fastify-plugin to escape the encapsulated scope. Without `fp()`
+ * the preHandler hook only fires for routes registered INSIDE this plugin —
+ * every sibling under `/api/v1/*` would bypass auth entirely. The
+ * `{ name: 'wft-auth', fastify: '5.x' }` options match the pre-split
+ * plugin's identity so any downstream `fastify.hasPlugin('wft-auth')`
+ * checks keep working.
+ */
+const authChain = fp(authChainImpl, {
+    name: 'wft-auth',
+    fastify: '5.x',
+});
+export default authChain;
+//# sourceMappingURL=index.js.map

package/dist/api/plugins/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/plugins/auth/index.ts"],"names":[],"mappings":"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"}

package/dist/api/plugins/auth/keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SHA-256 hash of a key, returned as a 32-byte Buffer.
+ *
+ * Hashing both sides of the comparison guarantees `timingSafeEqual` receives
+ * equal-length buffers, eliminating the length-leak that arises from comparing
+ * raw keys of different lengths.
+ */
+export declare function hashKey(key: string): Buffer;
+/**
+ * Validate API keys for a production environment.
+ *
+ * Throws an Error listing every failure mode. The error message references
+ * keys by their 1-based index — it never includes the key value itself, so
+ * the error is safe to log.
+ *
+ * Rules:
+ * - At least one key must be present.
+ * - Every key must be at least 32 characters.
+ * - No key may contain a known placeholder substring (case-insensitive).
+ * - No key may equal a known placeholder value (lowercased).
+ * - No key may be a single character repeated (zero entropy).
+ */
+export declare function validateApiKeysForProduction(keys: string[]): void;

package/dist/api/plugins/auth/keys.js

@@ -0,0 +1,100 @@
+/**
+ * API key helpers — hashing + production validation.
+ *
+ * Extracted from `src/api/plugins/auth.ts` during the Phase 28 (Plan 28-04)
+ * chain split. The runtime behaviour of `hashKey` and
+ * `validateApiKeysForProduction` is byte-identical to the pre-split
+ * implementation; only the file location changed so the new chain plugin at
+ * `src/api/plugins/auth/index.ts` and the legacy strategy at
+ * `src/api/plugins/auth/strategies/legacy.ts` can import them without a
+ * circular reference back through the shim at `src/api/plugins/auth.ts`.
+ *
+ * The legacy shim re-exports both functions verbatim, so existing
+ * `import { hashKey } from '../plugins/auth.js'` callers (e.g. routes/events.ts,
+ * sse-caps.test.ts, the legacy strategy module) keep working unchanged.
+ */
+import { createHash } from 'crypto';
+/**
+ * Placeholder substrings rejected in production keys (case-insensitive contains check).
+ *
+ * Substring matches catch keys that embed an obvious placeholder phrase even if
+ * padded to satisfy the length floor (e.g. "change-me-to-a-real-keyxxxxxxxxxx").
+ */
+const PLACEHOLDER_SUBSTRINGS = [
+    'change-me-to-a-real-key',
+    'changeme',
+    'placeholder',
+    'example',
+];
+/**
+ * Placeholder values rejected in production keys (exact lowercase match).
+ *
+ * Exact matches catch the literal short placeholders the audit named without
+ * false-positive on legitimate keys that happen to include the chars "test"
+ * or "dev" elsewhere.
+ */
+const PLACEHOLDER_EXACT = new Set(['test', 'dev', 'placeholder']);
+/**
+ * Minimum length required for each API key when NODE_ENV=production.
+ * 32 characters gives ~190 bits of entropy if generated from a hex/base64 RNG.
+ */
+const MIN_PRODUCTION_KEY_LENGTH = 32;
+/**
+ * SHA-256 hash of a key, returned as a 32-byte Buffer.
+ *
+ * Hashing both sides of the comparison guarantees `timingSafeEqual` receives
+ * equal-length buffers, eliminating the length-leak that arises from comparing
+ * raw keys of different lengths.
+ */
+export function hashKey(key) {
+    return createHash('sha256').update(key, 'utf8').digest();
+}
+/**
+ * Validate API keys for a production environment.
+ *
+ * Throws an Error listing every failure mode. The error message references
+ * keys by their 1-based index — it never includes the key value itself, so
+ * the error is safe to log.
+ *
+ * Rules:
+ * - At least one key must be present.
+ * - Every key must be at least 32 characters.
+ * - No key may contain a known placeholder substring (case-insensitive).
+ * - No key may equal a known placeholder value (lowercased).
+ * - No key may be a single character repeated (zero entropy).
+ */
+export function validateApiKeysForProduction(keys) {
+    const errors = [];
+    if (keys.length === 0) {
+        errors.push('API_KEYS must contain at least one key (got empty list)');
+    }
+    for (let i = 0; i < keys.length; i++) {
+        const k = keys[i];
+        const idx = i + 1;
+        if (k.length === 0) {
+            errors.push(`key #${idx}: empty value`);
+            continue;
+        }
+        if (k.length < MIN_PRODUCTION_KEY_LENGTH) {
+            errors.push(`key #${idx}: must be at least ${MIN_PRODUCTION_KEY_LENGTH} characters (got ${k.length})`);
+        }
+        const lower = k.toLowerCase();
+        for (const phrase of PLACEHOLDER_SUBSTRINGS) {
+            if (lower.includes(phrase)) {
+                errors.push(`key #${idx}: contains placeholder phrase "${phrase}"`);
+            }
+        }
+        if (PLACEHOLDER_EXACT.has(lower)) {
+            errors.push(`key #${idx}: matches known placeholder value`);
+        }
+        if (new Set(k).size === 1) {
+            errors.push(`key #${idx}: single character repeated (no entropy)`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`API_KEYS validation failed for production:\n  - ${errors.join('\n  - ')}\n` +
+            `Set API_KEYS to comma-separated keys of at least ${MIN_PRODUCTION_KEY_LENGTH} ` +
+            `characters each, with sufficient entropy and no placeholder phrases.`);
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/api/plugins/auth/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../../src/api/plugins/auth/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG;IAC7B,yBAAyB;IACzB,UAAU;IACV,aAAa;IACb,SAAS;CACV,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC;AAElE;;;GAGG;AACH,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAc;IACzD,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QAElB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC;YACxC,SAAS;QACX,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,GAAG,yBAAyB,EAAE,CAAC;YACzC,MAAM,CAAC,IAAI,CACT,QAAQ,GAAG,sBAAsB,yBAAyB,oBAAoB,CAAC,CAAC,MAAM,GAAG,CAC1F,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9B,KAAK,MAAM,MAAM,IAAI,sBAAsB,EAAE,CAAC;YAC5C,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,kCAAkC,MAAM,GAAG,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QACD,IAAI,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,mCAAmC,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,0CAA0C,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,mDAAmD,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI;YAC1E,oDAAoD,yBAAyB,GAAG;YAChF,sEAAsE,CACzE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/api/plugins/auth/strategies/legacy.d.ts

@@ -0,0 +1,46 @@
+import type { FastifyRequest } from 'fastify';
+import type { UserRepository } from '../../../../repositories/user.repository.js';
+import type { ApiKeyEntry } from '../../../../config/env.js';
+import type { StrategyOutcome } from './types.js';
+export interface LegacyDeps {
+    userRepository: UserRepository;
+    /**
+     * Pre-computed SHA-256 hashes of every configured API_KEYS entry. The
+     * chain plugin computes this once at register time via
+     * `precomputeHashedEntries` and passes it in so the strategy never
+     * re-hashes per request.
+     */
+    hashedEntries: Array<{
+        hash: Buffer;
+        label: string;
+    }>;
+}
+/**
+ * Pre-compute the SHA-256 hash + label for each parsed API_KEYS entry.
+ *
+ * Called once by the chain plugin at register time. The result feeds into
+ * `LegacyDeps.hashedEntries` for every subsequent request, avoiding
+ * per-request rehash of the configured key list.
+ */
+export declare function precomputeHashedEntries(entries: ApiKeyEntry[]): Array<{
+    hash: Buffer;
+    label: string;
+}>;
+/**
+ * Inspect the request for a legacy `x-api-key` header and return the
+ * outcome.
+ *
+ * Decision tree:
+ *   1. No / empty `x-api-key` header                   → skip
+ *      (chain catch-all wraps this as `missing_credential` in the audit
+ *      log if no other strategy matched.)
+ *   2. Supplied hash compares equal to a configured one → look up legacy
+ *      user via `findLegacyByDisplayName(label)`:
+ *      - user row missing OR user.disabled_at set       → fail/user_disabled
+ *      - otherwise                                       → match
+ *   3. Supplied hash equals NONE of the configured hashes → fail/unknown_token
+ *
+ * The strategy emits NO log lines — the chain owns audit logging via
+ * Phase 27's `logAuthFailure` helper.
+ */
+export declare function tryAuth(request: FastifyRequest, deps: LegacyDeps): Promise<StrategyOutcome>;

package/dist/api/plugins/auth/strategies/legacy.js

@@ -0,0 +1,87 @@
+// Legacy API_KEYS auth strategy (MIGR-01 break-glass).
+//
+// Behaviour ported nearly byte-for-byte from `src/api/plugins/auth.ts:170-216`
+// (the existing inline preHandler that this strategy will replace once the
+// chain plugin lands in Plan 28-04). The boundary changes are deliberate:
+//
+//   - Returns a categorical `StrategyOutcome` instead of mutating
+//     `request.apiKeyLabel` / `request.log` and sending a 401. The chain
+//     plugin (Plan 28-04) applies the outcome.
+//   - On a successful hash match, performs the additional
+//     `userRepository.findLegacyByDisplayName(label)` lookup so the
+//     chain can populate `request.user` from a real `users` row (the
+//     legacy identity seeded by Phase 27's identity-seeder service).
+//
+// The constant-time comparison loop is preserved verbatim — every
+// configured hash is compared against the supplied hash regardless of
+// where (or whether) a match occurs. This is the timing-attack defence
+// originally documented at `src/api/plugins/auth.ts:198` and re-asserted
+// by the unit test `does NOT short-circuit on first match`.
+import { timingSafeEqual } from 'node:crypto';
+import { hashKey } from '../keys.js';
+import { toAuthenticatedUser } from './pat.js';
+/**
+ * Pre-compute the SHA-256 hash + label for each parsed API_KEYS entry.
+ *
+ * Called once by the chain plugin at register time. The result feeds into
+ * `LegacyDeps.hashedEntries` for every subsequent request, avoiding
+ * per-request rehash of the configured key list.
+ */
+export function precomputeHashedEntries(entries) {
+    return entries.map((e) => ({ hash: hashKey(e.key), label: e.label }));
+}
+/**
+ * Inspect the request for a legacy `x-api-key` header and return the
+ * outcome.
+ *
+ * Decision tree:
+ *   1. No / empty `x-api-key` header                   → skip
+ *      (chain catch-all wraps this as `missing_credential` in the audit
+ *      log if no other strategy matched.)
+ *   2. Supplied hash compares equal to a configured one → look up legacy
+ *      user via `findLegacyByDisplayName(label)`:
+ *      - user row missing OR user.disabled_at set       → fail/user_disabled
+ *      - otherwise                                       → match
+ *   3. Supplied hash equals NONE of the configured hashes → fail/unknown_token
+ *
+ * The strategy emits NO log lines — the chain owns audit logging via
+ * Phase 27's `logAuthFailure` helper.
+ */
+export async function tryAuth(request, deps) {
+    const supplied = request.headers['x-api-key'];
+    if (typeof supplied !== 'string' || supplied.length === 0) {
+        return { kind: 'skip' };
+    }
+    const suppliedHash = hashKey(supplied);
+    // Constant-time compare against EVERY configured hash. Do NOT break on
+    // first match — keeping the comparison count fixed prevents leaking the
+    // match position (or the existence of any match at all) via wall-clock
+    // timing. Preserved verbatim from src/api/plugins/auth.ts:194-200.
+    let matchedLabel;
+    for (const entry of deps.hashedEntries) {
+        if (timingSafeEqual(entry.hash, suppliedHash)) {
+            matchedLabel = entry.label;
+            // Do NOT break — keeps total comparison count fixed.
+        }
+    }
+    if (matchedLabel === undefined) {
+        return { kind: 'fail', reasonCode: 'unknown_token' };
+    }
+    // Match — resolve the legacy `users` row Phase 27 seeded so the chain
+    // can populate `request.user` with a real principal. `is_legacy=1` is
+    // already enforced inside the repository query.
+    const user = deps.userRepository.findLegacyByDisplayName(matchedLabel);
+    if (user === null || user.disabled_at !== null) {
+        return { kind: 'fail', reasonCode: 'user_disabled' };
+    }
+    return {
+        kind: 'match',
+        result: {
+            user: toAuthenticatedUser(user),
+            authMethod: 'legacy',
+            tokenId: null,
+        },
+        label: matchedLabel,
+    };
+}
+//# sourceMappingURL=legacy.js.map

package/dist/api/plugins/auth/strategies/legacy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.js","sourceRoot":"","sources":["../../../../../src/api/plugins/auth/strategies/legacy.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,0EAA0E;AAC1E,EAAE;AACF,kEAAkE;AAClE,yEAAyE;AACzE,+CAA+C;AAC/C,0DAA0D;AAC1D,oEAAoE;AACpE,qEAAqE;AACrE,qEAAqE;AACrE,EAAE;AACF,kEAAkE;AAClE,sEAAsE;AACtE,uEAAuE;AACvE,yEAAyE;AACzE,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAc/C;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAsB;IAEtB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAuB,EACvB,IAAgB;IAEhB,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvC,uEAAuE;IACvE,wEAAwE;IACxE,uEAAuE;IACvE,mEAAmE;IACnE,IAAI,YAAgC,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvC,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC;YAC9C,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC;YAC3B,qDAAqD;QACvD,CAAC;IACH,CAAC;IAED,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;IACvD,CAAC;IAED,sEAAsE;IACtE,sEAAsE;IACtE,gDAAgD;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC;IACvE,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;IACvD,CAAC;IAED,OAAO;QACL,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACN,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC;YAC/B,UAAU,EAAE,QAAQ;YACpB,OAAO,EAAE,IAAI;SACd;QACD,KAAK,EAAE,YAAY;KACpB,CAAC;AACJ,CAAC"}

package/dist/api/plugins/auth/strategies/pat.d.ts

@@ -0,0 +1,37 @@
+import type { FastifyRequest } from 'fastify';
+import type { ApiTokenRepository } from '../../../../repositories/api-token.repository.js';
+import type { UserRepository } from '../../../../repositories/user.repository.js';
+import type { AuthenticatedUser, User } from '../../../../types/identity.js';
+import type { StrategyOutcome } from './types.js';
+export interface PatDeps {
+    apiTokenRepository: ApiTokenRepository;
+    userRepository: UserRepository;
+}
+/**
+ * Map a snake_case `users` row to the camelCase boundary projection that
+ * the auth chain populates on `request.user`.
+ *
+ * SQLite returns booleans as INTEGER (0|1); the projection normalises to
+ * the boolean type the downstream consumers expect. Exported so the legacy
+ * strategy can share the conversion in Task 3.
+ */
+export declare function toAuthenticatedUser(user: User): AuthenticatedUser;
+/**
+ * Inspect the request for a PAT credential and return the outcome.
+ *
+ * Decision tree:
+ *   1. No Authorization header                       → skip
+ *   2. Authorization doesn't start with `Bearer `    → skip
+ *   3. Bearer body doesn't start with `wft_pat_`     → skip (legacy may try)
+ *   4. PAT body shape wrong (length / charset)       → fail/wrong_prefix
+ *   5. findByHash returns null                       → fail/unknown_token
+ *   6. row.revoked_at is set                         → fail/revoked
+ *   7. row.expires_at is past wall-clock now         → fail/expired
+ *   8. user row missing OR user.disabled_at set      → fail/user_disabled
+ *   9. all checks pass                               → match
+ *
+ * No side effects: no log writes, no last_used_at update — the chain (Plan
+ * 4) does both centrally after a strategy returns. Keeps this function
+ * pure and unit-testable without a Fastify instance.
+ */
+export declare function tryAuth(request: FastifyRequest, deps: PatDeps): Promise<StrategyOutcome>;