@mi9-identity/auth-middleware-express 1.0.0

package/dist/default-error-mapping.js

@@ -0,0 +1,124 @@
+import { AlgorithmNotAllowedError, AudienceMismatchError, InvalidTokenError, IssuerNotAllowedError, JwksUnavailableError, MissingRequiredClaimError, TokenExpiredError, } from '@mi9-identity/jwt-verifier';
+import { isEmpty, isUndefined } from './type-guards.js';
+import { InsufficientScopeError, MissingTokenError, RetailerMismatchError } from './errors.js';
+/**
+ * Sanitize an error message so it can be safely embedded in a
+ * `WWW-Authenticate` `error_description` parameter. RFC 6750 §3 disallows
+ * raw quotes / control chars; collapse them rather than expose
+ * implementation-specific text.
+ *
+ * @param { string } msg The raw error message.
+ * @returns { string } The sanitized, length-capped message.
+ */
+const sanitizeReason = (msg) => msg.replaceAll(/[\p{Cc}"\\]/gu, ' ').slice(0, 256);
+/**
+ * Build the `WWW-Authenticate` header value for a Bearer challenge. Omits
+ * `error=` when `errorCode` is undefined (RFC 6750 §3.1: a request without
+ * authentication info must not advertise a specific error code).
+ *
+ * @param { string | undefined } errorCode The RFC 6750 `error` parameter, or undefined for missing-credentials.
+ * @param { string | undefined } reason Optional `error_description` text.
+ * @param { readonly string[] | undefined } scope Optional list of required scopes for the `scope` parameter.
+ * @returns { string } The fully-formed header value.
+ */
+const wwwAuthenticate = (errorCode, reason, scope) => {
+    if (isUndefined(errorCode)) {
+        // RFC 6750 §3.1: a request without authentication info MUST receive
+        // `WWW-Authenticate: Bearer realm="..."` with no `error=` parameter.
+        // Including one mis-signals "request was malformed" to strict clients.
+        return 'Bearer realm="mi9"';
+    }
+    let header = `Bearer realm="mi9", error="${errorCode}"`;
+    if (!isEmpty(reason)) {
+        header += `, error_description="${sanitizeReason(reason)}"`;
+    }
+    if (!isEmpty(scope)) {
+        // RFC 6750 §3: `scope` lists scopes required for the resource.
+        // Space-delimited per RFC 6749 §3.3. MUST NOT appear more than once.
+        header += `, scope="${scope.join(' ')}"`;
+    }
+    return header;
+};
+/**
+ * Shared response builder for the RFC 6750 token-error classes (everything
+ * except `MissingTokenError`, which omits `error=`).
+ *
+ * @param { string } errorCode The RFC 6750 `error` parameter.
+ * @param { number } status The HTTP status code to return.
+ * @param { VerifierError } err The original error (drives `error_description`).
+ * @param { readonly string[] | undefined } scope Optional list of required scopes.
+ * @returns { ErrorResponse } The wire-shape response.
+ */
+const tokenError = (errorCode, status, err, scope) => ({
+    status,
+    headers: {
+        'WWW-Authenticate': wwwAuthenticate(errorCode, err.message, scope),
+    },
+    body: {
+        error: errorCode,
+        error_description: sanitizeReason(err.message),
+    },
+});
+/**
+ * RFC 6750 §3 default mapping. Keep deterministic: identical input must
+ * always produce identical output for downstream caching / observability.
+ *
+ * @param { VerifierError } err The error to map onto a wire-shape response.
+ * @returns { ErrorResponse } The RFC 6750-compliant response envelope.
+ */
+export const defaultErrorMapping = (err) => {
+    if (err instanceof MissingTokenError) {
+        // RFC 6750 §3.1: omit `error=` for missing-credentials. The body keeps
+        // a JSON envelope for client logs but the `WWW-Authenticate` header
+        // does not advertise a specific error code.
+        return {
+            status: 401,
+            headers: {
+                'WWW-Authenticate': wwwAuthenticate(undefined),
+            },
+            body: {
+                error_description: sanitizeReason(err.message),
+            },
+        };
+    }
+    if (err instanceof InsufficientScopeError) {
+        return tokenError('insufficient_scope', 403, err, err.requiredScopes);
+    }
+    if (err instanceof RetailerMismatchError) {
+        // Mi9-private error code. Token IS valid (signature, exp, aud all
+        // pass) — this is an authorization mismatch, not a scope shortage
+        // (`insufficient_scope`) or a token defect (`invalid_token`). RFC
+        // 6750 §3 does not restrict the `error=` parameter to registered
+        // codes; we use a namespaced private code so observability does not
+        // conflate this with scope failures.
+        return tokenError('mi9_retailer_mismatch', 403, err);
+    }
+    if (err instanceof JwksUnavailableError) {
+        // RFC 6750 §6.2.1 registers only `invalid_request`, `invalid_token`,
+        // `insufficient_scope`. `temporarily_unavailable` is from RFC 6749
+        // §4.1.2.1 (authorization endpoint), not the resource server. Use
+        // `invalid_token` + 503 + Retry-After to convey transience without
+        // emitting an unregistered error code.
+        return {
+            status: 503,
+            headers: {
+                'WWW-Authenticate': wwwAuthenticate('invalid_token', 'JWKS endpoint unavailable'),
+                'Retry-After': '30',
+            },
+            body: {
+                error: 'invalid_token',
+                error_description: 'JWKS endpoint unavailable',
+            },
+        };
+    }
+    if (err instanceof TokenExpiredError ||
+        err instanceof IssuerNotAllowedError ||
+        err instanceof AudienceMismatchError ||
+        err instanceof AlgorithmNotAllowedError ||
+        err instanceof MissingRequiredClaimError ||
+        err instanceof InvalidTokenError) {
+        return tokenError('invalid_token', 401, err);
+    }
+    return tokenError('invalid_token', 401, err);
+};
+//# sourceMappingURL=default-error-mapping.js.map

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+import type { AlgorithmNotAllowedError, AudienceMismatchError, InvalidTokenError, IssuerNotAllowedError, JwksUnavailableError, MissingRequiredClaimError, TokenExpiredError } from '@mi9-identity/jwt-verifier';
+/**
+ * Distinct from the verifier's `InvalidTokenError` family — raised when the
+ * `Authorization` header is absent or not a Bearer token. The default
+ * `onError` maps it to `401` with `WWW-Authenticate: Bearer realm="mi9"` and
+ * NO `error=` parameter, per RFC 6750 §3.1 (a request lacking any
+ * authentication info SHOULD NOT advertise a specific error code).
+ */
+export declare class MissingTokenError extends Error {
+    readonly name: string;
+}
+/**
+ * Insufficient scopes for the current route. Raised by `requireScope` /
+ * `requireAnyScope`. Default mapping: `403 insufficient_scope` (RFC 6750
+ * §6.2.1). When `requiredScopes` is supplied the default mapping appends a
+ * `scope="..."` parameter to `WWW-Authenticate` listing the required scopes.
+ */
+export declare class InsufficientScopeError extends Error {
+    readonly name: string;
+    readonly requiredScopes?: readonly string[];
+    /**
+     * Construct the error with an optional list of scopes that the request was
+     * missing — surfaced in the `WWW-Authenticate: ... scope="..."` parameter.
+     *
+     * @param { string } message Human-readable error message.
+     * @param { readonly string[] | undefined } requiredScopes Scopes required for the route (omitted from the wire when empty).
+     */
+    constructor(message: string, requiredScopes?: readonly string[]);
+}
+/**
+ * Token authenticated but its `retailerId` claim does not match the
+ * resolver value for the current request. Raised by `requireRetailer`.
+ * Distinct from `InsufficientScopeError` — this is an authorization mismatch
+ * on a verified token, not a scope shortage. See default mapping in
+ * `default-error-mapping.ts` for the wire shape.
+ */
+export declare class RetailerMismatchError extends Error {
+    readonly name: string;
+}
+/**
+ * Discriminated union of every error type the default `onError` understands.
+ * Custom handlers can narrow on `instanceof` to override one mapping while
+ * delegating the rest to the default.
+ */
+export type VerifierError = MissingTokenError | InsufficientScopeError | RetailerMismatchError | InvalidTokenError | TokenExpiredError | IssuerNotAllowedError | AudienceMismatchError | AlgorithmNotAllowedError | MissingRequiredClaimError | JwksUnavailableError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,45 @@
+import { isEmpty } from './type-guards.js';
+/**
+ * Distinct from the verifier's `InvalidTokenError` family — raised when the
+ * `Authorization` header is absent or not a Bearer token. The default
+ * `onError` maps it to `401` with `WWW-Authenticate: Bearer realm="mi9"` and
+ * NO `error=` parameter, per RFC 6750 §3.1 (a request lacking any
+ * authentication info SHOULD NOT advertise a specific error code).
+ */
+export class MissingTokenError extends Error {
+    name = 'MissingTokenError';
+}
+/**
+ * Insufficient scopes for the current route. Raised by `requireScope` /
+ * `requireAnyScope`. Default mapping: `403 insufficient_scope` (RFC 6750
+ * §6.2.1). When `requiredScopes` is supplied the default mapping appends a
+ * `scope="..."` parameter to `WWW-Authenticate` listing the required scopes.
+ */
+export class InsufficientScopeError extends Error {
+    name = 'InsufficientScopeError';
+    requiredScopes;
+    /**
+     * Construct the error with an optional list of scopes that the request was
+     * missing — surfaced in the `WWW-Authenticate: ... scope="..."` parameter.
+     *
+     * @param { string } message Human-readable error message.
+     * @param { readonly string[] | undefined } requiredScopes Scopes required for the route (omitted from the wire when empty).
+     */
+    constructor(message, requiredScopes) {
+        super(message);
+        if (!isEmpty(requiredScopes)) {
+            this.requiredScopes = requiredScopes;
+        }
+    }
+}
+/**
+ * Token authenticated but its `retailerId` claim does not match the
+ * resolver value for the current request. Raised by `requireRetailer`.
+ * Distinct from `InsufficientScopeError` — this is an authorization mismatch
+ * on a verified token, not a scope shortage. See default mapping in
+ * `default-error-mapping.ts` for the wire shape.
+ */
+export class RetailerMismatchError extends Error {
+    name = 'RetailerMismatchError';
+}
+//# sourceMappingURL=errors.js.map

package/dist/event.d.ts

@@ -0,0 +1,50 @@
+import type { Request } from 'express';
+import type { AuthContext } from '@mi9-identity/jwt-verifier';
+import type { AuthEvent } from './types.js';
+import type { VerifierError } from './errors.js';
+/**
+ * Default inbound request-id header name. Canonical casing per the design doc;
+ * lookups lowercase it, so the casing is for log readability only. Single
+ * source imported by the adapter and the guards.
+ */
+export declare const DEFAULT_REQUEST_ID_HEADER = "X-Request-ID";
+/**
+ * Read a header by case-insensitive name. Picks the first value when Node has
+ * arrayed the header (rare on `Authorization`-style names but supported by
+ * `IncomingMessage.headers`). Shared by the adapter (Authorization lookup) and
+ * the request-id resolver below.
+ *
+ * @param { Request } req The Express request.
+ * @param { string } name Header name (any casing).
+ * @returns { string | undefined } The header value, or `undefined` when absent.
+ */
+export declare const headerString: (req: Request, name: string) => string | undefined;
+/**
+ * Resolve a stable request id: inbound header → `req.id` (set by id middleware
+ * such as `express-request-id`) → UUID. Identical resolution for adapter and
+ * guards so the same request never produces two different ids in BigQuery.
+ *
+ * @param { Request } req The Express request.
+ * @param { string } headerName Name of the inbound request-id header.
+ * @returns { string } The resolved request id.
+ */
+export declare const resolveRequestId: (req: Request, headerName: string) => string;
+/**
+ * Build the `auth_succeeded` audit event from a verified `AuthContext`.
+ *
+ * @param { AuthContext } ctx The verified auth context.
+ * @param { string } requestId The resolved request id.
+ * @param { number } latencyMs Verification latency in milliseconds.
+ * @returns { AuthEvent } The success-shaped audit event.
+ */
+export declare const buildSuccessEvent: (ctx: AuthContext, requestId: string, latencyMs: number) => AuthEvent;
+/**
+ * Build the `auth_failed` audit event from a verifier or guard error.
+ *
+ * @param { VerifierError } err The error raised by verification or a guard.
+ * @param { string } requestId The resolved request id.
+ * @param { number } latencyMs Verification latency in milliseconds.
+ * @returns { AuthEvent } The failure-shaped audit event.
+ */
+export declare const buildFailureEvent: (err: VerifierError, requestId: string, latencyMs: number) => AuthEvent;
+//# sourceMappingURL=event.d.ts.map

package/dist/event.js

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+import { isEmpty, isString } from './type-guards.js';
+import { failureReasonFor } from './failure-reason.js';
+/**
+ * Default inbound request-id header name. Canonical casing per the design doc;
+ * lookups lowercase it, so the casing is for log readability only. Single
+ * source imported by the adapter and the guards.
+ */
+export const DEFAULT_REQUEST_ID_HEADER = 'X-Request-ID';
+/**
+ * Read a header by case-insensitive name. Picks the first value when Node has
+ * arrayed the header (rare on `Authorization`-style names but supported by
+ * `IncomingMessage.headers`). Shared by the adapter (Authorization lookup) and
+ * the request-id resolver below.
+ *
+ * @param { Request } req The Express request.
+ * @param { string } name Header name (any casing).
+ * @returns { string | undefined } The header value, or `undefined` when absent.
+ */
+export const headerString = (req, name) => {
+    const v = req.headers[name.toLowerCase()];
+    if (isString(v)) {
+        return v;
+    }
+    if (Array.isArray(v) && isString(v[0])) {
+        return v[0];
+    }
+    return undefined;
+};
+/**
+ * Resolve a stable request id: inbound header → `req.id` (set by id middleware
+ * such as `express-request-id`) → UUID. Identical resolution for adapter and
+ * guards so the same request never produces two different ids in BigQuery.
+ *
+ * @param { Request } req The Express request.
+ * @param { string } headerName Name of the inbound request-id header.
+ * @returns { string } The resolved request id.
+ */
+export const resolveRequestId = (req, headerName) => {
+    const fromHeader = headerString(req, headerName);
+    if (!isEmpty(fromHeader)) {
+        return fromHeader;
+    }
+    const reqAny = req;
+    if (isString(reqAny.id) && !isEmpty(reqAny.id)) {
+        return reqAny.id;
+    }
+    return randomUUID();
+};
+/**
+ * Build the `auth_succeeded` audit event from a verified `AuthContext`.
+ *
+ * @param { AuthContext } ctx The verified auth context.
+ * @param { string } requestId The resolved request id.
+ * @param { number } latencyMs Verification latency in milliseconds.
+ * @returns { AuthEvent } The success-shaped audit event.
+ */
+export const buildSuccessEvent = (ctx, requestId, latencyMs) => ({
+    event: 'auth_succeeded',
+    request_id: requestId,
+    client_id: ctx.sub,
+    retailer_code: ctx.retailerId,
+    product: ctx.product,
+    success: true,
+    latency_ms: latencyMs,
+    jti: ctx.jti,
+});
+/**
+ * Build the `auth_failed` audit event from a verifier or guard error.
+ *
+ * @param { VerifierError } err The error raised by verification or a guard.
+ * @param { string } requestId The resolved request id.
+ * @param { number } latencyMs Verification latency in milliseconds.
+ * @returns { AuthEvent } The failure-shaped audit event.
+ */
+export const buildFailureEvent = (err, requestId, latencyMs) => ({
+    event: 'auth_failed',
+    request_id: requestId,
+    success: false,
+    latency_ms: latencyMs,
+    failure_reason: failureReasonFor(err),
+});
+//# sourceMappingURL=event.js.map

package/dist/failure-reason.d.ts

@@ -0,0 +1,12 @@
+import type { AuthEvent } from './types.js';
+import { type VerifierError } from './errors.js';
+/**
+ * Map a verifier or guard error onto its `AuthEvent.failure_reason` string.
+ * Single source of truth so adapter and guard rejections never disagree on
+ * the audit code for the same error class.
+ *
+ * @param { VerifierError } err The verifier or guard error to classify.
+ * @returns { NonNullable<AuthEvent['failure_reason']> } The matching audit `failure_reason` string.
+ */
+export declare const failureReasonFor: (err: VerifierError) => NonNullable<AuthEvent["failure_reason"]>;
+//# sourceMappingURL=failure-reason.d.ts.map

package/dist/failure-reason.js

@@ -0,0 +1,44 @@
+import { AlgorithmNotAllowedError, AudienceMismatchError, InvalidTokenError, IssuerNotAllowedError, JwksUnavailableError, MissingRequiredClaimError, TokenExpiredError, } from '@mi9-identity/jwt-verifier';
+import { InsufficientScopeError, MissingTokenError, RetailerMismatchError } from './errors.js';
+/**
+ * Map a verifier or guard error onto its `AuthEvent.failure_reason` string.
+ * Single source of truth so adapter and guard rejections never disagree on
+ * the audit code for the same error class.
+ *
+ * @param { VerifierError } err The verifier or guard error to classify.
+ * @returns { NonNullable<AuthEvent['failure_reason']> } The matching audit `failure_reason` string.
+ */
+export const failureReasonFor = (err) => {
+    if (err instanceof MissingTokenError) {
+        return 'missing_token';
+    }
+    if (err instanceof InsufficientScopeError) {
+        return 'insufficient_scope';
+    }
+    if (err instanceof RetailerMismatchError) {
+        return 'retailer_mismatch';
+    }
+    if (err instanceof TokenExpiredError) {
+        return 'token_expired';
+    }
+    if (err instanceof IssuerNotAllowedError) {
+        return 'issuer_not_allowed';
+    }
+    if (err instanceof AudienceMismatchError) {
+        return 'audience_mismatch';
+    }
+    if (err instanceof AlgorithmNotAllowedError) {
+        return 'algorithm_not_allowed';
+    }
+    if (err instanceof MissingRequiredClaimError) {
+        return 'missing_required_claim';
+    }
+    if (err instanceof JwksUnavailableError) {
+        return 'jwks_unavailable';
+    }
+    if (err instanceof InvalidTokenError) {
+        return 'invalid_token';
+    }
+    return 'invalid_token';
+};
+//# sourceMappingURL=failure-reason.js.map

package/dist/guards.d.ts

@@ -0,0 +1,47 @@
+import type { Request, RequestHandler } from 'express';
+import type { AuthEvent } from './types.js';
+/**
+ * Configuration for `createGuards`. Pass `onAuthEvent` to surface scope and
+ * retailer rejections in the same structured-event sink the adapter uses —
+ * without it, a guard rejection is honored on the wire but invisible to
+ * BigQuery/audit pipelines.
+ */
+export interface GuardOptions {
+    /** Defaults to no-op. Wire your structured logger here. Mirror of `Mi9AuthOptions.onAuthEvent`. */
+    onAuthEvent?: (e: AuthEvent) => void;
+    /** Defaults to `'X-Request-ID'`. Used only when `mi9Auth` did not stash `req.mi9AuthState` (i.e. guard mounted without the adapter). */
+    requestIdHeader?: string;
+}
+/**
+ * Bundle returned by `createGuards`. Signatures are identical to the legacy
+ * top-level exports, so a consumer migrating only changes the construction
+ * site.
+ */
+export interface Guards {
+    requireScope: (scope: string | readonly string[]) => RequestHandler;
+    requireAnyScope: (scopes: readonly string[]) => RequestHandler;
+    requireRetailer: (resolveExpected: string | ((req: Request) => string)) => RequestHandler;
+}
+/**
+ * Build a guard set bound to a structured-event emitter. Guard rejections
+ * (`insufficient_scope`, `retailer_mismatch`, `missing_token`) emit
+ * `auth_failed` events with the same `request_id` shape as the adapter — so a
+ * single request that verifies but fails authorization produces one
+ * `auth_succeeded` row followed by one `auth_failed` row, both keyed on the
+ * same id. Top-level `requireScope` / `requireAnyScope` / `requireRetailer`
+ * exports are equivalent to `createGuards()` with no event sink.
+ *
+ * @param { GuardOptions } options Guard configuration (`onAuthEvent`, `requestIdHeader`).
+ * @returns { Guards } The bundle of `requireScope` / `requireAnyScope` / `requireRetailer` factories.
+ */
+export declare const createGuards: (options?: GuardOptions) => Guards;
+/**
+ * AND-semantics convenience export bound to a no-op event emitter. Call
+ * `createGuards({ onAuthEvent })` instead when rejections must reach BigQuery.
+ */
+export declare const requireScope: (scope: string | readonly string[]) => RequestHandler;
+/** OR-semantics. See `createGuards` for event wiring. */
+export declare const requireAnyScope: (scopes: readonly string[]) => RequestHandler;
+/** Exact retailer match. See `createGuards` for event wiring. */
+export declare const requireRetailer: (resolveExpected: string | ((req: Request) => string)) => RequestHandler;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.js

@@ -0,0 +1,180 @@
+import { defaultErrorMapping } from './default-error-mapping.js';
+import { isEmpty, isFunction, isString, isUndefined } from './type-guards.js';
+import { buildFailureEvent, DEFAULT_REQUEST_ID_HEADER, resolveRequestId } from './event.js';
+import { InsufficientScopeError, MissingTokenError, RetailerMismatchError } from './errors.js';
+/**
+ * Apply a mapped `ErrorResponse` onto the outbound Express response,
+ * populating headers (when present) and writing the JSON body at the
+ * mapped status.
+ *
+ * @param { Parameters<RequestHandler>[1] } res The Express response.
+ * @param { VerifierError } err The error to map and send.
+ * @returns { void } Nothing.
+ */
+const respondWithError = (res, err) => {
+    const mapped = defaultErrorMapping(err);
+    /* v8 ignore next 5 -- defaultErrorMapping always populates headers for the guard error classes */
+    if (!isUndefined(mapped.headers)) {
+        for (const [k, v] of Object.entries(mapped.headers)) {
+            res.setHeader(k, v);
+        }
+    }
+    res.status(mapped.status).json(mapped.body);
+};
+/**
+ * Return the verified `AuthContext` attached to the request, or throw
+ * `MissingTokenError` if `mi9Auth` did not run before the guard.
+ *
+ * @param { Request } req The Express request.
+ * @returns { AuthContext } The verified auth context.
+ * @throws { MissingTokenError } If no auth context is present on the request.
+ */
+const requireAuth = (req) => {
+    if (isUndefined(req.auth)) {
+        throw new MissingTokenError('mi9Auth middleware did not run before this guard');
+    }
+    return req.auth;
+};
+/**
+ * Coerce a single-scope string or scope list into a `readonly string[]` for
+ * uniform set-membership checks downstream.
+ *
+ * @param { string | readonly string[] } scope The scope or scope list.
+ * @returns { readonly string[] } The normalized scope list.
+ */
+const toScopeList = (scope) => (isString(scope) ? [scope] : scope);
+/**
+ * Build a guard set bound to a structured-event emitter. Guard rejections
+ * (`insufficient_scope`, `retailer_mismatch`, `missing_token`) emit
+ * `auth_failed` events with the same `request_id` shape as the adapter — so a
+ * single request that verifies but fails authorization produces one
+ * `auth_succeeded` row followed by one `auth_failed` row, both keyed on the
+ * same id. Top-level `requireScope` / `requireAnyScope` / `requireRetailer`
+ * exports are equivalent to `createGuards()` with no event sink.
+ *
+ * @param { GuardOptions } options Guard configuration (`onAuthEvent`, `requestIdHeader`).
+ * @returns { Guards } The bundle of `requireScope` / `requireAnyScope` / `requireRetailer` factories.
+ */
+export const createGuards = (options = {}) => {
+    const emit = options.onAuthEvent ?? (() => undefined);
+    const requestIdHeader = options.requestIdHeader ?? DEFAULT_REQUEST_ID_HEADER;
+    const fail = (req, res, err) => {
+        // mi9AuthState is stashed by `mi9Auth` so guard latency spans the
+        // same anchor as the adapter's success event. Absent only when the
+        // adapter never ran — fall back to header/`req.id`/UUID and 0ms.
+        const stashed = req.mi9AuthState;
+        const requestId = stashed?.requestId ?? resolveRequestId(req, requestIdHeader);
+        const latencyMs = isUndefined(stashed) ? 0 : Date.now() - stashed.startedAt;
+        emit(buildFailureEvent(err, requestId, latencyMs));
+        respondWithError(res, err);
+    };
+    /**
+     * AND-semantics: the request's `scopes` must contain every entry in
+     * `scope`. A single string is treated as a one-element array. Use this
+     * when an operation requires multiple scopes simultaneously
+     * (e.g. `['orders:read', 'pos:write']`).
+     *
+     * @param { string | readonly string[] } scope Required scope or scopes.
+     * @returns { RequestHandler } Express middleware that enforces AND-scope semantics.
+     */
+    const requireScope = (scope) => {
+        const required = toScopeList(scope);
+        return (req, res, next) => {
+            let auth;
+            try {
+                auth = requireAuth(req);
+            }
+            catch (err) {
+                fail(req, res, err);
+                return;
+            }
+            const granted = new Set(auth.scopes);
+            const missing = required.filter((s) => !granted.has(s));
+            if (missing.length > 0) {
+                fail(req, res, new InsufficientScopeError(`Missing required scope(s): ${missing.join(' ')}`, required));
+                return;
+            }
+            next();
+        };
+    };
+    /**
+     * OR-semantics: any one of the listed scopes is sufficient. Use this when
+     * an operation can be authorized by alternative scopes (admin OR self).
+     *
+     * @param { readonly string[] } scopes Candidate scopes (at least one must match).
+     * @returns { RequestHandler } Express middleware that enforces OR-scope semantics.
+     * @throws { Error } If `scopes` is empty (wiring bug — surfaced at factory call, not request time).
+     */
+    const requireAnyScope = (scopes) => {
+        const required = Array.from(scopes);
+        if (required.length === 0) {
+            throw new Error('requireAnyScope: `scopes` must contain at least one entry');
+        }
+        return (req, res, next) => {
+            let auth;
+            try {
+                auth = requireAuth(req);
+            }
+            catch (err) {
+                fail(req, res, err);
+                return;
+            }
+            const granted = new Set(auth.scopes);
+            const matched = required.some((s) => granted.has(s));
+            if (!matched) {
+                fail(req, res, new InsufficientScopeError(`Required at least one scope: ${required.join(' ')}`, required));
+                return;
+            }
+            next();
+        };
+    };
+    /**
+     * Exact retailer match — required arg, no defaults. Caller decides whether
+     * to read from `req.params`, a literal, or a header. Resolver throws to
+     * surface "wiring missing" loudly via Express's error handler.
+     *
+     * @param { string | ((req: Request) => string) } resolveExpected Literal retailer id or a resolver function.
+     * @returns { RequestHandler } Express middleware that enforces exact retailer match.
+     */
+    const requireRetailer = (resolveExpected) => {
+        return (req, res, next) => {
+            let auth;
+            try {
+                auth = requireAuth(req);
+            }
+            catch (err) {
+                fail(req, res, err);
+                return;
+            }
+            let expected;
+            try {
+                expected = isFunction(resolveExpected) ? resolveExpected(req) : resolveExpected;
+            }
+            catch (err) {
+                next(err);
+                return;
+            }
+            if (!isString(expected) || isEmpty(expected)) {
+                next(new Error('requireRetailer: resolver returned empty value'));
+                return;
+            }
+            if (auth.retailerId !== expected) {
+                fail(req, res, new RetailerMismatchError('Retailer mismatch: token retailer does not match resource'));
+                return;
+            }
+            next();
+        };
+    };
+    return { requireScope, requireAnyScope, requireRetailer };
+};
+const noEventGuards = createGuards();
+/**
+ * AND-semantics convenience export bound to a no-op event emitter. Call
+ * `createGuards({ onAuthEvent })` instead when rejections must reach BigQuery.
+ */
+export const requireScope = noEventGuards.requireScope;
+/** OR-semantics. See `createGuards` for event wiring. */
+export const requireAnyScope = noEventGuards.requireAnyScope;
+/** Exact retailer match. See `createGuards` for event wiring. */
+export const requireRetailer = noEventGuards.requireRetailer;
+//# sourceMappingURL=guards.js.map

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { AuthContext } from '@mi9-identity/jwt-verifier';
+export { mi9Auth } from './adapter.js';
+export { createGuards, requireAnyScope, requireScope, requireRetailer, type GuardOptions, type Guards } from './guards.js';
+export { defaultErrorMapping } from './default-error-mapping.js';
+export { InsufficientScopeError, MissingTokenError, RetailerMismatchError, type VerifierError } from './errors.js';
+export type { AuthEvent, ErrorResponse, Mi9AuthOptions } from './types.js';
+declare global {
+    namespace Express {
+        interface Request {
+            auth?: AuthContext;
+            /**
+             * Set by `mi9Auth` once the request enters the verifier pipeline.
+             * Read by guards built via `createGuards` so guard-rejection
+             * `auth_failed` rows keep the adapter's `request_id` and measure
+             * latency from the same anchor. Absent when `mi9Auth` did not run.
+             */
+            mi9AuthState?: {
+                startedAt: number;
+                requestId: string;
+            };
+        }
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+export { mi9Auth } from './adapter.js';
+export { createGuards, requireAnyScope, requireScope, requireRetailer } from './guards.js';
+export { defaultErrorMapping } from './default-error-mapping.js';
+export { InsufficientScopeError, MissingTokenError, RetailerMismatchError } from './errors.js';
+//# sourceMappingURL=index.js.map