wb-auth 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# wbauth (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+npm install wbauth   # Phase 5 — not yet published
+```
+
+Phase 1: stub package — only used as the cross-language vector check oracle.
+Phase 4: full SDK with createSignedFetch + Playwright applyTo.

package/dist/index.d.cts

@@ -0,0 +1,189 @@
+import { Signer } from 'http-message-sig';
+import { Page } from 'playwright';
+
+/**
+ * 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.
+ *
+ * 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).
+ */
+
+/** Default path for the active signing key. Matches Python DEFAULT_KEY_PATH. */
+declare const DEFAULT_KEY_PATH: string;
+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 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. */
+    kid: string;
+    /** Pre-resolved web-bot-auth Signer (caches the imported CryptoKey). */
+    signer: Signer;
+}
+declare class Identity {
+    private _active;
+    private _retiring;
+    readonly signatureAgentUrl: string;
+    readonly userAgent: string | undefined;
+    private constructor();
+    /** 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. */
+    _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`.
+     */
+    exportJwks(): {
+        keys: JsonWebKey[];
+    };
+    /**
+     * 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).
+     */
+    rotate(newPath?: string): 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).
+     */
+    static loadOrGenerate(path: string | undefined, opts: IdentityOptions): 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.
+     */
+    static fromTestKey(signatureAgentUrl: string): Promise<Identity>;
+    toString(): string;
+}
+
+/**
+ * createSignedFetch — drop-in `fetch` wrapper that signs every outgoing request.
+ *
+ * Mirrors python/src/wbauth/adapters/httpx_auth.py. Stateless: closure over
+ * `identity` only. Returns a function whose signature matches `typeof fetch`,
+ * so user code can swap `fetch` for `signedFetch` without other changes.
+ *
+ * v1 limitation (Pitfall 4): streaming bodies are NOT supported. The adapter
+ * reads the full body via `req.clone().arrayBuffer()` to compute Content-Digest.
+ */
+
+declare function createSignedFetch(identity: Identity): typeof fetch;
+
+/**
+ * applyTo — Playwright async helper for Web Bot Auth (ADAPT-05).
+ *
+ * Mirrors python/src/wbauth/adapters/playwright.py. Registers a route
+ * handler that intercepts every outgoing request, signs it via wbauth.sign(),
+ * and continues with the signed headers.
+ *
+ * Pitfall 3: Call applyTo(page, identity) BEFORE the first page.goto()/click
+ * that should produce signed requests. page.route must be registered before
+ * navigation begins, or the navigation request leaves the browser unsigned.
+ *
+ * Pitfall (iframe coverage): page.route('**\/*', handler) covers all
+ * sub-frame requests by default. If the target site uses Service Workers,
+ * set serviceWorkers="block" on the BrowserContext (Playwright option).
+ *
+ * Note: `playwright` is a peerDependency (optional). End users only install
+ * it if they actually use this adapter — fetch-only consumers pay zero cost.
+ */
+
+declare function applyTo(page: Page, identity: Identity): Promise<void>;
+
+/**
+ * NormalizedRequest — the structural input to wbauth.sign().
+ *
+ * Mirrors python/src/wbauth/normalized_request.py. The Web Bot Auth signer
+ * does not care which HTTP client produced the request; it only needs the
+ * five fields below. Adapter glue (createSignedFetch, applyTo) constructs
+ * a NormalizedRequest from its native request type and hands it to sign().
+ *
+ * The `headers` dict is mutated in place by sign() — Signature, Signature-Input,
+ * and Signature-Agent are written back so the caller can read them out.
+ */
+interface NormalizedRequest {
+    /** HTTP method ("GET" | "POST" | "PUT" | "PATCH" | "DELETE" | ...). */
+    method: string;
+    /** Absolute URL — must be https:// for production targets. */
+    url: string;
+    /** Mutable header dict. sign() writes Signature, Signature-Input, Signature-Agent. */
+    headers: Record<string, string>;
+    /** Body bytes for content-digest computation; null/undefined for bodiless methods. */
+    body: Uint8Array | null;
+}
+
+interface SignatureHeaders {
+    signature: string;
+    signatureInput: string;
+    signatureAgent: string;
+}
+interface SignOptions {
+    /** Signing timestamp. Defaults to `new Date()`. Override for vector reproducibility. */
+    created?: Date;
+    /** Validity window in seconds. Defaults to 60. */
+    expiresAfterSeconds?: number;
+    /** Anti-replay nonce. Defaults to web-bot-auth's `generateNonce()` (64-byte b64). */
+    nonce?: string;
+    /** Signature label (the `sig1=` prefix). Defaults to "sig1". */
+    label?: 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.
+ */
+declare function sign(request: NormalizedRequest, identity: Identity, opts?: SignOptions): Promise<SignatureHeaders>;
+
+/**
+ * wbauth: Web Bot Auth (RFC 9421) TypeScript SDK — Phase 4 public surface.
+ *
+ * Per CONTEXT D-74: flat root exports. Subpath exports (`wbauth/adapters`)
+ * are a v1.x optimization, not required for Phase 4.
+ *
+ * Quickstart:
+ *   import { Identity, createSignedFetch } from "wbauth";
+ *   const id = await Identity.loadOrGenerate("./key.pem", {
+ *     signatureAgentUrl: "https://example.com/.well-known/.../<kid>",
+ *   });
+ *   const sf = createSignedFetch(id);
+ *   const res = await sf("https://api.example.com/data");
+ */
+
+declare const VERSION = "0.1.0";
+
+export { DEFAULT_KEY_PATH, Identity, type IdentityOptions, type KeyPair, type NormalizedRequest, type SignOptions, type SignatureHeaders, VERSION, applyTo, createSignedFetch, sign };

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import { Signer } from 'http-message-sig';
+import { Page } from 'playwright';
+
+/**
+ * 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.
+ *
+ * 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).
+ */
+
+/** Default path for the active signing key. Matches Python DEFAULT_KEY_PATH. */
+declare const DEFAULT_KEY_PATH: string;
+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 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. */
+    kid: string;
+    /** Pre-resolved web-bot-auth Signer (caches the imported CryptoKey). */
+    signer: Signer;
+}
+declare class Identity {
+    private _active;
+    private _retiring;
+    readonly signatureAgentUrl: string;
+    readonly userAgent: string | undefined;
+    private constructor();
+    /** 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. */
+    _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`.
+     */
+    exportJwks(): {
+        keys: JsonWebKey[];
+    };
+    /**
+     * 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).
+     */
+    rotate(newPath?: string): 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).
+     */
+    static loadOrGenerate(path: string | undefined, opts: IdentityOptions): 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.
+     */
+    static fromTestKey(signatureAgentUrl: string): Promise<Identity>;
+    toString(): string;
+}
+
+/**
+ * createSignedFetch — drop-in `fetch` wrapper that signs every outgoing request.
+ *
+ * Mirrors python/src/wbauth/adapters/httpx_auth.py. Stateless: closure over
+ * `identity` only. Returns a function whose signature matches `typeof fetch`,
+ * so user code can swap `fetch` for `signedFetch` without other changes.
+ *
+ * v1 limitation (Pitfall 4): streaming bodies are NOT supported. The adapter
+ * reads the full body via `req.clone().arrayBuffer()` to compute Content-Digest.
+ */
+
+declare function createSignedFetch(identity: Identity): typeof fetch;
+
+/**
+ * applyTo — Playwright async helper for Web Bot Auth (ADAPT-05).
+ *
+ * Mirrors python/src/wbauth/adapters/playwright.py. Registers a route
+ * handler that intercepts every outgoing request, signs it via wbauth.sign(),
+ * and continues with the signed headers.
+ *
+ * Pitfall 3: Call applyTo(page, identity) BEFORE the first page.goto()/click
+ * that should produce signed requests. page.route must be registered before
+ * navigation begins, or the navigation request leaves the browser unsigned.
+ *
+ * Pitfall (iframe coverage): page.route('**\/*', handler) covers all
+ * sub-frame requests by default. If the target site uses Service Workers,
+ * set serviceWorkers="block" on the BrowserContext (Playwright option).
+ *
+ * Note: `playwright` is a peerDependency (optional). End users only install
+ * it if they actually use this adapter — fetch-only consumers pay zero cost.
+ */
+
+declare function applyTo(page: Page, identity: Identity): Promise<void>;
+
+/**
+ * NormalizedRequest — the structural input to wbauth.sign().
+ *
+ * Mirrors python/src/wbauth/normalized_request.py. The Web Bot Auth signer
+ * does not care which HTTP client produced the request; it only needs the
+ * five fields below. Adapter glue (createSignedFetch, applyTo) constructs
+ * a NormalizedRequest from its native request type and hands it to sign().
+ *
+ * The `headers` dict is mutated in place by sign() — Signature, Signature-Input,
+ * and Signature-Agent are written back so the caller can read them out.
+ */
+interface NormalizedRequest {
+    /** HTTP method ("GET" | "POST" | "PUT" | "PATCH" | "DELETE" | ...). */
+    method: string;
+    /** Absolute URL — must be https:// for production targets. */
+    url: string;
+    /** Mutable header dict. sign() writes Signature, Signature-Input, Signature-Agent. */
+    headers: Record<string, string>;
+    /** Body bytes for content-digest computation; null/undefined for bodiless methods. */
+    body: Uint8Array | null;
+}
+
+interface SignatureHeaders {
+    signature: string;
+    signatureInput: string;
+    signatureAgent: string;
+}
+interface SignOptions {
+    /** Signing timestamp. Defaults to `new Date()`. Override for vector reproducibility. */
+    created?: Date;
+    /** Validity window in seconds. Defaults to 60. */
+    expiresAfterSeconds?: number;
+    /** Anti-replay nonce. Defaults to web-bot-auth's `generateNonce()` (64-byte b64). */
+    nonce?: string;
+    /** Signature label (the `sig1=` prefix). Defaults to "sig1". */
+    label?: 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.
+ */
+declare function sign(request: NormalizedRequest, identity: Identity, opts?: SignOptions): Promise<SignatureHeaders>;
+
+/**
+ * wbauth: Web Bot Auth (RFC 9421) TypeScript SDK — Phase 4 public surface.
+ *
+ * Per CONTEXT D-74: flat root exports. Subpath exports (`wbauth/adapters`)
+ * are a v1.x optimization, not required for Phase 4.
+ *
+ * Quickstart:
+ *   import { Identity, createSignedFetch } from "wbauth";
+ *   const id = await Identity.loadOrGenerate("./key.pem", {
+ *     signatureAgentUrl: "https://example.com/.well-known/.../<kid>",
+ *   });
+ *   const sf = createSignedFetch(id);
+ *   const res = await sf("https://api.example.com/data");
+ */
+
+declare const VERSION = "0.1.0";
+
+export { DEFAULT_KEY_PATH, Identity, type IdentityOptions, type KeyPair, type NormalizedRequest, type SignOptions, type SignatureHeaders, VERSION, applyTo, createSignedFetch, sign };

package/dist/index.js

@@ -0,0 +1,300 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_KEY_PATH: () => DEFAULT_KEY_PATH,
+  Identity: () => Identity,
+  VERSION: () => VERSION,
+  applyTo: () => applyTo,
+  createSignedFetch: () => createSignedFetch,
+  sign: () => sign
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/signer.ts
+var import_web_bot_auth = require("web-bot-auth");
+var DEFAULT_LABEL = "sig1";
+var DEFAULT_EXPIRES_SECONDS = 60;
+var DIGEST_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+function componentsFor(method, hasBody) {
+  const base = ["@authority", "signature-agent"];
+  if (hasBody && DIGEST_METHODS.has(method.toUpperCase())) {
+    base.push("content-digest");
+  }
+  return base;
+}
+async function sign(request, identity, opts = {}) {
+  if (!identity.signatureAgentUrl.startsWith("https://")) {
+    throw new Error(
+      `signatureAgentUrl must be https://, got: ${identity.signatureAgentUrl}`
+    );
+  }
+  const signatureAgentHeader = `"${identity.signatureAgentUrl}"`;
+  request.headers["Signature-Agent"] = signatureAgentHeader;
+  const created = opts.created ?? /* @__PURE__ */ new Date();
+  const expiresAfterSeconds = opts.expiresAfterSeconds ?? DEFAULT_EXPIRES_SECONDS;
+  const expires = new Date(created.getTime() + expiresAfterSeconds * 1e3);
+  const label = opts.label ?? DEFAULT_LABEL;
+  const hasBody = request.body !== null && request.body !== void 0;
+  const components = componentsFor(request.method, hasBody);
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(request.headers)) headers.set(k, v);
+  const init = { method: request.method, headers };
+  if (hasBody) init.body = request.body;
+  const req = new Request(request.url, init);
+  const params = {
+    created,
+    expires,
+    key: label,
+    components,
+    ...opts.nonce !== void 0 ? { nonce: opts.nonce } : {}
+  };
+  const result = await (0, import_web_bot_auth.signatureHeaders)(req, identity._signer(), params);
+  request.headers.Signature = result.Signature;
+  request.headers["Signature-Input"] = result["Signature-Input"];
+  return {
+    signature: result.Signature,
+    signatureInput: result["Signature-Input"],
+    signatureAgent: signatureAgentHeader
+  };
+}
+
+// src/adapters/_utils.ts
+var import_node_crypto = require("crypto");
+var DIGEST_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+function ensureContentDigest(method, headers, body) {
+  if (!body || body.byteLength === 0) return;
+  if (!DIGEST_METHODS2.has(method.toUpperCase())) return;
+  if (Object.keys(headers).some((k) => k.toLowerCase() === "content-digest")) {
+    return;
+  }
+  const b64 = (0, import_node_crypto.createHash)("sha256").update(body).digest("base64");
+  headers["Content-Digest"] = `sha-256=:${b64}:`;
+}
+
+// src/adapters/fetch.ts
+function createSignedFetch(identity) {
+  return async function signedFetch(input, init = {}) {
+    const req = new Request(input, init);
+    const method = req.method;
+    const url = req.url;
+    let body = null;
+    if (req.body) {
+      const buf = await req.clone().arrayBuffer();
+      body = buf.byteLength > 0 ? new Uint8Array(buf) : null;
+    }
+    const headers = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    ensureContentDigest(method, headers, body);
+    await sign({ method, url, headers, body }, identity);
+    if (identity.userAgent && !Object.keys(headers).some((k) => k.toLowerCase() === "user-agent")) {
+      headers["User-Agent"] = identity.userAgent;
+    }
+    return fetch(url, {
+      ...init,
+      method,
+      headers,
+      body: body ?? void 0
+    });
+  };
+}
+
+// src/adapters/playwright.ts
+async function applyTo(page, identity) {
+  await page.route("**/*", async (route, request) => {
+    const headers = await request.allHeaders();
+    const postData = request.postDataBuffer();
+    const body = postData ? new Uint8Array(postData) : null;
+    ensureContentDigest(request.method(), headers, body);
+    await sign(
+      { method: request.method(), url: request.url(), headers, body },
+      identity
+    );
+    if (identity.userAgent && !Object.keys(headers).some((k) => k.toLowerCase() === "user-agent")) {
+      headers["User-Agent"] = identity.userAgent;
+    }
+    await route.continue({ headers });
+  });
+}
+
+// src/identity.ts
+var import_node_crypto2 = require("crypto");
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_crypto = require("web-bot-auth/crypto");
+var DEFAULT_KEY_PATH = (0, import_node_path.resolve)(
+  (0, import_node_os.homedir)(),
+  ".config",
+  "wbauth",
+  "key.pem"
+);
+var TEST_KEY_JWK = {
+  kty: "OKP",
+  crv: "Ed25519",
+  d: "n4Ni-HpISpVObnQMW0wOhCKROaIKqKtW_2ZYb2p9KcU",
+  x: "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs"
+};
+var Identity = class _Identity {
+  _active;
+  _retiring;
+  signatureAgentUrl;
+  userAgent;
+  constructor(active, opts, retiring = null) {
+    if (!opts.signatureAgentUrl.startsWith("https://")) {
+      throw new Error(
+        `signatureAgentUrl must be https://, got: ${opts.signatureAgentUrl}`
+      );
+    }
+    this._active = active;
+    this._retiring = retiring;
+    this.signatureAgentUrl = opts.signatureAgentUrl;
+    this.userAgent = opts.userAgent;
+  }
+  // ---------- Public read-only API ----------
+  /** The active key's kid (used as `keyid=` param in Signature-Input). */
+  get kid() {
+    return this._active.kid;
+  }
+  /** Module-internal: returns the resolved Signer for sign() to use. */
+  _signer() {
+    return this._active.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`.
+   */
+  exportJwks() {
+    const keys = [this._active.publicJwk];
+    if (this._retiring) keys.push(this._retiring.publicJwk);
+    return { keys };
+  }
+  /**
+   * 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).
+   */
+  async rotate(newPath = DEFAULT_KEY_PATH) {
+    const newPair = await generateKeypairTo(expandUser(newPath));
+    return new _Identity(
+      newPair,
+      { signatureAgentUrl: this.signatureAgentUrl, userAgent: this.userAgent },
+      this._active
+    );
+  }
+  // ---------- Constructors ----------
+  /**
+   * 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).
+   */
+  static async loadOrGenerate(path = DEFAULT_KEY_PATH, opts) {
+    const resolved = expandUser(path);
+    const pair = (0, import_node_fs.existsSync)(resolved) ? await loadKeypair(resolved) : await generateKeypairTo(resolved);
+    return new _Identity(pair, opts);
+  }
+  /**
+   * 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.
+   */
+  static async fromTestKey(signatureAgentUrl) {
+    const pair = await keyPairFromJwk(TEST_KEY_JWK);
+    return new _Identity(pair, { signatureAgentUrl });
+  }
+  // ---------- Redaction guarantees (IDENT-08) ----------
+  toString() {
+    return `<Identity REDACTED kid='${this.kid}' sig_agent='${this.signatureAgentUrl}'>`;
+  }
+  /** util.inspect / console.log render the same REDACTED form (IDENT-08). */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+};
+function expandUser(path) {
+  return (0, import_node_path.resolve)(path.startsWith("~") ? path.replace(/^~/, (0, import_node_os.homedir)()) : path);
+}
+async function keyPairFromJwk(privateJwk) {
+  const signer = await (0, import_crypto.signerFromJWK)(privateJwk);
+  const kid = signer.keyid;
+  const publicJwk = {
+    kty: privateJwk.kty,
+    crv: privateJwk.crv,
+    x: privateJwk.x,
+    kid
+  };
+  return { privateJwk, publicJwk, kid, signer };
+}
+async function loadKeypair(path) {
+  if (process.platform !== "win32") {
+    const mode = (0, import_node_fs.statSync)(path).mode & 511;
+    if ((mode & 63) !== 0) {
+      throw new Error(
+        `Key file ${path} has mode 0o${mode.toString(8)}; expected 0o600. Fix: chmod 600 ${path}`
+      );
+    }
+  } else {
+    process.emitWarning(
+      `Windows detected \u2014 file permissions on ${path} cannot be enforced via POSIX mode. Use NTFS ACLs or store the key in a per-user secrets vault.`
+    );
+  }
+  const pem = (0, import_node_fs.readFileSync)(path, "utf8");
+  const jwk = (0, import_node_crypto2.createPrivateKey)(pem).export({ format: "jwk" });
+  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519") {
+    throw new TypeError(`Expected Ed25519, got kty=${jwk.kty}, crv=${jwk.crv}`);
+  }
+  return keyPairFromJwk(jwk);
+}
+async function generateKeypairTo(path) {
+  const dir = (0, import_node_path.dirname)(path);
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  if ((0, import_node_fs.existsSync)(path)) {
+    throw new Error(`Key already exists at ${path}; refuse overwrite`);
+  }
+  const { privateKey } = (0, import_node_crypto2.generateKeyPairSync)("ed25519");
+  const pem = privateKey.export({ format: "pem", type: "pkcs8" });
+  const fd = (0, import_node_fs.openSync)(path, "wx", 384);
+  try {
+    (0, import_node_fs.writeFileSync)(fd, pem);
+  } finally {
+    (0, import_node_fs.closeSync)(fd);
+  }
+  const jwk = privateKey.export({ format: "jwk" });
+  return keyPairFromJwk(jwk);
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_KEY_PATH,
+  Identity,
+  VERSION,
+  applyTo,
+  createSignedFetch,
+  sign
+});

package/dist/index.mjs

@@ -0,0 +1,276 @@
+// src/signer.ts
+import { signatureHeaders } from "web-bot-auth";
+var DEFAULT_LABEL = "sig1";
+var DEFAULT_EXPIRES_SECONDS = 60;
+var DIGEST_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+function componentsFor(method, hasBody) {
+  const base = ["@authority", "signature-agent"];
+  if (hasBody && DIGEST_METHODS.has(method.toUpperCase())) {
+    base.push("content-digest");
+  }
+  return base;
+}
+async function sign(request, identity, opts = {}) {
+  if (!identity.signatureAgentUrl.startsWith("https://")) {
+    throw new Error(
+      `signatureAgentUrl must be https://, got: ${identity.signatureAgentUrl}`
+    );
+  }
+  const signatureAgentHeader = `"${identity.signatureAgentUrl}"`;
+  request.headers["Signature-Agent"] = signatureAgentHeader;
+  const created = opts.created ?? /* @__PURE__ */ new Date();
+  const expiresAfterSeconds = opts.expiresAfterSeconds ?? DEFAULT_EXPIRES_SECONDS;
+  const expires = new Date(created.getTime() + expiresAfterSeconds * 1e3);
+  const label = opts.label ?? DEFAULT_LABEL;
+  const hasBody = request.body !== null && request.body !== void 0;
+  const components = componentsFor(request.method, hasBody);
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(request.headers)) headers.set(k, v);
+  const init = { method: request.method, headers };
+  if (hasBody) init.body = request.body;
+  const req = new Request(request.url, init);
+  const params = {
+    created,
+    expires,
+    key: label,
+    components,
+    ...opts.nonce !== void 0 ? { nonce: opts.nonce } : {}
+  };
+  const result = await signatureHeaders(req, identity._signer(), params);
+  request.headers.Signature = result.Signature;
+  request.headers["Signature-Input"] = result["Signature-Input"];
+  return {
+    signature: result.Signature,
+    signatureInput: result["Signature-Input"],
+    signatureAgent: signatureAgentHeader
+  };
+}
+
+// src/adapters/_utils.ts
+import { createHash } from "crypto";
+var DIGEST_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+function ensureContentDigest(method, headers, body) {
+  if (!body || body.byteLength === 0) return;
+  if (!DIGEST_METHODS2.has(method.toUpperCase())) return;
+  if (Object.keys(headers).some((k) => k.toLowerCase() === "content-digest")) {
+    return;
+  }
+  const b64 = createHash("sha256").update(body).digest("base64");
+  headers["Content-Digest"] = `sha-256=:${b64}:`;
+}
+
+// src/adapters/fetch.ts
+function createSignedFetch(identity) {
+  return async function signedFetch(input, init = {}) {
+    const req = new Request(input, init);
+    const method = req.method;
+    const url = req.url;
+    let body = null;
+    if (req.body) {
+      const buf = await req.clone().arrayBuffer();
+      body = buf.byteLength > 0 ? new Uint8Array(buf) : null;
+    }
+    const headers = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    ensureContentDigest(method, headers, body);
+    await sign({ method, url, headers, body }, identity);
+    if (identity.userAgent && !Object.keys(headers).some((k) => k.toLowerCase() === "user-agent")) {
+      headers["User-Agent"] = identity.userAgent;
+    }
+    return fetch(url, {
+      ...init,
+      method,
+      headers,
+      body: body ?? void 0
+    });
+  };
+}
+
+// src/adapters/playwright.ts
+async function applyTo(page, identity) {
+  await page.route("**/*", async (route, request) => {
+    const headers = await request.allHeaders();
+    const postData = request.postDataBuffer();
+    const body = postData ? new Uint8Array(postData) : null;
+    ensureContentDigest(request.method(), headers, body);
+    await sign(
+      { method: request.method(), url: request.url(), headers, body },
+      identity
+    );
+    if (identity.userAgent && !Object.keys(headers).some((k) => k.toLowerCase() === "user-agent")) {
+      headers["User-Agent"] = identity.userAgent;
+    }
+    await route.continue({ headers });
+  });
+}
+
+// src/identity.ts
+import { createPrivateKey, generateKeyPairSync } from "crypto";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+import { signerFromJWK } from "web-bot-auth/crypto";
+var DEFAULT_KEY_PATH = resolve(
+  homedir(),
+  ".config",
+  "wbauth",
+  "key.pem"
+);
+var TEST_KEY_JWK = {
+  kty: "OKP",
+  crv: "Ed25519",
+  d: "n4Ni-HpISpVObnQMW0wOhCKROaIKqKtW_2ZYb2p9KcU",
+  x: "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs"
+};
+var Identity = class _Identity {
+  _active;
+  _retiring;
+  signatureAgentUrl;
+  userAgent;
+  constructor(active, opts, retiring = null) {
+    if (!opts.signatureAgentUrl.startsWith("https://")) {
+      throw new Error(
+        `signatureAgentUrl must be https://, got: ${opts.signatureAgentUrl}`
+      );
+    }
+    this._active = active;
+    this._retiring = retiring;
+    this.signatureAgentUrl = opts.signatureAgentUrl;
+    this.userAgent = opts.userAgent;
+  }
+  // ---------- Public read-only API ----------
+  /** The active key's kid (used as `keyid=` param in Signature-Input). */
+  get kid() {
+    return this._active.kid;
+  }
+  /** Module-internal: returns the resolved Signer for sign() to use. */
+  _signer() {
+    return this._active.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`.
+   */
+  exportJwks() {
+    const keys = [this._active.publicJwk];
+    if (this._retiring) keys.push(this._retiring.publicJwk);
+    return { keys };
+  }
+  /**
+   * 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).
+   */
+  async rotate(newPath = DEFAULT_KEY_PATH) {
+    const newPair = await generateKeypairTo(expandUser(newPath));
+    return new _Identity(
+      newPair,
+      { signatureAgentUrl: this.signatureAgentUrl, userAgent: this.userAgent },
+      this._active
+    );
+  }
+  // ---------- Constructors ----------
+  /**
+   * 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).
+   */
+  static async loadOrGenerate(path = DEFAULT_KEY_PATH, opts) {
+    const resolved = expandUser(path);
+    const pair = existsSync(resolved) ? await loadKeypair(resolved) : await generateKeypairTo(resolved);
+    return new _Identity(pair, opts);
+  }
+  /**
+   * 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.
+   */
+  static async fromTestKey(signatureAgentUrl) {
+    const pair = await keyPairFromJwk(TEST_KEY_JWK);
+    return new _Identity(pair, { signatureAgentUrl });
+  }
+  // ---------- Redaction guarantees (IDENT-08) ----------
+  toString() {
+    return `<Identity REDACTED kid='${this.kid}' sig_agent='${this.signatureAgentUrl}'>`;
+  }
+  /** util.inspect / console.log render the same REDACTED form (IDENT-08). */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+};
+function expandUser(path) {
+  return resolve(path.startsWith("~") ? path.replace(/^~/, homedir()) : path);
+}
+async function keyPairFromJwk(privateJwk) {
+  const signer = await signerFromJWK(privateJwk);
+  const kid = signer.keyid;
+  const publicJwk = {
+    kty: privateJwk.kty,
+    crv: privateJwk.crv,
+    x: privateJwk.x,
+    kid
+  };
+  return { privateJwk, publicJwk, kid, signer };
+}
+async function loadKeypair(path) {
+  if (process.platform !== "win32") {
+    const mode = statSync(path).mode & 511;
+    if ((mode & 63) !== 0) {
+      throw new Error(
+        `Key file ${path} has mode 0o${mode.toString(8)}; expected 0o600. Fix: chmod 600 ${path}`
+      );
+    }
+  } else {
+    process.emitWarning(
+      `Windows detected \u2014 file permissions on ${path} cannot be enforced via POSIX mode. Use NTFS ACLs or store the key in a per-user secrets vault.`
+    );
+  }
+  const pem = readFileSync(path, "utf8");
+  const jwk = createPrivateKey(pem).export({ format: "jwk" });
+  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519") {
+    throw new TypeError(`Expected Ed25519, got kty=${jwk.kty}, crv=${jwk.crv}`);
+  }
+  return keyPairFromJwk(jwk);
+}
+async function generateKeypairTo(path) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  if (existsSync(path)) {
+    throw new Error(`Key already exists at ${path}; refuse overwrite`);
+  }
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const pem = privateKey.export({ format: "pem", type: "pkcs8" });
+  const fd = openSync(path, "wx", 384);
+  try {
+    writeFileSync(fd, pem);
+  } finally {
+    closeSync(fd);
+  }
+  const jwk = privateKey.export({ format: "jwk" });
+  return keyPairFromJwk(jwk);
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+export {
+  DEFAULT_KEY_PATH,
+  Identity,
+  VERSION,
+  applyTo,
+  createSignedFetch,
+  sign
+};

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "wb-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Web Bot Auth (RFC 9421) TypeScript SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "http-message-sig": "^0.2.0",
+    "web-bot-auth": "^0.1.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2",
+    "@types/node": "^20",
+    "playwright": "^1.59",
+    "tsup": "^8",
+    "typescript": "^6",
+    "vitest": "^4"
+  },
+  "peerDependencies": {
+    "playwright": "^1"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "biome check ."
+  }
 }