@agentpress/sdk 0.2.113 → 0.3.0

package/README.md

@@ -320,29 +320,37 @@ try {
 
 ```
 AgentPressError (base)
-  ConfigurationError    -- invalid options or missing webhookSecret
-  HttpError             -- non-2xx response (has statusCode, responseBody, url)
-  TimeoutError          -- request exceeded timeout
-  WebhookSignatureError -- invalid/expired signature (from verifyOrThrow only)
+  ConfigurationError      -- invalid options or missing webhookSecret / partnerMcp
+  HttpError               -- non-2xx response (has statusCode, responseBody, url)
+  TimeoutError            -- request exceeded timeout
+  WebhookSignatureError   -- invalid/expired signature (from verifyOrThrow only)
+  PartnerTokenError       -- Partner MCP JWT verification failure (has typed `reason`)
+  KeyRotationVerifyError  -- Key-rotation webhook verification failure (has typed `reason`)
 ```
 
 ## Exported Types
 
 ```typescript
 import type {
-  ActionCallbackPayload,   // Inbound webhook payload from constructEvent()
-  ActionEventType,         // "action.pending_approval" | "action.approved" | ...
-  ActionManageResponse,    // Response from actions.approve() / actions.reject()
-  ActionStatus,            // "pending" | "staged" | "approved" | "rejected" | "completed" | "failed" | "expired"
-  AgentPressOptions,       // Constructor options
-  AgentResponse,           // Agent text response + tool calls
-  ApproveActionParams,     // actions.approve() params
-  RejectActionParams,      // actions.reject() params
-  StagedToolCall,          // Tool call awaiting approval
-  ToolCallResult,          // Individual tool call (name, arguments, result)
-  WebhookResponse,         // Response from send
-  WebhookSendParams,       // send params
-  WebhookVerifyParams,     // verify / verifyOrThrow / constructEvent params
+  ActionCallbackPayload,         // Inbound webhook payload from constructEvent()
+  ActionEventType,               // "action.pending_approval" | "action.approved" | ...
+  ActionManageResponse,          // Response from actions.approve() / actions.reject()
+  ActionStatus,                  // "pending" | "staged" | "approved" | "rejected" | "completed" | "failed" | "expired"
+  AgentPressOptions,             // Constructor options
+  AgentResponse,                 // Agent text response + tool calls
+  ApproveActionParams,           // actions.approve() params
+  KeyRotationEvent,              // Verified signing_key_rotation webhook payload
+  KeyRotationVerifyErrorReason,  // Union of KeyRotationVerifyError.reason values
+  KeyRotationVerifyParams,       // verifyKeyRotation() params
+  PartnerMcpOptions,             // AgentPressOptions.partnerMcp shape
+  PartnerTokenClaims,            // Verified Partner MCP Spec v1 JWT claims
+  PartnerTokenErrorReason,       // Union of PartnerTokenError.reason values
+  RejectActionParams,            // actions.reject() params
+  StagedToolCall,                // Tool call awaiting approval
+  ToolCallResult,                // Individual tool call (name, arguments, result)
+  WebhookResponse,               // Response from send
+  WebhookSendParams,             // send params
+  WebhookVerifyParams,           // verify / verifyOrThrow / constructEvent params
 } from "@agentpress/sdk";
 ```
 
@@ -384,6 +392,198 @@ app.post("/webhooks/agentpress", express.raw({ type: "application/json" }), (req
 });
 ```
 
+## Partner MCP Spec v1
+
+Partners building an MCP server that federates with AgentPress can use the SDK's built-in verifiers for the two cryptographic primitives the spec requires: **EdDSA JWT verification** (against a remote JWKS) for inbound bearer tokens, and **HMAC-SHA256 webhook verification** for `signing_key_rotation` notifications.
+
+This consolidates ~200 lines of hand-rolled JWT/JWKS/HMAC code that would otherwise live in every partner MCP integration. For the full wire protocol see the [Partner MCP Spec v1 guide](https://docs.agentpress.dev/guides/partner-mcp-spec-v1/).
+
+### Configuration
+
+Partner MCP helpers require a `partnerMcp` block on the constructor. All fields except `clockTolerance` and `jwksCacheMaxAgeMs` are required.
+
+```typescript
+import { AgentPress } from "@agentpress/sdk";
+
+// Per-org as of Partner MCP Spec v1 — each AgentPress org that registers you
+// as a partner has its own signing keypair and JWKS URL. The org admin who
+// registers you will share the org slug; your `issuer` + `jwksUrl` are
+// derived from it.
+const client = new AgentPress({
+  webhookSecret: "whsec_...",            // Needed for verifyKeyRotation
+  partnerMcp: {
+    jwksUrl: "https://api.agent.press/orgs/<org-slug>/.well-known/jwks.json",
+    issuer: "https://api.agent.press/orgs/<org-slug>",
+    audience: "https://mcp.example.com", // Your MCP's stable URL
+    expectedExtProvider: "localfalcon",  // Required ext_provider claim value
+    clockTolerance: "30s",               // Default: "30s" (accepts number of seconds or jose duration string)
+    jwksCacheMaxAgeMs: 3_600_000,        // Default: 1 hour
+  },
+});
+```
+
+### Running staging and production side-by-side
+
+Staging and production MUST be separate `AgentPress` client instances, each with its own `partnerMcp` block. JWKS cache state is per-instance (not module-global), so two clients can run side-by-side in the same process without cross-talk.
+
+```typescript
+const staging = new AgentPress({
+  webhookSecret: process.env.AGENTPRESS_WEBHOOK_SECRET_STAGING,
+  partnerMcp: {
+    jwksUrl: "https://stg-api.agent.press/orgs/<org-slug>/.well-known/jwks.json",
+    issuer: "https://stg-api.agent.press/orgs/<org-slug>",
+    audience: "https://mcp-staging.example.com",
+    expectedExtProvider: "localfalcon",
+  },
+});
+
+const production = new AgentPress({
+  webhookSecret: process.env.AGENTPRESS_WEBHOOK_SECRET_PROD,
+  partnerMcp: {
+    jwksUrl: "https://api.agent.press/orgs/<org-slug>/.well-known/jwks.json",
+    issuer: "https://api.agent.press/orgs/<org-slug>",
+    audience: "https://mcp.example.com",
+    expectedExtProvider: "localfalcon",
+  },
+});
+```
+
+Route requests to the correct client by inspecting the JWT's `iss` claim (or by a request-scoped environment flag upstream of the verifier). If the same partner integration serves multiple AgentPress orgs, spin up one client per org — do NOT share a single client across orgs (JWKS caches, `iss`, and `aud` are all org-scoped).
+
+---
+
+### client.partners.verifyToken(token)
+
+Verifies an EdDSA JWT issued by AgentPress against the configured remote JWKS. Returns typed `PartnerTokenClaims` on success; throws `PartnerTokenError` with a typed `reason` on failure.
+
+Enforces the full spec: `alg` pinned to `EdDSA`, `iss` / `aud` exact-match, `ext_provider` exact-match, `sub` / `jti` / `scope` required and non-empty, `kid` header required, `exp` / `iat` validated with configurable skew (default ±30s).
+
+```typescript
+import { AgentPress, PartnerTokenError } from "@agentpress/sdk";
+import { Hono } from "hono";
+
+const client = new AgentPress({ partnerMcp: { /* ... */ } });
+
+const app = new Hono();
+
+app.post("/mcp", async (c) => {
+  const auth = c.req.header("authorization") ?? "";
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+
+  if (!token) {
+    return c.text("Unauthorized", 401, {
+      "WWW-Authenticate": 'Bearer error="invalid_token", error_description="Missing bearer token"',
+    });
+  }
+
+  try {
+    const claims = await client.partners.verifyToken(token);
+
+    // claims is typed PartnerTokenClaims -- use `sub` to resolve the external user
+    // into your local user record (partner-domain logic):
+    const user = await resolveExternalUser(claims.ext_provider, claims.sub);
+    c.set("user", user);
+    c.set("claims", claims);
+
+    return handleMcpRequest(c);
+  } catch (err) {
+    if (err instanceof PartnerTokenError) {
+      const description = mapReasonToDescription(err.reason);
+      return c.text("Unauthorized", 401, {
+        "WWW-Authenticate": `Bearer error="invalid_token", error_description="${description}"`,
+      });
+    }
+    throw err;
+  }
+});
+```
+
+**Error handling table** — all `PartnerTokenError` reasons map to RFC 6750 `error="invalid_token"`. Use `error_description` to distinguish:
+
+| `reason` | HTTP | `error` | `error_description` |
+|---|---|---|---|
+| `signature_invalid` | 401 | `invalid_token` | `Signature verification failed` |
+| `issuer_mismatch` | 401 | `invalid_token` | `Issuer does not match` |
+| `audience_mismatch` | 401 | `invalid_token` | `Audience does not match` |
+| `expired` | 401 | `invalid_token` | `Token expired` |
+| `not_yet_valid` | 401 | `invalid_token` | `Token not yet valid` |
+| `missing_claim` | 401 | `invalid_token` | `Required claim missing or invalid` |
+| `ext_provider_mismatch` | 401 | `invalid_token` | `ext_provider does not match` |
+| `algorithm_not_allowed` | 401 | `invalid_token` | `Algorithm not allowed` |
+| `kid_missing_or_unknown` | 401 | `invalid_token` | `Signing key id missing or unknown` |
+| `malformed` | 401 | `invalid_token` | `Malformed token` |
+
+---
+
+### client.webhooks.verifyKeyRotation(params) + client.partners.refreshJwks()
+
+Verifies a `signing_key_rotation` webhook signed by AgentPress with HMAC-SHA256 over the raw request body, then refreshes the JWKS cache so the next verified token picks up the new signing key without a failed-verify penalty.
+
+The rotation webhook handler is **optional** — partners who don't implement it still pick up rotations automatically on the next `kid` miss (with one failed verify latency). Implement it to make rotations seamless.
+
+```typescript
+import { AgentPress, KeyRotationVerifyError } from "@agentpress/sdk";
+import { Hono } from "hono";
+
+const client = new AgentPress({
+  webhookSecret: process.env.AGENTPRESS_WEBHOOK_SECRET,
+  partnerMcp: { /* ... */ },
+});
+
+const app = new Hono();
+
+app.post("/webhooks/agentpress/key-rotation", async (c) => {
+  // IMPORTANT: read the raw body, not c.req.json() -- HMAC is computed over
+  // the exact bytes AgentPress sent, not a re-serialized JSON object.
+  const rawBody = await c.req.text();
+
+  // Headers are passed verbatim as Record<string, string | undefined>; casing
+  // is handled internally.
+  const headers: Record<string, string | undefined> = {};
+  c.req.raw.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  try {
+    const event = client.webhooks.verifyKeyRotation({
+      payload: rawBody,
+      headers,
+    });
+
+    // event is typed KeyRotationEvent
+    console.log(
+      `Rotation (${event.type}): ${event.retiredKid} -> ${event.newCurrentKid}`,
+    );
+
+    // Force-refetch the JWKS so the next verifyToken() picks up the new key.
+    await client.partners.refreshJwks();
+
+    return c.json({ received: true });
+  } catch (err) {
+    if (err instanceof KeyRotationVerifyError) {
+      const status = mapRotationReasonToStatus(err.reason);
+      return c.text(err.message, status);
+    }
+    throw err;
+  }
+});
+```
+
+**Error handling table** for `KeyRotationVerifyError` reasons:
+
+| `reason` | HTTP | Notes |
+|---|---|---|
+| `invalid_signature` | 401 | HMAC mismatch |
+| `invalid_signature_format` | 401 | `x-agentpress-signature` missing or not `sha256=<hex>` |
+| `timestamp_out_of_window` | 401 | `x-agentpress-timestamp` outside ±5 min tolerance |
+| `invalid_timestamp` | 401 | `x-agentpress-timestamp` missing or not a unix-seconds integer |
+| `malformed_payload` | 400 | Body is not valid JSON or doesn't match the rotation event schema |
+| `payload_too_large` | 413 | Body exceeds 8 KB cap |
+
+---
+
+For the full Partner MCP Spec v1 — token shape, JWKS discovery, rotation semantics, and error protocol — see the [guide on docs.agentpress.dev](https://docs.agentpress.dev/guides/partner-mcp-spec-v1/).
+
 ## File Structure
 
 ```
@@ -396,7 +596,10 @@ packages/sdk/src/
   utils.ts              -- randomMessageId() helper (msg_<uuid>)
   actions/
     client.ts           -- ActionsClient (approve, reject)
+  partners/
+    client.ts           -- PartnersClient (verifyToken, refreshJwks)
   webhooks/
-    client.ts           -- WebhooksClient (send, verify, verifyOrThrow, constructEvent)
+    client.ts           -- WebhooksClient (send, verify, verifyOrThrow, constructEvent, verifyKeyRotation)
     signing.ts          -- HMAC-SHA256 Svix-compatible sign + verify functions
+    keyRotation.ts      -- Partner MCP Spec v1 rotation webhook HMAC + timestamp + payload validation
 ```

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let node_crypto = require("node:crypto");
+let jose = require("jose");
 //#region src/errors.ts
 /**
 * Base error class for all SDK errors. Catch this to handle any error
@@ -60,6 +61,33 @@ var WebhookSignatureError = class extends AgentPressError {
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 };
+/**
+* Thrown by {@link PartnersClient.verifyToken} when a Partner MCP Spec v1 JWT
+* fails verification. Partners map `reason` to their RFC 6750 `WWW-Authenticate`
+* response (`401 invalid_token` for all reasons in this class).
+*/
+var PartnerTokenError = class extends AgentPressError {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "PartnerTokenError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/**
+* Thrown by {@link WebhooksClient.verifyKeyRotation} when a `signing_key_rotation`
+* webhook fails HMAC / timestamp / payload validation.
+*/
+var KeyRotationVerifyError = class extends AgentPressError {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "KeyRotationVerifyError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
 //#endregion
 //#region src/utils.ts
 function randomMessageId() {
@@ -67,7 +95,7 @@ function randomMessageId() {
 }
 //#endregion
 //#region src/webhooks/signing.ts
-const SIGNATURE_PREFIX = "v1,";
+const SIGNATURE_PREFIX$1 = "v1,";
 const DEFAULT_TOLERANCE_SECONDS = 300;
 /**
 * Sign a webhook payload using Svix-compatible HMAC-SHA256.
@@ -81,7 +109,7 @@ const DEFAULT_TOLERANCE_SECONDS = 300;
 function sign(secret, msgId, timestamp, body) {
 	const secretBytes = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
 	const message = `${msgId}.${timestamp}.${body}`;
-	return `${SIGNATURE_PREFIX}${(0, node_crypto.createHmac)("sha256", secretBytes).update(message).digest("base64")}`;
+	return `${SIGNATURE_PREFIX$1}${(0, node_crypto.createHmac)("sha256", secretBytes).update(message).digest("base64")}`;
 }
 /**
 * Verify a Svix webhook signature.
@@ -234,6 +262,121 @@ var HttpClient = class {
 	}
 };
 //#endregion
+//#region src/partners/client.ts
+const ALGORITHMS = ["EdDSA"];
+/**
+* Client for Partner MCP Spec v1 helpers. Created automatically when
+* {@link AgentPressOptions.partnerMcp} is provided.
+*
+* State (JWKS cache) is per-instance, NOT module-global, so staging and
+* production clients can run side-by-side without cross-talk.
+*/
+var PartnersClient = class {
+	options;
+	partnerMcp;
+	jwks = null;
+	jwksKeyFn = null;
+	constructor(options) {
+		this.options = options;
+		this.partnerMcp = options.partnerMcp;
+	}
+	/**
+	* Verify an inbound Partner MCP Spec v1 JWT against AgentPress's JWKS.
+	*
+	* Enforces the full spec: `algorithms: ["EdDSA"]` pinned; `iss`, `aud`,
+	* `ext_provider` validated; `sub`, `jti`, `scope` required and non-empty;
+	* `kid` header required; `exp` / `iat` validated with ±30s skew (configurable).
+	*
+	* @param token - Bare JWT string (no `Bearer ` prefix).
+	* @returns Typed {@link PartnerTokenClaims}.
+	* @throws {PartnerTokenError} with a typed `reason` for RFC 6750 mapping.
+	* @throws {ConfigurationError} if `partnerMcp` is not configured.
+	*/
+	async verifyToken(token) {
+		const cfg = this.requireConfig();
+		const jwks = this.getJwks();
+		let payload;
+		let protectedHeader;
+		try {
+			const result = await (0, jose.jwtVerify)(token, jwks, {
+				algorithms: [...ALGORITHMS],
+				issuer: cfg.issuer,
+				audience: cfg.audience,
+				clockTolerance: cfg.clockTolerance
+			});
+			payload = result.payload;
+			protectedHeader = result.protectedHeader;
+		} catch (err) {
+			throw mapJoseError(err);
+		}
+		if (!protectedHeader.kid || typeof protectedHeader.kid !== "string") throw new PartnerTokenError("kid_missing_or_unknown", "JWT header missing required 'kid'");
+		const claims = payload;
+		if (typeof claims.iat !== "number" || !Number.isFinite(claims.iat)) throw new PartnerTokenError("missing_claim", "'iat' claim must be a number");
+		const toleranceSeconds = toSeconds(cfg.clockTolerance);
+		const nowSec = Math.floor(Date.now() / 1e3);
+		if (claims.iat - nowSec > toleranceSeconds) throw new PartnerTokenError("not_yet_valid", `'iat' is ${claims.iat - nowSec}s in the future, beyond ${toleranceSeconds}s tolerance`);
+		if (typeof claims.sub !== "string" || claims.sub.length === 0) throw new PartnerTokenError("missing_claim", "'sub' claim is required");
+		if (typeof claims.jti !== "string" || claims.jti.length === 0) throw new PartnerTokenError("missing_claim", "'jti' claim is required");
+		if (typeof claims.scope !== "string") throw new PartnerTokenError("missing_claim", "'scope' claim must be a string");
+		if (typeof claims.ext_provider !== "string" || claims.ext_provider.length === 0) throw new PartnerTokenError("missing_claim", "'ext_provider' claim is required");
+		if (claims.ext_provider !== cfg.expectedExtProvider) throw new PartnerTokenError("ext_provider_mismatch", `ext_provider '${claims.ext_provider}' does not match expected '${cfg.expectedExtProvider}'`);
+		return claims;
+	}
+	/**
+	* Force the JWKS cache to refetch immediately. Call this from your
+	* `signing_key_rotation` webhook handler after verifying the webhook —
+	* otherwise the cache picks up new keys on the next `kid` miss (which
+	* works, but with one failed verify latency penalty).
+	*/
+	async refreshJwks() {
+		const anyJwks = this.getJwks();
+		if (typeof anyJwks.reload === "function") await anyJwks.reload();
+	}
+	requireConfig() {
+		if (!this.partnerMcp) throw new ConfigurationError("partnerMcp options are required for partner token operations");
+		return this.partnerMcp;
+	}
+	getJwks() {
+		const cfg = this.requireConfig();
+		if (!this.jwks) {
+			this.jwks = (0, jose.createRemoteJWKSet)(new URL(cfg.jwksUrl), {
+				cacheMaxAge: cfg.jwksCacheMaxAgeMs,
+				cooldownDuration: 3e4
+			});
+			this.jwksKeyFn = this.jwks;
+		}
+		return this.jwks;
+	}
+};
+function toSeconds(tolerance) {
+	if (typeof tolerance === "number") return tolerance;
+	const match = tolerance.trim().match(/^(\d+)\s*(s|m|h)$/i);
+	if (!match) return 30;
+	const n = Number.parseInt(match[1], 10);
+	const unit = match[2].toLowerCase();
+	if (unit === "s") return n;
+	if (unit === "m") return n * 60;
+	if (unit === "h") return n * 3600;
+	return 30;
+}
+function mapJoseError(err) {
+	if (err instanceof PartnerTokenError) return err;
+	if (err instanceof jose.errors.JWSSignatureVerificationFailed) return new PartnerTokenError("signature_invalid", "JWT signature verification failed");
+	if (err instanceof jose.errors.JWKSNoMatchingKey) return new PartnerTokenError("kid_missing_or_unknown", "No JWKS key matches the JWT 'kid' header");
+	if (err instanceof jose.errors.JOSEAlgNotAllowed) return new PartnerTokenError("algorithm_not_allowed", "JWT 'alg' is not EdDSA");
+	if (err instanceof jose.errors.JWTExpired) return new PartnerTokenError("expired", "JWT has expired");
+	if (err instanceof jose.errors.JWTClaimValidationFailed) {
+		const claim = err.claim;
+		if (claim === "iss") return new PartnerTokenError("issuer_mismatch", "JWT 'iss' does not match expected issuer");
+		if (claim === "aud") return new PartnerTokenError("audience_mismatch", "JWT 'aud' does not match expected audience");
+		if (claim === "iat") return new PartnerTokenError("not_yet_valid", "JWT 'iat' is in the future beyond clock tolerance");
+		return new PartnerTokenError("missing_claim", err.message || "Claim validation failed");
+	}
+	if (err instanceof jose.errors.JWTInvalid || err instanceof jose.errors.JWSInvalid) return new PartnerTokenError("malformed", err.message || "Malformed JWT");
+	if (err instanceof Error) return new PartnerTokenError("malformed", err.message);
+	return new PartnerTokenError("malformed", String(err));
+}
+//#endregion
 //#region src/userApprovals/client.ts
 /**
 * Client for managing per-user auto-approval rules — the SDK equivalent of the
@@ -349,6 +492,74 @@ var UserApprovalsClient = class {
 	}
 };
 //#endregion
+//#region src/webhooks/keyRotation.ts
+const MAX_PAYLOAD_BYTES = 8 * 1024;
+const TIMESTAMP_SKEW_SECONDS = 300;
+const SIGNATURE_PREFIX = "sha256=";
+/**
+* Verify a `signing_key_rotation` webhook signed by AgentPress with
+* HMAC-SHA256 over the raw request body. Returns the typed
+* {@link KeyRotationEvent} payload.
+*
+* @throws {KeyRotationVerifyError} with a typed `reason` for HTTP mapping.
+* @throws {ConfigurationError} if `webhookSecret` is not configured.
+*/
+function verifyKeyRotation(secret, params) {
+	if (!secret) throw new ConfigurationError("webhookSecret is required for key rotation webhook verification");
+	const body = typeof params.payload === "string" ? params.payload : params.payload.toString("utf-8");
+	if ((typeof params.payload === "string" ? Buffer.byteLength(params.payload, "utf-8") : params.payload.length) > MAX_PAYLOAD_BYTES) throw new KeyRotationVerifyError("payload_too_large", `Payload exceeds ${MAX_PAYLOAD_BYTES} bytes`);
+	const signatureHeader = readHeader(params.headers, "x-agentpress-signature");
+	const timestampHeader = readHeader(params.headers, "x-agentpress-timestamp");
+	if (!signatureHeader?.startsWith(SIGNATURE_PREFIX)) throw new KeyRotationVerifyError("invalid_signature_format", `Signature header missing or does not start with '${SIGNATURE_PREFIX}'`);
+	const providedHex = signatureHeader.slice(7).toLowerCase();
+	if (!/^[0-9a-f]+$/.test(providedHex)) throw new KeyRotationVerifyError("invalid_signature_format", "Signature is not a hex string");
+	if (!timestampHeader) throw new KeyRotationVerifyError("invalid_timestamp", "x-agentpress-timestamp header is required");
+	const timestamp = Number.parseInt(timestampHeader, 10);
+	if (!Number.isFinite(timestamp) || String(timestamp) !== timestampHeader.trim()) throw new KeyRotationVerifyError("invalid_timestamp", "x-agentpress-timestamp is not a valid unix seconds integer");
+	const now = Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - timestamp) > TIMESTAMP_SKEW_SECONDS) throw new KeyRotationVerifyError("timestamp_out_of_window", `Timestamp skew ${Math.abs(now - timestamp)}s exceeds ${TIMESTAMP_SKEW_SECONDS}s tolerance`);
+	const expectedHex = (0, node_crypto.createHmac)("sha256", secret).update(body).digest("hex");
+	const providedBuf = Buffer.from(providedHex, "hex");
+	const expectedBuf = Buffer.from(expectedHex, "hex");
+	if (providedBuf.length !== expectedBuf.length || !(0, node_crypto.timingSafeEqual)(providedBuf, expectedBuf)) throw new KeyRotationVerifyError("invalid_signature", "HMAC signature mismatch");
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		throw new KeyRotationVerifyError("malformed_payload", "Payload is not valid JSON");
+	}
+	return validatePayload(parsed);
+}
+function readHeader(headers, name) {
+	const lowered = name.toLowerCase();
+	for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === lowered && typeof v === "string" && v.length > 0) return v;
+}
+function validatePayload(raw) {
+	if (!raw || typeof raw !== "object") throw new KeyRotationVerifyError("malformed_payload", "Payload must be a JSON object");
+	const obj = raw;
+	if (obj.event !== "signing_key_rotation") throw new KeyRotationVerifyError("malformed_payload", `Unexpected event '${String(obj.event)}'`);
+	if (obj.type !== "scheduled" && obj.type !== "emergency") throw new KeyRotationVerifyError("malformed_payload", "'type' must be 'scheduled' or 'emergency'");
+	for (const key of [
+		"retiredKid",
+		"newCurrentKid",
+		"retiredAt",
+		"effectiveAt",
+		"jwksUrl"
+	]) if (typeof obj[key] !== "string" || obj[key].length === 0) throw new KeyRotationVerifyError("malformed_payload", `'${key}' must be a non-empty string`);
+	if (obj.reason !== void 0 && typeof obj.reason !== "string") throw new KeyRotationVerifyError("malformed_payload", "'reason' must be a string when present");
+	const event = {
+		event: "signing_key_rotation",
+		type: obj.type,
+		retiredKid: obj.retiredKid,
+		newCurrentKid: obj.newCurrentKid,
+		retiredAt: obj.retiredAt,
+		effectiveAt: obj.effectiveAt,
+		jwksUrl: obj.jwksUrl
+	};
+	if (typeof obj.reason === "string") event.reason = obj.reason;
+	return event;
+}
+//#endregion
 //#region src/webhooks/client.ts
 var WebhooksClient = class {
 	options;
@@ -420,6 +631,18 @@ var WebhooksClient = class {
 			throw new AgentPressError("Webhook payload is not valid JSON");
 		}
 	}
+	/**
+	* Verify an inbound `signing_key_rotation` webhook (HMAC-SHA256 + timestamp
+	* + typed payload) from AgentPress. See the Partner MCP Spec v1 for the
+	* full contract.
+	*
+	* @throws {KeyRotationVerifyError} with a typed `reason` for HTTP mapping
+	*   (401 for signature errors, 400 for malformed payload, 413 for oversize).
+	* @throws {ConfigurationError} if `webhookSecret` is not configured.
+	*/
+	verifyKeyRotation(params) {
+		return verifyKeyRotation(this.options.webhookSecret, params);
+	}
 };
 //#endregion
 //#region src/client.ts
@@ -445,6 +668,8 @@ var AgentPress = class {
 	actions;
 	/** Per-user auto-approval rules (read / create / update / delete). */
 	userApprovals;
+	/** Partner MCP Spec v1 helpers (inbound JWT verification, JWKS refresh). */
+	partners;
 	/**
 	* @param options - SDK configuration. All fields are optional with sensible defaults.
 	* @throws {ConfigurationError} If `timeout` is non-positive or `webhookSecret` has an invalid prefix.
@@ -455,6 +680,7 @@ var AgentPress = class {
 		this.webhooks = new WebhooksClient(resolved, http);
 		this.actions = new ActionsClient(resolved, http);
 		this.userApprovals = new UserApprovalsClient(resolved, http);
+		this.partners = new PartnersClient(resolved);
 	}
 };
 function resolveOptions(options) {
@@ -469,18 +695,46 @@ function resolveOptions(options) {
 		org,
 		webhookSecret: options.webhookSecret,
 		apiKey: options.apiKey,
+		partnerMcp: resolvePartnerMcp(options.partnerMcp),
 		onRequest: options.onRequest,
 		onResponse: options.onResponse
 	};
 }
+function resolvePartnerMcp(options) {
+	if (!options) return void 0;
+	if (typeof options.jwksUrl !== "string" || options.jwksUrl.length === 0) throw new ConfigurationError("partnerMcp.jwksUrl is required");
+	try {
+		new URL(options.jwksUrl);
+	} catch {
+		throw new ConfigurationError("partnerMcp.jwksUrl must be a valid URL");
+	}
+	if (typeof options.issuer !== "string" || options.issuer.length === 0) throw new ConfigurationError("partnerMcp.issuer is required");
+	if (typeof options.audience !== "string" || options.audience.length === 0) throw new ConfigurationError("partnerMcp.audience is required");
+	if (typeof options.expectedExtProvider !== "string" || options.expectedExtProvider.length === 0) throw new ConfigurationError("partnerMcp.expectedExtProvider is required");
+	const clockTolerance = options.clockTolerance ?? "30s";
+	const jwksCacheMaxAgeMs = options.jwksCacheMaxAgeMs ?? 36e5;
+	if (jwksCacheMaxAgeMs <= 0 || !Number.isFinite(jwksCacheMaxAgeMs)) throw new ConfigurationError("partnerMcp.jwksCacheMaxAgeMs must be a positive number");
+	return {
+		jwksUrl: options.jwksUrl,
+		issuer: options.issuer,
+		audience: options.audience,
+		expectedExtProvider: options.expectedExtProvider,
+		clockTolerance,
+		jwksCacheMaxAgeMs
+	};
+}
 //#endregion
 exports.ActionsClient = ActionsClient;
 exports.AgentPress = AgentPress;
 exports.AgentPressError = AgentPressError;
 exports.ConfigurationError = ConfigurationError;
 exports.HttpError = HttpError;
+exports.KeyRotationVerifyError = KeyRotationVerifyError;
+exports.PartnerTokenError = PartnerTokenError;
+exports.PartnersClient = PartnersClient;
 exports.TimeoutError = TimeoutError;
 exports.UserApprovalsClient = UserApprovalsClient;
 exports.WebhookSignatureError = WebhookSignatureError;
+exports.WebhooksClient = WebhooksClient;
 
 //# sourceMappingURL=index.cjs.map