@mi9-identity/auth-middleware-express 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# @mi9-identity/auth-middleware-express
+
+All notable changes to this package are documented here. **Manually maintained** —
+versions are semver and the three publishable `@mi9-identity/*` packages are
+released in lockstep at the same version. Releases up to `2026.8.21` used calver
+(`YYYY.M.D`).
+
+## 1.0.0
+
+- **First public release on npmjs.com**, under the **Apache-2.0** license. Earlier versions were published only to an internal Mi9 registry.
+- **Versioning changes from calver (`YYYY.M.D`) to semver**, starting at `1.0.0`. The three `@mi9-identity/*` packages stay in lockstep at one version. Issuer compatibility is still signalled by the `/api/v{N}` URL, not by the package version.
+- **No functional change compared with `2026.8.21`** — same public API, same wire shapes, same behaviour.
+
+## 2026.7.24
+
+- No user-facing changes. Internal: adds a package-local `type-guards.ts` (`isNull` / `isUndefined` / `isNil` / `isString` / `isEmpty` / `isFunction`, not exported from the package entrypoint) and routes the inline nullish, string, empty-length, and callable checks in `adapter.ts`, `guards.ts`, `default-error-mapping.ts`, `errors.ts`, and `event.ts` through it. Every predicate is equivalent to the expression it replaced — no public API, RFC 6750 wire shape, or `AuthEvent` field changed. Lockstep version bump with the rest of the family.
+
+## 2026.6.3
+
+- **BREAKING**: drops Express 4 support. The minimum Express is now 5 (peer `express: ">=5.0.0"`, `@types/express: ^5.0.0`). The adapter source is version-neutral, so no public API or wire-shape changed — but the peer-dep floor is raised. Consumers still on Express 4 must pin the prior `@mi9-identity/*` release. Decision and migration review recorded in ADR-15.
+
+## 2026.6.1
+
+- No user-facing changes. Internal: the case-insensitive header lookup (`headerString`) and the `X-Request-ID` default header are now sourced once from `event.ts` and shared by the adapter and guards (removes a duplicated helper + constant). Lockstep version bump with the rest of the family.
+
+## 2026.5.27
+
+- **Multiple audiences per token** (ADR-6 amended). Follows `@mi9-identity/jwt-verifier` — `AuthContext.aud` widens to `string | string[]`; the scope/retailer guards are unaffected.
+- **`/api/v1` cutover** (ADR-13). Consumers configure the versioned issuer URL; `mi9IdentityEndpoints()` (from `@mi9-identity/jwt-verifier`) derives the endpoints.
+
+## 0.1.0
+
+- Version reset to pre-1.0 (`0.1.0`); the earlier `1.0.0` placeholder is superseded.
+- **Breaking**: follows `@mi9-identity/jwt-verifier@0.1.0` `AuthContext` rename — `requireRetailer` now reads `auth.retailerId` instead of `auth.retailer_id`. Audit-event field names (`retailer_code`, `client_id`, `latency_ms`, …) keep snake_case — independent surface (analyst convention) per ADR-12.
+- Depends on `@mi9-identity/jwt-verifier` (peer, `workspace:^`).

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mi9 Retail
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,234 @@
+# @mi9-identity/auth-middleware-express
+
+Express middleware that verifies Mi9-issued JWTs, attaches `AuthContext` to
+`req.auth`, and ships scope/retailer guard factories. Layered on
+[`@mi9-identity/jwt-verifier`](https://www.npmjs.com/package/@mi9-identity/jwt-verifier).
+
+Apache-2.0-licensed and free to use; access to the Mi9 Identity Platform whose
+tokens it verifies is governed by your commercial agreement with Mi9 Retail.
+
+## Which package do I need?
+
+| Package | Use it when |
+| --- | --- |
+| **`@mi9-identity/auth-middleware-express`** (this one) | Your service **receives** Mi9-issued tokens and is an Express 5 app. |
+| [`@mi9-identity/jwt-verifier`](https://www.npmjs.com/package/@mi9-identity/jwt-verifier) | The same, but not Express — the framework-agnostic verifier this package wraps. Installed alongside this one. |
+| [`@mi9-identity/token-client`](https://www.npmjs.com/package/@mi9-identity/token-client) | Your service **calls** a Mi9 API and needs a token. |
+
+A service that both calls Mi9 APIs and serves Mi9-authenticated requests
+installs the token client too.
+
+## Install
+
+```sh
+npm install @mi9-identity/auth-middleware-express@1.0.0 @mi9-identity/jwt-verifier@1.0.0
+```
+
+`express` is a peer dependency. **Express 5** is required (peer `>=5.0.0`);
+Express 4 is no longer supported. Packages are **ESM-only** and require **Node 24+**.
+
+Versions are **semver**, and the three `@mi9-identity/*` packages
+(`auth-middleware-express`, `jwt-verifier`, `token-client`) are released in
+lockstep at the same version — pin an exact version, not a `^` range. Breaking
+wire changes ship as new API path versions, not as new package majors.
+
+## Configuration
+
+Verifying needs **no credential**: the signing keys are public and served from
+the issuer's JWKS URL. You need two values, both given to you by your Mi9
+contact when your service is registered — the issuer URL, and the audience
+identifier assigned to your service.
+
+Configure one issuer URL and one audience for your own service:
+
+```
+MI9_IDENTITY_ISSUER     # https://identity.mi9retail.com/api/v1  — matches the JWT `iss` claim
+MI9_IDENTITY_AUDIENCE   # this service's own audience identifier (a full URL)
+```
+
+The issuer URL is the **versioned** one, and the JWKS URI is derived from it
+with `mi9IdentityJwksEndpoint(issuer)` from `@mi9-identity/jwt-verifier`.
+Audience values are full URLs (`https://merchant.mi9retail.com/api`), never a
+bare service name.
+
+## Usage
+
+```ts
+import express, { type Request } from 'express';
+import { createVerifier } from '@mi9-identity/jwt-verifier';
+import { mi9Auth, requireRetailer } from '@mi9-identity/auth-middleware-express';
+
+const verifier = createVerifier({
+    jwksUri: process.env.MI9_IDENTITY_JWKS_URI,
+    issuers: ['https://identity.mi9retail.com/api/v1'],
+    audience: 'https://merchant.mi9retail.com/api',
+});
+
+const resolveRetailerCode = (req: Request): string => {
+    const code = req.params.retailerCode;
+    if (typeof code !== 'string' || code.length === 0) {
+        throw new Error('retailerCode path parameter is required');
+    }
+    return code;
+};
+
+const app = express();
+app.use(mi9Auth({ verifier }));
+
+app.get(
+    '/retailer/:retailerCode/orders',
+    requireRetailer(resolveRetailerCode),
+    (req, res) => res.json({ retailer: req.auth?.retailerId }),
+);
+```
+
+> **The scope guards are not usable today.** `requireScope` and
+> `requireAnyScope` are exported and work, but Mi9 credentials are provisioned
+> with an empty authorized-scope list, so issued tokens carry an empty `scope`
+> claim and every scope guard rejects with 403 `insufficient_scope`. Authorize
+> on the retailer, the product or the audience instead. Use the scope guards
+> only once your Mi9 administrator confirms that your credentials carry
+> authorized scopes.
+
+### `Mi9AuthOptions` reference
+
+| Option | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `verifier` | **yes** | — | A `Verifier` from `createVerifier(...)`. |
+| `headerName` | no | `'authorization'` | Inbound header to read the Bearer token from (case-insensitive). |
+| `requestIdHeader` | no | `'X-Request-ID'` | Inbound correlation-id header; its value flows to `AuthEvent.request_id`. |
+| `onAuthEvent` | no | no-op | Sink for the structured `AuthEvent` (wire your logger / analytics here). |
+| `onError` | no | RFC 6750 §3 mapping | Override the error envelope (status + headers + body) — see `defaultErrorMapping`. |
+
+### `req.auth` — `AuthContext`
+
+On a successful verify, `mi9Auth` attaches the verified token payload to
+`req.auth`. The type is `AuthContext` from `@mi9-identity/jwt-verifier`:
+
+```ts
+import type { AuthContext } from '@mi9-identity/jwt-verifier';
+```
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `iss` | `string` | Issuer (versioned, e.g. `…/api/v1`). |
+| `sub` | `string` | **Is the `clientId`** (UUIDv7) — no separate `clientId` claim. |
+| `aud` | `string \| string[]` | Scalar for one audience, array for several. |
+| `exp` / `iat` / `nbf` | `number` | Unix seconds. |
+| `jti` | `string` | Token id. |
+| `scope` | `string` | Raw space-separated scope string. Empty today — see the note under [Usage](#usage). |
+| `scopes` | `readonly string[]` | Pre-split, deduped view of `scope`. Empty today. |
+| `retailerId` | `string` | From the `https://mi9retail.com/retailerId` claim. |
+| `product` | `string` | Product the credential belongs to. |
+| `storeCode` | `string \| null` | Always present; `null` unless the credential is store-bound. |
+
+Issuer-internal claims are stripped by the verifier before `AuthContext` is
+built, so nothing outside this table reaches `req.auth`.
+
+### `createGuards` — guards bound to an audit sink
+
+The top-level `requireScope` / `requireAnyScope` / `requireRetailer` exports are convenience wrappers that emit nothing on rejection. Production consumers should call `createGuards({ onAuthEvent })` so scope and retailer failures land in the same `AuthEvent` stream as token verification failures — otherwise an entire class of authorization rejection becomes invisible to your audit sink.
+
+```ts
+import { createGuards } from '@mi9-identity/auth-middleware-express';
+
+const { requireScope, requireAnyScope, requireRetailer } = createGuards({
+    onAuthEvent: (event) => log.info(event, event.event),
+});
+```
+
+The returned object satisfies the `Guards` interface and is otherwise drop-in compatible with the top-level guard primitives.
+
+### Express version
+
+This adapter requires **Express 5** (peer `>=5.0.0`). The adapter calls
+`next(err)` itself, so `mi9Auth` works without additional wrappers. Express 5
+also propagates rejections from `async` middleware automatically, so any custom
+middleware you write around `req.auth` can be plain `async` — no
+`express-async-handler` needed.
+
+### Default error mapping (RFC 6750 §3)
+
+| Error                          | Status | `WWW-Authenticate` `error=`              | Body `error`         |
+| ------------------------------ | ------ | ---------------------------------------- | -------------------- |
+| `MissingTokenError`            | 401    | _omitted_ (RFC 6750 §3.1)                | _omitted_            |
+| `InvalidTokenError` family¹    | 401    | `invalid_token`                          | `invalid_token`      |
+| `InsufficientScopeError`       | 403    | `insufficient_scope` + `scope="..."`²    | `insufficient_scope` |
+| `RetailerMismatchError`        | 403    | `mi9_retailer_mismatch`⁴                 | `mi9_retailer_mismatch` |
+| `JwksUnavailableError`         | 503    | `invalid_token` + `Retry-After: 30`³     | `invalid_token`      |
+
+¹ Includes `TokenExpiredError`, `IssuerNotAllowedError`, `AudienceMismatchError`, `AlgorithmNotAllowedError`, `MissingRequiredClaimError`, `InvalidTokenError`.
+² `scope="..."` parameter is appended automatically when `requireScope` / `requireAnyScope` is the source. Space-delimited per RFC 6749 §3.3.
+³ `temporarily_unavailable` is registered for the authorization endpoint (RFC 6749 §4.1.2.1), not the resource server. RFC 6750 §6.2.1 registers only `invalid_request`, `invalid_token`, `insufficient_scope`. We use `invalid_token` + 503 + `Retry-After` to convey transience without emitting an unregistered code.
+⁴ Mi9-private (non-standard). The token is fully valid — signature, `exp`, and `aud` all pass — but the `retailerId` claim does not match the resource. Registered codes don't fit: `insufficient_scope` is a scope shortage, `invalid_token` is a token defect. RFC 6750 §3 does not restrict the `error=` parameter to registered codes; the `mi9_` namespace prefix marks it as application-specific.
+
+The body shape is `{ error, error_description }` for every row except `MissingTokenError`. RFC 6750 §3.1 forbids the `error=` parameter on a bare 401 challenge, so `MissingTokenError` emits a body of `{ error_description }` only — clients narrowing on `body.error` must tolerate `undefined`. `defaultErrorMapping` is exported as a load-bearing primitive — consumers who want to override one error class while delegating the rest can compose:
+
+```ts
+mi9Auth({
+    verifier,
+    onError: (err) => err instanceof MyCustomError ? customResponse(err) : defaultErrorMapping(err),
+});
+```
+
+To emit `scope="..."` in your own `InsufficientScopeError` instances, pass the required scope list to the constructor: `new InsufficientScopeError('msg', ['orders:read', 'pos:write'])`.
+
+This RFC 6750 surface, which your resource server returns to **its** callers,
+keeps the snake_case `error` / `error_description` names that RFC 6750 defines.
+It is not the same shape as the issuer's own error envelope, whose
+`errorDescription` field is camelCase — that one is handled by
+[`@mi9-identity/token-client`](https://www.npmjs.com/package/@mi9-identity/token-client).
+
+If you override the envelope via `onError`, keep the `WWW-Authenticate`
+parameters: proxies and clients key off them.
+
+### `AuthEvent` shape is a contract
+
+`onAuthEvent` receives a fixed-shape object that analytics sinks consume.
+Don't rename or drop fields — pass it straight to your structured logger:
+
+```ts
+mi9Auth({ verifier, onAuthEvent: (e) => log.info(e, e.event) });
+```
+
+Field names are **snake_case** by analyst convention, independent of the
+camelCase wire surface:
+
+```ts
+interface AuthEvent {
+    event: 'auth_succeeded' | 'auth_failed';
+    request_id: string;
+    client_id?: string;      // present on success
+    retailer_code?: string;  // present on success
+    product?: string;        // present on success
+    success: boolean;
+    latency_ms: number;
+    jti?: string;            // present on success
+    failure_reason?:         // present on failure
+        | 'missing_token' | 'invalid_token' | 'token_expired'
+        | 'issuer_not_allowed' | 'audience_mismatch' | 'algorithm_not_allowed'
+        | 'missing_required_claim' | 'insufficient_scope'
+        | 'retailer_mismatch' | 'jwks_unavailable';
+}
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Every request 401s with `invalid_token` right after a deploy | The token was signed by a key not yet in the cached JWKS | Self-heals within the verifier's unknown-`kid` cooldown (30 s by default). |
+| Requests 503 with `Retry-After: 30` | `JwksUnavailableError` — the JWKS is unreachable and no fresh cache is left | Transient; confirm the service can reach `${issuer}/.well-known/jwks.json`. |
+| 401 `invalid_token` with `audience_mismatch` in the audit event | The configured audience is a bare name, or does not match the token's `aud` | Set it to the full-URL audience the issuer mints for your service. |
+| Scope rejections never appear in your logs | The top-level guards were used instead of `createGuards({ onAuthEvent })` | Build the guards with `createGuards` so rejections emit an `AuthEvent`. |
+
+---
+
+Inbound verification internals (JWKS caching, key rotation, the error taxonomy)
+live in
+[`@mi9-identity/jwt-verifier`](https://www.npmjs.com/package/@mi9-identity/jwt-verifier);
+outbound token acquisition lives in
+[`@mi9-identity/token-client`](https://www.npmjs.com/package/@mi9-identity/token-client).
+
+## License
+
+Apache-2.0. The full text ships in the package as `LICENSE`.

package/dist/adapter.d.ts

@@ -0,0 +1,12 @@
+import type { RequestHandler } from 'express';
+import type { Mi9AuthOptions } from './types.js';
+/**
+ * Build the Express middleware that verifies the inbound Bearer token,
+ * populates `req.auth`, and emits an `AuthEvent`. Errors short-circuit to
+ * the configured `onError` (default: RFC 6750 §3 mapping).
+ *
+ * @param { Mi9AuthOptions } opts Middleware configuration (verifier, header name, event sink, error mapper).
+ * @returns { RequestHandler } The configured Express request handler.
+ */
+export declare const mi9Auth: (opts: Mi9AuthOptions) => RequestHandler;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.js

@@ -0,0 +1,89 @@
+import { isNull, isUndefined } from './type-guards.js';
+import { defaultErrorMapping } from './default-error-mapping.js';
+import { MissingTokenError } from './errors.js';
+import { buildFailureEvent, buildSuccessEvent, DEFAULT_REQUEST_ID_HEADER, headerString, resolveRequestId } from './event.js';
+/**
+ * RFC 7235 §2.1: scheme name is case-insensitive. RFC 6750 §2.1 permits
+ * one or more SP between scheme and token; HTAB is allowed by RFC 7230 §3.2
+ * for header field whitespace.
+ */
+const BEARER_SCHEME = /^Bearer[ \t]+(.+)$/i;
+const DEFAULT_HEADER_NAME = 'authorization';
+/**
+ * Parse the inbound `Authorization` header into a Bearer token string. Empty,
+ * missing, or non-Bearer headers raise `MissingTokenError` so the adapter can
+ * map them onto the RFC 6750 §3.1 wire shape.
+ *
+ * @param { string | undefined } header The raw `Authorization` header value.
+ * @returns { string } The trimmed Bearer token.
+ * @throws { MissingTokenError } If the header is missing, not a Bearer scheme, or empty after trimming.
+ */
+const extractToken = (header) => {
+    if (isUndefined(header)) {
+        throw new MissingTokenError('Authorization header missing');
+    }
+    const match = BEARER_SCHEME.exec(header);
+    if (isNull(match)) {
+        throw new MissingTokenError('Authorization header is not a Bearer token');
+    }
+    /* v8 ignore next -- regex with one mandatory capture group always populates match[1]; fallback covers TS narrowing */
+    const token = (match[1] ?? '').trim();
+    if (token.length === 0) {
+        throw new MissingTokenError('Bearer token is empty');
+    }
+    return token;
+};
+/**
+ * Build the Express middleware that verifies the inbound Bearer token,
+ * populates `req.auth`, and emits an `AuthEvent`. Errors short-circuit to
+ * the configured `onError` (default: RFC 6750 §3 mapping).
+ *
+ * @param { Mi9AuthOptions } opts Middleware configuration (verifier, header name, event sink, error mapper).
+ * @returns { RequestHandler } The configured Express request handler.
+ */
+export const mi9Auth = (opts) => {
+    const headerName = opts.headerName ?? DEFAULT_HEADER_NAME;
+    const requestIdHeader = opts.requestIdHeader ?? DEFAULT_REQUEST_ID_HEADER;
+    const emitEvent = opts.onAuthEvent ?? (() => undefined);
+    const mapError = opts.onError ?? defaultErrorMapping;
+    return (req, res, next) => {
+        const startedAt = Date.now();
+        const requestId = resolveRequestId(req, requestIdHeader);
+        // Guards built via `createGuards` read this so guard-rejection
+        // `auth_failed` rows keep the same request_id and measure latency
+        // from the same anchor as the adapter's success event.
+        req.mi9AuthState = { startedAt, requestId };
+        const fail = (err) => {
+            const latencyMs = Date.now() - startedAt;
+            emitEvent(buildFailureEvent(err, requestId, latencyMs));
+            const mapped = mapError(err);
+            /* v8 ignore next 5 -- defaultErrorMapping always populates headers; branch covers custom onError that omits them */
+            if (!isUndefined(mapped.headers)) {
+                for (const [k, v] of Object.entries(mapped.headers)) {
+                    res.setHeader(k, v);
+                }
+            }
+            res.status(mapped.status).json(mapped.body);
+        };
+        let token;
+        try {
+            token = extractToken(headerString(req, headerName));
+        }
+        catch (err) {
+            fail(err);
+            return;
+        }
+        opts.verifier
+            .verify(token)
+            .then((ctx) => {
+            req.auth = ctx;
+            const latencyMs = Date.now() - startedAt;
+            emitEvent(buildSuccessEvent(ctx, requestId, latencyMs));
+            next();
+        })
+            .catch((err) => {
+            fail(err);
+        });
+    };
+};
+//# sourceMappingURL=adapter.js.map

package/dist/default-error-mapping.d.ts

@@ -0,0 +1,11 @@
+import type { ErrorResponse } from './types.js';
+import { type VerifierError } from './errors.js';
+/**
+ * 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 declare const defaultErrorMapping: (err: VerifierError) => ErrorResponse;
+//# sourceMappingURL=default-error-mapping.d.ts.map