@mi9-identity/jwt-verifier 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# @mi9-identity/jwt-verifier
+
+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.8.21
+
+- **BREAKING — `mi9IdentityEndpoints()` is replaced by `mi9IdentityJwksEndpoint()`, and it returns a bare `string`.** Inbound verification is this package's only role, so it no longer derives the mint (`/oauth/token`) or credential-claim (`/credentials/me`) URLs; those moved to `mi9IdentityEndpoints()` in `@mi9-identity/token-client`, which returns `{ tokenEndpoint, credentialEndpoint }`. Deriving all three here forced an outbound-only consumer to install this package — and its `jose` dependency — to concatenate two strings.
+
+  Migration is mechanical:
+
+  ```diff
+  - import { mi9IdentityEndpoints } from '@mi9-identity/jwt-verifier';
+  - const { jwksUri } = mi9IdentityEndpoints(issuer);
+  + import { mi9IdentityJwksEndpoint } from '@mi9-identity/jwt-verifier';
+  + const jwksUri = mi9IdentityJwksEndpoint(issuer);
+  ```
+
+  If you read `tokenEndpoint` or `credentialEndpoint` off this package, take them from `@mi9-identity/token-client` instead. TypeScript flags every affected call site — there is no silent-`undefined` path. Trailing-slash stripping and the no-`/api/v{N}`-literal guarantee (ADR-13) are unchanged.
+
+## 2026.7.24
+
+- **`jwksFetchTimeoutMs` option.** Configures the per-fetch timeout for JWKS downloads (`jose`'s `timeoutDuration`). Default 5_000 ms, matching `jose`'s own default — no behavior change for existing consumers that don't set it.
+
+## 2026.6.1
+
+- The optional `logger` now emits a single `warn` (`jwt-verifier.jwks_unavailable`) when verification fails because the JWKS is unavailable (fetch failed and no fresh cached key set). Previously the option was accepted but never written to — observability beyond that one event stays the adapter's job.
+
+## 2026.5.27
+
+- **Multiple audiences per token** (ADR-6 amended). The verifier accepts both `aud` forms — a scalar string and a JSON array (array `aud` is no longer rejected); `AuthContext.aud` widens to `string | string[]`, matched by OR-membership against the configured audiences.
+- **`/api/v1` cutover** (ADR-13). Consumers point their issuer URL at the versioned value (`.../api/v1`); the `mi9IdentityEndpoints()` helper derives the three Mi9 endpoint URLs from that single value (the package carries no `/api/v{N}` literal).
+
+## 0.1.0
+
+- Version reset to pre-1.0 (`0.1.0`); the earlier `1.0.0` placeholder is superseded.
+- **Breaking**: wire-naming aligned with ADR-12. Mi9 custom-claim namespace URL keys changed from snake_case to camelCase: `https://mi9retail.com/retailerId`, `https://mi9retail.com/storeCode`, `https://mi9retail.com/authClass`.
+- **Breaking**: `AuthContext` field renames: `retailer_id` → `retailerId`, `store_code` → `storeCode`. Consumers update `req.auth.retailer_id` → `req.auth.retailerId` and `req.auth.store_code` → `req.auth.storeCode`.

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,220 @@
+# @mi9-identity/jwt-verifier
+
+Pure RS256/JWKS verifier for Mi9-issued JWTs. Framework-agnostic — used as
+the verification core by `@mi9-identity/auth-middleware-express`, raw HTTP handlers,
+and operational scripts.
+
+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/token-client`](https://www.npmjs.com/package/@mi9-identity/token-client) | Your service **calls** a Mi9 API and needs a token. |
+| **`@mi9-identity/jwt-verifier`** (this one) | Your service **receives** Mi9-issued tokens and must verify them. |
+| [`@mi9-identity/auth-middleware-express`](https://www.npmjs.com/package/@mi9-identity/auth-middleware-express) | The same, and your service is an Express 5 app — it wraps this verifier as middleware. |
+
+A service that both calls Mi9 APIs and serves Mi9-authenticated requests
+installs two of them.
+
+## Install
+
+```sh
+npm install @mi9-identity/jwt-verifier@1.0.0
+```
+
+Versions are **semver**, and the three `@mi9-identity/*` packages
+(`jwt-verifier`, `token-client`, `auth-middleware-express`) are released in
+lockstep at the same version — pin an exact version rather than a `^` or `~`
+range. A breaking change to the HTTP wire shapes ships as a new API path
+version (`/api/v2`), not as a package major bump.
+
+The package targets ESM and Node 24+. Use `await import()` if you consume it
+from CommonJS.
+
+## 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:
+
+```
+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: `/api/v1` (or a future `/api/v2`) is
+part of the configured value, and every endpoint URL is derived from it.
+
+Audience values are always full URLs of the form `https://<host>/<path>`, never
+a bare service name — for example `https://merchant.mi9retail.com/api`, not
+`merchant`. A token is valid for your service when your configured audience
+appears in its `aud`.
+
+## Usage
+
+```ts
+import { createVerifier, mi9IdentityJwksEndpoint } from '@mi9-identity/jwt-verifier';
+
+const jwksUri = mi9IdentityJwksEndpoint('https://identity.mi9retail.com/api/v1');
+
+const verifier = createVerifier({
+    jwksUri,
+    issuers: ['https://identity.mi9retail.com/api/v1'],
+    audience: 'https://merchant.mi9retail.com/api',
+});
+
+const ctx = await verifier.verify(token);
+console.log(ctx.retailerId, ctx.product);
+```
+
+### `mi9IdentityJwksEndpoint` — single-source-of-truth helper
+
+Consumers configure one issuer URL (`MI9_IDENTITY_ISSUER`) that matches the
+JWT `iss` claim — e.g. `https://identity.mi9retail.com/api/v1`. The helper
+appends the bare JWKS path to that single value. It contains no `/api/v1`
+literal; the version lives in the caller's issuer URL, so a future `v2`
+cutover is a one-env-var change at each consumer.
+
+Inbound verification is this package's only role, so the mint and
+credential-claim URLs are **not** derived here — `mi9IdentityEndpoints(issuer)`
+in [`@mi9-identity/token-client`](https://www.npmjs.com/package/@mi9-identity/token-client)
+returns `{ tokenEndpoint, credentialEndpoint }`. Neither package depends on the
+other, so an outbound-only service never installs a JOSE stack for a string
+concat.
+
+The Mi9 Identity Service does **not** publish
+`/.well-known/openid-configuration`. Generic OAuth client libraries that
+auto-discover will fail; configure the issuer URL, the JWKS URI, and the token
+endpoint explicitly, as above.
+
+## `VerifierOptions` reference
+
+| Option | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `jwksUri` | **yes** | — | Full JWKS URL; use `mi9IdentityJwksEndpoint(...)`. |
+| `issuers` | **yes** | — | Allowlist of acceptable `iss` values (no wildcards). |
+| `audience` | **yes** | — | `string \| string[]` — the token's `aud` must intersect this. |
+| `clockToleranceSec` | no | `30` | Leeway for `exp`/`iat`/`nbf`, in seconds. |
+| `jwksCacheTtlMs` | no | `3_600_000` (1 h) | How long a fetched JWKS is served before a re-fetch. |
+| `jwksInitialJitterMs` | no | `30_000` | Random delay before the first JWKS fetch — thundering-herd guard. |
+| `jwksCooldownMs` | no | `30_000` | Min interval between unknown-`kid` re-fetches. |
+| `jwksFetchTimeoutMs` | no | `5_000` | Per-fetch timeout for a JWKS download (`jose`'s `timeoutDuration`). |
+| `logger` | no | none | Optional pino-shaped `Logger`; see [Logging](#logging) below. |
+
+## Logging
+
+Pass a pino-compatible `Logger` to receive observability events from the
+verifier core. The verifier emits exactly **one** log event:
+
+- **`warn`** — `event: 'jwks_unavailable'`, message `'jwt-verifier.jwks_unavailable'`:
+  fired when `JwksUnavailableError` is thrown (JWKS fetch failed and no fresh
+  cache is available). This is the only event the framework-agnostic core emits;
+  richer observability (per-request audit, scope/retailer guard events) is the
+  adapter's job.
+
+See the **JWKS availability** section below for the failure semantics this event
+signals.
+
+## Validation pipeline
+
+1. Extract Bearer token (caller's responsibility — verifier accepts the raw
+   string).
+2. Decode header, read `kid` and `iss`.
+3. `iss` must be in the configured allowlist.
+4. Fetch JWKS from the explicitly-configured `jwksUri` (the verifier never
+   derives the URL from `iss`). The underlying `jose.createRemoteJWKSet`
+   caches the document for `jwksCacheTtlMs` (default 1h) and applies a
+   `cooldownDuration` (default 30s) between unknown-`kid` refreshes — so an
+   unknown `kid` triggers a single re-fetch and is then memoised for the
+   cooldown window before retrying.
+5. Verify RS256 signature against the key for `kid`.
+6. Validate `aud` (OR-membership against configured audiences) and
+   `exp` / `nbf` / `iat` with a 30-second default clock skew leeway.
+7. Extract custom claims and return `AuthContext`.
+
+## `AuthContext`
+
+Returned on success:
+
+| 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** — Mi9 credentials are provisioned with no authorized scopes, so do not authorize on it. |
+| `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. |
+
+The `authClass` claim (issuer-internal, used only by the rotation-pickup
+path) is **stripped** before `AuthContext` is returned. The verifier
+exposes only an explicit allowlist of fields — anything else is dropped, so
+future internal claims added by the issuer cannot leak to gateway code.
+
+## Error taxonomy
+
+Typed errors thrown on failure:
+
+| Error                       | When                                           |
+| --------------------------- | ---------------------------------------------- |
+| `MissingTokenError`         | (Adapter-level — the verifier itself receives a string.) |
+| `InvalidTokenError`         | Signature mismatch, malformed token, decode failure. |
+| `TokenExpiredError`         | `exp` in the past (after leeway).              |
+| `IssuerNotAllowedError`     | `iss` not in allowlist.                        |
+| `AudienceMismatchError`     | `aud` does not intersect configured audiences. |
+| `AlgorithmNotAllowedError`  | Header `alg` ≠ `RS256`.                        |
+| `MissingRequiredClaimError` | Required claim absent (e.g. `retailerId`).     |
+| `JwksUnavailableError`      | JWKS fetch failed and no *fresh* cached key set (within `jwksCacheTtlMs`) is available. |
+
+## JWKS availability
+
+`jose.createRemoteJWKSet` serves keys from its in-memory cache only while the
+cache is **fresh** — younger than `jwksCacheTtlMs` (default 1h). Once the cache
+is stale, the next `verify()` triggers a refetch; if that refetch fails, the
+verifier throws `JwksUnavailableError` (a `503`-shaped error). A *fresh* cache
+is still served through a transient endpoint outage, so a blip shorter than the
+TTL is invisible — but a stale cache is **not** used as a fallback. **The
+verifier never falls back to an unauthenticated path; it never fails open.**
+
+### Unknown `kid` after signing-key rotation
+
+A token signed by a newly-rotated signing key whose `kid` is not yet in the
+cached JWKS maps to `InvalidTokenError` (401), not `JwksUnavailableError`
+(503): the JWKS is reachable, the key is simply absent from it for now. `jose`
+refetches once on an unknown `kid`, then memoises the miss for `jwksCooldownMs`
+(default 30s) before retrying — so such tokens 401 for at most that window,
+then recover on the next mint. This is deliberately conservative; the issuer
+publishes a rotated signing key to the JWKS document ahead of minting tokens
+under it, so the window should not arise in a normal rotation.
+
+Signing-key rotation is otherwise transparent to consumers — there is nothing
+to configure or rotate on your side.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Requests fail with `JwksUnavailableError` (503) | The JWKS document is unreachable and no fresh cache is left | Transient; confirm your service can reach `${issuer}/.well-known/jwks.json`. |
+| 401s right after a deploy or a signing-key rotation | The token was signed by a key not yet in the cached JWKS | Self-heals within `jwksCooldownMs`; callers recover on their next mint. |
+| `AudienceMismatchError` | 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. |
+| `IssuerNotAllowedError` | The configured issuer URL omits the `/api/v1` path segment | Configure the versioned issuer URL, exactly as it appears in the token's `iss`. |
+
+---
+
+Outbound token acquisition lives in
+[`@mi9-identity/token-client`](https://www.npmjs.com/package/@mi9-identity/token-client);
+the Express 5 adapter — scope/retailer guards and the RFC 6750 error mapping —
+lives in
+[`@mi9-identity/auth-middleware-express`](https://www.npmjs.com/package/@mi9-identity/auth-middleware-express).
+
+## License
+
+Apache-2.0. The full text ships in the package as `LICENSE`.

package/dist/claims.d.ts

@@ -0,0 +1,11 @@
+import type { AuthContext } from './types.js';
+/**
+ * Map a verified `jose` JWT payload into the canonical `AuthContext` surface,
+ * stripping anything that is not in the explicit allowlist.
+ *
+ * @param { Record<string, unknown> } payload The verified JWT payload from `jose.jwtVerify`.
+ * @returns { AuthContext } The canonical `AuthContext` projection.
+ * @throws { MissingRequiredClaimError } When any required claim is missing or malformed.
+ */
+export declare const toAuthContext: (payload: Record<string, unknown>) => AuthContext;
+//# sourceMappingURL=claims.d.ts.map

package/dist/claims.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { MissingRequiredClaimError } from './errors.js';
+/**
+ * UUIDv7 shape (8-4-4-4-12 hex with version nibble `7` and variant nibble in
+ * `[89ab]`). The issuer mints `clientId` as UUIDv7 per design doc §6, and
+ * `sub` IS `clientId` — this regex is the verifier's defense against an
+ * issuer that ever drifts off the contract.
+ */
+const UUIDV7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * The shape of namespaced custom claims emitted by the issuer. Issuer-internal
+ * claims (notably `authClass`) are intentionally NOT listed — `jose` surfaces
+ * them on `payload`, but the strip-and-allowlist below drops every key that
+ * is not in this schema's output.
+ *
+ * The schema is closed (no `.passthrough()`) on purpose — adding it would
+ * silently leak issuer-internal claims into `AuthContext`. Don't.
+ */
+const claimsSchema = z.object({
+    iss: z.url(),
+    scope: z.string(),
+    exp: z.number().int(),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    jti: z.string().min(1),
+    sub: z.string().regex(UUIDV7_PATTERN),
+    'https://mi9retail.com/product': z.string().min(1),
+    'https://mi9retail.com/retailerId': z.string().min(1),
+    'https://mi9retail.com/storeCode': z.union([z.string(), z.null()]),
+    aud: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
+});
+/**
+ * Whitespace-split + dedupe `scope` into a stable `scopes` array. Empty
+ * `scope` resolves to an empty array, NOT undefined — keeps the surface
+ * type predictable for guards.
+ *
+ * @param { string } scope The raw `scope` claim value.
+ * @returns { readonly string[] } The deduplicated list of scope strings.
+ */
+const splitScopes = (scope) => {
+    const parts = scope
+        .trim()
+        .split(/\s+/u)
+        .filter((s) => s.length > 0);
+    return Array.from(new Set(parts));
+};
+/**
+ * Map a verified `jose` JWT payload into the canonical `AuthContext` surface,
+ * stripping anything that is not in the explicit allowlist.
+ *
+ * @param { Record<string, unknown> } payload The verified JWT payload from `jose.jwtVerify`.
+ * @returns { AuthContext } The canonical `AuthContext` projection.
+ * @throws { MissingRequiredClaimError } When any required claim is missing or malformed.
+ */
+export const toAuthContext = (payload) => {
+    // `aud` may be a scalar string (single-audience token) or an array of
+    // strings (multi-audience token) per ADR-6 (amended). `jose.jwtVerify`
+    // already accepted both by membership; the schema below now mirrors that.
+    const parsed = claimsSchema.safeParse(payload);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        /* v8 ignore next -- defensive; Zod always produces at least one issue when safeParse fails */
+        const path = issue?.path.join('.') ?? '<unknown>';
+        throw new MissingRequiredClaimError(`Required claim missing or malformed: ${path}`);
+    }
+    const c = parsed.data;
+    return {
+        iss: c.iss,
+        sub: c.sub,
+        aud: c.aud,
+        exp: c.exp,
+        iat: c.iat,
+        nbf: c.nbf,
+        jti: c.jti,
+        scope: c.scope,
+        scopes: splitScopes(c.scope),
+        product: c['https://mi9retail.com/product'],
+        storeCode: c['https://mi9retail.com/storeCode'],
+        retailerId: c['https://mi9retail.com/retailerId'],
+    };
+};
+//# sourceMappingURL=claims.js.map

package/dist/endpoints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Derive the Mi9 Identity JWKS URI from a single issuer URL. Inbound
+ * verification is this package's only role, so the mint and credential-claim
+ * endpoints belong to `@mi9-identity/token-client` — a service that verifies
+ * but never mints has no use for them, and deriving them here is what forced
+ * token-client consumers to install a JOSE stack for a string concat.
+ *
+ * @param { string } issuerUrl Configured issuer URL (matches the JWT `iss` claim, e.g. `https://identity.mi9retail.com/api/v1`). Trailing slash tolerated.
+ * @returns { string } Full JWKS URL.
+ */
+export declare const mi9IdentityJwksEndpoint: (issuerUrl: string) => string;
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/endpoints.js

@@ -0,0 +1,12 @@
+/**
+ * Derive the Mi9 Identity JWKS URI from a single issuer URL. Inbound
+ * verification is this package's only role, so the mint and credential-claim
+ * endpoints belong to `@mi9-identity/token-client` — a service that verifies
+ * but never mints has no use for them, and deriving them here is what forced
+ * token-client consumers to install a JOSE stack for a string concat.
+ *
+ * @param { string } issuerUrl Configured issuer URL (matches the JWT `iss` claim, e.g. `https://identity.mi9retail.com/api/v1`). Trailing slash tolerated.
+ * @returns { string } Full JWKS URL.
+ */
+export const mi9IdentityJwksEndpoint = (issuerUrl) => `${issuerUrl.replace(/\/+$/, '')}/.well-known/jwks.json`;
+//# sourceMappingURL=endpoints.js.map

package/dist/errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Base class for all token-verification failures. Adapters map subclasses to
+ * RFC 6750 §3 status codes; see `@mi9-identity/auth-middleware-express` for the
+ * default mapping.
+ */
+export declare class InvalidTokenError extends Error {
+    readonly name: string;
+}
+/**
+ * Token signature verified but `exp` (with clock tolerance) is in the past.
+ */
+export declare class TokenExpiredError extends InvalidTokenError {
+    readonly name: string;
+}
+/**
+ * The token's `iss` claim was not in the configured `issuers` allowlist.
+ * Rejected before signature verification — cheap fail.
+ */
+export declare class IssuerNotAllowedError extends InvalidTokenError {
+    readonly name: string;
+}
+/**
+ * The token's `aud` did not match any of the configured audiences
+ * (OR-membership semantics — `aud` may be a scalar string or an array; see
+ * design doc §6 / ADR-6).
+ */
+export declare class AudienceMismatchError extends InvalidTokenError {
+    readonly name: string;
+}
+/**
+ * Token header `alg` was not RS256. The verifier accepts no other algorithm
+ * regardless of what JWKS publishes, defending against `alg` substitution
+ * attacks.
+ */
+export declare class AlgorithmNotAllowedError extends InvalidTokenError {
+    readonly name: string;
+}
+/**
+ * Token is otherwise valid but is missing one of the namespaced custom
+ * claims required to populate `AuthContext` (e.g. `retailerId`, `product`).
+ */
+export declare class MissingRequiredClaimError extends InvalidTokenError {
+    readonly name: string;
+}
+/**
+ * Distinct from the `InvalidToken*` family because the failure is server-side
+ * (JWKS endpoint unreachable, DNS, timeout, no cached key set). Adapters map
+ * this to HTTP 503 with `Retry-After`. The verifier never falls back to an
+ * unauthenticated path — failing open would defeat JWT-based auth.
+ */
+export declare class JwksUnavailableError extends Error {
+    readonly name: string;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Base class for all token-verification failures. Adapters map subclasses to
+ * RFC 6750 §3 status codes; see `@mi9-identity/auth-middleware-express` for the
+ * default mapping.
+ */
+export class InvalidTokenError extends Error {
+    name = 'InvalidTokenError';
+}
+/**
+ * Token signature verified but `exp` (with clock tolerance) is in the past.
+ */
+export class TokenExpiredError extends InvalidTokenError {
+    name = 'TokenExpiredError';
+}
+/**
+ * The token's `iss` claim was not in the configured `issuers` allowlist.
+ * Rejected before signature verification — cheap fail.
+ */
+export class IssuerNotAllowedError extends InvalidTokenError {
+    name = 'IssuerNotAllowedError';
+}
+/**
+ * The token's `aud` did not match any of the configured audiences
+ * (OR-membership semantics — `aud` may be a scalar string or an array; see
+ * design doc §6 / ADR-6).
+ */
+export class AudienceMismatchError extends InvalidTokenError {
+    name = 'AudienceMismatchError';
+}
+/**
+ * Token header `alg` was not RS256. The verifier accepts no other algorithm
+ * regardless of what JWKS publishes, defending against `alg` substitution
+ * attacks.
+ */
+export class AlgorithmNotAllowedError extends InvalidTokenError {
+    name = 'AlgorithmNotAllowedError';
+}
+/**
+ * Token is otherwise valid but is missing one of the namespaced custom
+ * claims required to populate `AuthContext` (e.g. `retailerId`, `product`).
+ */
+export class MissingRequiredClaimError extends InvalidTokenError {
+    name = 'MissingRequiredClaimError';
+}
+/**
+ * Distinct from the `InvalidToken*` family because the failure is server-side
+ * (JWKS endpoint unreachable, DNS, timeout, no cached key set). Adapters map
+ * this to HTTP 503 with `Retry-After`. The verifier never falls back to an
+ * unauthenticated path — failing open would defeat JWT-based auth.
+ */
+export class JwksUnavailableError extends Error {
+    name = 'JwksUnavailableError';
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createVerifier } from './verifier.js';
+export { mi9IdentityJwksEndpoint } from './endpoints.js';
+export { InvalidTokenError, TokenExpiredError, JwksUnavailableError, AudienceMismatchError, IssuerNotAllowedError, AlgorithmNotAllowedError, MissingRequiredClaimError, } from './errors.js';
+export type { AuthContext, Logger, Verifier, VerifierOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createVerifier } from './verifier.js';
+export { mi9IdentityJwksEndpoint } from './endpoints.js';
+export { InvalidTokenError, TokenExpiredError, JwksUnavailableError, AudienceMismatchError, IssuerNotAllowedError, AlgorithmNotAllowedError, MissingRequiredClaimError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/type-guards.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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).
+ */
+/**
+ * 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;
+/**
+ * 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;
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/type-guards.js

@@ -0,0 +1,30 @@
+/**
+ * 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).
+ */
+/**
+ * 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';
+/**
+ * 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,78 @@
+/**
+ * Structural logger contract — any pino-compatible object satisfies this.
+ * Exported so adapters and the token client can declare a logger option
+ * without a runtime dependency on a logger package.
+ */
+export interface Logger {
+    debug(obj: unknown, msg?: string): void;
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+}
+/**
+ * Configuration for `createVerifier`. Defaults match the design doc:
+ * 30 s clock tolerance, 1 h JWKS cache, 30 s startup jitter, 30 s cooldown
+ * between unknown-kid refresh storms.
+ */
+export interface VerifierOptions {
+    /** Full URL of the issuer's JWKS document, e.g. `${ISSUER_URL}/.well-known/jwks.json`. */
+    jwksUri: string;
+    /** Explicit allowlist of acceptable `iss` values. No wildcards — Mi9 issuer URL only. */
+    issuers: readonly string[];
+    /** OR-membership: the token's `aud` (scalar or array) must intersect these. Pass-through to `jose.jwtVerify`. */
+    audience: string | readonly string[];
+    /** `leeway` for `exp`/`iat`/`nbf`. Default 30 s. */
+    clockToleranceSec?: number;
+    /** JWKS cache lifetime. Default 3_600_000 ms (1 h, design doc §3.2). */
+    jwksCacheTtlMs?: number;
+    /** Uniform random delay (0–N ms) before the first JWKS fetch — thundering-herd mitigation. Default 30_000 ms. */
+    jwksInitialJitterMs?: number;
+    /** Cooldown between unknown-kid refresh attempts. Default 30_000 ms (matches `jose`'s `cooldownDuration`). */
+    jwksCooldownMs?: number;
+    /**
+     * Per-fetch timeout for JWKS downloads. Default 5_000 ms (jose's `timeoutDuration`).
+     */
+    jwksFetchTimeoutMs?: number;
+    /** Optional structured logger; receives a single `warn` when JWKS becomes unavailable (the only event this framework-agnostic core emits — richer observability is the adapter's job). */
+    logger?: Logger;
+}
+/**
+ * Canonical post-verification surface — same name and shape as
+ * design doc §3.3 `AuthContext`. Namespaced URI claims
+ * (`https://mi9retail.com/<key>`) are mapped to unprefixed fields here.
+ *
+ * Issuer-internal claims (notably `authClass`) are NEVER surfaced here — the
+ * verifier strips them via an explicit allowlist before returning.
+ */
+export interface AuthContext {
+    iss: string;
+    /** `sub` IS the `clientId` (UUIDv7); no separate `clientId` claim is issued. */
+    sub: string;
+    /** Mirrors the issuer's `aud` — a scalar string or an array of strings, echoing the requested `audience` shape verbatim (design doc §5.4 / ADR-6, amended). */
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    nbf: number;
+    jti: string;
+    /** Raw space-separated string from the JWT. */
+    scope: string;
+    /** Pre-split, deduped convenience view of `scope`. */
+    scopes: readonly string[];
+    retailerId: string;
+    product: string;
+    /** `null` when the token was not minted for a Tier 3 / store-bound credential. */
+    storeCode: string | null;
+}
+/**
+ * Verifier handle returned by `createVerifier`. Stateless from the caller's
+ * perspective; internally holds a `jose` `RemoteJWKSet` with TTL and cooldown
+ * caching.
+ */
+export interface Verifier {
+    /**
+     * Verify a Bearer token. Resolves to `AuthContext` on success; rejects with
+     * one of the typed error classes from `./errors.ts` on failure.
+     */
+    verify(token: string): Promise<AuthContext>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

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

package/dist/verifier.d.ts

@@ -0,0 +1,12 @@
+import type { Verifier, VerifierOptions } from './types.js';
+/**
+ * Build a verifier bound to one issuer's JWKS. Construction is side-effect
+ * free; the JWKS document is fetched lazily on first `verify()` (modulo
+ * startup jitter).
+ *
+ * @param { VerifierOptions } opts Verifier configuration (JWKS URI, issuers, audience, cache/jitter knobs).
+ * @returns { Verifier } The configured verifier with its bound `verify` method.
+ * @throws { Error } If `issuers` is empty or `audience` is an empty array.
+ */
+export declare const createVerifier: (opts: VerifierOptions) => Verifier;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/verifier.js

@@ -0,0 +1,168 @@
+import { inspect } from 'node:util';
+import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from 'jose';
+import { toAuthContext } from './claims.js';
+import { isFunction, isString } from './type-guards.js';
+import { InvalidTokenError, TokenExpiredError, JwksUnavailableError, AudienceMismatchError, IssuerNotAllowedError, AlgorithmNotAllowedError, MissingRequiredClaimError, } from './errors.js';
+const DEFAULT_CLOCK_TOLERANCE_SEC = 30;
+const DEFAULT_JWKS_COOLDOWN_MS = 30_000;
+const DEFAULT_JWKS_CACHE_TTL_MS = 3_600_000;
+const DEFAULT_JWKS_FETCH_TIMEOUT_MS = 5_000;
+const DEFAULT_JWKS_INITIAL_JITTER_MS = 30_000;
+/**
+ * One-shot delay scheduled at construction time. The first `verify()` call
+ * awaits this gate so a fleet of consumer pods that all boot at once does
+ * not synchronously hammer the JWKS endpoint.
+ *
+ * @param { number } jitterMaxMs Upper bound (inclusive) for the random delay; non-positive disables jitter.
+ * @returns { Promise<void> } Resolves after the random delay (or immediately when disabled).
+ */
+const scheduleStartupJitter = (jitterMaxMs) => {
+    if (jitterMaxMs <= 0) {
+        return Promise.resolve();
+    }
+    const delayMs = Math.floor(Math.random() * jitterMaxMs);
+    if (delayMs === 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, delayMs);
+        /* v8 ignore next 3 -- defensive cross-runtime guard; setTimeout in Node always returns a Timeout with unref */
+        if (isFunction(timer.unref)) {
+            timer.unref();
+        }
+    });
+};
+/**
+ * Translate a `jose` error into the verifier's typed error hierarchy. Falls
+ * back to a generic `InvalidTokenError` for unrecognized codes so callers
+ * never see a `jose`-specific class. Returns the mapped error so the caller
+ * throws once at the call site (`throw mapJoseError(err)`).
+ *
+ * @param { unknown } err The raw error thrown by `jose` (or downstream).
+ * @returns { Error } The mapped error from the verifier's typed hierarchy.
+ */
+const mapJoseError = (err) => {
+    if (err instanceof joseErrors.JWTExpired) {
+        return new TokenExpiredError(err.message, { cause: err });
+    }
+    if (err instanceof joseErrors.JOSEAlgNotAllowed) {
+        return new AlgorithmNotAllowedError(err.message, { cause: err });
+    }
+    if (err instanceof joseErrors.JWTClaimValidationFailed) {
+        if (err.claim === 'iss') {
+            return new IssuerNotAllowedError(err.message, { cause: err });
+        }
+        if (err.claim === 'aud') {
+            return new AudienceMismatchError(err.message, { cause: err });
+        }
+        return new InvalidTokenError(err.message, { cause: err });
+    }
+    if (err instanceof joseErrors.JWKSNoMatchingKey) {
+        // Unknown `kid`: the JWKS is reachable but this token's key is absent
+        // from it right now — most plausibly a token signed by a freshly-rotated
+        // signing key whose `kid` has not yet landed in the cached JWKS. `jose`
+        // refetches once on an unknown `kid`, then memoises the miss for
+        // `cooldownDuration` (jwksCooldownMs, default 30s) before retrying, so
+        // such a token 401s for at most that window. Mapped to InvalidTokenError
+        // (401), NOT JwksUnavailableError (503): the document is fetchable, the
+        // key is genuinely not in it. Conservative by design — a brief
+        // post-rotation 401 is safer than failing open.
+        return new InvalidTokenError(err.message, { cause: err });
+    }
+    if (err instanceof joseErrors.JWKSMultipleMatchingKeys) {
+        // Duplicate `kid` in the JWKS document — issuer-side configuration
+        // bug, not a token validity issue. Surface as 503 so consumers retry
+        // rather than rejecting the user with 401.
+        return new JwksUnavailableError(err.message, { cause: err });
+    }
+    if (err instanceof joseErrors.JWKSTimeout || err instanceof joseErrors.JWKSInvalid) {
+        return new JwksUnavailableError(err.message, { cause: err });
+    }
+    if (err instanceof joseErrors.JOSEError) {
+        return new InvalidTokenError(err.message, { cause: err });
+    }
+    if (err instanceof TypeError) {
+        // `fetch` throws `TypeError` on DNS / network failure; the JWKS endpoint
+        // is unreachable rather than the token being malformed.
+        return new JwksUnavailableError(err.message, { cause: err });
+    }
+    if (err instanceof Error) {
+        return err;
+    }
+    if (isString(err)) {
+        return new Error(err);
+    }
+    try {
+        /* v8 ignore next -- `?? inspect(err)` covers `JSON.stringify(undefined)`; not reachable from jose error shapes */
+        return new Error(JSON.stringify(err) ?? inspect(err));
+        /* v8 ignore next 3 -- defensive; JSON.stringify on the synthetic shapes thrown by jose does not throw in practice */
+    }
+    catch {
+        return new Error(inspect(err));
+    }
+};
+/**
+ * Build a verifier bound to one issuer's JWKS. Construction is side-effect
+ * free; the JWKS document is fetched lazily on first `verify()` (modulo
+ * startup jitter).
+ *
+ * @param { VerifierOptions } opts Verifier configuration (JWKS URI, issuers, audience, cache/jitter knobs).
+ * @returns { Verifier } The configured verifier with its bound `verify` method.
+ * @throws { Error } If `issuers` is empty or `audience` is an empty array.
+ */
+export const createVerifier = (opts) => {
+    if (opts.issuers.length === 0) {
+        throw new Error('createVerifier: `issuers` must contain at least one entry');
+    }
+    const audience = isString(opts.audience) ? opts.audience : Array.from(opts.audience);
+    /* v8 ignore next 3 -- string-audience path skips this guard; type system already excludes empty-string at the call site */
+    if (Array.isArray(audience) && audience.length === 0) {
+        throw new Error('createVerifier: `audience` must be a non-empty string or array');
+    }
+    const issuer = Array.from(opts.issuers);
+    const cacheMaxAge = opts.jwksCacheTtlMs ?? DEFAULT_JWKS_CACHE_TTL_MS;
+    const cooldownDuration = opts.jwksCooldownMs ?? DEFAULT_JWKS_COOLDOWN_MS;
+    const clockTolerance = opts.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC;
+    const jitterMaxMs = opts.jwksInitialJitterMs ?? DEFAULT_JWKS_INITIAL_JITTER_MS;
+    const timeoutDuration = opts.jwksFetchTimeoutMs ?? DEFAULT_JWKS_FETCH_TIMEOUT_MS;
+    const jwks = createRemoteJWKSet(new URL(opts.jwksUri), {
+        cacheMaxAge,
+        timeoutDuration,
+        cooldownDuration,
+    });
+    const startupGate = scheduleStartupJitter(jitterMaxMs);
+    const verify = async (token) => {
+        if (!isString(token) || token.length === 0) {
+            throw new InvalidTokenError('Token is empty');
+        }
+        await startupGate;
+        let payload;
+        try {
+            const result = await jwtVerify(token, jwks, {
+                issuer,
+                audience,
+                clockTolerance,
+                algorithms: ['RS256'],
+            });
+            payload = result.payload;
+        }
+        catch (err) {
+            const mapped = mapJoseError(err);
+            if (mapped instanceof JwksUnavailableError) {
+                opts.logger?.warn({ event: 'jwks_unavailable', jwksUri: opts.jwksUri, err: mapped.message }, 'jwt-verifier.jwks_unavailable');
+            }
+            throw mapped;
+        }
+        try {
+            return toAuthContext(payload);
+        }
+        catch (err) {
+            if (err instanceof MissingRequiredClaimError) {
+                throw err;
+            }
+            throw new InvalidTokenError('Failed to map verified payload to AuthContext', { cause: err });
+        }
+    };
+    return { verify };
+};
+//# sourceMappingURL=verifier.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@mi9-identity/jwt-verifier",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Mi9 JWT verifier — pure RS256/JWKS core for verifying tokens issued by the Mi9 Identity Service. Framework-agnostic.",
+  "keywords": [
+    "mi9",
+    "identity",
+    "oauth2",
+    "jwt",
+    "rs256",
+    "jwks",
+    "m2m"
+  ],
+  "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",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^6.2.9",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@vitest/coverage-v8": "4.1.11",
+    "vitest": "4.1.11",
+    "@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"
+  }
+}