@pithy-sh/core 0.1.1 → 0.1.3

package/dist/controlPlane/scope/scope.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+/**
+ * One granted operation. Validated on the way into the connection row and on the way out of a token,
+ * so a malformed scope is a parse failure at the boundary rather than a silent never-match — a scope
+ * that reads as a grant in the row and denies at every call looks like a bug in the seam.
+ */
+export declare const ControlPlaneScope: z.ZodString;
+export type ControlPlaneScope = z.output<typeof ControlPlaneScope>;
+/**
+ * The requirement for a route that needs a **verified caller but no authorization** — today, only
+ * `GET /control-plane/ping`.
+ *
+ * Ping is not a scope, and modeling it as one would be dishonest: granting it would change nothing
+ * and withholding it would change nothing, because ping must work for a connection granted nothing at
+ * all. It is the call that proves a newly registered key works *before* the key it replaces is
+ * expired, and that ordering is the entire safety property of rotation. A ping that could be withheld
+ * would let a connection reach a state where the replacement can never be proven — and then either the
+ * old key is never expired, or it is expired anyway and nobody can get back in.
+ *
+ * A symbol rather than a magic string, so it is unforgeable by construction. Claims arrive over the
+ * wire as JSON, and no JSON value is ever equal to this — a caller cannot present it, only a route can
+ * require it.
+ */
+export declare const ANY_VERIFIED_CALLER: unique symbol;
+/**
+ * What a route demands of a caller: one named operation, or merely that it verified.
+ *
+ * `requireControlPlane` takes this rather than an optional scope on purpose. An optional argument is a
+ * thing you can forget, and forgetting it on an admin route would mean shipping an unscoped one; a
+ * required argument means the only way to write a route with no authorization is to say
+ * {@link ANY_VERIFIED_CALLER} out loud, which is as deliberate as naming a scope.
+ */
+export type ControlPlaneRequirement = ControlPlaneScope | typeof ANY_VERIFIED_CALLER;
+/**
+ * Read this Worker's composed capability manifest — the discovery-over-configuration call.
+ *
+ * Annotated `: ControlPlaneScope` like every capability's scope, and not merely for symmetry: that
+ * annotation is how `tooling/browser-scopes` finds a control-plane scope at all. Matching the type
+ * rather than the `_SCOPE` suffix is what keeps `PLAY_SCOPE` (a Google OAuth URL) and `GLOBAL_SCOPE`
+ * (an environment name) out of a gate that has nothing to say about either.
+ */
+export declare const MANIFEST_READ_SCOPE: ControlPlaneScope;
+/**
+ * Register a new public key, expire a superseded one, and read the registration state. One scope for
+ * the whole key lifecycle, granted separately at connect: an adopter who does not want a management
+ * client changing keys on a schedule simply does not grant it, and then it *cannot*, whatever the
+ * client intends. Better than a toggle anyone has to be trusted to honor.
+ */
+export declare const KEYS_ROTATE_SCOPE: ControlPlaneScope;
+/**
+ * Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
+ * Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ */
+export declare const SEAM_SCOPES: readonly ControlPlaneScope[];
+/**
+ * Does this call carry what the route requires?
+ *
+ * Both sides must agree, and they are checked against different things on purpose. `granted` is what
+ * the **adopter** stored on the connection; `presented` is the single scope the **caller** put in the
+ * token for this one call. A scope the adopter never granted is denied however the token is written,
+ * and a token that claims a broad grant still only exercises the one operation it named.
+ *
+ * Matching is exact string equality. There is no prefix or wildcard rule, because
+ * `payments:entitlements` must not quietly confer `payments:entitlements:revoke` — prefix semantics on
+ * an authorization check is how a read grant becomes a write one without anybody deciding it should.
+ */
+export declare function scopeCovers(required: ControlPlaneRequirement, presented: string, granted: readonly string[]): boolean;
+//# sourceMappingURL=scope.d.ts.map

package/dist/controlPlane/scope/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}

package/dist/controlPlane/scope/scope.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+/**
+* One granted operation. Validated on the way into the connection row and on the way out of a token,
+* so a malformed scope is a parse failure at the boundary rather than a silent never-match — a scope
+* that reads as a grant in the row and denies at every call looks like a bug in the seam.
+*/
+const ControlPlaneScope = z.string().regex(/^[a-z][a-z0-9]*(?::[a-z][a-z0-9_]*)+$/, "A control-plane scope must be lowercase colon-separated segments naming one operation (e.g. `manifest:read`, `payments:entitlements:grant`).").describe("One management operation a connection may perform, as a colon-separated `resource:action` code. The taxonomy is federated: each capability declares its own scopes, and core holds only the seam's.");
+/**
+* The requirement for a route that needs a **verified caller but no authorization** — today, only
+* `GET /control-plane/ping`.
+*
+* Ping is not a scope, and modeling it as one would be dishonest: granting it would change nothing
+* and withholding it would change nothing, because ping must work for a connection granted nothing at
+* all. It is the call that proves a newly registered key works *before* the key it replaces is
+* expired, and that ordering is the entire safety property of rotation. A ping that could be withheld
+* would let a connection reach a state where the replacement can never be proven — and then either the
+* old key is never expired, or it is expired anyway and nobody can get back in.
+*
+* A symbol rather than a magic string, so it is unforgeable by construction. Claims arrive over the
+* wire as JSON, and no JSON value is ever equal to this — a caller cannot present it, only a route can
+* require it.
+*/
+const ANY_VERIFIED_CALLER = Symbol.for("pithy.controlPlane.anyVerifiedCaller");
+/**
+* Read this Worker's composed capability manifest — the discovery-over-configuration call.
+*
+* Annotated `: ControlPlaneScope` like every capability's scope, and not merely for symmetry: that
+* annotation is how `tooling/browser-scopes` finds a control-plane scope at all. Matching the type
+* rather than the `_SCOPE` suffix is what keeps `PLAY_SCOPE` (a Google OAuth URL) and `GLOBAL_SCOPE`
+* (an environment name) out of a gate that has nothing to say about either.
+*/
+const MANIFEST_READ_SCOPE = "manifest:read";
+/**
+* Register a new public key, expire a superseded one, and read the registration state. One scope for
+* the whole key lifecycle, granted separately at connect: an adopter who does not want a management
+* client changing keys on a schedule simply does not grant it, and then it *cannot*, whatever the
+* client intends. Better than a toggle anyone has to be trusted to honor.
+*/
+const KEYS_ROTATE_SCOPE = "keys:rotate";
+/**
+* Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
+* Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+*/
+const SEAM_SCOPES = [MANIFEST_READ_SCOPE, KEYS_ROTATE_SCOPE];
+/**
+* Does this call carry what the route requires?
+*
+* Both sides must agree, and they are checked against different things on purpose. `granted` is what
+* the **adopter** stored on the connection; `presented` is the single scope the **caller** put in the
+* token for this one call. A scope the adopter never granted is denied however the token is written,
+* and a token that claims a broad grant still only exercises the one operation it named.
+*
+* Matching is exact string equality. There is no prefix or wildcard rule, because
+* `payments:entitlements` must not quietly confer `payments:entitlements:revoke` — prefix semantics on
+* an authorization check is how a read grant becomes a write one without anybody deciding it should.
+*/
+function scopeCovers(required, presented, granted) {
+	if (required === ANY_VERIFIED_CALLER) return true;
+	if (presented !== required) return false;
+	return granted.includes(required);
+}
+//#endregion
+export { ANY_VERIFIED_CALLER, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, SEAM_SCOPES, scopeCovers };

package/dist/controlPlane/token/base64url.d.ts

@@ -0,0 +1,10 @@
+/** Encode raw bytes as unpadded base64url. */
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+/**
+ * Decode unpadded base64url to raw bytes, or throw {@link ControlPlaneInvalidCredentialError}.
+ *
+ * Every rejection is the same error for the same reason the verification steps are: a caller learns
+ * that the credential is not valid here, never which character gave it away.
+ */
+export declare function base64UrlDecode(value: string): Uint8Array;
+//# sourceMappingURL=base64url.d.ts.map

package/dist/controlPlane/token/base64url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64url.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/token/base64url.ts"],"names":[],"mappings":"AAyBA,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAOzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAuBzD"}

package/dist/controlPlane/token/base64url.js

@@ -0,0 +1,48 @@
+import { ControlPlaneInvalidCredentialError } from "../error/errors.js";
+//#region src/controlPlane/token/base64url.ts
+/**
+* base64url, the encoding every part of a compact JWS is written in (RFC 4648 §5). Core ships no
+* base64 helper, so the seam brings its own rather than reaching into another package's crypto.
+*
+* Two properties matter here and nowhere else in the tree.
+*
+* **Decoding is strict.** A token segment is attacker-supplied by definition, and `atob` is famously
+* forgiving — it will happily digest whitespace and, on some runtimes, characters that mean nothing.
+* Silently decoding malformed input produces bytes that parse into *something*, and something is
+* exactly what an attacker wants a verifier to work with. So anything outside the url alphabet is a
+* throw, and the throw is a credential failure that renders as a 401 through the one handler.
+*
+* **Padding is rejected, not tolerated.** RFC 7515 §2 mandates unpadded segments. Accepting `=`
+* would give one token two spellings, and a token with two spellings is two strings to log, two to
+* compare, and one more thing an equality check can be wrong about.
+*/
+/** The url alphabet, unpadded. Whitespace, `+`, `/` and `=` are all outside it, deliberately. */
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
+/** Encode raw bytes as unpadded base64url. */
+function base64UrlEncode(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+* Decode unpadded base64url to raw bytes, or throw {@link ControlPlaneInvalidCredentialError}.
+*
+* Every rejection is the same error for the same reason the verification steps are: a caller learns
+* that the credential is not valid here, never which character gave it away.
+*/
+function base64UrlDecode(value) {
+	if (!BASE64URL_PATTERN.test(value)) throw new ControlPlaneInvalidCredentialError({ detail: "token segment is not unpadded base64url (RFC 4648 §5)" });
+	if (value.length % 4 === 1) throw new ControlPlaneInvalidCredentialError({ detail: "token segment has an impossible base64url length" });
+	const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - value.length % 4) % 4);
+	let binary;
+	try {
+		binary = atob(padded);
+	} catch (cause) {
+		throw new ControlPlaneInvalidCredentialError({ detail: "token segment failed base64url decode" }, { cause });
+	}
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+//#endregion
+export { base64UrlDecode, base64UrlEncode };

package/dist/controlPlane/token/claims.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+/**
+ * The token a management client presents: what it claims, and what shape the envelope around it must
+ * have. This is the wire contract between the hosted dashboard and an adopter's Worker.
+ *
+ * **Not Cloudflare's control plane.** That is the outbound provisioning REST API this project calls
+ * through `@pithy-sh/cloudflare`. This is the inbound admin seam, authenticated by the adopter, in the
+ * adopter's Worker. The names collide; nothing else does.
+ *
+ * These schemas describe *untrusted* data. Parsing one proves the token is well-formed and nothing
+ * more — a forged token parses exactly as cleanly as a real one. Authenticity comes only from
+ * `verifyEd25519` (`./jws`), and nothing may act on these values before it returns true.
+ */
+/**
+ * How long a token may live, from `iat` to `exp`.
+ *
+ * A minute is the whole budget: mint, send, verify. Nothing legitimate needs more, because the client
+ * mints per call rather than caching a credential.
+ *
+ * **This cap is what makes the replay window sound.** Replay defense is a `jti` held in a KV set with
+ * a TTL, and a set with a TTL only covers tokens that expire inside it. Without a cap, a client could
+ * mint an `exp` an hour out; the `jti` would age out after {@link CONTROL_PLANE_JTI_TTL_SECONDS} and
+ * the same token would then replay freely for the remaining fifty-odd minutes. So the cap is enforced
+ * at verification, not merely recommended — a token whose lifetime exceeds it is rejected however
+ * validly it is signed.
+ */
+export declare const CONTROL_PLANE_MAX_TOKEN_LIFETIME_SECONDS = 60;
+/**
+ * How far the two clocks may disagree before a valid call is refused.
+ *
+ * Applied at both ends: a token is not "not yet valid" until it is this far in the future, and not
+ * expired until this far in the past. Machines that never sync do exist, and a management client
+ * locked out by a drifting clock has no way to notice, let alone fix it. A minute is generous enough
+ * to survive that and short enough to stay inside the replay window below.
+ */
+export declare const CONTROL_PLANE_CLOCK_SKEW_SECONDS = 60;
+/**
+ * How long a spent `jti` stays in the replay set.
+ *
+ * It must **outlive** the longest window in which its token could still verify — the max lifetime plus
+ * a skew at each end, so 60 + 60 + 60 = 180. Shorter, and a token becomes replayable the moment its id
+ * ages out; longer only costs storage in a store whose entries expire on their own.
+ *
+ * 300 rather than exactly 180, because equal is not longer. At 180 the memory ends on the same instant
+ * the token stops being accepted, which leaves the boundary decided by whichever clock rounds first —
+ * and "the replay window is only open for the last instant" is not a property worth defending. The two
+ * extra minutes cost nothing and make the relation a strict inequality, which is what
+ * `ControlPlaneConfig` now enforces and `claims.test.ts` asserts.
+ */
+export declare const CONTROL_PLANE_JTI_TTL_SECONDS = 300;
+/**
+ * The JWS protected header.
+ *
+ * **`alg` is a pinned literal, and that is the algorithm-confusion defense.** The classic JWT breaks
+ * are both header-driven: `"alg":"none"` asking the verifier to skip verification, and swapping RS256
+ * for HS256 so a *public* key is used as an HMAC secret. Both need the verifier to take its algorithm
+ * from the token. Here the schema decides and the token merely has to agree, so neither attack has a
+ * shape it can be written in — the header is rejected at parse, before a key is ever imported.
+ */
+export declare const ControlPlaneJwsHeader: z.ZodObject<{
+    alg: z.ZodLiteral<"EdDSA">;
+    typ: z.ZodLiteral<"JWT">;
+    kid: z.ZodString;
+}, z.core.$strip>;
+export type ControlPlaneJwsHeader = z.infer<typeof ControlPlaneJwsHeader>;
+/**
+ * The token payload.
+ *
+ * Every claim is a check the Worker performs against something it already knows — the connection row,
+ * its own clock, its own environment, the body it just read. None of them are informational.
+ */
+export declare const ControlPlaneClaims: z.ZodObject<{
+    iss: z.ZodURL;
+    aud: z.ZodUUID;
+    sub: z.ZodString;
+    scope: z.ZodString;
+    jti: z.ZodString;
+    iat: z.ZodInt;
+    exp: z.ZodInt;
+    bodySha256: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ControlPlaneClaims = z.infer<typeof ControlPlaneClaims>;
+//# sourceMappingURL=claims.d.ts.map

package/dist/controlPlane/token/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/token/claims.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAKjD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;iBAoB/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAiD5B,CAAC;AACJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/controlPlane/token/claims.js

@@ -0,0 +1,86 @@
+import { ControlPlaneScope } from "../scope/scope.js";
+import { z } from "zod";
+//#region src/controlPlane/token/claims.ts
+/**
+* The token a management client presents: what it claims, and what shape the envelope around it must
+* have. This is the wire contract between the hosted dashboard and an adopter's Worker.
+*
+* **Not Cloudflare's control plane.** That is the outbound provisioning REST API this project calls
+* through `@pithy-sh/cloudflare`. This is the inbound admin seam, authenticated by the adopter, in the
+* adopter's Worker. The names collide; nothing else does.
+*
+* These schemas describe *untrusted* data. Parsing one proves the token is well-formed and nothing
+* more — a forged token parses exactly as cleanly as a real one. Authenticity comes only from
+* `verifyEd25519` (`./jws`), and nothing may act on these values before it returns true.
+*/
+/**
+* How long a token may live, from `iat` to `exp`.
+*
+* A minute is the whole budget: mint, send, verify. Nothing legitimate needs more, because the client
+* mints per call rather than caching a credential.
+*
+* **This cap is what makes the replay window sound.** Replay defense is a `jti` held in a KV set with
+* a TTL, and a set with a TTL only covers tokens that expire inside it. Without a cap, a client could
+* mint an `exp` an hour out; the `jti` would age out after {@link CONTROL_PLANE_JTI_TTL_SECONDS} and
+* the same token would then replay freely for the remaining fifty-odd minutes. So the cap is enforced
+* at verification, not merely recommended — a token whose lifetime exceeds it is rejected however
+* validly it is signed.
+*/
+const CONTROL_PLANE_MAX_TOKEN_LIFETIME_SECONDS = 60;
+/**
+* How far the two clocks may disagree before a valid call is refused.
+*
+* Applied at both ends: a token is not "not yet valid" until it is this far in the future, and not
+* expired until this far in the past. Machines that never sync do exist, and a management client
+* locked out by a drifting clock has no way to notice, let alone fix it. A minute is generous enough
+* to survive that and short enough to stay inside the replay window below.
+*/
+const CONTROL_PLANE_CLOCK_SKEW_SECONDS = 60;
+/**
+* How long a spent `jti` stays in the replay set.
+*
+* It must **outlive** the longest window in which its token could still verify — the max lifetime plus
+* a skew at each end, so 60 + 60 + 60 = 180. Shorter, and a token becomes replayable the moment its id
+* ages out; longer only costs storage in a store whose entries expire on their own.
+*
+* 300 rather than exactly 180, because equal is not longer. At 180 the memory ends on the same instant
+* the token stops being accepted, which leaves the boundary decided by whichever clock rounds first —
+* and "the replay window is only open for the last instant" is not a property worth defending. The two
+* extra minutes cost nothing and make the relation a strict inequality, which is what
+* `ControlPlaneConfig` now enforces and `claims.test.ts` asserts.
+*/
+const CONTROL_PLANE_JTI_TTL_SECONDS = 300;
+/** A base64url SHA-256: 32 bytes, unpadded, exactly 43 characters. */
+const BODY_SHA256_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+/**
+* The JWS protected header.
+*
+* **`alg` is a pinned literal, and that is the algorithm-confusion defense.** The classic JWT breaks
+* are both header-driven: `"alg":"none"` asking the verifier to skip verification, and swapping RS256
+* for HS256 so a *public* key is used as an HMAC secret. Both need the verifier to take its algorithm
+* from the token. Here the schema decides and the token merely has to agree, so neither attack has a
+* shape it can be written in — the header is rejected at parse, before a key is ever imported.
+*/
+const ControlPlaneJwsHeader = z.object({
+	alg: z.literal("EdDSA").describe("The signature algorithm, pinned to EdDSA (Ed25519). A literal rather than a choice: the verifier never takes its algorithm from the token, so `none` and HMAC-for-RSA confusion are unrepresentable."),
+	typ: z.literal("JWT").describe("The token type, always `JWT`. Pinned so a JWS meant for another purpose cannot be replayed here."),
+	kid: z.string().min(1).max(64).describe("Which registered key signed this token, matched against the connection's `keys`. A hint for lookup only — an unknown or forged `kid` selects no key and the call is denied.")
+}).describe("The protected header of a control-plane token. Untrusted until the signature verifies; `alg` is pinned rather than read.");
+/**
+* The token payload.
+*
+* Every claim is a check the Worker performs against something it already knows — the connection row,
+* its own clock, its own environment, the body it just read. None of them are informational.
+*/
+const ControlPlaneClaims = z.object({
+	iss: z.url().describe("The management client's origin. Checked against the `issuer` the adopter stored on the connection, so a token minted by another origin is denied even if it is validly signed."),
+	aud: z.uuid().describe("The connection this token addresses — the row's UUID. A UUID because it is externally exposed; checked so a token for one adopter's connection cannot be presented to another's Worker."),
+	sub: z.string().min(1).max(256).describe("The dashboard user acting, in the management client's own id space. Recorded as the audit `actorId` so the trail says which person acted, not merely which service."),
+	scope: ControlPlaneScope.describe("The single operation this token authorizes. One call, one scope: a token carrying the whole grant would make every call as dangerous as the most dangerous one it could make."),
+	jti: z.string().min(1).max(128).describe("A unique id for this one token, claimed in the replay set on first use. Bounded so an unbounded string cannot be used to bloat that set."),
+	iat: z.int().describe("When the token was minted, in seconds since the epoch. With `exp` it bounds the lifetime, which is capped at CONTROL_PLANE_MAX_TOKEN_LIFETIME_SECONDS."),
+	exp: z.int().describe("When the token stops being accepted, in seconds since the epoch. Honored within CONTROL_PLANE_CLOCK_SKEW_SECONDS, and never further out than the max lifetime allows."),
+	bodySha256: z.string().regex(BODY_SHA256_PATTERN, "bodySha256 must be a base64url SHA-256 digest.").nullable().describe("Base64url SHA-256 of the request body, binding this token to one call — or null for a request with no body. The signature covers the header and claims only, so without this a token could be lifted onto a different body for the same route.")
+}).describe("The claims a management client signs for exactly one control-plane call. Well-formed after parsing; authentic only after the signature verifies.");
+//#endregion
+export { CONTROL_PLANE_CLOCK_SKEW_SECONDS, CONTROL_PLANE_JTI_TTL_SECONDS, CONTROL_PLANE_MAX_TOKEN_LIFETIME_SECONDS, ControlPlaneClaims, ControlPlaneJwsHeader };

package/dist/controlPlane/token/digest.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The two primitives the body-binding check needs: hash a request body, then compare that hash to the
+ * one the token committed to.
+ *
+ * Body binding is what stops a verified token being lifted off one call and stapled to another. The
+ * signature covers the header and claims, never the body — so the claims carry `bodySha256`, and the
+ * Worker recomputes it. Without that, an intercepted `keys:rotate` token would authorize *any*
+ * `keys:rotate` body, including one registering the interceptor's key.
+ */
+/**
+ * SHA-256 a request body, base64url-encoded — the exact form `bodySha256` is written in.
+ *
+ * **A view is copied before it is hashed, and that is a fix rather than a formality** (#315).
+ * `crypto.subtle.digest` takes a `BufferSource`, which is `ArrayBufferView<ArrayBuffer> | ArrayBuffer`
+ * — a plain `Uint8Array` is `Uint8Array<ArrayBufferLike>`, which also admits a view onto a
+ * `SharedArrayBuffer`, and so does not satisfy it. `@cloudflare/workers-types` spells `BufferSource`
+ * loosely enough that the mismatch never surfaced in a Worker program; an adopter compiling this
+ * module against the DOM lib got a type error inside our source, with nothing on their side to fix.
+ *
+ * The copy is what makes the narrowing true rather than asserted, and the reason it is worth its cost:
+ * a digest of memory another thread can write is a check that does not bind what it checked. Copying
+ * fixes the bytes at the instant they are hashed, so `bodySha256` commits to what the verifier
+ * actually compared. The bodies here are small signed control-plane requests, and the alternative was
+ * a cast that would have kept the hazard and hidden the argument.
+ */
+export declare function sha256Base64Url(bytes: ArrayBuffer | Uint8Array): Promise<string>;
+/**
+ * Compare two strings without leaking, through timing, where they first differ.
+ *
+ * The honest caveat first: `===` on a **digest** is a weak oracle at best. To exploit the early return
+ * an attacker must steer the digest byte by byte, which means finding preimages — so this is not the
+ * classic "guess the MAC one byte at a time" break that constant-time comparison was invented for.
+ *
+ * We do it anyway, for two reasons. The threat model is not fixed: this helper is the one every future
+ * comparison in the seam will reach for, and the next thing compared may well be a value an attacker
+ * *can* choose freely, at which point a plain `===` becomes a real break with no diff to notice it in.
+ * And the cost is a loop over 43 characters. Paying it always is cheaper than auditing, every time,
+ * whether this particular comparison happened to be safe.
+ *
+ * The scan runs to the end of the longer string and folds the length difference into the same
+ * accumulator, so neither an early match nor an early mismatch changes the work done.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+//# sourceMappingURL=digest.d.ts.map

package/dist/controlPlane/token/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/token/digest.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAItF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAS7D"}

package/dist/controlPlane/token/digest.js

@@ -0,0 +1,56 @@
+import { base64UrlEncode } from "./base64url.js";
+//#region src/controlPlane/token/digest.ts
+/**
+* The two primitives the body-binding check needs: hash a request body, then compare that hash to the
+* one the token committed to.
+*
+* Body binding is what stops a verified token being lifted off one call and stapled to another. The
+* signature covers the header and claims, never the body — so the claims carry `bodySha256`, and the
+* Worker recomputes it. Without that, an intercepted `keys:rotate` token would authorize *any*
+* `keys:rotate` body, including one registering the interceptor's key.
+*/
+/**
+* SHA-256 a request body, base64url-encoded — the exact form `bodySha256` is written in.
+*
+* **A view is copied before it is hashed, and that is a fix rather than a formality** (#315).
+* `crypto.subtle.digest` takes a `BufferSource`, which is `ArrayBufferView<ArrayBuffer> | ArrayBuffer`
+* — a plain `Uint8Array` is `Uint8Array<ArrayBufferLike>`, which also admits a view onto a
+* `SharedArrayBuffer`, and so does not satisfy it. `@cloudflare/workers-types` spells `BufferSource`
+* loosely enough that the mismatch never surfaced in a Worker program; an adopter compiling this
+* module against the DOM lib got a type error inside our source, with nothing on their side to fix.
+*
+* The copy is what makes the narrowing true rather than asserted, and the reason it is worth its cost:
+* a digest of memory another thread can write is a check that does not bind what it checked. Copying
+* fixes the bytes at the instant they are hashed, so `bodySha256` commits to what the verifier
+* actually compared. The bodies here are small signed control-plane requests, and the alternative was
+* a cast that would have kept the hazard and hidden the argument.
+*/
+async function sha256Base64Url(bytes) {
+	const source = bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes;
+	const digest = await crypto.subtle.digest("SHA-256", source);
+	return base64UrlEncode(new Uint8Array(digest));
+}
+/**
+* Compare two strings without leaking, through timing, where they first differ.
+*
+* The honest caveat first: `===` on a **digest** is a weak oracle at best. To exploit the early return
+* an attacker must steer the digest byte by byte, which means finding preimages — so this is not the
+* classic "guess the MAC one byte at a time" break that constant-time comparison was invented for.
+*
+* We do it anyway, for two reasons. The threat model is not fixed: this helper is the one every future
+* comparison in the seam will reach for, and the next thing compared may well be a value an attacker
+* *can* choose freely, at which point a plain `===` becomes a real break with no diff to notice it in.
+* And the cost is a loop over 43 characters. Paying it always is cheaper than auditing, every time,
+* whether this particular comparison happened to be safe.
+*
+* The scan runs to the end of the longer string and folds the length difference into the same
+* accumulator, so neither an early match nor an early mismatch changes the work done.
+*/
+function timingSafeEqual(a, b) {
+	let difference = a.length ^ b.length;
+	const width = Math.max(a.length, b.length);
+	for (let i = 0; i < width; i++) difference |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+	return difference === 0;
+}
+//#endregion
+export { sha256Base64Url, timingSafeEqual };

package/dist/controlPlane/token/jws.d.ts

@@ -0,0 +1,52 @@
+import type { Ed25519PublicJwk } from "../data/connection";
+import { ControlPlaneClaims, ControlPlaneJwsHeader } from "./claims";
+/**
+ * Compact JWS: parse, then verify. Two functions, in that order, and the order is the security model.
+ *
+ * **No JWT library.** Core's runtime dependencies are fixed and `jose` is not among them — but the
+ * better reason is that the whole surface is one algorithm, one key type, one token shape. Ed25519
+ * over WebCrypto is a dozen lines; a general-purpose library brings the algorithm agility that causes
+ * the JWT vulnerabilities in the first place. There is nothing to negotiate here, so nothing
+ * negotiates.
+ */
+/** What {@link parseCompactJws} hands back: shape only, authenticity not yet established. */
+export interface ParsedCompactJws {
+    /** The validated protected header. `alg` is EdDSA because the schema says so, not because the token did. */
+    header: ControlPlaneJwsHeader;
+    /** The validated claims. Well-formed, entirely unproven. */
+    claims: ControlPlaneClaims;
+    /** The first two segments verbatim — the exact bytes the signature covers. */
+    signingInput: string;
+    /** The raw Ed25519 signature, 64 bytes when genuine. */
+    signature: Uint8Array;
+}
+/**
+ * Split a compact JWS, decode it, and validate both segments through their schemas.
+ *
+ * **Everything this returns is untrusted.** Parsing proves the token is well-formed; a forged token is
+ * well-formed too. No caller may read a claim, load a connection by `aud`, or act on `scope` before
+ * {@link verifyEd25519} has returned true for the `signingInput` and `signature` returned alongside
+ * them. The only exception is the `kid` lookup that finds the key to verify *with* — and that lookup
+ * grants nothing on its own.
+ *
+ * Every failure throws the one {@link ControlPlaneInvalidCredentialError}. Segment count, base64,
+ * JSON, schema — a caller cannot tell which, and so cannot use the response to find out how far a
+ * forgery got.
+ */
+export declare function parseCompactJws(token: string): ParsedCompactJws;
+/**
+ * Verify an Ed25519 signature over the signing input with a registered public key.
+ *
+ * `false` rather than a throw is the contract, and it covers WebCrypto throwing too. An unimportable
+ * key means the adopter's connection row holds something malformed — that is a denial, not a Worker
+ * crash, and it must render as the same 401 a bad signature does. Turning a bad row into a 500 would
+ * both leak that the row is bad and take the route down for everyone.
+ *
+ * **The signature is copied before it is verified**, for the reason `sha256Base64Url` copies a body
+ * (#315): `crypto.subtle.verify` takes a `BufferSource`, which excludes a view onto a
+ * `SharedArrayBuffer`, and a bare `Uint8Array` does not exclude one. Under the DOM lib that was a type
+ * error in our source that an adopter's browser program could not fix; under Workers types it was a
+ * signature verified against bytes another thread could still be writing. Sixty-four bytes.
+ */
+export declare function verifyEd25519(signingInput: string, signature: Uint8Array, jwk: Ed25519PublicJwk): Promise<boolean>;
+//# sourceMappingURL=jws.d.ts.map

package/dist/controlPlane/token/jws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jws.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/token/jws.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAErE;;;;;;;;GAQG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,MAAM,EAAE,qBAAqB,CAAC;IAC9B,4DAA4D;IAC5D,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAiB/D;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,OAAO,CAAC,CAYlB"}

package/dist/controlPlane/token/jws.js

@@ -0,0 +1,65 @@
+import { ControlPlaneClaims, ControlPlaneJwsHeader } from "./claims.js";
+import { ControlPlaneInvalidCredentialError } from "../error/errors.js";
+import { base64UrlDecode } from "./base64url.js";
+//#region src/controlPlane/token/jws.ts
+/**
+* Split a compact JWS, decode it, and validate both segments through their schemas.
+*
+* **Everything this returns is untrusted.** Parsing proves the token is well-formed; a forged token is
+* well-formed too. No caller may read a claim, load a connection by `aud`, or act on `scope` before
+* {@link verifyEd25519} has returned true for the `signingInput` and `signature` returned alongside
+* them. The only exception is the `kid` lookup that finds the key to verify *with* — and that lookup
+* grants nothing on its own.
+*
+* Every failure throws the one {@link ControlPlaneInvalidCredentialError}. Segment count, base64,
+* JSON, schema — a caller cannot tell which, and so cannot use the response to find out how far a
+* forgery got.
+*/
+function parseCompactJws(token) {
+	const segments = token.split(".");
+	const [encodedHeader, encodedClaims, encodedSignature] = segments;
+	if (segments.length !== 3 || !encodedHeader || !encodedClaims || !encodedSignature) throw new ControlPlaneInvalidCredentialError({ detail: `expected 3 non-empty compact JWS segments, got ${segments.length}` });
+	return {
+		header: decodeSegment(encodedHeader, ControlPlaneJwsHeader, "header"),
+		claims: decodeSegment(encodedClaims, ControlPlaneClaims, "claims"),
+		signingInput: `${encodedHeader}.${encodedClaims}`,
+		signature: base64UrlDecode(encodedSignature)
+	};
+}
+/** Decode one JSON segment and validate it, collapsing every failure into the one credential error. */
+function decodeSegment(segment, schema, label) {
+	let json;
+	try {
+		json = JSON.parse(new TextDecoder().decode(base64UrlDecode(segment)));
+	} catch (cause) {
+		if (cause instanceof ControlPlaneInvalidCredentialError) throw cause;
+		throw new ControlPlaneInvalidCredentialError({ detail: `token ${label} is not JSON` }, { cause });
+	}
+	const result = schema.safeParse(json);
+	if (!result.success) throw new ControlPlaneInvalidCredentialError({ detail: `token ${label} failed schema validation` });
+	return result.data;
+}
+/**
+* Verify an Ed25519 signature over the signing input with a registered public key.
+*
+* `false` rather than a throw is the contract, and it covers WebCrypto throwing too. An unimportable
+* key means the adopter's connection row holds something malformed — that is a denial, not a Worker
+* crash, and it must render as the same 401 a bad signature does. Turning a bad row into a 500 would
+* both leak that the row is bad and take the route down for everyone.
+*
+* **The signature is copied before it is verified**, for the reason `sha256Base64Url` copies a body
+* (#315): `crypto.subtle.verify` takes a `BufferSource`, which excludes a view onto a
+* `SharedArrayBuffer`, and a bare `Uint8Array` does not exclude one. Under the DOM lib that was a type
+* error in our source that an adopter's browser program could not fix; under Workers types it was a
+* signature verified against bytes another thread could still be writing. Sixty-four bytes.
+*/
+async function verifyEd25519(signingInput, signature, jwk) {
+	try {
+		const key = await crypto.subtle.importKey("jwk", jwk, { name: "Ed25519" }, false, ["verify"]);
+		return await crypto.subtle.verify("Ed25519", key, new Uint8Array(signature), new TextEncoder().encode(signingInput));
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { parseCompactJws, verifyEd25519 };