@dwk/dpop 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# `@dwk/dpop`
+
+> DPoP (RFC 9449) proof verification. Cross-standard reusable.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/dpop.md) for the full requirements.
+
+This package is **cross-standard reusable**: it takes plain-data inputs only,
+has no Workers-runtime dependency (only Web Crypto), and unit-tests in isolation
+(Node, no `workerd`). It is **protocol-agnostic** — it knows nothing about
+IndieAuth or Solid. The caller supplies the request facts and any access-token
+binding it expects, and owns replay detection via the returned `jti`.
+
+## API
+
+```ts
+import { verifyDpopProof } from "@dwk/dpop";
+
+const result = await verifyDpopProof({
+  proof: request.headers.get("DPoP")!, // the DPoP proof JWT
+  htm: request.method, // HTTP method, e.g. "POST"
+  htu: "https://pod.example/resource", // request URI (query/fragment ignored)
+  // now,            // epoch seconds; defaults to Date.now()
+  // maxAgeSeconds,  // iat clock-skew window; defaults to 300
+});
+
+if (!result.valid) {
+  // result.reason is a stable code, e.g. "htu_mismatch", "signature_invalid"
+  return new Response("invalid DPoP proof", { status: 401 });
+}
+
+// Enforce your own replay policy with the verified jti.
+if (await seenBefore(result.jti)) return new Response("DPoP replay", { status: 401 });
+```
+
+### Resource Server: token binding
+
+When a request carries a DPoP-bound access token, pass the token and the token's
+`cnf.jkt` to verify the binding:
+
+```ts
+const result = await verifyDpopProof({
+  proof,
+  htm,
+  htu,
+  accessToken, // proof MUST carry ath = base64url(SHA-256(accessToken))
+  expectedJkt, // proof key thumbprint MUST equal this
+});
+```
+
+A Resource Server enforcing `ath` MUST pass `expectedJkt` too: `ath` only proves
+the proof was made for this token, while `cnf.jkt` proves the proof key is the
+one the token was issued to. Supplying `accessToken` without `expectedJkt` is
+rejected with `jkt_required` rather than validating an unbound proof
+(RFC 9449 §7.1).
+
+## What is verified
+
+- **Header** — `typ` is exactly `dpop+jwt`; no `crit` parameter is present
+  (RFC 7515 §4.1.11); `alg` is an asymmetric algorithm from the allow-list
+  (`ES256`, `ES384`, `RS256`, `PS256` — never `none` or HMAC); `jwk` is present,
+  carries no private key material, has an EC `crv` matching the `alg`, and (for
+  RSA) a modulus of at least 2048 bits.
+- **Signature** — over `header.payload` using the embedded `jwk`.
+- **Claims** — `htm` matches the request method (case-insensitive); `htu`
+  matches the request URI after normalization (scheme/host lowercased, default
+  port and any query/fragment removed); `iat` is within the clock-skew window;
+  `jti` is a present, non-empty string.
+- **Bindings** (optional) — `ath` matches `base64url(SHA-256(accessToken))`; the
+  computed `jkt` (RFC 7638 thumbprint) equals `expectedJkt`.
+- **Server nonce** (optional, RFC 9449 §8/§9) — when `expectedNonce` is supplied,
+  the proof's `nonce` claim must equal it (else `nonce_mismatch`). The proof's
+  `nonce` is surfaced on the result either way so a caller can answer a mismatch
+  with a `use_dpop_nonce` error and a fresh `DPoP-Nonce`.
+
+`verifyDpopProof` never throws — failures return `{ valid: false, reason }` with
+a stable `DpopFailureReason` code (the proof's `nonce` is also surfaced on a
+`nonce_mismatch`). On success it returns `{ valid: true, jti, jkt, nonce? }`.
+
+## Out of scope
+
+- Replay detection storage (the caller owns the `jti` cache).
+- `DPoP-Nonce` issuance and rotation, and emitting the `use_dpop_nonce` error
+  (the caller owns the nonce lifecycle; this lib only checks the proof's `nonce`
+  against the `expectedNonce` it is given).
+- Access-token validation beyond the DPoP binding checks.
+
+## License
+
+[ISC](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `@dwk/dpop` — DPoP (RFC 9449) proof verification.
+ *
+ * A pure, runtime-agnostic library: HTTP request facts and token claims go in,
+ * a verification result comes out. It performs no I/O beyond Web Crypto, holds
+ * no state, and needs no Cloudflare bindings, so it unit-tests without a
+ * Workers runtime.
+ *
+ * The library stays protocol-agnostic — it knows nothing about IndieAuth or
+ * Solid. The caller supplies the request facts and any access-token binding it
+ * expects, and owns replay detection via the returned `jti`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9449
+ * @see spec/packages/dpop.md
+ * @packageDocumentation
+ */
+/** Default clock-skew window (seconds) applied to `iat` when none is given. */
+export declare const DEFAULT_MAX_AGE_SECONDS = 300;
+/**
+ * Asymmetric signature algorithms accepted in the DPoP proof JOSE header.
+ *
+ * Symmetric (`HS*`) and `none` are deliberately excluded: a DPoP proof must be
+ * signed by the client-held private key whose public half is embedded as `jwk`.
+ */
+export type DpopAlgorithm = "ES256" | "ES384" | "RS256" | "PS256";
+/** Stable, locale-independent failure codes returned in {@link DpopVerifyResult.reason}. */
+export type DpopFailureReason = "proof_malformed" | "header_invalid" | "payload_invalid" | "typ_invalid" | "crit_unsupported" | "alg_unsupported" | "jwk_missing" | "jwk_private" | "jwk_invalid" | "crv_mismatch" | "rsa_key_too_small" | "signature_invalid" | "htm_mismatch" | "htu_invalid" | "htu_mismatch" | "iat_invalid" | "proof_expired" | "proof_future" | "jti_missing" | "nonce_mismatch" | "ath_mismatch" | "jkt_required" | "jkt_mismatch";
+/** Plain-data inputs required to verify a DPoP proof. */
+export interface DpopVerifyInput {
+    /** The DPoP proof JWT (compact JWS) from the `DPoP` header. */
+    proof: string;
+    /** HTTP method of the request the proof is bound to, e.g. `"POST"`. */
+    htm: string;
+    /** HTTP target URI of the request (query/fragment are ignored per §4.3). */
+    htu: string;
+    /**
+     * Expected access-token hash binding (Resource Server case). When provided,
+     * the proof MUST carry an `ath` claim equal to `base64url(SHA-256(accessToken))`.
+     *
+     * A Resource Server enforcing `ath` MUST also supply {@link expectedJkt}: the
+     * `ath` proves the proof was made for this token, but only the `cnf.jkt`
+     * binding proves the proof key is the one the token was issued to. Passing
+     * `accessToken` without `expectedJkt` defeats proof-of-possession
+     * (RFC 9449 §7.1) and is rejected with `jkt_required` rather than validating.
+     */
+    accessToken?: string;
+    /**
+     * Token confirmation thumbprint (`cnf.jkt`) to match against the proof key.
+     * Required whenever {@link accessToken} is supplied (see its note).
+     */
+    expectedJkt?: string;
+    /**
+     * Server-provided DPoP nonce the proof must carry (RFC 9449 §8/§9). When set,
+     * the proof MUST carry a `nonce` claim equal to this value, else it is
+     * rejected with `nonce_mismatch`. An AS/RS uses this to bound proof lifetime
+     * and force fresh proofs as a replay defense: on a mismatch (or when no nonce
+     * was sent yet) the caller answers with a `use_dpop_nonce` error carrying a
+     * fresh `DPoP-Nonce`. Issuing and rotating the nonce is the caller's job; this
+     * library only checks equality and surfaces the proof's {@link DpopVerifyResult.nonce}.
+     */
+    expectedNonce?: string;
+    /** Current time in seconds since the epoch. Defaults to `Date.now()`. */
+    now?: number;
+    /** Allowed clock skew in seconds for the `iat` window. Defaults to {@link DEFAULT_MAX_AGE_SECONDS}. */
+    maxAgeSeconds?: number;
+}
+/** Result of verifying a DPoP proof. */
+export interface DpopVerifyResult {
+    /** Whether the proof is valid. */
+    valid: boolean;
+    /** The verified JWT ID (`jti`) for replay detection by the caller. */
+    jti?: string;
+    /** The RFC 7638 thumbprint of the proof key (`jkt`). */
+    jkt?: string;
+    /**
+     * The proof's `nonce` claim, when it carried one (string only). Surfaced on
+     * both success and a `nonce_mismatch` so a caller enforcing the
+     * `DPoP-Nonce` mechanism (RFC 9449 §8/§9) can decide whether to answer with a
+     * `use_dpop_nonce` error and a fresh nonce.
+     */
+    nonce?: string;
+    /** Stable failure code (see {@link DpopFailureReason}) when `valid` is false. */
+    reason?: DpopFailureReason;
+}
+/**
+ * Verify a DPoP proof JWT and, optionally, its binding to an access token.
+ *
+ * Pure async function; performs no I/O beyond Web Crypto. Never throws — every
+ * failure is returned as `{ valid: false, reason }` with a stable
+ * {@link DpopFailureReason} code.
+ *
+ * @param input - Request facts, the proof, and any expected token binding.
+ * @returns On success `{ valid: true, jti, jkt }`; otherwise `{ valid: false, reason }`.
+ */
+export declare function verifyDpopProof(input: DpopVerifyInput): Promise<DpopVerifyResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAElE,4FAA4F;AAC5F,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,GACjB,aAAa,GACb,kBAAkB,GAClB,iBAAiB,GACjB,aAAa,GACb,aAAa,GACb,aAAa,GACb,cAAc,GACd,mBAAmB,GACnB,mBAAmB,GACnB,cAAc,GACd,aAAa,GACb,cAAc,GACd,aAAa,GACb,eAAe,GACf,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,cAAc,CAAC;AAEnB,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAkMD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,CAAC,CA6L3B"}

package/dist/index.js

@@ -0,0 +1,333 @@
+/**
+ * `@dwk/dpop` — DPoP (RFC 9449) proof verification.
+ *
+ * A pure, runtime-agnostic library: HTTP request facts and token claims go in,
+ * a verification result comes out. It performs no I/O beyond Web Crypto, holds
+ * no state, and needs no Cloudflare bindings, so it unit-tests without a
+ * Workers runtime.
+ *
+ * The library stays protocol-agnostic — it knows nothing about IndieAuth or
+ * Solid. The caller supplies the request facts and any access-token binding it
+ * expects, and owns replay detection via the returned `jti`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9449
+ * @see spec/packages/dpop.md
+ * @packageDocumentation
+ */
+/** Default clock-skew window (seconds) applied to `iat` when none is given. */
+export const DEFAULT_MAX_AGE_SECONDS = 300;
+const ALGS = {
+    ES256: {
+        kty: "EC",
+        expectedCrv: "P-256",
+        importParams: { name: "ECDSA", namedCurve: "P-256" },
+        verifyParams: { name: "ECDSA", hash: "SHA-256" },
+    },
+    ES384: {
+        kty: "EC",
+        expectedCrv: "P-384",
+        importParams: { name: "ECDSA", namedCurve: "P-384" },
+        verifyParams: { name: "ECDSA", hash: "SHA-384" },
+    },
+    RS256: {
+        kty: "RSA",
+        importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+        verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+    },
+    PS256: {
+        kty: "RSA",
+        importParams: { name: "RSA-PSS", hash: "SHA-256" },
+        verifyParams: { name: "RSA-PSS", saltLength: 32 },
+    },
+};
+/**
+ * Minimum accepted RSA modulus size in bits. Keys below this are rejected
+ * regardless of a valid signature: an attacker who controls an undersized
+ * key's private half could otherwise mint accepted proofs.
+ */
+const MIN_RSA_KEY_BITS = 2048;
+/** RSA/EC private-key JWK members; their presence means a private key was sent. */
+const PRIVATE_JWK_MEMBERS = ["d", "p", "q", "dp", "dq", "qi"];
+const BASE64URL_SEGMENT = /^[A-Za-z0-9_-]+$/;
+function fail(reason) {
+    return { valid: false, reason };
+}
+function base64urlToBytes(segment) {
+    const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = b64.length % 4 === 0 ? b64 : b64 + "=".repeat(4 - (b64.length % 4));
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function bytesToBase64url(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function decodeJsonSegment(segment) {
+    const text = new TextDecoder().decode(base64urlToBytes(segment));
+    return JSON.parse(text);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Bit length of an RSA modulus encoded as a base64url big-endian integer
+ * (the JWK `n` member). Leading zero bytes are ignored. Returns 0 if `n`
+ * cannot be decoded or is empty.
+ */
+function rsaModulusBits(n) {
+    let bytes;
+    try {
+        bytes = base64urlToBytes(n);
+    }
+    catch {
+        return 0;
+    }
+    let i = 0;
+    while (i < bytes.length && bytes[i] === 0)
+        i++;
+    if (i >= bytes.length)
+        return 0;
+    let bits = (bytes.length - i - 1) * 8;
+    for (let v = bytes[i]; v > 0; v >>= 1)
+        bits++;
+    return bits;
+}
+/**
+ * Normalize an HTTP URI for `htu` comparison: lowercase the scheme and host
+ * (the URL parser does this), drop default ports, and strip query and fragment.
+ * Returns `null` when the URI cannot be parsed.
+ */
+function normalizeHtu(uri) {
+    try {
+        const url = new URL(uri);
+        return `${url.protocol}//${url.host}${url.pathname}`;
+    }
+    catch {
+        return null;
+    }
+}
+async function sha256Base64url(input) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+    return bytesToBase64url(new Uint8Array(digest));
+}
+/**
+ * Compute the RFC 7638 JWK thumbprint (base64url SHA-256 over the canonical,
+ * lexicographically-ordered required members). Returns `null` if the required
+ * members for the key type are missing.
+ */
+async function jwkThumbprint(jwk) {
+    let canonical;
+    if (jwk.kty === "EC") {
+        const { crv, x, y } = jwk;
+        if (typeof crv !== "string" ||
+            typeof x !== "string" ||
+            typeof y !== "string") {
+            return null;
+        }
+        canonical = JSON.stringify({ crv, kty: "EC", x, y });
+    }
+    else if (jwk.kty === "RSA") {
+        const { e, n } = jwk;
+        if (typeof e !== "string" || typeof n !== "string") {
+            return null;
+        }
+        canonical = JSON.stringify({ e, kty: "RSA", n });
+    }
+    else {
+        return null;
+    }
+    return sha256Base64url(canonical);
+}
+/** Build a clean public-only JWK for `importKey`, dropping `alg`/`use`/`key_ops`. */
+function publicJwk(jwk, kty) {
+    if (kty === "EC") {
+        const { crv, x, y } = jwk;
+        if (typeof crv !== "string" ||
+            typeof x !== "string" ||
+            typeof y !== "string") {
+            return null;
+        }
+        return { kty: "EC", crv, x, y };
+    }
+    const { n, e } = jwk;
+    if (typeof n !== "string" || typeof e !== "string") {
+        return null;
+    }
+    return { kty: "RSA", n, e };
+}
+/**
+ * Verify a DPoP proof JWT and, optionally, its binding to an access token.
+ *
+ * Pure async function; performs no I/O beyond Web Crypto. Never throws — every
+ * failure is returned as `{ valid: false, reason }` with a stable
+ * {@link DpopFailureReason} code.
+ *
+ * @param input - Request facts, the proof, and any expected token binding.
+ * @returns On success `{ valid: true, jti, jkt }`; otherwise `{ valid: false, reason }`.
+ */
+export async function verifyDpopProof(input) {
+    const { proof, htm, htu } = input;
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const maxAgeSeconds = input.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+    // 1. Parse the compact JWS: exactly three non-empty base64url segments.
+    if (typeof proof !== "string") {
+        return fail("proof_malformed");
+    }
+    const segments = proof.split(".");
+    if (segments.length !== 3) {
+        return fail("proof_malformed");
+    }
+    const [headerSeg, payloadSeg, signatureSeg] = segments;
+    if (!BASE64URL_SEGMENT.test(headerSeg) ||
+        !BASE64URL_SEGMENT.test(payloadSeg) ||
+        !BASE64URL_SEGMENT.test(signatureSeg)) {
+        return fail("proof_malformed");
+    }
+    let header;
+    try {
+        header = decodeJsonSegment(headerSeg);
+    }
+    catch {
+        return fail("header_invalid");
+    }
+    if (!isObject(header)) {
+        return fail("header_invalid");
+    }
+    // 2. Header checks: typ, crit, alg allow-list, public-only jwk.
+    if (header.typ !== "dpop+jwt") {
+        return fail("typ_invalid");
+    }
+    // RFC 7515 §4.1.11: reject any JWS carrying critical header parameters this
+    // library does not understand. It understands no extensions, so any `crit`.
+    if ("crit" in header) {
+        return fail("crit_unsupported");
+    }
+    const alg = header.alg;
+    const algSpec = typeof alg === "string" ? ALGS[alg] : undefined;
+    if (!algSpec) {
+        return fail("alg_unsupported");
+    }
+    const jwk = header.jwk;
+    if (!isObject(jwk)) {
+        return fail("jwk_missing");
+    }
+    if (PRIVATE_JWK_MEMBERS.some((member) => member in jwk)) {
+        return fail("jwk_private");
+    }
+    if (jwk.kty !== algSpec.kty) {
+        return fail("jwk_invalid");
+    }
+    // EC: the curve must be the one the alg implies (ES256⇒P-256, …). WebCrypto
+    // would also reject a mismatch on import, but check it explicitly up front.
+    // A missing/non-string `crv` is malformed, not a mismatch — let it fall
+    // through to `publicJwk` below, which rejects it as `jwk_invalid`.
+    if (algSpec.kty === "EC" &&
+        typeof jwk.crv === "string" &&
+        jwk.crv !== algSpec.expectedCrv) {
+        return fail("crv_mismatch");
+    }
+    // RSA: reject undersized moduli whose private half an attacker could control.
+    // A missing/non-string `n` is malformed, not undersized — let it fall through
+    // to `publicJwk` below, which rejects it as `jwk_invalid`.
+    if (algSpec.kty === "RSA") {
+        const n = jwk.n;
+        if (typeof n === "string" && rsaModulusBits(n) < MIN_RSA_KEY_BITS) {
+            return fail("rsa_key_too_small");
+        }
+    }
+    const importable = publicJwk(jwk, algSpec.kty);
+    if (importable === null) {
+        return fail("jwk_invalid");
+    }
+    // 3. Verify the signature over `header.payload` using the embedded jwk.
+    let signatureValid;
+    try {
+        const key = await crypto.subtle.importKey("jwk", importable, algSpec.importParams, false, ["verify"]);
+        signatureValid = await crypto.subtle.verify(algSpec.verifyParams, key, base64urlToBytes(signatureSeg), new TextEncoder().encode(`${headerSeg}.${payloadSeg}`));
+    }
+    catch {
+        return fail("jwk_invalid");
+    }
+    if (!signatureValid) {
+        return fail("signature_invalid");
+    }
+    let payload;
+    try {
+        payload = decodeJsonSegment(payloadSeg);
+    }
+    catch {
+        return fail("payload_invalid");
+    }
+    if (!isObject(payload)) {
+        return fail("payload_invalid");
+    }
+    // 4. Claim checks: htm, htu, iat window, jti.
+    if (typeof payload.htm !== "string" ||
+        payload.htm.toUpperCase() !== htm.toUpperCase()) {
+        return fail("htm_mismatch");
+    }
+    const expectedHtu = normalizeHtu(htu);
+    if (expectedHtu === null) {
+        return fail("htu_invalid");
+    }
+    const proofHtu = typeof payload.htu === "string" ? normalizeHtu(payload.htu) : null;
+    if (proofHtu === null || proofHtu !== expectedHtu) {
+        return fail("htu_mismatch");
+    }
+    const iat = payload.iat;
+    if (typeof iat !== "number" || !Number.isFinite(iat)) {
+        return fail("iat_invalid");
+    }
+    if (iat < now - maxAgeSeconds) {
+        return fail("proof_expired");
+    }
+    if (iat > now + maxAgeSeconds) {
+        return fail("proof_future");
+    }
+    if (typeof payload.jti !== "string" || payload.jti.length === 0) {
+        return fail("jti_missing");
+    }
+    const jti = payload.jti;
+    // Server-provided nonce (RFC 9449 §4.3 step 10): when the caller issued a
+    // nonce, the proof's `nonce` claim MUST equal it. Surface the proof's nonce
+    // either way so the caller can answer a mismatch with `use_dpop_nonce`.
+    const nonce = typeof payload.nonce === "string" ? payload.nonce : undefined;
+    if (input.expectedNonce !== undefined && nonce !== input.expectedNonce) {
+        return { valid: false, reason: "nonce_mismatch", nonce };
+    }
+    // Compute the thumbprint once, for both the cnf.jkt check and the result.
+    const jkt = await jwkThumbprint(jwk);
+    if (jkt === null) {
+        return fail("jwk_invalid");
+    }
+    // 5. Resource Server: access-token hash binding. Enforcing `ath` without the
+    //    `cnf.jkt` binding would let a proof made for the token but signed by any
+    //    key validate, defeating proof-of-possession (RFC 9449 §7.1), so an
+    //    access token requires the expected thumbprint too.
+    if (input.accessToken !== undefined) {
+        if (input.expectedJkt === undefined) {
+            return fail("jkt_required");
+        }
+        const expectedAth = await sha256Base64url(input.accessToken);
+        if (typeof payload.ath !== "string" || payload.ath !== expectedAth) {
+            return fail("ath_mismatch");
+        }
+    }
+    // 6. Resource Server: token confirmation thumbprint binding.
+    if (input.expectedJkt !== undefined && input.expectedJkt !== jkt) {
+        return fail("jkt_mismatch");
+    }
+    // 7. Success.
+    return { valid: true, jti, jkt, nonce };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dwk/dpop",
+  "version": "0.1.0-beta.0",
+  "description": "DPoP (RFC 9449) proof verification. Cross-standard reusable; no Workers runtime dependency.",
+  "keywords": [
+    "dpop",
+    "rfc9449",
+    "oauth2",
+    "proof-of-possession",
+    "access-token",
+    "web-crypto"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/dpop#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/dpop"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,507 @@
+/**
+ * `@dwk/dpop` — DPoP (RFC 9449) proof verification.
+ *
+ * A pure, runtime-agnostic library: HTTP request facts and token claims go in,
+ * a verification result comes out. It performs no I/O beyond Web Crypto, holds
+ * no state, and needs no Cloudflare bindings, so it unit-tests without a
+ * Workers runtime.
+ *
+ * The library stays protocol-agnostic — it knows nothing about IndieAuth or
+ * Solid. The caller supplies the request facts and any access-token binding it
+ * expects, and owns replay detection via the returned `jti`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9449
+ * @see spec/packages/dpop.md
+ * @packageDocumentation
+ */
+
+/** Default clock-skew window (seconds) applied to `iat` when none is given. */
+export const DEFAULT_MAX_AGE_SECONDS = 300;
+
+/**
+ * Asymmetric signature algorithms accepted in the DPoP proof JOSE header.
+ *
+ * Symmetric (`HS*`) and `none` are deliberately excluded: a DPoP proof must be
+ * signed by the client-held private key whose public half is embedded as `jwk`.
+ */
+export type DpopAlgorithm = "ES256" | "ES384" | "RS256" | "PS256";
+
+/** Stable, locale-independent failure codes returned in {@link DpopVerifyResult.reason}. */
+export type DpopFailureReason =
+  | "proof_malformed"
+  | "header_invalid"
+  | "payload_invalid"
+  | "typ_invalid"
+  | "crit_unsupported"
+  | "alg_unsupported"
+  | "jwk_missing"
+  | "jwk_private"
+  | "jwk_invalid"
+  | "crv_mismatch"
+  | "rsa_key_too_small"
+  | "signature_invalid"
+  | "htm_mismatch"
+  | "htu_invalid"
+  | "htu_mismatch"
+  | "iat_invalid"
+  | "proof_expired"
+  | "proof_future"
+  | "jti_missing"
+  | "nonce_mismatch"
+  | "ath_mismatch"
+  | "jkt_required"
+  | "jkt_mismatch";
+
+/** Plain-data inputs required to verify a DPoP proof. */
+export interface DpopVerifyInput {
+  /** The DPoP proof JWT (compact JWS) from the `DPoP` header. */
+  proof: string;
+  /** HTTP method of the request the proof is bound to, e.g. `"POST"`. */
+  htm: string;
+  /** HTTP target URI of the request (query/fragment are ignored per §4.3). */
+  htu: string;
+  /**
+   * Expected access-token hash binding (Resource Server case). When provided,
+   * the proof MUST carry an `ath` claim equal to `base64url(SHA-256(accessToken))`.
+   *
+   * A Resource Server enforcing `ath` MUST also supply {@link expectedJkt}: the
+   * `ath` proves the proof was made for this token, but only the `cnf.jkt`
+   * binding proves the proof key is the one the token was issued to. Passing
+   * `accessToken` without `expectedJkt` defeats proof-of-possession
+   * (RFC 9449 §7.1) and is rejected with `jkt_required` rather than validating.
+   */
+  accessToken?: string;
+  /**
+   * Token confirmation thumbprint (`cnf.jkt`) to match against the proof key.
+   * Required whenever {@link accessToken} is supplied (see its note).
+   */
+  expectedJkt?: string;
+  /**
+   * Server-provided DPoP nonce the proof must carry (RFC 9449 §8/§9). When set,
+   * the proof MUST carry a `nonce` claim equal to this value, else it is
+   * rejected with `nonce_mismatch`. An AS/RS uses this to bound proof lifetime
+   * and force fresh proofs as a replay defense: on a mismatch (or when no nonce
+   * was sent yet) the caller answers with a `use_dpop_nonce` error carrying a
+   * fresh `DPoP-Nonce`. Issuing and rotating the nonce is the caller's job; this
+   * library only checks equality and surfaces the proof's {@link DpopVerifyResult.nonce}.
+   */
+  expectedNonce?: string;
+  /** Current time in seconds since the epoch. Defaults to `Date.now()`. */
+  now?: number;
+  /** Allowed clock skew in seconds for the `iat` window. Defaults to {@link DEFAULT_MAX_AGE_SECONDS}. */
+  maxAgeSeconds?: number;
+}
+
+/** Result of verifying a DPoP proof. */
+export interface DpopVerifyResult {
+  /** Whether the proof is valid. */
+  valid: boolean;
+  /** The verified JWT ID (`jti`) for replay detection by the caller. */
+  jti?: string;
+  /** The RFC 7638 thumbprint of the proof key (`jkt`). */
+  jkt?: string;
+  /**
+   * The proof's `nonce` claim, when it carried one (string only). Surfaced on
+   * both success and a `nonce_mismatch` so a caller enforcing the
+   * `DPoP-Nonce` mechanism (RFC 9449 §8/§9) can decide whether to answer with a
+   * `use_dpop_nonce` error and a fresh nonce.
+   */
+  nonce?: string;
+  /** Stable failure code (see {@link DpopFailureReason}) when `valid` is false. */
+  reason?: DpopFailureReason;
+}
+
+// Structural shapes for the Web Crypto algorithm parameters. We avoid the
+// standard DOM lib names (EcKeyImportParams, EcdsaParams, …) because
+// @cloudflare/workers-types does not declare them; these objects are accepted
+// structurally by crypto.subtle.importKey / verify.
+interface ImportAlg {
+  name: string;
+  namedCurve?: string;
+  hash?: string;
+}
+interface VerifyAlg {
+  name: string;
+  hash?: string;
+  saltLength?: number;
+}
+
+interface AlgSpec {
+  kty: "EC" | "RSA";
+  /** For EC algorithms, the curve the `alg` implies (`jwk.crv` must match it). */
+  expectedCrv?: string;
+  importParams: ImportAlg;
+  verifyParams: VerifyAlg;
+}
+
+const ALGS: Record<DpopAlgorithm, AlgSpec> = {
+  ES256: {
+    kty: "EC",
+    expectedCrv: "P-256",
+    importParams: { name: "ECDSA", namedCurve: "P-256" },
+    verifyParams: { name: "ECDSA", hash: "SHA-256" },
+  },
+  ES384: {
+    kty: "EC",
+    expectedCrv: "P-384",
+    importParams: { name: "ECDSA", namedCurve: "P-384" },
+    verifyParams: { name: "ECDSA", hash: "SHA-384" },
+  },
+  RS256: {
+    kty: "RSA",
+    importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+  },
+  PS256: {
+    kty: "RSA",
+    importParams: { name: "RSA-PSS", hash: "SHA-256" },
+    verifyParams: { name: "RSA-PSS", saltLength: 32 },
+  },
+};
+
+/**
+ * Minimum accepted RSA modulus size in bits. Keys below this are rejected
+ * regardless of a valid signature: an attacker who controls an undersized
+ * key's private half could otherwise mint accepted proofs.
+ */
+const MIN_RSA_KEY_BITS = 2048;
+
+/** RSA/EC private-key JWK members; their presence means a private key was sent. */
+const PRIVATE_JWK_MEMBERS = ["d", "p", "q", "dp", "dq", "qi"] as const;
+
+const BASE64URL_SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+function fail(reason: DpopFailureReason): DpopVerifyResult {
+  return { valid: false, reason };
+}
+
+function base64urlToBytes(segment: string): Uint8Array {
+  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded =
+    b64.length % 4 === 0 ? b64 : b64 + "=".repeat(4 - (b64.length % 4));
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+function bytesToBase64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function decodeJsonSegment(segment: string): unknown {
+  const text = new TextDecoder().decode(base64urlToBytes(segment));
+  return JSON.parse(text) as unknown;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Bit length of an RSA modulus encoded as a base64url big-endian integer
+ * (the JWK `n` member). Leading zero bytes are ignored. Returns 0 if `n`
+ * cannot be decoded or is empty.
+ */
+function rsaModulusBits(n: string): number {
+  let bytes: Uint8Array;
+  try {
+    bytes = base64urlToBytes(n);
+  } catch {
+    return 0;
+  }
+  let i = 0;
+  while (i < bytes.length && bytes[i] === 0) i++;
+  if (i >= bytes.length) return 0;
+  let bits = (bytes.length - i - 1) * 8;
+  for (let v = bytes[i]!; v > 0; v >>= 1) bits++;
+  return bits;
+}
+
+/**
+ * Normalize an HTTP URI for `htu` comparison: lowercase the scheme and host
+ * (the URL parser does this), drop default ports, and strip query and fragment.
+ * Returns `null` when the URI cannot be parsed.
+ */
+function normalizeHtu(uri: string): string | null {
+  try {
+    const url = new URL(uri);
+    return `${url.protocol}//${url.host}${url.pathname}`;
+  } catch {
+    return null;
+  }
+}
+
+async function sha256Base64url(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(input),
+  );
+  return bytesToBase64url(new Uint8Array(digest));
+}
+
+/**
+ * Compute the RFC 7638 JWK thumbprint (base64url SHA-256 over the canonical,
+ * lexicographically-ordered required members). Returns `null` if the required
+ * members for the key type are missing.
+ */
+async function jwkThumbprint(
+  jwk: Record<string, unknown>,
+): Promise<string | null> {
+  let canonical: string;
+  if (jwk.kty === "EC") {
+    const { crv, x, y } = jwk;
+    if (
+      typeof crv !== "string" ||
+      typeof x !== "string" ||
+      typeof y !== "string"
+    ) {
+      return null;
+    }
+    canonical = JSON.stringify({ crv, kty: "EC", x, y });
+  } else if (jwk.kty === "RSA") {
+    const { e, n } = jwk;
+    if (typeof e !== "string" || typeof n !== "string") {
+      return null;
+    }
+    canonical = JSON.stringify({ e, kty: "RSA", n });
+  } else {
+    return null;
+  }
+  return sha256Base64url(canonical);
+}
+
+/** Build a clean public-only JWK for `importKey`, dropping `alg`/`use`/`key_ops`. */
+function publicJwk(
+  jwk: Record<string, unknown>,
+  kty: "EC" | "RSA",
+): JsonWebKey | null {
+  if (kty === "EC") {
+    const { crv, x, y } = jwk;
+    if (
+      typeof crv !== "string" ||
+      typeof x !== "string" ||
+      typeof y !== "string"
+    ) {
+      return null;
+    }
+    return { kty: "EC", crv, x, y };
+  }
+  const { n, e } = jwk;
+  if (typeof n !== "string" || typeof e !== "string") {
+    return null;
+  }
+  return { kty: "RSA", n, e };
+}
+
+/**
+ * Verify a DPoP proof JWT and, optionally, its binding to an access token.
+ *
+ * Pure async function; performs no I/O beyond Web Crypto. Never throws — every
+ * failure is returned as `{ valid: false, reason }` with a stable
+ * {@link DpopFailureReason} code.
+ *
+ * @param input - Request facts, the proof, and any expected token binding.
+ * @returns On success `{ valid: true, jti, jkt }`; otherwise `{ valid: false, reason }`.
+ */
+export async function verifyDpopProof(
+  input: DpopVerifyInput,
+): Promise<DpopVerifyResult> {
+  const { proof, htm, htu } = input;
+  const now = input.now ?? Math.floor(Date.now() / 1000);
+  const maxAgeSeconds = input.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+
+  // 1. Parse the compact JWS: exactly three non-empty base64url segments.
+  if (typeof proof !== "string") {
+    return fail("proof_malformed");
+  }
+  const segments = proof.split(".");
+  if (segments.length !== 3) {
+    return fail("proof_malformed");
+  }
+  const [headerSeg, payloadSeg, signatureSeg] = segments as [
+    string,
+    string,
+    string,
+  ];
+  if (
+    !BASE64URL_SEGMENT.test(headerSeg) ||
+    !BASE64URL_SEGMENT.test(payloadSeg) ||
+    !BASE64URL_SEGMENT.test(signatureSeg)
+  ) {
+    return fail("proof_malformed");
+  }
+
+  let header: unknown;
+  try {
+    header = decodeJsonSegment(headerSeg);
+  } catch {
+    return fail("header_invalid");
+  }
+  if (!isObject(header)) {
+    return fail("header_invalid");
+  }
+
+  // 2. Header checks: typ, crit, alg allow-list, public-only jwk.
+  if (header.typ !== "dpop+jwt") {
+    return fail("typ_invalid");
+  }
+  // RFC 7515 §4.1.11: reject any JWS carrying critical header parameters this
+  // library does not understand. It understands no extensions, so any `crit`.
+  if ("crit" in header) {
+    return fail("crit_unsupported");
+  }
+  const alg = header.alg;
+  const algSpec =
+    typeof alg === "string" ? ALGS[alg as DpopAlgorithm] : undefined;
+  if (!algSpec) {
+    return fail("alg_unsupported");
+  }
+
+  const jwk = header.jwk;
+  if (!isObject(jwk)) {
+    return fail("jwk_missing");
+  }
+  if (PRIVATE_JWK_MEMBERS.some((member) => member in jwk)) {
+    return fail("jwk_private");
+  }
+  if (jwk.kty !== algSpec.kty) {
+    return fail("jwk_invalid");
+  }
+  // EC: the curve must be the one the alg implies (ES256⇒P-256, …). WebCrypto
+  // would also reject a mismatch on import, but check it explicitly up front.
+  // A missing/non-string `crv` is malformed, not a mismatch — let it fall
+  // through to `publicJwk` below, which rejects it as `jwk_invalid`.
+  if (
+    algSpec.kty === "EC" &&
+    typeof jwk.crv === "string" &&
+    jwk.crv !== algSpec.expectedCrv
+  ) {
+    return fail("crv_mismatch");
+  }
+  // RSA: reject undersized moduli whose private half an attacker could control.
+  // A missing/non-string `n` is malformed, not undersized — let it fall through
+  // to `publicJwk` below, which rejects it as `jwk_invalid`.
+  if (algSpec.kty === "RSA") {
+    const n = jwk.n;
+    if (typeof n === "string" && rsaModulusBits(n) < MIN_RSA_KEY_BITS) {
+      return fail("rsa_key_too_small");
+    }
+  }
+  const importable = publicJwk(jwk, algSpec.kty);
+  if (importable === null) {
+    return fail("jwk_invalid");
+  }
+
+  // 3. Verify the signature over `header.payload` using the embedded jwk.
+  let signatureValid: boolean;
+  try {
+    const key = await crypto.subtle.importKey(
+      "jwk",
+      importable,
+      algSpec.importParams,
+      false,
+      ["verify"],
+    );
+    signatureValid = await crypto.subtle.verify(
+      algSpec.verifyParams,
+      key,
+      base64urlToBytes(signatureSeg),
+      new TextEncoder().encode(`${headerSeg}.${payloadSeg}`),
+    );
+  } catch {
+    return fail("jwk_invalid");
+  }
+  if (!signatureValid) {
+    return fail("signature_invalid");
+  }
+
+  let payload: unknown;
+  try {
+    payload = decodeJsonSegment(payloadSeg);
+  } catch {
+    return fail("payload_invalid");
+  }
+  if (!isObject(payload)) {
+    return fail("payload_invalid");
+  }
+
+  // 4. Claim checks: htm, htu, iat window, jti.
+  if (
+    typeof payload.htm !== "string" ||
+    payload.htm.toUpperCase() !== htm.toUpperCase()
+  ) {
+    return fail("htm_mismatch");
+  }
+
+  const expectedHtu = normalizeHtu(htu);
+  if (expectedHtu === null) {
+    return fail("htu_invalid");
+  }
+  const proofHtu =
+    typeof payload.htu === "string" ? normalizeHtu(payload.htu) : null;
+  if (proofHtu === null || proofHtu !== expectedHtu) {
+    return fail("htu_mismatch");
+  }
+
+  const iat = payload.iat;
+  if (typeof iat !== "number" || !Number.isFinite(iat)) {
+    return fail("iat_invalid");
+  }
+  if (iat < now - maxAgeSeconds) {
+    return fail("proof_expired");
+  }
+  if (iat > now + maxAgeSeconds) {
+    return fail("proof_future");
+  }
+
+  if (typeof payload.jti !== "string" || payload.jti.length === 0) {
+    return fail("jti_missing");
+  }
+  const jti = payload.jti;
+
+  // Server-provided nonce (RFC 9449 §4.3 step 10): when the caller issued a
+  // nonce, the proof's `nonce` claim MUST equal it. Surface the proof's nonce
+  // either way so the caller can answer a mismatch with `use_dpop_nonce`.
+  const nonce = typeof payload.nonce === "string" ? payload.nonce : undefined;
+  if (input.expectedNonce !== undefined && nonce !== input.expectedNonce) {
+    return { valid: false, reason: "nonce_mismatch", nonce };
+  }
+
+  // Compute the thumbprint once, for both the cnf.jkt check and the result.
+  const jkt = await jwkThumbprint(jwk);
+  if (jkt === null) {
+    return fail("jwk_invalid");
+  }
+
+  // 5. Resource Server: access-token hash binding. Enforcing `ath` without the
+  //    `cnf.jkt` binding would let a proof made for the token but signed by any
+  //    key validate, defeating proof-of-possession (RFC 9449 §7.1), so an
+  //    access token requires the expected thumbprint too.
+  if (input.accessToken !== undefined) {
+    if (input.expectedJkt === undefined) {
+      return fail("jkt_required");
+    }
+    const expectedAth = await sha256Base64url(input.accessToken);
+    if (typeof payload.ath !== "string" || payload.ath !== expectedAth) {
+      return fail("ath_mismatch");
+    }
+  }
+
+  // 6. Resource Server: token confirmation thumbprint binding.
+  if (input.expectedJkt !== undefined && input.expectedJkt !== jkt) {
+    return fail("jkt_mismatch");
+  }
+
+  // 7. Success.
+  return { valid: true, jti, jkt, nonce };
+}