wb-auth 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,90 +1,130 @@
-import { Signer } from 'http-message-sig';
 import { Page } from 'playwright';
 
+interface SignScopeOptions {
+    /** Only sign requests to these hosts (`example.com`, `*.example.com`). */
+    hosts?: readonly string[];
+    /** Custom predicate; takes precedence over `hosts`. */
+    shouldSign?: (url: URL) => boolean;
+    /** Also sign plain `http://` requests (off by default: replayable in clear text). */
+    allowInsecure?: boolean;
+}
+
 /**
  * Identity, KeyPair, and key-file helpers for the wbauth TypeScript SDK.
  *
- * Mirrors python/src/wbauth/identity.py — same on-disk format (PKCS8
- * NoEncryption PEM at 0o600), same kid (RFC 7638 JWK thumbprint), same
- * multi-key rotation semantics (active + retiring), same REDACTED repr
- * (IDENT-08).
- *
- * Cross-language guarantee (D-60): the PEM file Python writes via
- * `Ed25519PrivateKey.private_bytes(PEM, PKCS8, NoEncryption)` is byte-equal
- * to what Node's `crypto.generateKeyPairSync('ed25519').privateKey.export({
- * format: 'pem', type: 'pkcs8' })` writes. Both runtimes can load each
- * other's keyfile and produce the same kid + signatures.
+ * Mirrors python/src/wbauth/identity.py — same on-disk format (PKCS8 PEM at
+ * 0o600, optionally passphrase-encrypted), same kid (RFC 7638 JWK
+ * thumbprint), same multi-key rotation semantics (active + retiring, in
+ * memory via `rotate()` or persisted via `rotateKeyring()`), same REDACTED
+ * repr (IDENT-08).
  *
- * Key implementation choice (Pitfall 1): PEM→JWK is done via Node 20+
- * stdlib `node:crypto.createPrivateKey(pem).export({format:'jwk'})`. We do
- * NOT use `jose` or any third-party JOSE library — the stdlib output is
- * verified byte-identical to what Python's cryptography library produces
- * for the same PKCS8 PEM (RESEARCH §2.2 live verification 2026-05-10).
+ * Key material is held in ECMAScript `#private` fields and only as a
+ * non-extractable `KeyObject`/`Signer`, so `JSON.stringify(identity)`,
+ * `structuredClone`, spreading or `Object.entries` never expose `d`.
  */
-
 /** Default path for the active signing key. Matches Python DEFAULT_KEY_PATH. */
 declare const DEFAULT_KEY_PATH: string;
+/** Environment variable holding the passphrase for encrypted PEM key files. */
+declare const KEY_PASSWORD_ENV = "WBAUTH_KEY_PASSWORD";
 interface IdentityOptions {
     /** Stable HTTPS URL where this agent's JWKS is published. Must start with `https://`. */
     signatureAgentUrl: string;
     /** Optional User-Agent string adapters inject when caller did not supply one. */
     userAgent?: string;
 }
+interface KeyOptions {
+    /** Passphrase for an encrypted PEM. Defaults to `$WBAUTH_KEY_PASSWORD`. */
+    password?: string;
+}
+/** Public JWK of one key ({kty, crv, x, kid}). */
+type PublicJwk = JsonWebKey & {
+    kid: string;
+};
+/**
+ * Pluggable Ed25519 signing backend (local key, KMS, HSM, keychain).
+ * `sign` receives the RFC 9421 signature base as UTF-8 bytes and must return
+ * the raw 64-byte Ed25519 signature.
+ */
+interface Ed25519SignerBackend {
+    /** Public key as a JWK ({kty:"OKP", crv:"Ed25519", x}). */
+    publicJwk: JsonWebKey;
+    sign(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+}
+/** Signer handed to `sign()` (structurally compatible with web-bot-auth's). */
+interface Signer {
+    alg: "ed25519";
+    keyid: string;
+    sign(data: string): Promise<Uint8Array>;
+}
+/** Public view of a key pair. Private material is never exposed. */
 interface KeyPair {
-    /** Private JWK (includes "d") — used to mint the signer. Never logged. */
-    privateJwk: JsonWebKey;
-    /** Public JWK ({kty, crv, x, kid}) — what exportJwks returns per key. */
-    publicJwk: JsonWebKey & {
-        kid: string;
-    };
-    /** RFC 7638 base64url-no-pad thumbprint of the public key. */
+    publicJwk: PublicJwk;
     kid: string;
-    /** Pre-resolved web-bot-auth Signer (caches the imported CryptoKey). */
     signer: Signer;
 }
+/**
+ * Validate a Signature-Agent URL: absolute https:// with a host, printable
+ * ASCII only, no spaces/quotes/backslashes (it is emitted as an RFC 8941
+ * sf-string and must not break the header or the signature base).
+ */
+declare function validateSignatureAgentUrl(url: string): string;
 declare class Identity {
-    private _active;
-    private _retiring;
-    readonly signatureAgentUrl: string;
-    readonly userAgent: string | undefined;
+    #private;
     private constructor();
+    get signatureAgentUrl(): string;
+    get userAgent(): string | undefined;
     /** The active key's kid (used as `keyid=` param in Signature-Input). */
     get kid(): string;
-    /** Module-internal: returns the resolved Signer for sign() to use. */
+    /** The active key's public JWK (copy; never contains private material). */
+    get publicJwk(): PublicJwk;
+    /** Module-internal: returns the active Signer for sign() to use. */
     _signer(): Signer;
-    /**
-     * Export the public JWKS document.
-     *
-     * Returns `{keys: [active_jwk]}` if no retiring key is held, or
-     * `{keys: [active_jwk, retiring_jwk]}` after a rotation. Active is always
-     * first. Verifiers select by `kid`. Mirror of Python `export_jwks`.
-     */
+    /** Public JWKS: active first, then the retiring key (if any). */
     exportJwks(): {
-        keys: Array<JsonWebKey & {
-            kid: string;
-        }>;
+        keys: PublicJwk[];
     };
     /**
      * IDENT-07: generate a new active key, demote current to retiring.
-     *
-     * Returns a NEW Identity (immutable update — the old Identity is unchanged).
-     * Any previously-retiring key is dropped (only one overlap window).
+     * In-memory only — use `rotateKeyring()` to persist. The default path is
+     * a fresh timestamped file next to DEFAULT_KEY_PATH (never collides).
      */
-    rotate(newPath?: string): Promise<Identity>;
+    rotate(newPath?: string, keyOpts?: KeyOptions): Promise<Identity>;
     /**
-     * Primary entry point. Loads `path` if it exists, generates a fresh key
-     * there otherwise. The on-disk file is PKCS8 NoEncryption PEM at 0o600,
-     * byte-equal to what Python's `Identity.load_or_generate` writes (D-60).
+     * Persisted rotation: `<dir>/active.pem` → `retiring.pem` (replacing the
+     * previous retiring key), then a fresh `active.pem` is generated.
      */
-    static loadOrGenerate(path: string | undefined, opts: IdentityOptions): Promise<Identity>;
+    rotateKeyring(dir: string, keyOpts?: KeyOptions): Promise<Identity>;
     /**
-     * Construct from the RFC 9421 Appendix B.1.4 publicly-known test key.
-     * For tests + Cloudflare debug smoke checks. NEVER use in production.
-     * Does NOT write any file to disk.
+     * Loads `path` if it exists, generates a fresh key there otherwise.
+     * Concurrent first starts are safe: the loser of the O_EXCL race loads the
+     * winner's key. `retiringPath` optionally loads the previous key.
      */
+    static loadOrGenerate(path: string | undefined, opts: IdentityOptions & KeyOptions & {
+        retiringPath?: string;
+    }): Promise<Identity>;
+    /** Load an existing key; never creates one. */
+    static load(path: string, opts: IdentityOptions & KeyOptions): Promise<Identity>;
+    /** Generate a new key at `path`; never overwrites. */
+    static generate(path: string, opts: IdentityOptions & KeyOptions): Promise<Identity>;
+    /** `<dir>/active.pem` (+ `retiring.pem`), generating active on first use. */
+    static loadKeyring(dir: string, opts: IdentityOptions & KeyOptions): Promise<Identity>;
+    /** Wrap an external signer (KMS, HSM, keychain). */
+    static fromSigner(backend: Ed25519SignerBackend, opts: IdentityOptions): Promise<Identity>;
+    /** RFC 9421 Appendix B.1.4 test key. NEVER use in production. */
     static fromTestKey(signatureAgentUrl: string, opts?: Omit<IdentityOptions, "signatureAgentUrl">): Promise<Identity>;
     toString(): string;
+    /** JSON.stringify(identity) → public data only. */
+    toJSON(): {
+        kid: string;
+        signatureAgentUrl: string;
+        userAgent?: string;
+        jwks: {
+            keys: PublicJwk[];
+        };
+    };
 }
+/** RFC 7638 thumbprint of an Ed25519 OKP JWK. */
+declare function thumbprint(jwk: JsonWebKey): string;
 
 /**
  * createSignedFetch — drop-in `fetch` wrapper that signs every outgoing request.
@@ -103,11 +143,15 @@ declare class Identity {
  *   redirect target. Method/body rewriting and cross-origin credential
  *   stripping follow the WHATWG fetch spec.
  *
+ * - `hosts` / `shouldSign` restrict which hosts receive your identity
+ *   (redirects to other hosts go out unsigned); plain-http requests are
+ *   unsigned unless `allowInsecure: true`.
+ *
  * v1 limitation: streaming bodies are buffered (`req.clone().arrayBuffer()`)
  * so Content-Digest can be computed.
  */
 
-interface SignedFetchOptions {
+interface SignedFetchOptions extends SignScopeOptions {
     /** Underlying fetch implementation. Defaults to `globalThis.fetch` at call time. */
     fetch?: typeof fetch;
     /** Maximum redirects followed (and re-signed). Default 20, like fetch. */
@@ -130,15 +174,11 @@ declare function createSignedFetch(identity: Identity, options?: SignedFetchOpti
  * Note: Playwright disables the HTTP cache while a route is active.
  */
 
-interface ApplyToOptions {
-    /** Only sign requests to these hosts (`example.com`, `*.example.com`). */
-    hosts?: readonly string[];
-    /** Custom predicate; takes precedence over `hosts`. */
-    shouldSign?: (url: URL) => boolean;
+interface ApplyToOptions extends SignScopeOptions {
     /** Route pattern passed to `page.route`. Default `"**\/*"`. */
     pattern?: string;
 }
-declare function applyTo(page: Page, identity: Identity, options?: ApplyToOptions): Promise<void>;
+declare function applyTo(page: Page, identity: Identity, options?: ApplyToOptions): Promise<() => Promise<void>>;
 
 /**
  * NormalizedRequest — the structural input to wbauth.sign().
@@ -172,25 +212,74 @@ interface SignOptions {
     created?: Date;
     /** Validity window in seconds. Defaults to 60. */
     expiresAfterSeconds?: number;
-    /** Anti-replay nonce. Defaults to web-bot-auth's `generateNonce()` (64-byte b64). */
+    /** Anti-replay nonce. Defaults to 64 random bytes, base64. */
     nonce?: string;
     /** Signature label (the `sig1=` prefix). Defaults to "sig1". */
     label?: string;
 }
+/** RFC 9421 §2.2.3 `@authority`: lower-case host, no userinfo, no default port. */
+declare function normalizeAuthority(url: string): string;
 /**
  * Sign a NormalizedRequest with the Web Bot Auth profile.
  *
- * Mutates `request.headers` in place: writes Signature-Agent BEFORE building
- * the signing base (Pitfall 6 — without pre-set, web-bot-auth defaults to
- * `["@authority"]` only and silently breaks byte-equality with the Python
- * signer). After signatureHeaders returns, also writes Signature and
- * Signature-Input back into `request.headers`.
- *
- * @returns the same three values as a typed dataclass for callers that prefer
- * a return value over header inspection.
+ * Mutates `request.headers` in place (Signature-Agent, Signature-Input,
+ * Signature) and returns the same three values.
  */
 declare function sign(request: NormalizedRequest, identity: Identity, opts?: SignOptions): Promise<SignatureHeaders>;
 
+declare class VerificationError extends Error {
+    name: string;
+}
+interface VerifiedAgent {
+    kid: string;
+    signatureAgentUrl: string | null;
+    label: string;
+    created: number;
+    expires: number;
+    nonce: string | null;
+    covered: string[];
+    jwk: JsonWebKey;
+}
+type KeyResolver = (kid: string, signatureAgent: string | null) => Promise<JsonWebKey | null | undefined>;
+interface VerifierOptions {
+    keyResolver?: KeyResolver;
+    /** fetch used for directory lookups (default globalThis.fetch). */
+    fetch?: typeof fetch;
+    /** Directory cache TTL in seconds (default 300). */
+    jwksTtlSeconds?: number;
+    /** Clock skew tolerance in seconds (default 5). */
+    maxSkew?: number;
+    requireNonce?: boolean;
+    nonceStore?: NonceStore;
+}
+/** In-memory TTL set of seen nonces. Replace with a shared store in clusters. */
+declare class NonceStore {
+    #private;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    seen(nonce: string, expiresAt: number): boolean;
+}
+declare class Verifier {
+    #private;
+    constructor(opts?: VerifierOptions);
+    /**
+     * Verify a WHATWG Request (body is read from a clone). `authority`
+     * overrides the value derived from the URL (e.g. behind a proxy).
+     */
+    verify(request: Request, opts?: {
+        authority?: string;
+        now?: number;
+    }): Promise<VerifiedAgent>;
+}
+/**
+ * Fetch-style middleware helper (Hono, itty-router, Workers, Bun, Deno…):
+ * returns the verified agent, `null` for unsigned requests, or a 401
+ * `Response` when `required` and verification fails.
+ */
+declare function createVerifierMiddleware(opts?: VerifierOptions & {
+    required?: boolean;
+}): (request: Request) => Promise<VerifiedAgent | null | Response>;
+
 /**
  * wbauth: Web Bot Auth (RFC 9421) TypeScript SDK — Phase 4 public surface.
  *
@@ -206,6 +295,6 @@ declare function sign(request: NormalizedRequest, identity: Identity, opts?: Sig
  *   const res = await sf("https://api.example.com/data");
  */
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.0";
 
-export { type ApplyToOptions, DEFAULT_KEY_PATH, Identity, type IdentityOptions, type KeyPair, type NormalizedRequest, type SignOptions, type SignatureHeaders, type SignedFetchOptions, VERSION, applyTo, createSignedFetch, sign };
+export { type ApplyToOptions, DEFAULT_KEY_PATH, type Ed25519SignerBackend, Identity, type IdentityOptions, KEY_PASSWORD_ENV, type KeyOptions, type KeyPair, type KeyResolver, NonceStore, type NormalizedRequest, type PublicJwk, type SignOptions, type SignScopeOptions, type SignatureHeaders, type SignedFetchOptions, type Signer, VERSION, VerificationError, type VerifiedAgent, Verifier, type VerifierOptions, applyTo, createSignedFetch, createVerifierMiddleware, normalizeAuthority, sign, thumbprint, validateSignatureAgentUrl };