@bigfootds/bigfootds-service-utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BigfootDS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# BigfootDS Service Utils
+
+Reusable service-side utilities for BigfootDS microservices.
+
+This package helps services apply the same request, error, and internal-caller conventions without copying helper code into each service. It is a package, not a service, and it does not own runtime data.
+
+## First-Pass Scope
+
+- request ID generation, validation, inbound resolution, active request metadata, and response-header wiring
+- standard JSON error helpers built from the global error catalogue in `@bigfootds/bigfootds-shared-data`
+- framework-neutral bearer service-token verification and service caller policy results
+- thin Express-style adapters for request IDs, service-token verification, and standard error responses
+
+Deferred areas include broad validation helpers, audit helpers, Morgan logging helpers, admin/operator bulk helpers, and profanity matching/normalisation helpers.
+
+## Public Package Safety
+
+This package is publicly published on NPM, so its contents must be safe for public-facing usage.
+
+It should contain reusable code, public type definitions, and public convention constants only.
+
+Do not put secrets, service-token values, private route policies, private diagnostics, account data, provider payloads, environment-specific URLs, live-ops configuration, audit records, or service-owned runtime data in this package.
+
+Service-token helpers accept token values at runtime from the consuming service. Tokens should come from that service's environment or secret manager, never from this package.
+
+## Installation
+
+```sh
+npm install @bigfootds/bigfootds-service-utils
+```
+
+## Request IDs
+
+```ts
+import {
+	resolveRequestIdFromHeaders,
+	writeRequestIdHeader
+} from "@bigfootds/bigfootds-service-utils";
+
+const metadata = resolveRequestIdFromHeaders(request.headers);
+
+writeRequestIdHeader(response, metadata.requestId);
+```
+
+Inbound `x-request-id` values are accepted only when they are safe ASCII, 8-64 characters long, and contain letters, numbers, `.`, `_`, `:`, or `-`. Missing or unsafe values are replaced with a generated UUID.
+
+## Standard Errors
+
+```ts
+import {
+	ERROR_CODES
+} from "@bigfootds/bigfootds-shared-data";
+import {
+	createServiceError,
+	serializeServiceError
+} from "@bigfootds/bigfootds-service-utils";
+
+const error = createServiceError(ERROR_CODES.VALIDATION_FAILED, {
+	message: "Display name is required.",
+	safeDetails: { field: "displayName" },
+	requestId: "req_123456"
+});
+
+const { httpStatus, body } = serializeServiceError(error);
+```
+
+Serialised errors include stable `error.code` values and safe messages. They do not include stack traces, causes, tokens, or private diagnostics.
+
+## Service Tokens
+
+```ts
+import {
+	verifyServiceTokenFromHeaders
+} from "@bigfootds/bigfootds-service-utils";
+
+const result = verifyServiceTokenFromHeaders(request.headers, {
+	acceptedCallers: [
+		{
+			serviceId: "ms-auth",
+			token: process.env.ACCEPT_MS_AUTH_SERVICE_TOKEN ?? ""
+		}
+	],
+	allowedServiceIds: ["ms-auth"]
+});
+
+if (!result.ok) {
+	console.log(result.errorCode);
+}
+```
+
+Callers send tokens with `Authorization: Bearer <token>`. Caller identity comes from the existing `pkg-bigfoot-fetcher` `productName` header. Package-style identities such as `@bigfootds/ms-auth` are normalised to canonical Project IDs such as `ms-auth`.
+
+## Express Adapters
+
+The Express adapters use structural types, so this package does not require Express as a dependency.
+
+```ts
+import {
+	requestIdMiddleware,
+	serviceTokenMiddleware,
+	standardErrorHandler
+} from "@bigfootds/bigfootds-service-utils";
+
+app.use(requestIdMiddleware());
+
+app.post(
+	"/internal/auth-user-deleted",
+	serviceTokenMiddleware({
+		acceptedCallers: [
+			{
+				serviceId: "ms-auth",
+				token: process.env.ACCEPT_MS_AUTH_SERVICE_TOKEN ?? ""
+			}
+		],
+		allowedServiceIds: ["ms-auth"]
+	}),
+	controller
+);
+
+app.use(standardErrorHandler());
+```
+
+## Package Boundary
+
+`pkg-service-utils` depends on `@bigfootds/bigfootds-shared-data` for stable Project Definitions, error-code metadata, and shared response data shapes.
+
+Do not copy shared data into this package. Do not make `pkg-shared-data` depend on this package.
+
+The intended dependency direction is:
+
+```text
+microservice -> pkg-service-utils -> pkg-shared-data
+```

package/dist/errors.d.ts

@@ -0,0 +1,72 @@
+import { type GlobalErrorCode, type GlobalErrorHttpStatusCode, type SharedErrorResponse } from "@bigfootds/bigfootds-shared-data";
+/**
+ * Options for constructing a standard service error.
+ */
+export interface ServiceErrorOptions {
+    /**
+     * Safe message override. Defaults to the shared catalogue message.
+     */
+    readonly message?: string;
+    /**
+     * Safe structured context to include in the response payload.
+     */
+    readonly safeDetails?: unknown;
+    /**
+     * Request correlation ID to include in the response payload.
+     */
+    readonly requestId?: string;
+    /**
+     * HTTP status override for this response.
+     */
+    readonly httpStatus?: GlobalErrorHttpStatusCode;
+    /**
+     * Lower-level cause retained on the Error object but never serialised.
+     */
+    readonly cause?: unknown;
+}
+/**
+ * Options for serialising a standard service error.
+ */
+export interface SerializeServiceErrorOptions {
+    /**
+     * Request correlation ID to include when the error did not already carry one.
+     */
+    readonly requestId?: string;
+}
+/**
+ * Status/body pair ready for an HTTP adapter.
+ */
+export interface SerializedServiceError {
+    readonly httpStatus: GlobalErrorHttpStatusCode;
+    readonly body: SharedErrorResponse;
+}
+/**
+ * Error class backed by the shared global error catalogue.
+ */
+export declare class ServiceError extends Error {
+    readonly code: GlobalErrorCode;
+    readonly httpStatus: GlobalErrorHttpStatusCode;
+    readonly requestId?: string;
+    readonly safeDetails?: unknown;
+    constructor(code: GlobalErrorCode, options?: ServiceErrorOptions);
+}
+/**
+ * Creates a standard service error.
+ */
+export declare function createServiceError(code: GlobalErrorCode, options?: ServiceErrorOptions): ServiceError;
+/**
+ * Checks whether a value is a standard service error.
+ */
+export declare function isServiceError(value: unknown): value is ServiceError;
+/**
+ * Serialises a standard service error without leaking stack traces or causes.
+ */
+export declare function serializeServiceError(error: ServiceError, options?: SerializeServiceErrorOptions): SerializedServiceError;
+/**
+ * Converts unknown thrown values into a standard service error.
+ */
+export declare function normalizeServiceError(error: unknown, options?: ServiceErrorOptions): ServiceError;
+/**
+ * Builds a serialised response directly from a global error code.
+ */
+export declare function createErrorResponse(code: GlobalErrorCode, options?: ServiceErrorOptions): SerializedServiceError;

package/dist/errors.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceError = void 0;
+exports.createServiceError = createServiceError;
+exports.isServiceError = isServiceError;
+exports.serializeServiceError = serializeServiceError;
+exports.normalizeServiceError = normalizeServiceError;
+exports.createErrorResponse = createErrorResponse;
+const bigfootds_shared_data_1 = require("@bigfootds/bigfootds-shared-data");
+/**
+ * Error class backed by the shared global error catalogue.
+ */
+class ServiceError extends Error {
+    code;
+    httpStatus;
+    requestId;
+    safeDetails;
+    constructor(code, options = {}) {
+        const definition = (0, bigfootds_shared_data_1.getErrorCodeDefinition)(code);
+        const message = options.message ?? definition?.defaultMessage ?? "Something went wrong.";
+        const errorOptions = options.cause === undefined ? undefined : { cause: options.cause };
+        super(message, errorOptions);
+        this.name = "ServiceError";
+        this.code = code;
+        this.httpStatus = options.httpStatus ?? definition?.defaultHttpStatus ?? 500;
+        if (options.requestId !== undefined) {
+            this.requestId = options.requestId;
+        }
+        if (options.safeDetails !== undefined) {
+            this.safeDetails = options.safeDetails;
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+exports.ServiceError = ServiceError;
+/**
+ * Creates a standard service error.
+ */
+function createServiceError(code, options = {}) {
+    return new ServiceError(code, options);
+}
+/**
+ * Checks whether a value is a standard service error.
+ */
+function isServiceError(value) {
+    return value instanceof ServiceError;
+}
+/**
+ * Serialises a standard service error without leaking stack traces or causes.
+ */
+function serializeServiceError(error, options = {}) {
+    const errorData = {
+        code: error.code,
+        message: error.message
+    };
+    const requestId = error.requestId ?? options.requestId;
+    if (requestId !== undefined) {
+        Object.assign(errorData, { requestId });
+    }
+    if (error.safeDetails !== undefined) {
+        Object.assign(errorData, { details: error.safeDetails });
+    }
+    return {
+        httpStatus: error.httpStatus,
+        body: {
+            error: errorData
+        }
+    };
+}
+/**
+ * Converts unknown thrown values into a standard service error.
+ */
+function normalizeServiceError(error, options = {}) {
+    if (isServiceError(error)) {
+        return error;
+    }
+    return createServiceError(bigfootds_shared_data_1.ERROR_CODES.INTERNAL_ERROR, {
+        ...options,
+        cause: options.cause ?? error
+    });
+}
+/**
+ * Builds a serialised response directly from a global error code.
+ */
+function createErrorResponse(code, options = {}) {
+    return serializeServiceError(createServiceError(code, options));
+}

package/dist/express.d.ts

@@ -0,0 +1,55 @@
+import { type ServiceErrorOptions } from "./errors";
+import { type ActiveRequestMetadata, type HeaderRecord } from "./requestIds";
+import { type ServiceCaller, type ServiceCallerPolicy } from "./serviceTokens";
+/**
+ * Request context attached by BigfootDS Express adapters.
+ */
+export interface BigfootDSRequestContext extends ActiveRequestMetadata {
+    readonly serviceCaller?: ServiceCaller;
+}
+/**
+ * Minimal Express-like request shape used by the adapters.
+ */
+export interface ExpressLikeRequest {
+    readonly headers?: HeaderRecord;
+    readonly method?: string;
+    readonly originalUrl?: string;
+    readonly url?: string;
+    bigfootds?: BigfootDSRequestContext;
+}
+/**
+ * Minimal Express-like response shape used by the adapters.
+ */
+export interface ExpressLikeResponse {
+    statusCode?: number;
+    readonly headersSent?: boolean;
+    set?(name: string, value: string): unknown;
+    setHeader?(name: string, value: string): unknown;
+    status?(statusCode: number): ExpressLikeResponse;
+    json?(body: unknown): unknown;
+    send?(body: unknown): unknown;
+    end?(body?: unknown): unknown;
+}
+export type ExpressLikeNextFunction = (error?: unknown) => void;
+export type ExpressLikeMiddleware = (request: ExpressLikeRequest, response: ExpressLikeResponse, next: ExpressLikeNextFunction) => void;
+export type ExpressLikeErrorMiddleware = (error: unknown, request: ExpressLikeRequest, response: ExpressLikeResponse, next: ExpressLikeNextFunction) => void;
+export interface RequestIdMiddlewareOptions {
+    readonly generateRequestId?: () => string;
+    readonly nowMs?: number;
+}
+/**
+ * Creates middleware that resolves, stores, and returns the standard request ID.
+ */
+export declare function requestIdMiddleware(options?: RequestIdMiddlewareOptions): ExpressLikeMiddleware;
+/**
+ * Creates middleware that verifies bearer service-token callers.
+ */
+export declare function serviceTokenMiddleware(policy: ServiceCallerPolicy): ExpressLikeMiddleware;
+/**
+ * Creates Express-style error middleware for standard service responses.
+ */
+export declare function standardErrorHandler(options?: ServiceErrorOptions): ExpressLikeErrorMiddleware;
+/**
+ * Sends a standard unauthenticated error response.
+ */
+export declare function sendUnauthorizedResponse(response: ExpressLikeResponse, requestId?: string): void;

package/dist/express.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestIdMiddleware = requestIdMiddleware;
+exports.serviceTokenMiddleware = serviceTokenMiddleware;
+exports.standardErrorHandler = standardErrorHandler;
+exports.sendUnauthorizedResponse = sendUnauthorizedResponse;
+const bigfootds_shared_data_1 = require("@bigfootds/bigfootds-shared-data");
+const errors_1 = require("./errors");
+const requestIds_1 = require("./requestIds");
+const serviceTokens_1 = require("./serviceTokens");
+/**
+ * Creates middleware that resolves, stores, and returns the standard request ID.
+ */
+function requestIdMiddleware(options = {}) {
+    return (request, response, next) => {
+        const metadata = (0, requestIds_1.createActiveRequestMetadata)(request.headers, options);
+        request.bigfootds = {
+            ...request.bigfootds,
+            ...metadata
+        };
+        (0, requestIds_1.writeRequestIdHeader)(response, metadata.requestId);
+        next();
+    };
+}
+/**
+ * Creates middleware that verifies bearer service-token callers.
+ */
+function serviceTokenMiddleware(policy) {
+    return (request, response, next) => {
+        const context = ensureRequestContext(request, response);
+        const result = (0, serviceTokens_1.verifyServiceTokenFromHeaders)(request.headers, policy);
+        if (!result.ok) {
+            sendSerializedError(response, (0, errors_1.createErrorResponse)(result.errorCode, {
+                requestId: context.requestId,
+                httpStatus: result.httpStatus
+            }));
+            return;
+        }
+        request.bigfootds = {
+            ...context,
+            serviceCaller: result.caller
+        };
+        next();
+    };
+}
+/**
+ * Creates Express-style error middleware for standard service responses.
+ */
+function standardErrorHandler(options = {}) {
+    return (error, request, response, next) => {
+        if (response.headersSent === true) {
+            next(error);
+            return;
+        }
+        const serviceError = (0, errors_1.normalizeServiceError)(error, {
+            ...options,
+            requestId: options.requestId ?? request.bigfootds?.requestId
+        });
+        sendSerializedError(response, (0, errors_1.serializeServiceError)(serviceError, {
+            requestId: options.requestId ?? request.bigfootds?.requestId
+        }));
+    };
+}
+/**
+ * Sends a standard unauthenticated error response.
+ */
+function sendUnauthorizedResponse(response, requestId) {
+    sendSerializedError(response, (0, errors_1.createErrorResponse)(bigfootds_shared_data_1.ERROR_CODES.UNAUTHORIZED, {
+        requestId
+    }));
+}
+function ensureRequestContext(request, response) {
+    if (request.bigfootds !== undefined) {
+        return request.bigfootds;
+    }
+    const metadata = (0, requestIds_1.createActiveRequestMetadata)(request.headers);
+    const context = metadata;
+    request.bigfootds = context;
+    (0, requestIds_1.writeRequestIdHeader)(response, metadata.requestId);
+    return context;
+}
+function sendSerializedError(response, serializedError) {
+    const statusResponse = response.status?.(serializedError.httpStatus) ?? response;
+    if (response.status === undefined) {
+        response.statusCode = serializedError.httpStatus;
+    }
+    if (typeof response.json === "function") {
+        response.json(serializedError.body);
+        return;
+    }
+    const body = JSON.stringify(serializedError.body);
+    if (typeof response.setHeader === "function") {
+        response.setHeader("content-type", "application/json");
+    }
+    else if (typeof response.set === "function") {
+        response.set("content-type", "application/json");
+    }
+    if (typeof statusResponse.send === "function") {
+        statusResponse.send(body);
+        return;
+    }
+    statusResponse.end?.(body);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./requestIds";
+export * from "./errors";
+export * from "./serviceTokens";
+export * from "./express";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./requestIds"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./serviceTokens"), exports);
+__exportStar(require("./express"), exports);

package/dist/requestIds.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Standard request correlation header used by BigfootDS services.
+ */
+export declare const REQUEST_ID_HEADER_NAME = "x-request-id";
+/**
+ * Minimum accepted inbound request ID length.
+ */
+export declare const REQUEST_ID_MIN_LENGTH = 8;
+/**
+ * Maximum accepted inbound request ID length.
+ */
+export declare const REQUEST_ID_MAX_LENGTH = 64;
+/**
+ * Safe ASCII inbound request ID pattern.
+ */
+export declare const REQUEST_ID_PATTERN: RegExp;
+/**
+ * Minimal request-header object shape used by Node and Express.
+ */
+export type HeaderRecord = Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Minimal response-header writer shape used by Node and Express.
+ */
+export interface HeaderWriter {
+    set?(name: string, value: string): unknown;
+    setHeader?(name: string, value: string): unknown;
+}
+/**
+ * Request ID resolution result.
+ */
+export interface RequestIdResolution {
+    /**
+     * Request ID that should be used for logs, responses, and downstream calls.
+     */
+    readonly requestId: string;
+    /**
+     * Whether the request ID was generated locally instead of accepted from inbound headers.
+     */
+    readonly generated: boolean;
+    /**
+     * Inbound header value, when one was present.
+     */
+    readonly inboundRequestId?: string;
+}
+/**
+ * Active request metadata shared by middleware and helper code.
+ */
+export interface ActiveRequestMetadata extends RequestIdResolution {
+    /**
+     * Milliseconds since Unix epoch when request handling started.
+     */
+    readonly startedAtMs: number;
+}
+export interface ResolveRequestIdOptions {
+    /**
+     * Optional generator used by tests or services that need a custom ID source.
+     */
+    readonly generateRequestId?: () => string;
+}
+export interface CreateRequestMetadataOptions extends ResolveRequestIdOptions {
+    /**
+     * Millisecond timestamp to use for the metadata.
+     */
+    readonly nowMs?: number;
+}
+/**
+ * Generates a new request ID using Node's UUID implementation.
+ */
+export declare function generateRequestId(): string;
+/**
+ * Checks whether a raw value is safe to accept as an inbound request ID.
+ */
+export declare function isValidRequestId(value: unknown): value is string;
+/**
+ * Reads a header value from a header record using case-insensitive matching.
+ */
+export declare function getHeaderValue(headers: HeaderRecord | undefined, headerName: string): string | undefined;
+/**
+ * Resolves an accepted inbound request ID or generates a replacement.
+ */
+export declare function resolveRequestId(inboundRequestId?: unknown, options?: ResolveRequestIdOptions): RequestIdResolution;
+/**
+ * Resolves the standard request ID from a header record.
+ */
+export declare function resolveRequestIdFromHeaders(headers: HeaderRecord | undefined, options?: ResolveRequestIdOptions): RequestIdResolution;
+/**
+ * Creates active request metadata from inbound headers.
+ */
+export declare function createActiveRequestMetadata(headers: HeaderRecord | undefined, options?: CreateRequestMetadataOptions): ActiveRequestMetadata;
+/**
+ * Writes the request ID to a response-like object.
+ */
+export declare function writeRequestIdHeader(response: HeaderWriter, requestId: string, headerName?: string): void;

package/dist/requestIds.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_ID_PATTERN = exports.REQUEST_ID_MAX_LENGTH = exports.REQUEST_ID_MIN_LENGTH = exports.REQUEST_ID_HEADER_NAME = void 0;
+exports.generateRequestId = generateRequestId;
+exports.isValidRequestId = isValidRequestId;
+exports.getHeaderValue = getHeaderValue;
+exports.resolveRequestId = resolveRequestId;
+exports.resolveRequestIdFromHeaders = resolveRequestIdFromHeaders;
+exports.createActiveRequestMetadata = createActiveRequestMetadata;
+exports.writeRequestIdHeader = writeRequestIdHeader;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Standard request correlation header used by BigfootDS services.
+ */
+exports.REQUEST_ID_HEADER_NAME = "x-request-id";
+/**
+ * Minimum accepted inbound request ID length.
+ */
+exports.REQUEST_ID_MIN_LENGTH = 8;
+/**
+ * Maximum accepted inbound request ID length.
+ */
+exports.REQUEST_ID_MAX_LENGTH = 64;
+/**
+ * Safe ASCII inbound request ID pattern.
+ */
+exports.REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{8,64}$/;
+/**
+ * Generates a new request ID using Node's UUID implementation.
+ */
+function generateRequestId() {
+    return (0, node_crypto_1.randomUUID)();
+}
+/**
+ * Checks whether a raw value is safe to accept as an inbound request ID.
+ */
+function isValidRequestId(value) {
+    return typeof value === "string" && exports.REQUEST_ID_PATTERN.test(value);
+}
+/**
+ * Reads a header value from a header record using case-insensitive matching.
+ */
+function getHeaderValue(headers, headerName) {
+    if (headers === undefined) {
+        return undefined;
+    }
+    const directValue = readSingleHeaderValue(headers[headerName]);
+    if (directValue !== undefined) {
+        return directValue;
+    }
+    const lowerHeaderName = headerName.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lowerHeaderName) {
+            return readSingleHeaderValue(value);
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolves an accepted inbound request ID or generates a replacement.
+ */
+function resolveRequestId(inboundRequestId, options = {}) {
+    const headerValue = readSingleHeaderValue(inboundRequestId);
+    if (isValidRequestId(headerValue)) {
+        return {
+            requestId: headerValue,
+            generated: false,
+            inboundRequestId: headerValue
+        };
+    }
+    return {
+        requestId: options.generateRequestId?.() ?? generateRequestId(),
+        generated: true,
+        inboundRequestId: headerValue
+    };
+}
+/**
+ * Resolves the standard request ID from a header record.
+ */
+function resolveRequestIdFromHeaders(headers, options = {}) {
+    return resolveRequestId(getHeaderValue(headers, exports.REQUEST_ID_HEADER_NAME), options);
+}
+/**
+ * Creates active request metadata from inbound headers.
+ */
+function createActiveRequestMetadata(headers, options = {}) {
+    return {
+        ...resolveRequestIdFromHeaders(headers, options),
+        startedAtMs: options.nowMs ?? Date.now()
+    };
+}
+/**
+ * Writes the request ID to a response-like object.
+ */
+function writeRequestIdHeader(response, requestId, headerName = exports.REQUEST_ID_HEADER_NAME) {
+    if (typeof response.setHeader === "function") {
+        response.setHeader(headerName, requestId);
+        return;
+    }
+    if (typeof response.set === "function") {
+        response.set(headerName, requestId);
+    }
+}
+function readSingleHeaderValue(value) {
+    if (Array.isArray(value)) {
+        return typeof value[0] === "string" ? value[0] : undefined;
+    }
+    return typeof value === "string" ? value : undefined;
+}

package/dist/serviceTokens.d.ts

@@ -0,0 +1,94 @@
+import { type GlobalErrorCode } from "@bigfootds/bigfootds-shared-data";
+import { type HeaderRecord } from "./requestIds";
+/**
+ * Header populated by `pkg-bigfoot-fetcher` with the caller's package/product name.
+ */
+export declare const SERVICE_CALLER_HEADER_NAME = "productName";
+/**
+ * Standard HTTP authorization header name.
+ */
+export declare const AUTHORIZATION_HEADER_NAME = "authorization";
+/**
+ * Expected authorization scheme for service tokens.
+ */
+export declare const SERVICE_TOKEN_AUTHORIZATION_SCHEME = "Bearer";
+/**
+ * Token accepted for one calling service.
+ */
+export interface ServiceTokenCredential {
+    /**
+     * Canonical caller service ID, such as `ms-auth`.
+     */
+    readonly serviceId: string;
+    /**
+     * Secret token expected for this caller.
+     */
+    readonly token: string;
+}
+/**
+ * Route-level service caller policy.
+ */
+export interface ServiceCallerPolicy {
+    /**
+     * Callers and tokens this target route can authenticate.
+     */
+    readonly acceptedCallers: readonly ServiceTokenCredential[];
+    /**
+     * Optional route-level allowlist. When omitted, all accepted callers are allowed.
+     */
+    readonly allowedServiceIds?: readonly string[];
+    /**
+     * Header used for caller identity. Defaults to `productName`.
+     */
+    readonly serviceIdentityHeaderName?: string;
+    /**
+     * Header used for bearer token authentication. Defaults to `authorization`.
+     */
+    readonly authorizationHeaderName?: string;
+}
+/**
+ * Authenticated service caller identity.
+ */
+export interface ServiceCaller {
+    /**
+     * Canonical service ID after normalisation.
+     */
+    readonly serviceId: string;
+    /**
+     * Raw service identity value declared by the caller.
+     */
+    readonly declaredServiceId: string;
+}
+export type ServiceTokenFailureReason = "missing_service_identity" | "missing_authorization" | "malformed_authorization" | "unknown_service_identity" | "token_mismatch" | "caller_not_allowed";
+export interface ServiceTokenVerificationSuccess {
+    readonly ok: true;
+    readonly caller: ServiceCaller;
+}
+export interface ServiceTokenVerificationFailure {
+    readonly ok: false;
+    readonly reason: ServiceTokenFailureReason;
+    readonly errorCode: GlobalErrorCode;
+    readonly httpStatus: 401 | 403;
+}
+export type ServiceTokenVerificationResult = ServiceTokenVerificationSuccess | ServiceTokenVerificationFailure;
+export interface VerifyServiceTokenInput {
+    readonly authorizationHeader?: string;
+    readonly serviceIdentityHeader?: string;
+    readonly policy: ServiceCallerPolicy;
+}
+/**
+ * Verifies a bearer service token and route-level service caller policy.
+ */
+export declare function verifyServiceToken(input: VerifyServiceTokenInput): ServiceTokenVerificationResult;
+/**
+ * Verifies a service token from request headers.
+ */
+export declare function verifyServiceTokenFromHeaders(headers: HeaderRecord | undefined, policy: ServiceCallerPolicy): ServiceTokenVerificationResult;
+/**
+ * Extracts a bearer token from an Authorization header.
+ */
+export declare function extractBearerToken(authorizationHeader?: string): string | undefined;
+/**
+ * Normalises package-style caller names into canonical BigfootDS project IDs.
+ */
+export declare function normalizeServiceIdentity(serviceIdentity: string): string;

package/dist/serviceTokens.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_TOKEN_AUTHORIZATION_SCHEME = exports.AUTHORIZATION_HEADER_NAME = exports.SERVICE_CALLER_HEADER_NAME = void 0;
+exports.verifyServiceToken = verifyServiceToken;
+exports.verifyServiceTokenFromHeaders = verifyServiceTokenFromHeaders;
+exports.extractBearerToken = extractBearerToken;
+exports.normalizeServiceIdentity = normalizeServiceIdentity;
+const node_crypto_1 = require("node:crypto");
+const bigfootds_shared_data_1 = require("@bigfootds/bigfootds-shared-data");
+const requestIds_1 = require("./requestIds");
+/**
+ * Header populated by `pkg-bigfoot-fetcher` with the caller's package/product name.
+ */
+exports.SERVICE_CALLER_HEADER_NAME = "productName";
+/**
+ * Standard HTTP authorization header name.
+ */
+exports.AUTHORIZATION_HEADER_NAME = "authorization";
+/**
+ * Expected authorization scheme for service tokens.
+ */
+exports.SERVICE_TOKEN_AUTHORIZATION_SCHEME = "Bearer";
+/**
+ * Verifies a bearer service token and route-level service caller policy.
+ */
+function verifyServiceToken(input) {
+    const declaredServiceId = input.serviceIdentityHeader?.trim();
+    if (declaredServiceId === undefined || declaredServiceId === "") {
+        return unauthenticated("missing_service_identity");
+    }
+    const bearerToken = extractBearerToken(input.authorizationHeader);
+    if (bearerToken === undefined) {
+        return unauthenticated(input.authorizationHeader === undefined ? "missing_authorization" : "malformed_authorization");
+    }
+    const serviceId = normalizeServiceIdentity(declaredServiceId);
+    const credential = input.policy.acceptedCallers.find((candidate) => normalizeServiceIdentity(candidate.serviceId) === serviceId);
+    if (credential === undefined) {
+        return unauthenticated("unknown_service_identity");
+    }
+    if (!tokensMatch(bearerToken, credential.token)) {
+        return unauthenticated("token_mismatch");
+    }
+    if (!isCallerAllowed(serviceId, input.policy.allowedServiceIds)) {
+        return {
+            ok: false,
+            reason: "caller_not_allowed",
+            errorCode: bigfootds_shared_data_1.ERROR_CODES.SERVICE_FORBIDDEN,
+            httpStatus: 403
+        };
+    }
+    return {
+        ok: true,
+        caller: {
+            serviceId,
+            declaredServiceId
+        }
+    };
+}
+/**
+ * Verifies a service token from request headers.
+ */
+function verifyServiceTokenFromHeaders(headers, policy) {
+    return verifyServiceToken({
+        authorizationHeader: (0, requestIds_1.getHeaderValue)(headers, policy.authorizationHeaderName ?? exports.AUTHORIZATION_HEADER_NAME),
+        serviceIdentityHeader: (0, requestIds_1.getHeaderValue)(headers, policy.serviceIdentityHeaderName ?? exports.SERVICE_CALLER_HEADER_NAME),
+        policy
+    });
+}
+/**
+ * Extracts a bearer token from an Authorization header.
+ */
+function extractBearerToken(authorizationHeader) {
+    if (authorizationHeader === undefined) {
+        return undefined;
+    }
+    const [scheme, token, extra] = authorizationHeader.trim().split(/\s+/);
+    if (extra !== undefined ||
+        scheme?.toLowerCase() !== exports.SERVICE_TOKEN_AUTHORIZATION_SCHEME.toLowerCase() ||
+        token === undefined ||
+        token === "") {
+        return undefined;
+    }
+    return token;
+}
+/**
+ * Normalises package-style caller names into canonical BigfootDS project IDs.
+ */
+function normalizeServiceIdentity(serviceIdentity) {
+    const trimmed = serviceIdentity.trim().toLowerCase();
+    return trimmed.startsWith("@bigfootds/") ? trimmed.slice("@bigfootds/".length) : trimmed;
+}
+function unauthenticated(reason) {
+    const errorCode = reason === "missing_service_identity" || reason === "missing_authorization"
+        ? bigfootds_shared_data_1.ERROR_CODES.SERVICE_TOKEN_MISSING
+        : bigfootds_shared_data_1.ERROR_CODES.SERVICE_TOKEN_INVALID;
+    return {
+        ok: false,
+        reason,
+        errorCode,
+        httpStatus: 401
+    };
+}
+function isCallerAllowed(serviceId, allowedServiceIds) {
+    if (allowedServiceIds === undefined) {
+        return true;
+    }
+    return allowedServiceIds.map(normalizeServiceIdentity).includes(serviceId);
+}
+function tokensMatch(actualToken, expectedToken) {
+    const actual = Buffer.from(actualToken);
+    const expected = Buffer.from(expectedToken);
+    if (actual.length !== expected.length) {
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(actual, expected);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@bigfootds/bigfootds-service-utils",
+  "version": "0.1.0",
+  "description": "Reusable service-side utilities for BigfootDS microservices.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./requestIds": {
+      "types": "./dist/requestIds.d.ts",
+      "require": "./dist/requestIds.js",
+      "default": "./dist/requestIds.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "require": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    },
+    "./serviceTokens": {
+      "types": "./dist/serviceTokens.d.ts",
+      "require": "./dist/serviceTokens.js",
+      "default": "./dist/serviceTokens.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "require": "./dist/express.js",
+      "default": "./dist/express.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BigfootDS/pkg-service-utils.git"
+  },
+  "keywords": [],
+  "author": "Alex Stormwood <alex.stormwood@bigfootds.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/BigfootDS/pkg-service-utils/issues"
+  },
+  "homepage": "https://github.com/BigfootDS/pkg-service-utils#readme",
+  "dependencies": {
+    "@bigfootds/bigfootds-shared-data": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  }
+}