@exortek/apikey 1.0.0

package/dist/internal/guards.d.ts

@@ -0,0 +1,4 @@
+export const invalidArgument: (msg: string, extra?: WrapExtra) => Error;
+export const parse: (schema: ParseableSchema, input: unknown, path?: string) => unknown;
+export const assertObject: (value: unknown, name: string, opts?: AssertOptions) => void;
+export const assertNonEmptyString: (value: unknown, name: string, opts?: AssertOptions) => void;

package/dist/middleware/core.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Normalize + validate middleware options. Throws `ApiKeyError` on
+ * misconfig so the mistake surfaces at boot, not per-request.
+ *
+ * @param {ApiKeyMiddlewareOptions} options
+ */
+export function normalizeOptions(options: ApiKeyMiddlewareOptions): {
+    store: import("../index.js").ApiKeyStore;
+    peppers: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    requiredScopes: string[] | undefined;
+    expectedPrefix: string | undefined;
+    updateLastUsed: boolean;
+    headerName: string;
+    scheme: "bearer" | "raw";
+    allowQueryParam: boolean;
+    queryParamName: string;
+    attach: string;
+    tokenFromRequest: ((ctx: AdapterContext) => string | undefined) | undefined;
+};
+/**
+ * Extract the raw key from a request context per the configured
+ * scheme. Returns `null` when no candidate was found (the caller then
+ * responds with 401 `missing_key`).
+ *
+ * @param {AdapterContext} ctx
+ * @param {ReturnType<typeof normalizeOptions>} config
+ * @returns {string | null}
+ */
+export function extractKey(ctx: AdapterContext, config: ReturnType<typeof normalizeOptions>): string | null;
+/**
+ * Run the verify against the request. Returns a discriminated result:
+ * on success the caller attaches `verifyResult` to the request and
+ * proceeds; on failure the caller sends the returned `response`.
+ *
+ * @param {AdapterContext} ctx
+ * @param {ReturnType<typeof normalizeOptions>} config
+ * @returns {Promise<AdapterResult>}
+ */
+export function runApiKey(ctx: AdapterContext, config: ReturnType<typeof normalizeOptions>): Promise<AdapterResult>;
+export type AdapterContext = {
+    getHeader: (name: string) => string | undefined;
+    method?: string | undefined;
+    ip?: string | undefined;
+    query?: Record<string, unknown> | undefined;
+};
+export type ApiKeyMiddlewareOptions = {
+    store: import("../index.js").ApiKeyStore;
+    peppers?: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    requiredScopes?: string[] | undefined;
+    expectedPrefix?: string | undefined;
+    updateLastUsed?: boolean | undefined;
+    /**
+     * Case-insensitive. The default reads `Authorization: Bearer <key>`;
+     * a `x-api-key` config reads `X-API-Key: <key>` directly.
+     */
+    headerName?: string | undefined;
+    /**
+     * `'bearer'` expects `Bearer <key>`; `'raw'` uses the header value as-is.
+     */
+    scheme?: "bearer" | "raw" | undefined;
+    /**
+     * When true, falls back to `?api_key=<key>` if no matching header is
+     * found. Discouraged because query strings leak into access logs and
+     * referer headers — off by default.
+     */
+    allowQueryParam?: boolean | undefined;
+    queryParamName?: string | undefined;
+    /**
+     * Property name attached to the request object on success.
+     */
+    attach?: string | undefined;
+    /**
+     * Override the default extraction entirely.
+     */
+    tokenFromRequest?: ((ctx: AdapterContext) => string | undefined) | undefined;
+};
+export type AdapterResult = {
+    verifyResult: import("../index.js").VerifyApiKeyResult;
+    response?: {
+        status: number;
+        body: {
+            error: string;
+            reason?: string;
+        };
+    };
+};