@mi9-identity/auth-middleware-express 1.0.0

package/dist/type-guards.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Narrowing type guards, duplicated per package by design (see CLAUDE.md) —
+ * mirrored from the identity service's canonical `utils/type-guards.ts`, plus
+ * a package-local `isFunction` (the canonical set has no function guard).
+ */
+/**
+ * Strict null check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null } True iff `value === null`.
+ * @example
+ * isNull(null); // true
+ * isNull(undefined); // false
+ * isNull(0); // false
+ * isNull(''); // false
+ */
+export declare const isNull: (value: unknown) => value is null;
+/**
+ * Strict undefined check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is undefined } True iff `value === undefined`.
+ * @example
+ * isUndefined(undefined); // true
+ * isUndefined(null); // false
+ * isUndefined(0); // false
+ */
+export declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Nullish check (null or undefined).
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null | undefined } True iff `value` is null or undefined.
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ */
+export declare const isNil: (value: unknown) => value is null | undefined;
+/**
+ * Primitive string check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is string } True iff `typeof value === 'string'`.
+ * @example
+ * isString('hello'); // true
+ * isString(''); // true
+ * isString(42); // false
+ * isString(new String('hello')); // false (boxed String, not primitive)
+ */
+export declare const isString: (value: unknown) => value is string;
+/**
+ * Narrowing return type for `isEmpty`. Listed unions are the structural
+ * "empty" shapes; the negation `!isEmpty(x)` strips `null | undefined`
+ * (and the empty literal forms where TS retains discrimination), so a
+ * `string | undefined` source narrows to `string` after a non-empty check.
+ */
+type EmptyValue = null | undefined | '' | readonly never[] | Map<unknown, never> | Set<never> | Record<string, never>;
+/**
+ * Empty-shape check (nullish, empty string, array, Map, Set, or plain object). Numbers and booleans are never empty.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is EmptyValue } True iff `value` is an empty shape.
+ * @example
+ * isEmpty(null); // true
+ * isEmpty(undefined); // true
+ * isEmpty(''); // true
+ * isEmpty([]); // true
+ * isEmpty({}); // true
+ * isEmpty(new Map()); // true
+ * isEmpty(new Set()); // true
+ * isEmpty('hello'); // false
+ * isEmpty(0); // false
+ * isEmpty(false); // false
+ * isEmpty([0]); // false
+ * isEmpty({ a: undefined }); // false (key still counted)
+ */
+export declare const isEmpty: (value: unknown) => value is EmptyValue;
+/**
+ * Callable check. Narrowing preserves the callable member of a union so the
+ * value stays invocable with its original signature.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is (...args: never[]) => unknown } True iff `typeof value === 'function'`.
+ * @example
+ * isFunction(() => 1); // true
+ * isFunction(class {}); // true (classes are callable)
+ * isFunction(42); // false
+ */
+export declare const isFunction: (value: unknown) => value is (...args: never[]) => unknown;
+export {};
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/type-guards.js

@@ -0,0 +1,102 @@
+/**
+ * Narrowing type guards, duplicated per package by design (see CLAUDE.md) —
+ * mirrored from the identity service's canonical `utils/type-guards.ts`, plus
+ * a package-local `isFunction` (the canonical set has no function guard).
+ */
+/**
+ * Strict null check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null } True iff `value === null`.
+ * @example
+ * isNull(null); // true
+ * isNull(undefined); // false
+ * isNull(0); // false
+ * isNull(''); // false
+ */
+export const isNull = (value) => value === null;
+/**
+ * Strict undefined check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is undefined } True iff `value === undefined`.
+ * @example
+ * isUndefined(undefined); // true
+ * isUndefined(null); // false
+ * isUndefined(0); // false
+ */
+export const isUndefined = (value) => value === undefined;
+/**
+ * Nullish check (null or undefined).
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null | undefined } True iff `value` is null or undefined.
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ */
+export const isNil = (value) => isNull(value) || isUndefined(value);
+/**
+ * Primitive string check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is string } True iff `typeof value === 'string'`.
+ * @example
+ * isString('hello'); // true
+ * isString(''); // true
+ * isString(42); // false
+ * isString(new String('hello')); // false (boxed String, not primitive)
+ */
+export const isString = (value) => typeof value === 'string';
+/**
+ * Empty-shape check (nullish, empty string, array, Map, Set, or plain object). Numbers and booleans are never empty.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is EmptyValue } True iff `value` is an empty shape.
+ * @example
+ * isEmpty(null); // true
+ * isEmpty(undefined); // true
+ * isEmpty(''); // true
+ * isEmpty([]); // true
+ * isEmpty({}); // true
+ * isEmpty(new Map()); // true
+ * isEmpty(new Set()); // true
+ * isEmpty('hello'); // false
+ * isEmpty(0); // false
+ * isEmpty(false); // false
+ * isEmpty([0]); // false
+ * isEmpty({ a: undefined }); // false (key still counted)
+ */
+export const isEmpty = (value) => {
+    if (isNil(value)) {
+        return true;
+    }
+    if (isString(value)) {
+        return value.length === 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (value instanceof Map || value instanceof Set) {
+        return value.size === 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+};
+/**
+ * Callable check. Narrowing preserves the callable member of a union so the
+ * value stays invocable with its original signature.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is (...args: never[]) => unknown } True iff `typeof value === 'function'`.
+ * @example
+ * isFunction(() => 1); // true
+ * isFunction(class {}); // true (classes are callable)
+ * isFunction(42); // false
+ */
+export const isFunction = (value) => typeof value === 'function';
+//# sourceMappingURL=type-guards.js.map

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+import type { Verifier } from '@mi9-identity/jwt-verifier';
+import type { VerifierError } from './errors.js';
+/**
+ * Structured event the middleware emits on every auth attempt. Field shape
+ * is a CONTRACT — BigQuery sinks consume it directly, and the issuer's audit
+ * pipeline mirrors these field names. Don't rename or drop.
+ */
+export interface AuthEvent {
+    event: 'auth_succeeded' | 'auth_failed';
+    request_id: string;
+    client_id?: string;
+    retailer_code?: string;
+    product?: string;
+    success: boolean;
+    latency_ms: number;
+    jti?: string;
+    failure_reason?: 'missing_token' | 'invalid_token' | 'token_expired' | 'issuer_not_allowed' | 'audience_mismatch' | 'algorithm_not_allowed' | 'missing_required_claim' | 'insufficient_scope' | 'retailer_mismatch' | 'jwks_unavailable';
+}
+/**
+ * Shape returned by `onError`. The adapter writes `status`, optionally sets
+ * `headers`, and JSON-encodes `body`.
+ */
+export interface ErrorResponse {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration for `mi9Auth`. The verifier is required; everything else is
+ * defaulted. Pass `onError` to override the RFC 6750 mapping with your own
+ * envelope (e.g. matching an existing API error contract).
+ */
+export interface Mi9AuthOptions {
+    verifier: Verifier;
+    /** Defaults to `'authorization'`. Case-insensitive — Express normalises. */
+    headerName?: string;
+    /** Defaults to `'X-Request-ID'`. Read on inbound (lookup is lowercased per Express convention), propagated to `AuthEvent.request_id`. */
+    requestIdHeader?: string;
+    /** Defaults to no-op. Wire your structured logger here. */
+    onAuthEvent?: (e: AuthEvent) => void;
+    /** Defaults to RFC 6750 §3 mapping (see `default-error-mapping.ts`). */
+    onError?: (err: VerifierError) => ErrorResponse;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@mi9-identity/auth-middleware-express",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Express adapter for the Mi9 JWT verifier — drop-in middleware that verifies Mi9-issued JWTs and attaches AuthContext to req.auth.",
+  "keywords": [
+    "mi9",
+    "identity",
+    "oauth2",
+    "jwt",
+    "rs256",
+    "jwks",
+    "m2m",
+    "express"
+  ],
+  "license": "Apache-2.0",
+  "author": "Mi9 Retail",
+  "homepage": "https://mi9retail.com",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@types/express": "^5.0.0",
+    "express": ">=5.0.0",
+    "@mi9-identity/jwt-verifier": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "24.13.3",
+    "@types/supertest": "7.2.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "express": "5.2.1",
+    "supertest": "7.2.2",
+    "vitest": "4.1.11",
+    "@mi9-identity/jwt-verifier": "^1.0.0",
+    "@mi9-identity/tsconfig": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "clean": "rimraf dist .turbo"
+  }
+}