first commit

docs/security-stack/crypto/crypto-rsa/src/jwk/thumbprint-uri.md

@@ -0,0 +1,59 @@
+# jwk/thumbprint-uri
+
+## Purpose
+
+Compute the JWK Thumbprint URI per RFC 9278 §3 — the canonical
+`urn:ietf:params:oauth:jwk-thumbprint:<hash-alg>:<base64url(thumbprint)>`
+form used by OAuth 2.0 Demonstrating Proof-of-Possession (DPoP),
+draft-ietf-oauth-dpop, and other OAuth/OIDC binding protocols. Wraps
+`jwkThumbprint` with the hash-algorithm label and URN prefix.
+
+## Features
+
+- RFC 9278 §3 conformant URN format
+- Default SHA-256 hash; SHA-1 / SHA-384 / SHA-512 supported
+- Hash labels match RFC 9278 §3.1 registry: `sha-1`, `sha-256`, `sha-384`,
+  `sha-512`
+- Returns a deterministic `string` ready to embed in OAuth tokens, DPoP
+  proofs, or `iss`/`sub` claims
+
+## Usage: Basic Example
+
+```ts
+import { jwkThumbprintUri } from "@suaveplan/crypto-rsa/jwk";
+
+const uri = jwkThumbprintUri(publicKey);
+// "urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8u..."
+```
+
+## Usage: Advanced Example
+
+For protocols that pin a non-default hash (e.g. SHA-512 for
+high-assurance bindings), pass the `hash` option:
+
+```ts
+import { jwkThumbprintUri } from "@suaveplan/crypto-rsa/jwk";
+
+const sha512Uri = jwkThumbprintUri(publicKey, { hash: "SHA-512" });
+// "urn:ietf:params:oauth:jwk-thumbprint:sha-512:..."
+```
+
+## API Reference
+
+### `jwkThumbprintUri(key, options?)`
+
+- `key: RsaPublicKey | RsaJwk` — public key or JWK
+- `options.hash?: RsaHashAlgorithm` — defaults to `"SHA-256"`
+- **returns** `string` — full URN
+- **throws** `CryptoRsaError(CRYPTO_RSA.UNSUPPORTED_HASH)` /
+  `CRYPTO_RSA.INVALID_KEY` (propagated from `jwkThumbprint`)
+
+## Implementation Notes
+
+- The hash-label mapping is a frozen lookup table mirroring the
+  IANA-registered names in RFC 9278 §3.1. Adding new RSA hash
+  algorithms (e.g. SHA-3) requires updating both this table and the
+  `RsaHashAlgorithm` union in `keys.types.ts`.
+- This helper is a thin wrapper over `jwkThumbprint` + `toBase64Url`;
+  it adds no cryptographic complexity, only the URN framing. Tests
+  cover the framing for every supported hash.