@enricai/barnacle 1.0.0

package/dist/api/errors.d.ts

@@ -0,0 +1,88 @@
+import { type ErrorCode } from "../api/schemas/common";
+/**
+ * Representation of the error envelope on the wire. Every non-2xx
+ * response from Barnacle conforms to this shape so clients can share a
+ * single parser across all error types.
+ */
+interface ApiStatusDetail {
+    code: number;
+    codeDescription: string;
+    detailType: string;
+    message: string;
+}
+interface ApiErrorEnvelope {
+    status: {
+        httpStatus: string;
+        dateTime: string;
+        details: ApiStatusDetail[];
+    };
+}
+/**
+ * Maps an error code to the HTTP status we return. Status codes come
+ * from the `http-status-codes` package (battle-tested, RFC-aligned, used
+ * by Express and thousands of production APIs) so we don't maintain our
+ * own numeric table.
+ *
+ * The envelope uses `httpStatus` as a string. Barnacle also sets the actual
+ * HTTP status code so modern clients can branch on either.
+ */
+export declare function httpStatusForCode(code: ErrorCode): number;
+/**
+ * Converts an HTTP status number into the upper-snake-case string used in
+ * the response envelope (e.g. 400 → `"BAD_REQUEST"`). Uses `getReasonPhrase`
+ * from `http-status-codes`, then uppercases and replaces non-alphanumeric
+ * runs with `_` (e.g. `I'm a teapot` → `I_M_A_TEAPOT`).
+ */
+export declare function httpStatusString(status: number): string;
+/**
+ * Base class for every structured error Barnacle surfaces to clients. Each
+ * subclass hard-codes an error code; the plugin-level error handler
+ * reads `code` + `message` and builds the envelope.
+ */
+export declare class ApiError extends Error {
+    readonly code: ErrorCode;
+    readonly detailType: string;
+    constructor(code: ErrorCode, message: string, detailType?: string);
+}
+export declare class UnauthorizedError extends ApiError {
+    constructor(message?: string);
+}
+export declare class FieldViolationError extends ApiError {
+    constructor(message: string);
+}
+export declare class ThrottledRequestError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * The upstream vendor has locked the target URL (e.g. Oracle ORA_URL_LOCKED).
+ * Signals "back off and retry later" — not a browser-fallback trigger.
+ */
+export declare class UrlLockedError extends ApiError {
+    constructor(message?: string);
+}
+export declare class ScrapeFailureError extends ApiError {
+    constructor(message?: string);
+}
+export declare class CaptchaEncounteredError extends ApiError {
+    constructor(message?: string);
+}
+export declare class EmptyResultsApiError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * The OTP a candidate supplied to /resume was rejected by Oracle HCM, which
+ * surfaces as a 401/403 on the first AccessCode-authed call. Distinct from a
+ * generic scrape failure so Vivian can re-prompt for the code rather than
+ * treating the resume as terminally failed.
+ */
+export declare class InvalidOtpError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Builds an error envelope for the given code + message. Used by the
+ * Fastify error handler and anywhere else a manual non-200 response needs
+ * to be emitted (e.g. Fastify's built-in rate-limit 429).
+ */
+export declare function buildErrorEnvelope(code: ErrorCode, message: string, detailType?: string): ApiErrorEnvelope;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/api/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5F;;;;GAIG;AACH,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,eAAe,EAAE,CAAC;KAC5B,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAgCzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,SAAU;CAMnE;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAA4C;CAGhE;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,qBAAsB,SAAQ,QAAQ;gBACrC,OAAO,SAAwB;CAG5C;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAA6D;CAGjF;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,SAA0C;CAG9D;AAED,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,SAA2C;CAG/D;AAED,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,SAA6C;CAGjE;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,SAA4C;CAGhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,UAAU,SAAU,GACnB,gBAAgB,CAgBlB"}

package/dist/api/errors.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidOtpError = exports.EmptyResultsApiError = exports.CaptchaEncounteredError = exports.ScrapeFailureError = exports.UrlLockedError = exports.ThrottledRequestError = exports.FieldViolationError = exports.UnauthorizedError = exports.ApiError = void 0;
+exports.httpStatusForCode = httpStatusForCode;
+exports.httpStatusString = httpStatusString;
+exports.buildErrorEnvelope = buildErrorEnvelope;
+const date_fns_1 = require("date-fns");
+const http_status_codes_1 = require("http-status-codes");
+const common_1 = require("../api/schemas/common");
+/**
+ * Maps an error code to the HTTP status we return. Status codes come
+ * from the `http-status-codes` package (battle-tested, RFC-aligned, used
+ * by Express and thousands of production APIs) so we don't maintain our
+ * own numeric table.
+ *
+ * The envelope uses `httpStatus` as a string. Barnacle also sets the actual
+ * HTTP status code so modern clients can branch on either.
+ */
+function httpStatusForCode(code) {
+    switch (code) {
+        case common_1.ERROR_CODES.PARTIAL_CONTENT_SUCCESS:
+            return http_status_codes_1.StatusCodes.PARTIAL_CONTENT;
+        case common_1.ERROR_CODES.AUTHORIZATION_ERROR:
+            return http_status_codes_1.StatusCodes.UNAUTHORIZED;
+        case common_1.ERROR_CODES.DECODING_ERROR:
+        case common_1.ERROR_CODES.FIELD_VIOLATION:
+        case common_1.ERROR_CODES.EMPTY_REQUEST:
+            return http_status_codes_1.StatusCodes.BAD_REQUEST;
+        case common_1.ERROR_CODES.RESOURCE_NOT_FOUND:
+        case common_1.ERROR_CODES.INDEX_NOT_FOUND:
+            return http_status_codes_1.StatusCodes.NOT_FOUND;
+        case common_1.ERROR_CODES.THROTTLED_REQUEST:
+        case common_1.ERROR_CODES.URL_LOCKED:
+            return http_status_codes_1.StatusCodes.TOO_MANY_REQUESTS;
+        case common_1.ERROR_CODES.TIME_OUT:
+            return http_status_codes_1.StatusCodes.GATEWAY_TIMEOUT;
+        case common_1.ERROR_CODES.EMPTY_RESULTS:
+            return http_status_codes_1.StatusCodes.NOT_FOUND;
+        case common_1.ERROR_CODES.CLIENT_CALL_ERROR:
+        case common_1.ERROR_CODES.GENERIC_ERROR:
+        case common_1.ERROR_CODES.EXTRA_DETAIL:
+        case common_1.ERROR_CODES.SCRAPE_FAILURE:
+        case common_1.ERROR_CODES.CAPTCHA_ENCOUNTERED:
+        case common_1.ERROR_CODES.VERIFICATION_TRIGGER_FAILED:
+            return http_status_codes_1.StatusCodes.INTERNAL_SERVER_ERROR;
+        case common_1.ERROR_CODES.RESUME_INVALID_OTP:
+            return http_status_codes_1.StatusCodes.BAD_REQUEST;
+        default:
+            return http_status_codes_1.StatusCodes.INTERNAL_SERVER_ERROR;
+    }
+}
+/**
+ * Converts an HTTP status number into the upper-snake-case string used in
+ * the response envelope (e.g. 400 → `"BAD_REQUEST"`). Uses `getReasonPhrase`
+ * from `http-status-codes`, then uppercases and replaces non-alphanumeric
+ * runs with `_` (e.g. `I'm a teapot` → `I_M_A_TEAPOT`).
+ */
+function httpStatusString(status) {
+    try {
+        return (0, http_status_codes_1.getReasonPhrase)(status)
+            .toUpperCase()
+            .replace(/[^A-Z0-9]+/g, "_");
+    }
+    catch {
+        return `HTTP_${status}`;
+    }
+}
+/**
+ * Base class for every structured error Barnacle surfaces to clients. Each
+ * subclass hard-codes an error code; the plugin-level error handler
+ * reads `code` + `message` and builds the envelope.
+ */
+class ApiError extends Error {
+    code;
+    detailType;
+    constructor(code, message, detailType = "ERROR") {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.detailType = detailType;
+    }
+}
+exports.ApiError = ApiError;
+class UnauthorizedError extends ApiError {
+    constructor(message = "missing or invalid Authorization header") {
+        super(common_1.ERROR_CODES.AUTHORIZATION_ERROR, message);
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+class FieldViolationError extends ApiError {
+    constructor(message) {
+        super(common_1.ERROR_CODES.FIELD_VIOLATION, message);
+    }
+}
+exports.FieldViolationError = FieldViolationError;
+class ThrottledRequestError extends ApiError {
+    constructor(message = "rate limit exceeded") {
+        super(common_1.ERROR_CODES.THROTTLED_REQUEST, message);
+    }
+}
+exports.ThrottledRequestError = ThrottledRequestError;
+/**
+ * The upstream vendor has locked the target URL (e.g. Oracle ORA_URL_LOCKED).
+ * Signals "back off and retry later" — not a browser-fallback trigger.
+ */
+class UrlLockedError extends ApiError {
+    constructor(message = "target URL is locked by the upstream vendor; retry later") {
+        super(common_1.ERROR_CODES.URL_LOCKED, message);
+    }
+}
+exports.UrlLockedError = UrlLockedError;
+class ScrapeFailureError extends ApiError {
+    constructor(message = "scraper failed to fulfill the request") {
+        super(common_1.ERROR_CODES.SCRAPE_FAILURE, message);
+    }
+}
+exports.ScrapeFailureError = ScrapeFailureError;
+class CaptchaEncounteredError extends ApiError {
+    constructor(message = "captcha challenge encountered upstream") {
+        super(common_1.ERROR_CODES.CAPTCHA_ENCOUNTERED, message);
+    }
+}
+exports.CaptchaEncounteredError = CaptchaEncounteredError;
+class EmptyResultsApiError extends ApiError {
+    constructor(message = "scrape completed but returned no results") {
+        super(common_1.ERROR_CODES.EMPTY_RESULTS, message);
+    }
+}
+exports.EmptyResultsApiError = EmptyResultsApiError;
+/**
+ * The OTP a candidate supplied to /resume was rejected by Oracle HCM, which
+ * surfaces as a 401/403 on the first AccessCode-authed call. Distinct from a
+ * generic scrape failure so Vivian can re-prompt for the code rather than
+ * treating the resume as terminally failed.
+ */
+class InvalidOtpError extends ApiError {
+    constructor(message = "provided OTP was rejected by Oracle HCM") {
+        super(common_1.ERROR_CODES.RESUME_INVALID_OTP, message);
+    }
+}
+exports.InvalidOtpError = InvalidOtpError;
+/**
+ * Builds an error envelope for the given code + message. Used by the
+ * Fastify error handler and anywhere else a manual non-200 response needs
+ * to be emitted (e.g. Fastify's built-in rate-limit 429).
+ */
+function buildErrorEnvelope(code, message, detailType = "ERROR") {
+    const httpStatus = httpStatusForCode(code);
+    return {
+        status: {
+            httpStatus: httpStatusString(httpStatus),
+            dateTime: (0, date_fns_1.formatISO)(new Date()),
+            details: [
+                {
+                    code,
+                    codeDescription: common_1.ERROR_CODE_DESCRIPTIONS[code],
+                    detailType,
+                    message,
+                },
+            ],
+        },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/errors.js.map

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

package/dist/api/helpers/envelope.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Builds the success envelope — `{ status: { httpStatus: "OK", ... } }`
+ * merged with the domain payload. Service methods return the complete
+ * envelope-shaped object so route handlers just pass them through.
+ */
+export declare function successEnvelope<T extends object>(payload: T): {
+    status: {
+        httpStatus: string;
+        dateTime: string;
+        details: unknown[];
+    };
+} & T;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/api/helpers/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/api/helpers/envelope.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,OAAO,EAAE,CAAC,GACT;IACD,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,EAAE,CAAC;KACpB,CAAC;CACH,GAAG,CAAC,CASJ"}

package/dist/api/helpers/envelope.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.successEnvelope = successEnvelope;
+const date_fns_1 = require("date-fns");
+/**
+ * Builds the success envelope — `{ status: { httpStatus: "OK", ... } }`
+ * merged with the domain payload. Service methods return the complete
+ * envelope-shaped object so route handlers just pass them through.
+ */
+function successEnvelope(payload) {
+    return {
+        status: {
+            httpStatus: "OK",
+            dateTime: (0, date_fns_1.formatISO)(new Date()),
+            details: [],
+        },
+        ...payload,
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/api/helpers/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/api/helpers/envelope.ts"],"names":[],"mappings":";;AAOA,0CAiBC;AAxBD,uCAAqC;AAErC;;;;GAIG;AACH,SAAgB,eAAe,CAC7B,OAAU;IAQV,OAAO;QACL,MAAM,EAAE;YACN,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,IAAA,oBAAS,EAAC,IAAI,IAAI,EAAE,CAAC;YAC/B,OAAO,EAAE,EAAE;SACZ;QACD,GAAG,OAAO;KACX,CAAC;AACJ,CAAC"}

package/dist/api/helpers/reply.d.ts

@@ -0,0 +1,9 @@
+import type { FastifyReply } from "fastify";
+import type { ErrorCode } from "../../api/schemas/common";
+import type { DispatchMetrics } from "../../types/dispatch-metrics";
+/**
+ * Sends a standard error envelope on the given reply, optionally including
+ * dispatch metrics so Vivian can forward step-level detail even on failures.
+ */
+export declare function replyWithError(reply: FastifyReply, code: ErrorCode, message: string, detailType?: string, statusOverride?: number, metrics?: DispatchMetrics): void;
+//# sourceMappingURL=reply.d.ts.map

package/dist/api/helpers/reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../../src/api/helpers/reply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,cAAc,CAAC,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,eAAe,GACxB,IAAI,CAIN"}

package/dist/api/helpers/reply.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replyWithError = replyWithError;
+const errors_1 = require("../../api/errors");
+/**
+ * Sends a standard error envelope on the given reply, optionally including
+ * dispatch metrics so Vivian can forward step-level detail even on failures.
+ */
+function replyWithError(reply, code, message, detailType, statusOverride, metrics) {
+    const envelope = (0, errors_1.buildErrorEnvelope)(code, message, detailType);
+    const body = metrics ? { ...envelope, metrics } : envelope;
+    void reply.status(statusOverride ?? (0, errors_1.httpStatusForCode)(code)).send(body);
+}
+//# sourceMappingURL=reply.js.map

package/dist/api/helpers/reply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.js","sourceRoot":"","sources":["../../../src/api/helpers/reply.ts"],"names":[],"mappings":";;AAUA,wCAWC;AAnBD,yCAAqE;AAIrE;;;GAGG;AACH,SAAgB,cAAc,CAC5B,KAAmB,EACnB,IAAe,EACf,OAAe,EACf,UAAmB,EACnB,cAAuB,EACvB,OAAyB;IAEzB,MAAM,QAAQ,GAAG,IAAA,2BAAkB,EAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC3D,KAAK,KAAK,CAAC,MAAM,CAAC,cAAc,IAAI,IAAA,0BAAiB,EAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1E,CAAC"}

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

@@ -0,0 +1,27 @@
+import type { FastifyInstance } from "fastify";
+declare module "fastify" {
+    interface FastifyInstance {
+        authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    }
+    interface FastifyRequest {
+        apiKeyTier?: string;
+        /**
+         * Short SHA-256 fingerprint of the matching bcrypt hash, or the
+         * literal `"dev-bypass"` when DEV_BYPASS_AUTH is used. Lets ops
+         * trace "which client hit this route" in logs without leaking the
+         * plaintext token or the full bcrypt hash.
+         */
+        apiKeyFingerprint?: string;
+    }
+}
+/**
+ * Fastify plugin exposing `app.authenticate`. Routes attach it via
+ * `{ onRequest: [app.authenticate] }` to require a valid Bearer token.
+ *
+ * Dev-only escape hatch: `DEV_BYPASS_AUTH=true` allows unauthenticated
+ * access in non-production environments. NEVER set this in prod.
+ */
+declare function authPlugin(app: FastifyInstance): Promise<void>;
+declare const _default: typeof authPlugin;
+export default _default;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/api/plugins/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAS7E,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,YAAY,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/E;IACD,UAAU,cAAc;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB;;;;;WAKG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B;CACF;AAsCD;;;;;;GAMG;AACH,iBAAe,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA6D7D;;AAED,wBAEG"}

package/dist/api/plugins/auth.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
+const bcryptjs_1 = require("bcryptjs");
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const errors_1 = require("../../api/errors");
+const config_1 = require("../../config");
+const logging_1 = require("../../lib/logging");
+const logger = (0, logging_1.getLogger)({ name: "api/plugins/auth" });
+/**
+ * Derives a short, stable fingerprint from a bcrypt hash. 12 hex chars
+ * = 48 bits — enough to tell registered keys apart in a log stream
+ * without making offline collision attacks viable.
+ */
+function fingerprintHash(hash) {
+    return (0, node_crypto_1.createHash)("sha256").update(hash).digest("hex").slice(0, 12);
+}
+/**
+ * Extracts the Bearer token from the Authorization header. Returns `null`
+ * if the header is missing or malformed — callers must translate that
+ * into the UnauthorizedError.
+ */
+function extractBearer(authHeader) {
+    if (!authHeader)
+        return null;
+    const parts = authHeader.trim().split(/\s+/);
+    if (parts.length !== 2)
+        return null;
+    if (parts[0]?.toLowerCase() !== "bearer")
+        return null;
+    const token = parts[1];
+    if (!token || token.length < 8)
+        return null;
+    return token;
+}
+/**
+ * Compares the plaintext token against every registered bcrypt hash. We
+ * walk the array linearly — bcrypt.compare is constant-time for a given
+ * input + hash, and the hash count is small (tens).
+ */
+async function findMatchingHash(token, hashes) {
+    for (const hash of hashes) {
+        if (await (0, bcryptjs_1.compare)(token, hash))
+            return hash;
+    }
+    return null;
+}
+/**
+ * Fastify plugin exposing `app.authenticate`. Routes attach it via
+ * `{ onRequest: [app.authenticate] }` to require a valid Bearer token.
+ *
+ * Dev-only escape hatch: `DEV_BYPASS_AUTH=true` allows unauthenticated
+ * access in non-production environments. NEVER set this in prod.
+ */
+async function authPlugin(app) {
+    // Reload config at plugin-registration time so tests can toggle
+    // DEV_BYPASS_AUTH and spin up a fresh server instance without the
+    // frozen module-scope `config` singleton getting in the way.
+    const cfg = (0, config_1.loadConfig)();
+    // Loud startup warn if dev-bypass is active. NODE_ENV unset defaults
+    // to "development" (see lib/env.ts), so a container that forgets to
+    // set NODE_ENV while DEV_BYPASS_AUTH=true would silently accept
+    // unauthenticated traffic without any runtime signal. Emitting at
+    // plugin registration means every boot of every environment logs
+    // the state — much harder to miss than discovering it via a breach.
+    if (cfg.auth.devBypass && cfg.nodeEnv !== "production") {
+        logger.warn(`DEV_BYPASS_AUTH is active (NODE_ENV=${cfg.nodeEnv}) — all requests will bypass authentication. DO NOT use this in production.`);
+    }
+    else if (cfg.auth.devBypass && cfg.nodeEnv === "production") {
+        // devBypass=true + NODE_ENV=production means the env var is present
+        // but the production guard disarmed it. Still loud-warn because
+        // that's a misconfiguration worth catching.
+        logger.warn("DEV_BYPASS_AUTH=true in production — the production guard disarmed it, but the env var should be removed from the deploy.");
+    }
+    app.decorate("authenticate", async (request, _reply) => {
+        if (cfg.auth.devBypass && cfg.nodeEnv !== "production") {
+            request.apiKeyTier = "dev";
+            // Stamp a stable sentinel fingerprint so log-aggregator
+            // filters on `apiKeyFingerprint` don't miss dev-bypass traffic.
+            request.apiKeyFingerprint = "dev-bypass";
+            request.log = request.log.child({ apiKeyFingerprint: "dev-bypass" });
+            return;
+        }
+        const token = extractBearer(request.headers.authorization);
+        if (!token) {
+            throw new errors_1.UnauthorizedError("missing or malformed Authorization: Bearer header");
+        }
+        if (cfg.auth.hashedKeys.length === 0) {
+            throw new errors_1.UnauthorizedError("no API keys configured on server");
+        }
+        const match = await findMatchingHash(token, cfg.auth.hashedKeys);
+        if (!match) {
+            throw new errors_1.UnauthorizedError("invalid API key");
+        }
+        request.apiKeyTier = "standard";
+        const fingerprint = fingerprintHash(match);
+        request.apiKeyFingerprint = fingerprint;
+        // Bind the fingerprint onto the per-request pino child so every
+        // subsequent log line for this request carries the identity
+        // automatically — no scattered `{ apiKeyFingerprint: ... }`
+        // calls in service code.
+        request.log = request.log.child({ apiKeyFingerprint: fingerprint });
+    });
+}
+exports.default = (0, fastify_plugin_1.default)(authPlugin, {
+    name: "auth",
+});
+//# sourceMappingURL=auth.js.map

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

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

package/dist/api/plugins/error-handler.d.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance } from "fastify";
+/**
+ * Fastify plugin that replaces Fastify's default error serializer with the
+ * engine error envelope. Every non-2xx response — Zod validation failures,
+ * thrown `ApiError` subclasses, 404s, unhandled crashes — serializes through
+ * the same `{ status: { httpStatus, dateTime, details: [...] } }` shape all
+ * clients expect.
+ */
+declare function errorHandlerPlugin(app: FastifyInstance): Promise<void>;
+declare const _default: typeof errorHandlerPlugin;
+export default _default;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/api/plugins/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/api/plugins/error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAW/C;;;;;;GAMG;AACH,iBAAe,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFrE;;AAED,wBAEG"}

package/dist/api/plugins/error-handler.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const fastify_type_provider_zod_1 = require("fastify-type-provider-zod");
+const v4_1 = require("zod/v4");
+const errors_1 = require("../../api/errors");
+const reply_1 = require("../../api/helpers/reply");
+const common_1 = require("../../api/schemas/common");
+const errors_2 = require("../../scraper/errors");
+/**
+ * Fastify plugin that replaces Fastify's default error serializer with the
+ * engine error envelope. Every non-2xx response — Zod validation failures,
+ * thrown `ApiError` subclasses, 404s, unhandled crashes — serializes through
+ * the same `{ status: { httpStatus, dateTime, details: [...] } }` shape all
+ * clients expect.
+ */
+async function errorHandlerPlugin(app) {
+    app.setNotFoundHandler((_request, reply) => {
+        (0, reply_1.replyWithError)(reply, common_1.ERROR_CODES.RESOURCE_NOT_FOUND, `route ${_request.method} ${_request.url} not found`);
+    });
+    app.setErrorHandler((error, request, reply) => {
+        const metrics = error.metrics;
+        if ((0, fastify_type_provider_zod_1.hasZodFastifySchemaValidationErrors)(error)) {
+            const message = error.validation
+                .map((issue) => `${issue.instancePath || "body"}: ${issue.message}`)
+                .join("; ");
+            (0, reply_1.replyWithError)(reply, common_1.ERROR_CODES.FIELD_VIOLATION, message, undefined, undefined, metrics);
+            return;
+        }
+        if (error instanceof v4_1.ZodError) {
+            const message = error.issues
+                .map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`)
+                .join("; ");
+            (0, reply_1.replyWithError)(reply, common_1.ERROR_CODES.FIELD_VIOLATION, message, undefined, undefined, metrics);
+            return;
+        }
+        if (error instanceof errors_1.ApiError) {
+            (0, reply_1.replyWithError)(reply, error.code, error.message, error.detailType, undefined, metrics);
+            return;
+        }
+        // Scraper errors that escaped the service-layer catch (captcha hits,
+        // exhausted selector retries, session timeouts) surface to clients as
+        // the dedicated codes 2004 / 2003 rather than a generic 1008 — the
+        // whole reason those codes exist is for clients to distinguish scrape
+        // failures from upstream target-site failures.
+        if (error instanceof errors_2.ScraperError) {
+            const code = error instanceof errors_2.CaptchaError
+                ? common_1.ERROR_CODES.CAPTCHA_ENCOUNTERED
+                : common_1.ERROR_CODES.SCRAPE_FAILURE;
+            (0, reply_1.replyWithError)(reply, code, error.message, undefined, undefined, metrics);
+            return;
+        }
+        const err = error;
+        if (typeof err.statusCode === "number" && err.statusCode === 429) {
+            (0, reply_1.replyWithError)(reply, common_1.ERROR_CODES.THROTTLED_REQUEST, err.message || "rate limit exceeded", undefined, undefined, metrics);
+            return;
+        }
+        if (typeof err.statusCode === "number" && err.statusCode < 500) {
+            (0, reply_1.replyWithError)(reply, common_1.ERROR_CODES.GENERIC_ERROR, err.message || "request failed", undefined, err.statusCode, metrics);
+            return;
+        }
+        request.log.error({ err }, "unhandled error");
+        (0, reply_1.replyWithError)(reply, common_1.ERROR_CODES.GENERIC_ERROR, "internal server error", undefined, undefined, metrics);
+    });
+}
+exports.default = (0, fastify_plugin_1.default)(errorHandlerPlugin, {
+    name: "error-handler",
+});
+//# sourceMappingURL=error-handler.js.map

package/dist/api/plugins/error-handler.js.map

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

package/dist/api/plugins/request-context.d.ts

@@ -0,0 +1,17 @@
+import type { FastifyInstance } from "fastify";
+declare module "fastify" {
+    interface FastifyRequest {
+        correlationId?: string;
+    }
+}
+/**
+ * Propagates request IDs and correlation IDs so logs can be stitched across
+ * services. We echo an inbound X-Request-ID when provided, otherwise
+ * generate a nanoid (replacing Fastify's per-process `req-N` default,
+ * which collides across pods), and always echo on response. Correlation
+ * IDs are echo-only — we never invent one.
+ */
+declare function requestContextPlugin(app: FastifyInstance): Promise<void>;
+declare const _default: typeof requestContextPlugin;
+export default _default;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/api/plugins/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../../src/api/plugins/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,SAAS,CAAC;AA0B/D,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;CACF;AAED;;;;;;GAMG;AACH,iBAAe,oBAAoB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBvE;;AAED,wBAEG"}