lacewing 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-07-12
+
+### Miscellaneous Tasks
+
+- Corrected url post migration from old repo
+
+<!-- generated by git-cliff -->

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Smiduweorc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/NOTICE.md

@@ -0,0 +1 @@
+This project includes code adapted from the [jose](https://github.com/panva/jose) repository, created by Panva. We are grateful for their work!

package/README.md

@@ -0,0 +1,313 @@
+# Lacewing
+![Logo](./assets/logo.png)
+
+**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.
+
+**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
+- **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
+
+## Requirements
+
+- Node **>= 24**
+- **ESM** only
+- **TypeScript-first** (full types shipped; the branded `VerifiedJwt`/`UntrustedJwt` types are part of the security model)
+
+## Installation
+
+```bash
+npm install lacewing
+```
+
+## Quick start
+
+The complete lifecycle - generate a key, sign, define a profile once, verify everywhere:
+
+```ts
+import { SignJWT, defineProfile, jwtVerify, generateKeyPair } from "lacewing";
+
+const { publicKey, privateKey } = await generateKeyPair(); // EdDSA by default
+
+const token = await new SignJWT("at+jwt")
+	.issuer("https://auth.example.com")
+	.audience("https://api.example.com")
+	.subject("user-42")
+	.expiresIn("10m")
+	.sign(privateKey);
+
+const profile = defineProfile({
+	typ: "at+jwt",
+	issuer: "https://auth.example.com",
+	audience: "https://api.example.com",
+	algorithms: ["EdDSA"],
+	keys: publicKey,
+	maxTokenAge: "10m",
+});
+
+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.
+
+**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
+
+### Verify: a profile backed by a remote JWKS
+
+This is what real deployments should look like, so it's the first example:
+
+```ts
+import { defineProfile, jwtVerify, createRemoteJWKSet } from "lacewing";
+
+const accessToken = defineProfile({
+	typ: "at+jwt",
+	issuer: "https://auth.example.com",
+	audience: "https://api.example.com",
+	algorithms: ["EdDSA"],
+	keys: createRemoteJWKSet("https://auth.example.com/jwks"), // cached, rate-limited, rotation-aware, HTTPS-only
+	maxTokenAge: "10m",
+});
+
+const { payload } = await jwtVerify(token, accessToken); // VerifiedJwt - every check passed
+```
+
+### 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
+JWS payload is base64url-encoded plaintext, readable by anyone who holds the
+token**. Never put secrets in it.
+
+```ts
+import { SignJWT, generateKeyPair } from "lacewing";
+
+const { publicKey, privateKey } = await generateKeyPair(); // EdDSA by default
+
+const token = await new SignJWT("at+jwt")
+	.issuer("https://auth.example.com")
+	.audience("https://api.example.com")
+	.subject("user-42")
+	.claim("scope", "read")
+	.expiresIn("10m")
+	.sign(privateKey);
+```
+
+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.
+
+### Transport: the paved road
+
+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
+const fromCookie = readTokenCookie(request);
+const fromHeader = parseBearer(request); // strict RFC 6750; no query-string tokens, ever
+```
+
+### 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
+`typ` (RFC 8725 §3.12), so presenting one where the other is expected fails,
+even with identical keys, claims and audience:
+
+```ts
+import { accessTokenProfile, refreshTokenProfile, newAccessToken } from "lacewing";
+
+const api = accessTokenProfile({          // typ: "at+jwt", 10m default cap
+  issuer: "https://auth.example.com",
+  audience: "https://api.example.com",    // the API
+  algorithms: ["EdDSA"],
+  keys: { jwksUri: "https://auth.example.com/jwks" },
+});
+
+const refresh = refreshTokenProfile({     // typ: "rt+jwt", 30d default cap
+  issuer: "https://auth.example.com",
+  audience: "https://auth.example.com/token", // the auth server, never the API
+  algorithms: ["EdDSA"],
+  keys: privateJwks,
+  revocation,                              // long-lived tokens must be revocable
+});
+
+const token = await newAccessToken()
+  .issuer("https://auth.example.com")
+  .audience("https://api.example.com")
+  .subject("user-42")
+  .expiresIn("10m")
+  .sign(privateKey);
+
+await jwtVerify(token, refresh); // -> JWTClaimValidationFailed (wrong typ)
+```
+
+### Revocation is built-in, not homework
+
+```ts
+import { MemoryRevocationStore } from "lacewing";
+
+const revocation = new MemoryRevocationStore(); // or your Redis/DB adapter (RevocationStore)
+const profile = defineProfile({ /* ...as above... */ revocation });
+
+revocation.revoke(payload.jti, payload.exp); // e.g. on logout
+await jwtVerify(token, profile); // -> JWTRevoked
+```
+
+The store is consulted only *after* signature and claims pass, and store
+errors fail closed.
+
+## Advanced
+
+### 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
+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.
+
+Your levers, in order of cheapness:
+
+- **Short lifetimes.** The default caps (10m access tokens) exist exactly to
+  shrink the replay window. Prefer shortening `exp` over building state.
+- **Revocation on every logout/refresh**, so a stolen token dies with the
+  session it came from.
+- **A jti-seen cache** when an endpoint must be strictly once-only (e.g. a
+  password-reset action token): every Lacewing token carries a unique `jti`,
+  so you can reject repeats with a `claimValidators` entry backed by a
+  store with the token's remaining TTL:
+
+  ```ts
+  const profile = defineProfile({
+    /* ...as above... */
+    claimValidators: {
+      jti: async (jti) => {
+        // setnx-style: returns false if the jti was already seen
+        if (!(await seenCache.addIfAbsent(String(jti), remainingTtl))) {
+          throw new Error("token replayed");
+        }
+      },
+    },
+  });
+  ```
+
+  This is intentionally not built in: a once-only cache is a distributed-state
+  decision (which store, which TTL, what happens when it's down) that your
+  deployment has to own, not something a library should silently half-do.
+- **Proof-of-possession** (mTLS-bound or DPoP-bound tokens) when replay by a
+  network eavesdropper is in your threat model. That is beyond Lacewing's
+  bearer-token scope today.
+
+### 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
+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
+whole point:
+
+```ts
+import {
+  EncryptJWT, jwtDecrypt, defineDecryptionProfile, generateEncryptionKeyPair,
+} from "lacewing";
+
+const { publicKey, privateKey } = await generateEncryptionKeyPair("ECDH-ES+A256KW");
+
+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
+  .expiresIn("10m")
+  .encrypt(publicKey);
+
+const profile = defineDecryptionProfile({
+  typ: "at+jwt",
+  issuer: "https://auth.example.com",
+  audience: "https://api.example.com",
+  keyManagementAlgorithms: ["ECDH-ES+A256KW"], // the header never chooses
+  contentEncryptionAlgorithms: ["A256GCM"],
+  key: privateKey,
+  maxTokenAge: "10m",
+});
+
+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.
+
+**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.
+
+### Debugging
+
+`unsafeDecode(token)` parses without verifying and returns an `UntrustedJwt`
+that is type-incompatible with `VerifiedJwt` - useful for inspecting expired
+tokens, useless (by design) for auth logic.
+
+### Legacy interop
+
+The `RS*` (RSASSA-PKCS1-v1_5) family exists only behind an explicit import, for
+verifying tokens from issuers you don't control and can't move off PKCS#1 v1.5:
+
+```ts
+import { enableLegacyRS256 } from "lacewing/legacy/rs256";
+enableLegacyRS256(); // grep for this in code review
+
+// Or, for an issuer that rotates across hash sizes:
+import { enableLegacyRSA } from "lacewing/legacy/rsa"; // RS256 + RS384 + RS512
+```
+
+Prefer `PS256`/`EdDSA` everywhere you control both sides.
+
+## Why Lacewing exists
+
+Lacewing is not trying to compete with general-purpose JWT libraries. It started as the hardened setup I kept rebuilding for my own projects, packaged so I'd stop rebuilding it.
+
+The other reason is irritation. Generic JWT libraries are fine, but they leave enough rope for misinformed developers (and lazy AI slop) to ship something unsafe. It pisses me off when people implement something genuinely safe wrongly and then blame the technology instead of accepting operator error. These are the mistakes Lacewing makes unrepresentable or loudly explicit:
+
+- Decoding instead of verifying
+- Accepting `"none"` for the algorithm
+- No explicit allowlist on the server that enforces expected algorithms
+- Putting sensitive data in the token payload
+- 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
+
+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
+
+Lacewing depends on and includes code adapted from the [jose](https://github.com/panva/jose) library, created by Filip Skokan (panva). We are grateful for their work!

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * Lacewing - an opinionated JWT library where RFC 8725 (JWT Best Current
+ * Practices) is the default behavior, not an optional configuration.
+ *
+ * This barrel is the public API. Internals under `src/lib/` are policy
+ * machinery and stay private; legacy interop algorithms live behind the
+ * explicit `lacewing/legacy/*` imports.
+ */
+// Verification profiles + the one verification path
+export { defineProfile } from "./src/jwt/profile.js";
+export { jwtVerify } from "./src/jwt/verify.js";
+// Signing
+export { SignJWT } from "./src/jwt/sign.js";
+// Encryption (JWE) - same profile discipline as sign/verify
+export { EncryptJWT } from "./src/jwt/encrypt.js";
+export { jwtDecrypt } from "./src/jwt/decrypt.js";
+export { defineDecryptionProfile, } from "./src/jwt/decryption_profile.js";
+export { generateEncryptionKeyPair, generateEncryptionSecret, generateDirectKey, importEncryptionKey, } from "./src/key/encryption.js";
+// Cookbook: the access-vs-refresh split, shipped rather than left as homework
+export { accessTokenProfile, refreshTokenProfile, newAccessToken, newRefreshToken, ACCESS_TOKEN_TYP, REFRESH_TOKEN_TYP, } from "./src/cookbook/access-refresh.js";
+// Keys
+export { importKey } from "./src/key/import.js";
+export { generateKeyPair, generateSecret, } from "./src/key/generate.js";
+export { exportKeyJWK, exportKeyPEM } from "./src/key/export.js";
+// JWKS key sources
+export { createLocalJWKSet } from "./src/jwks/local.js";
+export { createRemoteJWKSet } from "./src/jwks/remote.js";
+// Revocation
+export { buildRevocationContext } from "./src/revocation/store.js";
+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";
+// Debugging escape hatch - branded untrusted, incompatible with VerifiedJwt
+export { unsafeDecode } from "./src/util/unsafe-decode.js";
+// Typed errors
+export { JWTError, JWTInvalid, JWTExpired, JWTClaimValidationFailed, MissingClaim, AlgorithmNotAllowed, KeyImportFailed, KeyExportFailed, KeyTypeMismatch, EntropyCheckFailed, JWKSFetchFailed, JWKSNoMatchingKey, JWTRevoked, RevocationCheckFailed, PayloadHygieneViolation, MaxLifetimeExceeded, BearerParseFailed, } from "./src/util/errors.js";
+// Public types
+export { toSeconds, } from "./src/types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/src/cookbook/access-refresh.js

@@ -0,0 +1,86 @@
+/**
+ * Cookbook: access tokens vs refresh tokens (LW-kind.1).
+ *
+ * The single most common token-confusion bug is letting a refresh token buy
+ * access to an API (or letting a stolen access token mint new sessions). RFC
+ * 8725 §3.12 says the validation rules for different kinds of JWT must be
+ * mutually exclusive; Lacewing makes that concrete by shipping the two
+ * profiles rather than leaving them as an exercise.
+ *
+ * The separation is enforced on three axes at once:
+ *
+ *  | | access | refresh |
+ *  |---|---|---|
+ *  | `typ` | `at+jwt` | `rt+jwt` |
+ *  | audience | the API | the auth server's token endpoint |
+ *  | lifetime | minutes (default 10m) | days (default 30d) |
+ *  | key source | usually a public JWKS | usually a private, server-only key |
+ *  | revocation | optional | **strongly recommended** |
+ *
+ * `typ` alone is load-bearing: even with identical keys, claims and audience,
+ * each profile refuses the other's tokens. The rest is defense in depth.
+ *
+ * @example
+ * ```ts
+ * import { accessTokenProfile, refreshTokenProfile, newAccessToken } from "lacewing";
+ *
+ * const api = accessTokenProfile({
+ *   issuer: "https://auth.example.com",
+ *   audience: "https://api.example.com",
+ *   algorithms: ["EdDSA"],
+ *   keys: { jwksUri: "https://auth.example.com/jwks" },
+ * });
+ *
+ * const token = await newAccessToken()
+ *   .issuer("https://auth.example.com")
+ *   .audience("https://api.example.com")
+ *   .subject("user-42")
+ *   .expiresIn("10m")
+ *   .sign(privateKey);
+ * ```
+ */
+import { defineProfile } from "../jwt/profile.js";
+import { SignJWT } from "../jwt/sign.js";
+/** The `typ` of an OAuth 2.0 JWT access token (RFC 9068). */
+export const ACCESS_TOKEN_TYP = "at+jwt";
+/** The `typ` Lacewing uses for refresh tokens - anything but the access `typ`. */
+export const REFRESH_TOKEN_TYP = "rt+jwt";
+const DEFAULT_ACCESS_MAX_AGE = "10m";
+const DEFAULT_REFRESH_MAX_AGE = "30d";
+/**
+ * An access-token profile: short-lived, audience-scoped to your API, and
+ * pinned to `typ: "at+jwt"`. Verifies tokens presented by clients.
+ */
+export function accessTokenProfile(options) {
+    return defineProfile({
+        ...options,
+        maxTokenAge: options.maxTokenAge ?? DEFAULT_ACCESS_MAX_AGE,
+        typ: ACCESS_TOKEN_TYP,
+    });
+}
+/**
+ * A refresh-token profile: long-lived, audience-scoped to the *auth server*
+ * (never the API), and pinned to `typ: "rt+jwt"`. Pass a `revocation` store -
+ * a long-lived token you cannot revoke is a long-lived incident.
+ */
+export function refreshTokenProfile(options) {
+    return defineProfile({
+        ...options,
+        maxTokenAge: options.maxTokenAge ?? DEFAULT_REFRESH_MAX_AGE,
+        typ: REFRESH_TOKEN_TYP,
+    });
+}
+/** A {@link SignJWT} builder pre-set to the access-token `typ` and a 1h cap. */
+export function newAccessToken() {
+    return new SignJWT(ACCESS_TOKEN_TYP, { maxLifetime: "1h" });
+}
+/**
+ * A {@link SignJWT} builder pre-set to the refresh-token `typ`. The cap is
+ * raised to 90d because that is the point of a refresh token - but the
+ * lifetime you actually pass to `.expiresIn()` should be as short as your UX
+ * tolerates, and the token should be revocable.
+ */
+export function newRefreshToken() {
+    return new SignJWT(REFRESH_TOKEN_TYP, { maxLifetime: "90d" });
+}
+//# sourceMappingURL=access-refresh.js.map

package/dist/src/cookbook/access-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-refresh.js","sourceRoot":"","sources":["../../../src/cookbook/access-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,aAAa,EAAuB,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AACzC,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAE1C,MAAM,sBAAsB,GAAG,KAAK,CAAC;AACrC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAWtC;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,OAAO,aAAa,CAAC;QACpB,GAAG,OAAO;QACV,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,sBAAsB;QAC1D,GAAG,EAAE,gBAAgB;KACrB,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA4B;IAC/D,OAAO,aAAa,CAAC;QACpB,GAAG,OAAO;QACV,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,uBAAuB;QAC3D,GAAG,EAAE,iBAAiB;KACtB,CAAC,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,cAAc;IAC7B,OAAO,IAAI,OAAO,CAAC,gBAAgB,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,iBAAiB,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/dist/src/http/bearer.js

@@ -0,0 +1,44 @@
+/**
+ * Strict `Authorization: Bearer` parsing (RFC 6750 §2.1, LW-http.2).
+ *
+ * Deliberately unsupported: tokens in query strings (they leak through
+ * logs and the Referer header), multiple tokens, alternate casings and
+ * whitespace tricks. One header, one scheme, one token.
+ */
+import { BearerParseFailed } from "../util/errors.js";
+// RFC 6750 credentials: exact-case scheme, a single SP, one token68.
+const BEARER = /^Bearer ([A-Za-z0-9\-._~+/]+=*)$/;
+const MAX_HEADER_LENGTH = 16384;
+/**
+ * Extract the bearer token from an `Authorization` header. Accepts a
+ * `Headers` object, anything with a `.headers` (e.g. `Request`), or the
+ * raw header value. Throws {@link BearerParseFailed} on anything that
+ * isn't exactly one well-formed `Bearer <token>`.
+ *
+ * Note: when multiple `Authorization` headers were sent, `Headers`
+ * joins them with `", "` - which this parser rejects, by design.
+ */
+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");
+    }
+    if (typeof value !== "string" || value.length === 0) {
+        throw new BearerParseFailed("Missing Authorization header");
+    }
+    if (value.length > MAX_HEADER_LENGTH) {
+        throw new BearerParseFailed("Authorization header exceeds the maximum length");
+    }
+    const match = BEARER.exec(value);
+    if (match === null) {
+        throw new BearerParseFailed("Authorization header failed strict Bearer parsing (expected exactly \"Bearer <token>\")");
+    }
+    return match[1];
+}
+//# sourceMappingURL=bearer.js.map

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

@@ -0,0 +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"}

package/dist/src/http/cookies.js

@@ -0,0 +1,96 @@
+/**
+ * Cookie transport helpers (LW-http.1).
+ *
+ * The paved road for browser token storage: `HttpOnly; Secure; SameSite`
+ * are always emitted and cannot be configured away - weaker cookies are
+ * unrepresentable. `localStorage`/`sessionStorage` are script-readable
+ * and therefore one XSS away from token theft; don't put tokens there.
+ *
+ * Framework-agnostic: works on WHATWG `Headers` (and anything exposing
+ * them, e.g. `Request`/`Response`).
+ */
+// RFC 6265 cookie-name token; value charset covers compact JWTs.
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~A-Za-z0-9]+$/;
+const COOKIE_VALUE = /^[A-Za-z0-9._~+/=-]*$/;
+const DEFAULT_COOKIE_NAME = "__Host-token";
+/** Build a hardened `Set-Cookie` value. Prefer {@link setTokenCookie}. */
+export function buildTokenCookie(token, options = {}) {
+    if (typeof token !== "string" || !COOKIE_VALUE.test(token) || token.length === 0) {
+        throw new TypeError("Token contains characters that cannot be stored in a cookie");
+    }
+    const name = options.name ?? DEFAULT_COOKIE_NAME;
+    if (!COOKIE_NAME.test(name)) {
+        throw new TypeError("Invalid cookie name");
+    }
+    const sameSite = options.sameSite ?? "Lax";
+    if (sameSite !== "Lax" && sameSite !== "Strict") {
+        throw new TypeError("SameSite must be \"Lax\" or \"Strict\" - \"None\" is not supported");
+    }
+    const path = options.path ?? "/";
+    if (path.includes(";") || !path.startsWith("/")) {
+        throw new TypeError("Invalid cookie path");
+    }
+    if (name.startsWith("__Host-")) {
+        if (options.domain !== undefined) {
+            throw new TypeError("__Host- cookies must not set a Domain");
+        }
+        if (path !== "/") {
+            throw new TypeError("__Host- cookies require Path=/");
+        }
+    }
+    const parts = [`${name}=${token}`, `Path=${path}`];
+    if (options.domain !== undefined) {
+        if (!/^[A-Za-z0-9.-]+$/.test(options.domain)) {
+            throw new TypeError("Invalid cookie domain");
+        }
+        parts.push(`Domain=${options.domain}`);
+    }
+    if (options.maxAgeSeconds !== undefined) {
+        if (!Number.isInteger(options.maxAgeSeconds) || options.maxAgeSeconds < 0) {
+            throw new TypeError("maxAgeSeconds must be a non-negative integer");
+        }
+        parts.push(`Max-Age=${options.maxAgeSeconds}`);
+    }
+    // Non-negotiable (LW-http.1). There is no option to remove these.
+    parts.push("HttpOnly", "Secure", `SameSite=${sameSite}`);
+    return parts.join("; ");
+}
+/** Append a hardened token cookie to a response's headers. */
+export function setTokenCookie(headers, token, options = {}) {
+    headers.append("Set-Cookie", buildTokenCookie(token, options));
+}
+/** Expire a previously set token cookie. */
+export function clearTokenCookie(headers, options = {}) {
+    headers.append("Set-Cookie", buildTokenCookie("x", { ...options, maxAgeSeconds: 0 }).replace(/^([^=]+)=x;/, "$1=;"));
+}
+/**
+ * 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.
+ */
+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");
+    }
+    if (typeof cookieHeader !== "string" || cookieHeader.length > 16384) {
+        return undefined;
+    }
+    for (const pair of cookieHeader.split(";")) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        if (pair.slice(0, eq).trim() !== name)
+            continue;
+        const value = pair.slice(eq + 1).trim();
+        return COOKIE_VALUE.test(value) && value.length > 0 ? value : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=cookies.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../../src/http/cookies.ts"],"names":[],"mappings":"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"}