webhook-delivery-engine 0.0.0-stage → 1.0.0

package/dist/src/features/ingestion/ingestion.handler.d.ts

@@ -0,0 +1,81 @@
+import type { DatabaseAdapter } from '../../core/ports.js';
+/**
+ * Input required to accept one validated ingestion request.
+ *
+ * The host-configured client identity is supplied separately from parsed
+ * request data. The database dependency is limited to the canonical atomic
+ * upsert operation.
+ */
+export interface HandleIngestionInput {
+    /** Tenant identity configured by the host for this engine instance. */
+    readonly clientId: string;
+    /** Parsed request body, validated by the handler before use. */
+    readonly body: unknown;
+    /** Configured HTTPS destination used when the request omits its destination. */
+    readonly defaultDestinationUrl: string;
+    /** Persistence capability used to atomically insert or replay the event. */
+    readonly database: Pick<DatabaseAdapter, 'upsertEvent'>;
+}
+/**
+ * Accepted ingestion acknowledgment returned for new events and replays.
+ *
+ * `status` represents the accepted enqueue acknowledgment, not a current event
+ * state lookup; a previously accepted event may already have advanced.
+ */
+export interface IngestionAcceptedResponse {
+    /** HTTP status code for an eventual transport adapter. */
+    readonly statusCode: 202;
+    /** Stable acknowledgment fields for an accepted or replayed event. */
+    readonly body: {
+        /** System-generated id of the stored event. */
+        readonly id: string;
+        /** Tenant-scoped client idempotency key. */
+        readonly idempotency_key: string;
+        /** Whether the database returned an existing tenant/key match. */
+        readonly idempotent_replay: boolean;
+        /** Enqueue acknowledgment state required by the ingestion contract. */
+        readonly status: 'pending';
+    };
+}
+/**
+ * Non-storage failure results returned by the ingestion handler.
+ *
+ * Persistence failures reject the handler promise so callers cannot mistake
+ * an unavailable database for an accepted event.
+ */
+export type IngestionHandlerFailure = {
+    readonly statusCode: 400;
+    readonly body: {
+        readonly error: 'invalid_request';
+    };
+} | {
+    readonly statusCode: 422;
+    readonly body: {
+        readonly error: 'invalid_destination';
+    };
+} | {
+    readonly statusCode: 500;
+    readonly body: {
+        readonly error: 'invalid_default_destination';
+    };
+};
+/**
+ * Discriminated result of handling one ingestion request.
+ */
+export type IngestionHandlerResult = IngestionAcceptedResponse | IngestionHandlerFailure;
+/**
+ * Validates and atomically persists one webhook event request.
+ *
+ * The request schema rejects caller-supplied identity and unknown properties.
+ * An omitted destination uses the configured fallback, and both supplied and
+ * fallback URLs are checked by the same fail-closed SSRF validator before
+ * persistence. The system-generated event id and UTC timestamps are created
+ * in this function. Idempotency and replay identity are delegated to the
+ * adapter's atomic `(clientId, idempotencyKey)` upsert.
+ *
+ * @param input Host-configured identity, parsed input, configured fallback,
+ * and the adapter upsert capability.
+ * @returns A stable accepted response or a safe validation failure result.
+ * @throws When the database adapter rejects the upsert operation.
+ */
+export declare function handleIngestion(input: HandleIngestionInput): Promise<IngestionHandlerResult>;

package/dist/src/features/ingestion/ingestion.handler.js

@@ -0,0 +1,59 @@
+import { randomUUID } from 'node:crypto';
+import { validateDestinationUrl } from '../../security/ssrf.js';
+import { ingestionRequestSchema } from './ingestion.schema.js';
+/**
+ * Validates and atomically persists one webhook event request.
+ *
+ * The request schema rejects caller-supplied identity and unknown properties.
+ * An omitted destination uses the configured fallback, and both supplied and
+ * fallback URLs are checked by the same fail-closed SSRF validator before
+ * persistence. The system-generated event id and UTC timestamps are created
+ * in this function. Idempotency and replay identity are delegated to the
+ * adapter's atomic `(clientId, idempotencyKey)` upsert.
+ *
+ * @param input Host-configured identity, parsed input, configured fallback,
+ * and the adapter upsert capability.
+ * @returns A stable accepted response or a safe validation failure result.
+ * @throws When the database adapter rejects the upsert operation.
+ */
+export async function handleIngestion(input) {
+    const parsed = ingestionRequestSchema.safeParse(input.body);
+    if (!parsed.success) {
+        return { statusCode: 400, body: { error: 'invalid_request' } };
+    }
+    const usesDefaultDestination = parsed.data.destination_url === undefined;
+    const destinationUrl = parsed.data.destination_url ?? input.defaultDestinationUrl;
+    const validation = await validateDestinationUrl(destinationUrl);
+    if (!validation.valid) {
+        return usesDefaultDestination
+            ? { statusCode: 500, body: { error: 'invalid_default_destination' } }
+            : { statusCode: 422, body: { error: 'invalid_destination' } };
+    }
+    const timestamp = new Date().toISOString();
+    const event = {
+        id: randomUUID(),
+        idempotencyKey: parsed.data.idempotency_key,
+        clientId: input.clientId,
+        destinationUrl: validation.url,
+        payload: parsed.data.payload,
+        metadata: {},
+        headers: {},
+        status: 'pending',
+        attemptCount: 0,
+        nextRetryAt: null,
+        lockedAt: null,
+        lockedBy: null,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+    };
+    const upsertResult = await input.database.upsertEvent(event);
+    return {
+        statusCode: 202,
+        body: {
+            id: upsertResult.event.id,
+            idempotency_key: upsertResult.event.idempotencyKey,
+            idempotent_replay: !upsertResult.inserted,
+            status: 'pending',
+        },
+    };
+}

package/dist/src/features/ingestion/ingestion.routes.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DatabaseAdapter } from '../../core/ports.js';
+import type { ApiKeyAuthenticationResult } from '../../security/auth.js';
+export interface IngestionRouteOptions {
+    readonly request: IncomingMessage;
+    readonly response: ServerResponse;
+    readonly authentication: ApiKeyAuthenticationResult;
+    readonly database: Pick<DatabaseAdapter, 'upsertEvent'>;
+    readonly defaultDestinationUrl: string;
+}
+/** Maps a raw HTTP ingestion request onto the canonical ingestion handler. */
+export declare function handleIngestionRoute(options: IngestionRouteOptions): Promise<void>;

package/dist/src/features/ingestion/ingestion.routes.js

@@ -0,0 +1,25 @@
+import { handleIngestion } from './ingestion.handler.js';
+import { readJsonBody, sendJson } from '../http/http.responses.js';
+/** Maps a raw HTTP ingestion request onto the canonical ingestion handler. */
+export async function handleIngestionRoute(options) {
+    let body;
+    try {
+        body = await readJsonBody(options.request);
+    }
+    catch {
+        sendJson(options.response, 400, { error: 'invalid_request' });
+        return;
+    }
+    try {
+        const result = await handleIngestion({
+            authentication: options.authentication,
+            body,
+            database: options.database,
+            defaultDestinationUrl: options.defaultDestinationUrl,
+        });
+        sendJson(options.response, result.statusCode, result.body);
+    }
+    catch {
+        sendJson(options.response, 503, { error: 'service_unavailable' });
+    }
+}

package/dist/src/features/ingestion/ingestion.schema.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import type { JsonValue } from '../../core/types.js';
+/**
+ * Validates the strict public request body for webhook ingestion.
+ *
+ * Client identity and timestamps are deliberately absent because the
+ * configured engine context supplies them. The optional destination URL
+ * is resolved to configuration by the ingestion handler before SSRF checks.
+ */
+export declare const ingestionRequestSchema: z.ZodReadonly<z.ZodObject<{
+    idempotency_key: z.ZodEffects<z.ZodString, string, string>;
+    payload: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    destination_url: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    payload: JsonValue;
+    idempotency_key: string;
+    destination_url?: string | undefined;
+}, {
+    payload: JsonValue;
+    idempotency_key: string;
+    destination_url?: string | undefined;
+}>>;
+/**
+ * The validated shape of the parsed JSON ingestion request body.
+ */
+export type IngestionRequest = z.infer<typeof ingestionRequestSchema>;

package/dist/src/features/ingestion/ingestion.schema.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema).readonly(),
+    z.record(z.string(), jsonValueSchema).readonly(),
+]));
+/**
+ * Validates the strict public request body for webhook ingestion.
+ *
+ * Client identity and timestamps are deliberately absent because the
+ * configured engine context supplies them. The optional destination URL
+ * is resolved to configuration by the ingestion handler before SSRF checks.
+ */
+export const ingestionRequestSchema = z
+    .object({
+    idempotency_key: z.string().refine((value) => value.trim().length > 0),
+    payload: jsonValueSchema,
+    destination_url: z.string().optional(),
+})
+    .strict()
+    .readonly();

package/dist/src/features/query/query.routes.d.ts

@@ -0,0 +1,11 @@
+import type { ServerResponse } from 'node:http';
+import type { DatabaseAdapter } from '../../core/ports.js';
+import type { ApiKeyAuthenticationResult } from '../../security/auth.js';
+export interface QueryRouteOptions {
+    readonly response: ServerResponse;
+    readonly url: URL;
+    readonly authentication: ApiKeyAuthenticationResult;
+    readonly database: Pick<DatabaseAdapter, 'findEventById' | 'findEventByIdempotencyKey' | 'listEvents' | 'listAttempts'>;
+}
+/** Handles GET collection, event detail, and event-attempt routes. */
+export declare function handleQueryRoute(options: QueryRouteOptions): Promise<void>;

package/dist/src/features/query/query.routes.js

@@ -0,0 +1,99 @@
+import { EVENT_STATUSES } from '../../core/types.js';
+import { InvalidPageCursorError } from '../../core/errors.js';
+import { sendJson, serializeAttempt, serializeEvent } from '../http/http.responses.js';
+const maxPageSize = 1000;
+/** Handles GET collection, event detail, and event-attempt routes. */
+export async function handleQueryRoute(options) {
+    if (!options.authentication.authenticated) {
+        sendJson(options.response, 401, { error: 'unauthorized' });
+        return;
+    }
+    try {
+        if (options.url.pathname === '/webhooks') {
+            await listEvents(options, options.authentication.clientId);
+            return;
+        }
+        const segments = options.url.pathname.split('/').slice(2);
+        if (segments.length < 1 || segments.length > 2) {
+            sendJson(options.response, 404, { error: 'not_found' });
+            return;
+        }
+        let identifier;
+        try {
+            identifier = decodeURIComponent(segments[0] ?? '');
+        }
+        catch {
+            sendJson(options.response, 400, { error: 'invalid_request' });
+            return;
+        }
+        if (identifier.length === 0) {
+            sendJson(options.response, 404, { error: 'not_found' });
+            return;
+        }
+        const isAttempts = segments.length === 2 && segments[1] === 'attempts';
+        if (segments.length === 2 && !isAttempts) {
+            sendJson(options.response, 404, { error: 'not_found' });
+            return;
+        }
+        const clientId = options.authentication.clientId;
+        const event = (await options.database.findEventById(identifier, clientId)) ??
+            (await options.database.findEventByIdempotencyKey(clientId, identifier));
+        if (event === null) {
+            sendJson(options.response, 404, { error: 'not_found' });
+            return;
+        }
+        if (isAttempts) {
+            const attempts = await options.database.listAttempts(event.id, clientId);
+            sendJson(options.response, 200, { items: attempts.map(serializeAttempt) });
+            return;
+        }
+        sendJson(options.response, 200, serializeEvent(event));
+    }
+    catch (error) {
+        if (error instanceof InvalidPageCursorError) {
+            sendJson(options.response, 400, { error: 'invalid_request' });
+            return;
+        }
+        sendJson(options.response, 503, { error: 'service_unavailable' });
+    }
+}
+async function listEvents(options, clientId) {
+    const allowed = new Set(['status', 'limit', 'cursor']);
+    for (const key of options.url.searchParams.keys()) {
+        if (!allowed.has(key) || options.url.searchParams.getAll(key).length !== 1) {
+            sendJson(options.response, 400, { error: 'invalid_request' });
+            return;
+        }
+    }
+    const statusValue = options.url.searchParams.get('status') ?? undefined;
+    if (statusValue !== undefined && !EVENT_STATUSES.includes(statusValue)) {
+        sendJson(options.response, 400, { error: 'invalid_request' });
+        return;
+    }
+    const limitValue = options.url.searchParams.get('limit');
+    const limit = limitValue === null ? 100 : Number(limitValue);
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxPageSize) {
+        sendJson(options.response, 400, { error: 'invalid_request' });
+        return;
+    }
+    const cursor = options.url.searchParams.get('cursor') ?? undefined;
+    try {
+        const page = await options.database.listEvents({
+            clientId,
+            ...(statusValue === undefined ? {} : { status: statusValue }),
+            limit,
+            ...(cursor === undefined ? {} : { cursor }),
+        });
+        sendJson(options.response, 200, {
+            items: page.items.map(serializeEvent),
+            next_cursor: page.nextCursor,
+        });
+    }
+    catch (error) {
+        if (error instanceof InvalidPageCursorError) {
+            sendJson(options.response, 400, { error: 'invalid_request' });
+            return;
+        }
+        sendJson(options.response, 503, { error: 'service_unavailable' });
+    }
+}

package/dist/src/features/scheduler/scheduler.d.ts

@@ -0,0 +1,110 @@
+import type { WebhookEvent } from '../../core/types.js';
+import type { DatabaseAdapter } from '../../core/ports.js';
+import type { EngineConfig } from '../../config/engine.config.js';
+/**
+ * Callback seam invoked once per claimed event.
+ *
+ * The scheduler hands each claimed `WebhookEvent` to this function. Delivery,
+ * HMAC signing, attempt recording, and state transitions are the
+ * responsibility of the worker registered here (WBS 5.x). The scheduler does
+ * not await the callback's promise; in-flight work is the worker's concern.
+ */
+export type OnClaimCallback = (event: WebhookEvent) => void;
+/**
+ * Optional callback invoked when a poll cycle catches a transient adapter
+ * error.
+ *
+ * The scheduler always continues regardless of whether this callback is
+ * supplied. Callers may use this seam to log errors via the structured logger
+ * (WBS 6.3) without introducing a direct logger dependency inside the
+ * scheduler.
+ */
+export type OnPollErrorCallback = (error: unknown) => void;
+/** Callback invoked after stale-lease recovery completes. */
+export type OnRecoveryCallback = (recoveredCount: number) => void;
+/**
+ * Polling loop that coordinates stale-lease recovery and due-event claiming.
+ *
+ * Each cycle:
+ * 1. Calls `DatabaseAdapter.recoverStaleLeases` with the current UTC time and
+ *    the configured `timeoutLimitMs` to return expired processing leases to
+ *    the retry queue.
+ * 2. Calls `DatabaseAdapter.claimDueEvents` with a stable worker id, the
+ *    current UTC time, and the configured `batchSize` to atomically acquire
+ *    up to `batchSize` due events.
+ * 3. Passes each claimed event to the `onClaim` callback (the worker seam).
+ * 4. Sleeps for `pollIntervalMs` before the next cycle when the batch is
+ *    empty; starts the next cycle immediately when work was found.
+ *
+ * Transient errors thrown by either adapter operation are passed to the
+ * optional error callback so the loop continues rather than crashing. The
+ * scheduler does not own logging or register OS signal listeners (SIGINT/
+ * SIGTERM); those responsibilities belong to the composition root and
+ * graceful-shutdown module (WBS 4.2).
+ */
+export declare class ClaimScheduler {
+    private readonly adapter;
+    private readonly config;
+    private readonly onClaim;
+    private readonly onError?;
+    private readonly onRecovery?;
+    /** Stable id stamped on every lease this scheduler instance claims. */
+    private readonly workerId;
+    /** Whether the scheduler's poll loop is currently active. */
+    private running;
+    /** Promise that resolves when the active loop iteration completes. */
+    private loopPromise;
+    /** AbortController used to signal the sleeping poll interval to wake early. */
+    private abortController;
+    /**
+     * Creates a scheduler bound to the given adapter, config, and worker seam.
+     *
+     * @param adapter - The persistence adapter implementing atomic claiming and
+     * stale-lease recovery operations.
+     * @param config - Immutable engine configuration; `concurrency.batchSize`
+     * and `concurrency.pollIntervalMs` govern this scheduler.
+     * @param onClaim - Worker seam called once per claimed event. The scheduler
+     * does not await this callback.
+     * @param onError - Optional callback invoked when a poll cycle catches a
+     * transient adapter error. The scheduler always continues regardless of
+     * whether this is supplied.
+     */
+    constructor(adapter: Pick<DatabaseAdapter, 'recoverStaleLeases' | 'claimDueEvents'>, config: EngineConfig, onClaim: OnClaimCallback, onError?: OnPollErrorCallback | undefined, onRecovery?: OnRecoveryCallback | undefined);
+    /**
+     * Whether the poll loop is currently active.
+     *
+     * Returns `true` from the moment `start()` is called until `stop()` fully
+     * resolves.
+     */
+    get isRunning(): boolean;
+    /**
+     * Starts the poll loop.
+     *
+     * Has no effect when the scheduler is already running — only one loop runs
+     * at a time.
+     */
+    start(): void;
+    /**
+     * Signals the poll loop to stop and waits for the current cycle to finish.
+     *
+     * Safe to call multiple times; resolves immediately when the loop is not
+     * running.
+     */
+    stop(): Promise<void>;
+    /**
+     * The main poll loop. Runs until `signal.aborted`.
+     *
+     * Errors thrown by adapter operations are caught and reported via
+     * `console.error`; the loop continues to the next cycle in all cases.
+     *
+     * @param signal - Abort signal set by `stop()` to terminate the loop.
+     */
+    private runLoop;
+    /**
+     * Sleeps for `ms` milliseconds or until the abort signal fires.
+     *
+     * @param ms - Duration to wait.
+     * @param signal - Abort signal that cancels the sleep early.
+     */
+    private sleep;
+}

package/dist/src/features/scheduler/scheduler.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Polling loop that coordinates stale-lease recovery and due-event claiming.
+ *
+ * Each cycle:
+ * 1. Calls `DatabaseAdapter.recoverStaleLeases` with the current UTC time and
+ *    the configured `timeoutLimitMs` to return expired processing leases to
+ *    the retry queue.
+ * 2. Calls `DatabaseAdapter.claimDueEvents` with a stable worker id, the
+ *    current UTC time, and the configured `batchSize` to atomically acquire
+ *    up to `batchSize` due events.
+ * 3. Passes each claimed event to the `onClaim` callback (the worker seam).
+ * 4. Sleeps for `pollIntervalMs` before the next cycle when the batch is
+ *    empty; starts the next cycle immediately when work was found.
+ *
+ * Transient errors thrown by either adapter operation are passed to the
+ * optional error callback so the loop continues rather than crashing. The
+ * scheduler does not own logging or register OS signal listeners (SIGINT/
+ * SIGTERM); those responsibilities belong to the composition root and
+ * graceful-shutdown module (WBS 4.2).
+ */
+export class ClaimScheduler {
+    adapter;
+    config;
+    onClaim;
+    onError;
+    onRecovery;
+    /** Stable id stamped on every lease this scheduler instance claims. */
+    workerId;
+    /** Whether the scheduler's poll loop is currently active. */
+    running = false;
+    /** Promise that resolves when the active loop iteration completes. */
+    loopPromise = null;
+    /** AbortController used to signal the sleeping poll interval to wake early. */
+    abortController = null;
+    /**
+     * Creates a scheduler bound to the given adapter, config, and worker seam.
+     *
+     * @param adapter - The persistence adapter implementing atomic claiming and
+     * stale-lease recovery operations.
+     * @param config - Immutable engine configuration; `concurrency.batchSize`
+     * and `concurrency.pollIntervalMs` govern this scheduler.
+     * @param onClaim - Worker seam called once per claimed event. The scheduler
+     * does not await this callback.
+     * @param onError - Optional callback invoked when a poll cycle catches a
+     * transient adapter error. The scheduler always continues regardless of
+     * whether this is supplied.
+     */
+    constructor(adapter, config, onClaim, onError, onRecovery) {
+        this.adapter = adapter;
+        this.config = config;
+        this.onClaim = onClaim;
+        this.onError = onError;
+        this.onRecovery = onRecovery;
+        this.workerId = randomUUID();
+    }
+    /**
+     * Whether the poll loop is currently active.
+     *
+     * Returns `true` from the moment `start()` is called until `stop()` fully
+     * resolves.
+     */
+    get isRunning() {
+        return this.running;
+    }
+    /**
+     * Starts the poll loop.
+     *
+     * Has no effect when the scheduler is already running — only one loop runs
+     * at a time.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.abortController = new AbortController();
+        this.loopPromise = this.runLoop(this.abortController.signal);
+    }
+    /**
+     * Signals the poll loop to stop and waits for the current cycle to finish.
+     *
+     * Safe to call multiple times; resolves immediately when the loop is not
+     * running.
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.abortController?.abort();
+        await this.loopPromise;
+        this.loopPromise = null;
+        this.abortController = null;
+    }
+    /**
+     * The main poll loop. Runs until `signal.aborted`.
+     *
+     * Errors thrown by adapter operations are caught and reported via
+     * `console.error`; the loop continues to the next cycle in all cases.
+     *
+     * @param signal - Abort signal set by `stop()` to terminate the loop.
+     */
+    async runLoop(signal) {
+        while (!signal.aborted) {
+            let claimedCount = 0;
+            try {
+                const now = new Date().toISOString();
+                const recoveredCount = await this.adapter.recoverStaleLeases({
+                    now,
+                    timeoutLimitMs: this.config.timeoutLimitMs,
+                });
+                this.onRecovery?.(recoveredCount);
+                const claimed = await this.adapter.claimDueEvents({
+                    workerId: this.workerId,
+                    now,
+                    limit: this.config.concurrency.batchSize,
+                });
+                claimedCount = claimed.length;
+                for (const event of claimed) {
+                    this.onClaim(event);
+                }
+            }
+            catch (error) {
+                // Transient adapter failure — invoke optional error handler and
+                // continue to the next cycle regardless.
+                this.onError?.(error);
+            }
+            // Sleep between cycles when no work was found; skip sleep when the
+            // batch was non-empty to process available work without delay.
+            if (claimedCount === 0 && !signal.aborted) {
+                await this.sleep(this.config.concurrency.pollIntervalMs, signal);
+            }
+        }
+    }
+    /**
+     * Sleeps for `ms` milliseconds or until the abort signal fires.
+     *
+     * @param ms - Duration to wait.
+     * @param signal - Abort signal that cancels the sleep early.
+     */
+    sleep(ms, signal) {
+        return new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(resolve, ms);
+            signal.addEventListener('abort', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { createWebhookEngine } from './app/embedded.js';
+export type { CreateWebhookEngineOptions, EngineListEventsInput, WebhookEngine, } from './app/embedded.js';
+export type { EngineConfig, EngineConcurrency, RetryPolicy } from './config/engine.config.js';
+export type { EventPage, ListEventsInput } from './core/ports.js';
+export type { AttemptRecord, EventStatus, WebhookEvent } from './core/types.js';
+export type { IngestionRequest } from './features/ingestion/ingestion.schema.js';
+export type { LogLevel } from './shared/logger.js';
+export type { IngestionAcceptedResponse, IngestionHandlerFailure, IngestionHandlerResult, } from './features/ingestion/ingestion.handler.js';

package/dist/src/index.js

@@ -0,0 +1 @@
+export { createWebhookEngine } from './app/embedded.js';

package/dist/src/security/auth.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration for the v1 single-key authenticator.
+ */
+export interface ApiKeyAuthenticatorConfig {
+    /** Configured API key accepted by the authenticator. */
+    readonly apiKey: string;
+    /** Tenant identity returned after successful authentication. */
+    readonly clientId: string;
+}
+/**
+ * Result of checking a presented API key.
+ *
+ * Failed authentication always has the same result shape and carries no
+ * credential material.
+ */
+export type ApiKeyAuthenticationResult = {
+    readonly authenticated: true;
+    readonly clientId: string;
+} | {
+    readonly authenticated: false;
+    readonly statusCode: 401;
+};
+/**
+ * Function that authenticates a candidate API key.
+ */
+export type ApiKeyAuthenticator = (candidateToken: string | undefined) => ApiKeyAuthenticationResult;
+/**
+ * Creates an authenticator for one configured API key and tenant identity.
+ *
+ * The configured key is reduced to a fixed-length SHA-256 digest before the
+ * returned function is exposed. Each candidate, including an absent token,
+ * is hashed and compared with `timingSafeEqual`; credentials are never
+ * returned or logged. The HTTP layer maps an unauthorized result to a 401
+ * response.
+ *
+ * @param config - API key and its configured tenant identity.
+ * @returns A function that returns the tenant identity only for a valid key.
+ * @throws {@link TypeError} when either configured value is not a non-empty string.
+ */
+export declare function createApiKeyAuthenticator(config: ApiKeyAuthenticatorConfig): ApiKeyAuthenticator;