lacewing 1.0.0 → 1.0.2

package/README.md

@@ -3,15 +3,15 @@
 
 **Lacewing is an opinionated JWT library that makes common JWT security mistakes impossible by construction.**
 
-Instead of exposing low-level primitives and trusting you to compose them correctly, Lacewing provides secure verification profiles, safe defaults, mandatory claim validation, built-in revocation support, secure cookie helpers, and a curated algorithm set - everything [RFC 8725 (JWT Best Current Practices)](https://datatracker.ietf.org/doc/html/rfc8725) says an application MUST or SHOULD do is enforced by the type system, enforced at runtime, or impossible to express.
+Instead of exposing low-level primitives and trusting you to compose them correctly, Lacewing provides secure verification profiles, safe defaults, mandatory claim validation, built-in revocation support, secure cookie helpers, and a curated algorithm set. Everything [RFC 8725 (JWT Best Current Practices)](https://datatracker.ietf.org/doc/html/rfc8725) says an application MUST or SHOULD do is enforced by the type system, enforced at runtime, or impossible to express.
 
 **Batteries loaded (RFC 8725).** Out of the box:
 
-- **Verification profiles** - the only way to verify; `typ`, issuer, audience, algorithm allowlist and key source are structurally mandatory
-- **Remote JWKS** with caching, rotation handling, and `kid` hygiene
-- **Token revocation** - unique `jti` on every token, pluggable `RevocationStore`, in-memory store included
-- **Secure cookie + bearer helpers** - `HttpOnly; Secure; SameSite` enforced, strict RFC 6750 parsing
-- **Access/refresh token presets** - mutually exclusive by `typ`, shipped rather than left as homework
+- **Verification profiles**: the only way to verify; `typ`, issuer, audience, algorithm allowlist and key source are structurally mandatory
+- **Remote JWKS** with caching, rotation handling, `kid` hygiene, and a *bounded* stale-serving window when the endpoint goes down
+- **Token revocation**: unique `jti` on every token, pluggable `RevocationStore`, in-memory store included
+- **Secure cookie + bearer helpers**: `HttpOnly; Secure; SameSite` enforced, strict RFC 6750 parsing
+- **Access/refresh token presets**: mutually exclusive by `typ`, shipped rather than left as homework
 - **Encrypted JWTs (JWE)** with the same profile discipline
 - **Payload hygiene scanning** at sign time (passwords, card numbers, PEM keys never leave in plaintext)
 - **Typed errors** with machine-readable codes and no attacker-facing oracle
@@ -28,9 +28,14 @@ Instead of exposing low-level primitives and trusting you to compose them correc
 npm install lacewing
 ```
 
+[Getting started](./GETTING-STARTED.md) walks through adopting Lacewing in a
+real service: keys, profiles, transport, refresh tokens, revocation, key
+rotation, and a migration path from `jsonwebtoken`. The rest of this README is
+the pitch and the reference.
+
 ## Quick start
 
-The complete lifecycle - generate a key, sign, define a profile once, verify everywhere:
+The complete lifecycle (generate a key, sign, define a profile once, verify everywhere):
 
 ```ts
 import { SignJWT, defineProfile, jwtVerify, generateKeyPair } from "lacewing";
@@ -53,16 +58,16 @@ const profile = defineProfile({
 	maxTokenAge: "10m",
 });
 
-const { payload } = await jwtVerify(token, profile); // VerifiedJwt - every check passed
+const { payload } = await jwtVerify(token, profile); // VerifiedJwt: every check passed
 ```
 
 A runnable version of everything in this README ships with the repo: `npm run demo`.
 
 ## Concepts
 
-**Profiles are the central abstraction.** Configuration is something you create once - not something every endpoint reinvents. A profile names the expected `typ`, the trusted issuer, the required audience, an explicit algorithm allowlist, and the key source bound to that issuer. `jwtVerify(token, profile)` is the *only* verify path: there is no `decode()`, no `ignoreExpiration`, no "accept whatever the header says" mode. If any check fails you get a typed error (`JWTExpired`, `AlgorithmNotAllowed`, `JWTClaimValidationFailed`, ...) and no partial result.
+**Profiles are the central abstraction.** Configuration is something you create once, not something every endpoint reinvents. A profile names the expected `typ`, the trusted issuer, the required audience, an explicit algorithm allowlist, and the key source bound to that issuer. `jwtVerify(token, profile)` is the *only* verify path: there is no `decode()`, no `ignoreExpiration`, no "accept whatever the header says" mode. If any check fails you get a typed error (`JWTExpired`, `AlgorithmNotAllowed`, `JWTClaimValidationFailed`, ...) and no partial result.
 
-**Built on jose.** Lacewing does not reimplement cryptography. It is a hardened policy layer over [jose](https://github.com/panva/jose) - the audited, maintained, runtime-portable JOSE implementation - so the novel code is the policy, not the crypto. Tokens Lacewing signs or encrypts are standard JWTs/JWEs that jose (and any other conforming implementation) can consume, and the conformance suite proves it against the RFC 7515/7516/7519 worked examples plus tokens produced by OpenSSL and python-cryptography.
+**Built on jose.** Lacewing does not reimplement cryptography. It is a hardened policy layer over [jose](https://github.com/panva/jose) (the audited, maintained, runtime-portable JOSE implementation), so the novel code is the policy, not the crypto. Tokens Lacewing signs or encrypts are standard JWTs/JWEs that jose (and any other conforming implementation) can consume, and the conformance suite proves it against the RFC 7515/7516/7519 worked examples plus tokens produced by OpenSSL and python-cryptography.
 
 ## Usage
 
@@ -82,16 +87,85 @@ const accessToken = defineProfile({
 	maxTokenAge: "10m",
 });
 
-const { payload } = await jwtVerify(token, accessToken); // VerifiedJwt - every check passed
+const { payload } = await jwtVerify(token, accessToken); // VerifiedJwt: every check passed
+```
+
+**When the endpoint goes down**, the last good keys keep serving for a bounded
+window (1h by default) and then verification **fails closed**. The bound is the
+whole point: keys that go stale forever mean a key you rotated out *because it
+was compromised* stays trusted for exactly as long as an attacker can keep your
+JWKS unreachable. Trade availability against freshness explicitly:
+
+```ts
+createRemoteJWKSet("https://auth.example.com/jwks", {
+	cacheTtlSeconds: 300,         // fallback when the response sends no Cache-Control
+	cooldownSeconds: 30,          // floor between fetch attempts
+	staleWhileErrorSeconds: 3600, // how long a dead endpoint may coast; 0 = never
+});
+```
+
+Two more things that endpoint does not get to do. The response is read under a
+hard byte budget, checked against `Content-Length` and again on every chunk, so
+a hostile or broken endpoint cannot stream you out of memory. And symmetric
+(`oct`) entries are refused from a *remote* set: a JWKS endpoint is public, so a
+secret published there is one every reader could **mint** with, not merely
+verify with. A local JWKS may still carry them.
+
+### Verify: keys you already have
+
+Not everyone has a JWKS endpoint to point at. If the issuer handed you a raw
+public key, or you're pinning a single known one, the same `keys` field takes it
+directly. No URL, no fetch. `importKey` reads a PEM (SPKI public key), a JWK, or
+a `CryptoKey`, and binds it to exactly one algorithm:
+
+```ts
+import { defineProfile, importKey } from "lacewing";
+
+const publicKey = await importKey(spkiPem, "ES256"); // PEM string, JWK, or CryptoKey
+
+const profile = defineProfile({
+	typ: "at+jwt",
+	issuer: "https://auth.example.com",
+	audience: "https://api.example.com",
+	algorithms: ["ES256"],
+	keys: publicKey, // one pinned key, nothing to fetch
+	maxTokenAge: "10m",
+});
 ```
 
+Hand it a private key by mistake and it refuses: profiles verify, they don't
+sign, and the error says exactly that. The key's algorithm has to be one you
+allowlisted too, so a key you imported for `ES256` won't quietly slip into an
+`EdDSA`-only profile.
+
+Got a handful of keys but still no endpoint to serve them from? Pass a JWKS
+document straight in, the same shape a `/jwks` URL would return, just inlined:
+
+```ts
+keys: {
+	keys: [
+		{ kty: "OKP", crv: "Ed25519", x: "...", kid: "2024-key" },
+		{ kty: "EC", crv: "P-256", x: "...", y: "...", kid: "2025-key" },
+	],
+},
+```
+
+Selection is exact: the token's `kid` (and its algorithm's key type and curve)
+has to single out one key. Two keys that both match with no `kid` to tell them
+apart is treated as your mistake, not something to guess at.
+
+And if your keys live somewhere less ordinary (an HSM, a secrets manager, a
+database), anything with a `getVerificationKey(header)` method is a valid `keys`
+value. That's the escape hatch; the two built-in sources are just the ones
+you'll reach for most.
+
 ### Sign
 
 `typ` is a constructor argument, and `.sign()` refuses to run without
 `issuer`, `audience` and `expiresIn` (waivable only via grep-loud
 `unsafeAllowMissing*` calls). Every token gets a unique `jti`, lifetimes are
 capped (default 1h), and a hygiene scanner rejects payloads that contain
-things like passwords, card numbers, PEM keys, or other JWTs - because **a
+things like passwords, card numbers, PEM keys, or other JWTs, because **a
 JWS payload is base64url-encoded plaintext, readable by anyone who holds the
 token**. Never put secrets in it.
 
@@ -112,28 +186,50 @@ const token = await new SignJWT("at+jwt")
 A note on HMAC (`HS256/384/512`): it is supported, but every verifier of an
 HMAC token holds the same secret and can therefore also **mint** them. For
 anything beyond a single service, use asymmetric keys + JWKS. HMAC secrets
-are entropy-checked at import - `"my-secret"` will not import, ever;
-`generateSecret()` gives you a proper one.
+must meet the RFC 7518 length floor and are screened by an entropy
+heuristic, so `"my-secret"` will not import, ever. The heuristic catches
+short and low-entropy secrets, not every bad one a human can invent. PLEASE use
+`generateSecret()` and don't hand-write key material. Symmetric keys are
+also refused from a *remote* JWKS: that endpoint is public, so a secret
+published there is one anyone can mint with.
 
 ### Transport: the paved road
 
-Do **not** put tokens in `localStorage` or `sessionStorage` - both are
+Do **not** put tokens in `localStorage` or `sessionStorage`: both are
 readable by any script on the page, so one XSS means token theft. Use an
 `HttpOnly` cookie (browsers) or an in-memory bearer token (services):
 
 ```ts
 import { setTokenCookie, readTokenCookie, parseBearer } from "lacewing";
 
-setTokenCookie(response.headers, token); // always HttpOnly; Secure; SameSite - weaker is unrepresentable
+setTokenCookie(response.headers, token); // always HttpOnly; Secure; SameSite, weaker is unrepresentable
 const fromCookie = readTokenCookie(request);
 const fromHeader = parseBearer(request); // strict RFC 6750; no query-string tokens, ever
 ```
 
+Both readers refuse ambiguity rather than resolving it. `parseBearer` rejects
+the `", "`-joined value `Headers` produces when a request carried two
+`Authorization` headers, and `readTokenCookie` returns `undefined` when the
+cookie name appears twice, the servers disagree about whether the first or the
+last duplicate wins, and cookie shadowing is built on that disagreement.
+
+Both readers take WHATWG `Headers` (or anything carrying them, like `Request`),
+or the raw header string. Node-style frameworks - Express, Fastify, Koa - hand
+you a plain object instead, so convert once at the edge; a shape the readers
+don't accept throws rather than reading as "no token":
+
+```ts
+const headers = new Headers(req.headers as Record<string, string>);
+const fromCookie = readTokenCookie(headers);
+
+res.setHeader("Set-Cookie", buildTokenCookie(token)); // the response side is just a string
+```
+
 ### Access vs refresh (the cookbook)
 
 The single most common token-confusion bug is letting a refresh token buy API
 access, or an access token mint new sessions. Lacewing **ships** the two
-profiles rather than leaving them as homework - they are mutually exclusive by
+profiles rather than leaving them as homework. They are mutually exclusive by
 `typ` (RFC 8725 §3.12), so presenting one where the other is expected fails,
 even with identical keys, claims and audience:
 
@@ -182,10 +278,37 @@ errors fail closed.
 
 ## Advanced
 
+### Age vs lifetime: two different caps
+
+`maxTokenAge` and `maxTokenLifetime` sound alike and do different jobs.
+
+**`maxTokenAge`** (required) bounds how long after issuance a token still works
+*here* (`now - iat`). It is enforced independently of `exp`, so a token minted
+with a decade-long `exp` stops being accepted once it is older than your cap,
+no matter what the issuer wrote.
+
+**`maxTokenLifetime`** (optional) bounds the span the issuer *declared*
+ (`exp - iat`). Note what `maxTokenAge` alone does with that decade-long token:
+it accepts it, right up until the age window closes. That is usually fine, since
+the age window is what actually governs. But an `exp` wildly beyond your own
+policy is a misissuance signal, and this refuses it on sight instead of
+tolerating it for the length of the window:
+
+```ts
+const profile = defineProfile({
+	/* ...as above... */
+	maxTokenAge: "10m",     // unusable 10m after iat, whatever exp claims
+	maxTokenLifetime: "1h", // and refuse anything declaring a span beyond 1h
+});
+```
+
+It is opt-in because plenty of legitimate issuers set a generous `exp` and
+expect the verifier's own window to do the limiting.
+
 ### Revocation is not replay protection
 
 Be precise about what revocation buys you: it lets you kill a
-token you *know about* (logout, compromise). It does **not** stop replay - a
+token you *know about* (logout, compromise). It does **not** stop replay: a
 valid, non-revoked token that leaks can be replayed by anyone who holds it
 until `exp`. That is the deliberate cost of stateless verification, and no
 JWT library can remove it without becoming a session store.
@@ -225,10 +348,10 @@ Your levers, in order of cheapness:
 ### Encrypting (JWE): when the payload really is a secret
 
 A signed JWT is readable plaintext. When you genuinely need the payload
-*hidden* - not just tamper-evident - use an encrypted JWT. Same discipline as
+*hidden*, not just tamper-evident, use an encrypted JWT. Same discipline as
 signing (mandatory `typ`, required `iss`/`aud`/`exp`, unique `jti`, capped
 lifetime), but with a curated set of encryption algorithms and no `none`. The
-sign-time hygiene scanner is deliberately off here - hiding secrets is the
+sign-time hygiene scanner is deliberately off here, since hiding secrets is the
 whole point:
 
 ```ts
@@ -242,7 +365,7 @@ const token = await new EncryptJWT("at+jwt", { contentEncryption: "A256GCM" })
   .issuer("https://auth.example.com")
   .audience("https://api.example.com")
   .subject("user-42")
-  .claim("ssn", "123-45-6789") // fine - it's encrypted, not just encoded
+  .claim("ssn", "123-45-6789") // fine: it's encrypted, not just encoded
   .expiresIn("10m")
   .encrypt(publicKey);
 
@@ -256,24 +379,24 @@ const profile = defineDecryptionProfile({
   maxTokenAge: "10m",
 });
 
-const { payload } = await jwtDecrypt(token, profile); // DecryptedJwt - distinct from VerifiedJwt
+const { payload } = await jwtDecrypt(token, profile); // DecryptedJwt, distinct from VerifiedJwt
 ```
 
 `none`, `RSA1_5`, `RSA-OAEP` (SHA-1) and the password-based `PBES2*` family are
 absent by construction. A JWS handed to `jwtDecrypt` (or a JWE handed to
-`jwtVerify`) is rejected - the two formats never cross over.
+`jwtVerify`) is rejected: the two formats never cross over.
 
-**Portability caveat - 192-bit AES:** the registry includes the `A192*`
+**Portability caveat (192-bit AES):** the registry includes the `A192*`
 algorithms (`A192KW`, `A192GCMKW`, `A192GCM`, `A192CBC-HS384`) for JOSE
 completeness, and they work on Node ≥ 24 (Lacewing's floor). But WebCrypto
 implementations in browsers and some edge runtimes do not implement 192-bit
 AES at all. If tokens must be decrypted outside Node, stick to the `A128*` /
-`A256*` variants - there is no security reason to prefer 192-bit anyway.
+`A256*` variants. There is no security reason to prefer 192-bit anyway.
 
 ### Debugging
 
 `unsafeDecode(token)` parses without verifying and returns an `UntrustedJwt`
-that is type-incompatible with `VerifiedJwt` - useful for inspecting expired
+that is type-incompatible with `VerifiedJwt`: useful for inspecting expired
 tokens, useless (by design) for auth logic.
 
 ### Legacy interop
@@ -304,9 +427,9 @@ The other reason is irritation. Generic JWT libraries are fine, but they leave e
 - No way to revoke stateless JWTs
 - Storing tokens in `localStorage` or `sessionStorage`
 - Not configuring `iss` or `aud`
-- Over-caching a JWKS when an endpoint goes down
+- Over-caching a JWKS when an endpoint goes down (stale keys serve for a bounded window, then verification fails closed)
 
-Insecure usage is still *possible* - but only unmistakably deliberate, through `unsafe*`-prefixed escape hatches that are easy to grep for in code review. Secure usage is the path of least resistance.
+Insecure usage is still *possible*, but only unmistakably deliberate, through `unsafe*`-prefixed escape hatches that are easy to grep for in code review. Secure usage is the path of least resistance.
 
 ## Attribution
 

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 5.1.x   | :white_check_mark: |
+| 5.0.x   | :x:                |
+| 4.0.x   | :white_check_mark: |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

package/dist/index.js

@@ -31,6 +31,7 @@ export { MemoryRevocationStore } from "./src/revocation/memory.js";
 // HTTP transport helpers (the paved road: no localStorage, ever)
 export { buildTokenCookie, setTokenCookie, clearTokenCookie, readTokenCookie, } from "./src/http/cookies.js";
 export { parseBearer } from "./src/http/bearer.js";
+export {} from "./src/http/source.js";
 // Debugging escape hatch - branded untrusted, incompatible with VerifiedJwt
 export { unsafeDecode } from "./src/util/unsafe-decode.js";
 // Typed errors

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oDAAoD;AACpD,OAAO,EAAE,aAAa,EAAuB,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,UAAU;AACV,OAAO,EAAE,OAAO,EAAuB,MAAM,mBAAmB,CAAC;AAEjE,4DAA4D;AAC5D,OAAO,EAAE,UAAU,EAA0B,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACN,uBAAuB,GAEvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACN,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,GAGnB,MAAM,yBAAyB,CAAC;AAEjC,8EAA8E;AAC9E,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAEjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO;AACP,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACN,eAAe,EACf,cAAc,GAEd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEjE,mBAAmB;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAA4B,MAAM,sBAAsB,CAAC;AAEpF,aAAa;AACb,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,iEAAiE;AACjE,OAAO,EACN,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,eAAe,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,4EAA4E;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,eAAe;AACf,OAAO,EACN,QAAQ,EACR,UAAU,EACV,UAAU,EACV,wBAAwB,EACxB,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,eAAe;AACf,OAAO,EACN,SAAS,GAuBT,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oDAAoD;AACpD,OAAO,EAAE,aAAa,EAAuB,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,UAAU;AACV,OAAO,EAAE,OAAO,EAAuB,MAAM,mBAAmB,CAAC;AAEjE,4DAA4D;AAC5D,OAAO,EAAE,UAAU,EAA0B,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACN,uBAAuB,GAEvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACN,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,GAGnB,MAAM,yBAAyB,CAAC;AAEjC,8EAA8E;AAC9E,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAEjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO;AACP,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACN,eAAe,EACf,cAAc,GAEd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEjE,mBAAmB;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAA4B,MAAM,sBAAsB,CAAC;AAEpF,aAAa;AACb,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,iEAAiE;AACjE,OAAO,EACN,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,eAAe,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAqB,MAAM,sBAAsB,CAAC;AAEzD,4EAA4E;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,eAAe;AACf,OAAO,EACN,QAAQ,EACR,UAAU,EACV,UAAU,EACV,wBAAwB,EACxB,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,eAAe;AACf,OAAO,EACN,SAAS,GAuBT,MAAM,gBAAgB,CAAC"}

package/dist/src/http/bearer.js

@@ -6,6 +6,7 @@
  * whitespace tricks. One header, one scheme, one token.
  */
 import { BearerParseFailed } from "../util/errors.js";
+import { readHeaderValue } from "./source.js";
 // RFC 6750 credentials: exact-case scheme, a single SP, one token68.
 const BEARER = /^Bearer ([A-Za-z0-9\-._~+/]+=*)$/;
 const MAX_HEADER_LENGTH = 16384;
@@ -17,18 +18,13 @@ const MAX_HEADER_LENGTH = 16384;
  *
  * Note: when multiple `Authorization` headers were sent, `Headers`
  * joins them with `", "` - which this parser rejects, by design.
+ *
+ * A shape this library does not accept - notably a Node/Express
+ * request, whose `headers` is a plain record - throws {@link TypeError}
+ * rather than the misleading "missing header" it used to report.
  */
 export function parseBearer(source) {
-    let value;
-    if (typeof source === "string") {
-        value = source;
-    }
-    else if (source instanceof Headers) {
-        value = source.get("authorization");
-    }
-    else if (typeof source === "object" && source !== null && source.headers instanceof Headers) {
-        value = source.headers.get("authorization");
-    }
+    const value = readHeaderValue(source, "authorization", "parseBearer");
     if (typeof value !== "string" || value.length === 0) {
         throw new BearerParseFailed("Missing Authorization header");
     }

package/dist/src/http/bearer.js.map

@@ -1 +1 @@
-{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../../../src/http/bearer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,qEAAqE;AACrE,MAAM,MAAM,GAAG,kCAAkC,CAAC;AAClD,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAC1B,MAAkE;IAElE,IAAI,KAAgC,CAAC;IACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,KAAK,GAAG,MAAM,CAAC;IAChB,CAAC;SAAM,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;QACtC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;SAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,YAAY,OAAO,EAAE,CAAC;QAC/F,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,iBAAiB,CAAC,8BAA8B,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACtC,MAAM,IAAI,iBAAiB,CAAC,iDAAiD,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,iBAAiB,CAC1B,yFAAyF,CACzF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,CAAW,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../../../src/http/bearer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAqB,MAAM,aAAa,CAAC;AAEjE,qEAAqE;AACrE,MAAM,MAAM,GAAG,kCAAkC,CAAC;AAClD,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,MAAoB;IAC/C,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAC;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,iBAAiB,CAAC,8BAA8B,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACtC,MAAM,IAAI,iBAAiB,CAAC,iDAAiD,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,iBAAiB,CAC1B,yFAAyF,CACzF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,CAAW,CAAC;AAC3B,CAAC"}

package/dist/src/http/cookies.js

@@ -9,6 +9,7 @@
  * Framework-agnostic: works on WHATWG `Headers` (and anything exposing
  * them, e.g. `Request`/`Response`).
  */
+import { readHeaderValue } from "./source.js";
 // RFC 6265 cookie-name token; value charset covers compact JWTs.
 const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~A-Za-z0-9]+$/;
 const COOKIE_VALUE = /^[A-Za-z0-9._~+/=-]*$/;
@@ -67,30 +68,32 @@ export function clearTokenCookie(headers, options = {}) {
  * Read a token cookie from a request. Accepts a `Headers` object,
  * anything with a `.headers` (e.g. `Request`), or the raw `Cookie`
  * header string. Returns `undefined` when absent or malformed.
+ *
+ * Throws {@link TypeError} on a shape it does not accept - notably a
+ * Node/Express request, whose `headers` is a plain record. "I was
+ * handed something I don't understand" must not be indistinguishable
+ * from "this request carried no token".
  */
 export function readTokenCookie(source, name = DEFAULT_COOKIE_NAME) {
-    let cookieHeader;
-    if (typeof source === "string") {
-        cookieHeader = source;
-    }
-    else if (source instanceof Headers) {
-        cookieHeader = source.get("cookie");
-    }
-    else if (typeof source === "object" && source !== null && source.headers instanceof Headers) {
-        cookieHeader = source.headers.get("cookie");
-    }
+    const cookieHeader = readHeaderValue(source, "cookie", "readTokenCookie");
     if (typeof cookieHeader !== "string" || cookieHeader.length > 16384) {
         return undefined;
     }
+    let found;
     for (const pair of cookieHeader.split(";")) {
         const eq = pair.indexOf("=");
         if (eq === -1)
             continue;
         if (pair.slice(0, eq).trim() !== name)
             continue;
+        // Cookie shadowing: servers disagree about whether the first or last
+        // duplicate wins, so a header carrying the name twice is ambiguous.
+        // Ambiguous input is refused rather than guessed at.
+        if (found !== undefined)
+            return undefined;
         const value = pair.slice(eq + 1).trim();
-        return COOKIE_VALUE.test(value) && value.length > 0 ? value : undefined;
+        found = COOKIE_VALUE.test(value) && value.length > 0 ? value : "";
     }
-    return undefined;
+    return found === undefined || found === "" ? undefined : found;
 }
 //# sourceMappingURL=cookies.js.map

package/dist/src/http/cookies.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../../src/http/cookies.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../../src/http/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAqB,MAAM,aAAa,CAAC;AAEjE,iEAAiE;AACjE,MAAM,WAAW,GAAG,gCAAgC,CAAC;AACrD,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAE7C,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAe3C,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,UAA8B,EAAE;IAC/E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,mBAAmB,CAAC;IACjD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,qBAAqB,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3C,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC;IACjC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CAAC,qBAAqB,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YAClB,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;QACvD,CAAC;IACF,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,SAAS,CAAC,uBAAuB,CAAC,CAAC;QAC9C,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;QACrE,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,kEAAkE;IAClE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,YAAY,QAAQ,EAAE,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAC7B,OAAgB,EAChB,KAAa,EACb,UAA8B,EAAE;IAEhC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,gBAAgB,CAC/B,OAAgB,EAChB,UAAgE,EAAE;IAElE,OAAO,CAAC,MAAM,CACb,YAAY,EACZ,gBAAgB,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CACtF,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAoB,EACpB,OAAe,mBAAmB;IAElC,MAAM,YAAY,GAAG,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IAC1E,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;QACrE,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,KAAyB,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,SAAS;QACxB,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI;YAAE,SAAS;QAChD,qEAAqE;QACrE,oEAAoE;QACpE,qDAAqD;QACrD,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AAChE,CAAC"}

package/dist/src/http/source.js

@@ -0,0 +1,49 @@
+/**
+ * Header-source narrowing shared by the cookie and bearer readers.
+ *
+ * The contract is deliberately narrow: WHATWG `Headers` (or anything
+ * carrying them, e.g. `Request`) or the raw header string. Node's
+ * `IncomingMessage.headers` is a plain record, not `Headers`, and is
+ * *not* accepted - callers on Express/Fastify/Koa convert once at the
+ * edge rather than making every reader here carry a second shape.
+ *
+ * What matters is that an unrecognized shape throws instead of reading
+ * as "header absent". A helper that silently returns nothing for an
+ * argument it never understood is one people route around, and the
+ * hand-rolled replacement has none of the ambiguity refusals below.
+ */
+// Duck-typed rather than `instanceof`: a `Headers` from another realm
+// (undici's own copy, a vm context, an edge/node boundary) is still a
+// `Headers`, and `instanceof` would reject it. This widens nothing -
+// a plain Node header record has no `.get` and still fails.
+function isHeadersLike(value) {
+    return (typeof value === "object" && value !== null && typeof value.get === "function");
+}
+/**
+ * Read one header from an accepted source. Returns `undefined` when the
+ * header is absent; throws {@link TypeError} when `source` is a shape
+ * this library does not accept.
+ *
+ * @param helper - calling helper's name, used in the error message.
+ */
+export function readHeaderValue(source, header, helper) {
+    // An explicit nothing - including the `null` that `Headers.get` itself
+    // returns - is a legitimate "no such header", not a caller mistake.
+    if (source === null || source === undefined)
+        return undefined;
+    if (typeof source === "string")
+        return source;
+    if (isHeadersLike(source)) {
+        const value = source.get(header);
+        return typeof value === "string" ? value : undefined;
+    }
+    if (typeof source === "object" && isHeadersLike(source.headers)) {
+        const value = source.headers.get(header);
+        return typeof value === "string" ? value : undefined;
+    }
+    throw new TypeError(`${helper}() expects a Headers, an object with a .headers (e.g. Request), a raw ` +
+        "header string, or null/undefined. Node-style requests (Express, Fastify, Koa) " +
+        "expose a plain object instead - convert it first: " +
+        "new Headers(req.headers as Record<string, string>)");
+}
+//# sourceMappingURL=source.js.map

package/dist/src/http/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../../src/http/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,sEAAsE;AACtE,sEAAsE;AACtE,qEAAqE;AACrE,4DAA4D;AAC5D,SAAS,aAAa,CAAC,KAAc;IACpC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAAiB,CAAC,GAAG,KAAK,UAAU,CAC3F,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAoB,EACpB,MAAc,EACd,MAAc;IAEd,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9D,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC9C,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,aAAa,CAAE,MAAgC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5F,MAAM,KAAK,GAAI,MAA+B,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnE,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IACD,MAAM,IAAI,SAAS,CAClB,GAAG,MAAM,wEAAwE;QAChF,gFAAgF;QAChF,oDAAoD;QACpD,oDAAoD,CACrD,CAAC;AACH,CAAC"}

package/dist/src/jwks/local.js

@@ -26,8 +26,9 @@ function isCandidate(jwk, header) {
     return true;
 }
 /** Shared selection + import used by both local and remote sets. */
-export async function resolveFromJwks(keys, header) {
-    const candidates = keys.filter((jwk) => isCandidate(jwk, header));
+export async function resolveFromJwks(keys, header, options = {}) {
+    const allowSymmetric = options.allowSymmetric ?? true;
+    const candidates = keys.filter((jwk) => isCandidate(jwk, header) && (allowSymmetric || jwk.kty !== "oct"));
     if (candidates.length === 0) {
         throw new JWKSNoMatchingKey("No key in the JWKS matches this token");
     }

package/dist/src/jwks/local.js.map

@@ -1 +1 @@
-{"version":3,"file":"local.js","sourceRoot":"","sources":["../../../src/jwks/local.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../../src/jwks/local.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,GACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AASvD,SAAS,WAAW,CAAC,GAAc,EAAE,MAAiB;IACrD,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC7D,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,KAAM,MAAM,CAAC,GAAc;QAAE,OAAO,KAAK,CAAC;IAC9E,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACrE,OAAO,IAAI,CAAC;AACb,CAAC;AAWD,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,IAA0B,EAC1B,MAAiB,EACjB,UAAkC,EAAE;IAEpC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,IAAI,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAC7B,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,cAAc,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK,CAAC,CAC1E,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,iBAAiB,CAAC,uCAAuC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,iBAAiB,CAC1B,sEAAsE,CACtE,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAc,CAAC;IACvC,IAAI,CAAC;QACJ,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK,EAAE,CAAC;YACvB,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC/B,MAAM,IAAI,eAAe,CAAC,qCAAqC,CAAC,CAAC;YAClE,CAAC;YACD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACtC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YACvC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;QACzC,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAC1B,GAAsC,EACtC,MAAM,CAAC,GAAG,CACV,CAAC;QACF,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,YAAY,eAAe,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;YAC7E,MAAM,KAAK,CAAC;QACb,CAAC;QACD,MAAM,IAAI,eAAe,CAAC,gCAAgC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACxE,CAAC;AACF,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC9C,IACC,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,CAAC,KAAK,CAAC,OAAO,CAAE,IAAmB,CAAC,IAAI,CAAC,EACxC,CAAC;QACF,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,IAAI,GAAI,IAAmB,CAAC,IAAI,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IAChE,CAAC;IACD,uEAAuE;IACvE,oEAAoE;IACpE,OAAO,IAAI,CAAC,MAAM,CACjB,CAAC,GAAG,EAAE,EAAE,CACP,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ;QAC3B,CAAC,GAAG,CAAC,GAAG,KAAK,SAAS;YACrB,CAAC,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAC7D,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,IAAgB;IACjD,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO;QACN,kBAAkB,CAAC,MAAiB;YACnC,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;KACD,CAAC;AACH,CAAC"}