@pithy-sh/core 0.1.0

package/src/controlPlane/scope/scope.ts

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The control-plane scope model. Scopes are **per management operation, not per credential-holder**:
+ * a credential that may read purchases cannot revoke an entitlement unless separately scoped, and
+ * anything unscoped is denied.
+ *
+ * Scopes federate the way audit actions and migration namespaces do — a capability declares its own
+ * (`payments:entitlements:grant`) without touching core, so this is an open, pattern-validated string
+ * rather than a closed union. Core holds only the seam's own scopes and the matching rule.
+ */
+
+/** `resource:action`, or `resource:sub:action` — lowercase segments joined by colons. */
+const SCOPE_PATTERN = /^[a-z][a-z0-9]*(?::[a-z][a-z0-9_]*)+$/;
+
+/**
+ * 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 const ControlPlaneScope = z
+  .string()
+  .regex(
+    SCOPE_PATTERN,
+    "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.",
+  );
+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 const ANY_VERIFIED_CALLER: unique symbol = Symbol.for("pithy.controlPlane.anyVerifiedCaller");
+
+/**
+ * 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 const MANIFEST_READ_SCOPE: ControlPlaneScope = "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.
+ */
+export const KEYS_ROTATE_SCOPE: ControlPlaneScope = "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}.
+ */
+export const SEAM_SCOPES: readonly ControlPlaneScope[] = [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.
+ */
+export function scopeCovers(required: ControlPlaneRequirement, presented: string, granted: readonly string[]): boolean {
+  if (required === ANY_VERIFIED_CALLER) return true;
+  if (presented !== required) return false;
+  return granted.includes(required);
+}

package/src/controlPlane/token/base64url.ts

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ControlPlaneInvalidCredentialError } from "../error/errors";
+
+/**
+ * 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. */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  // Built one character at a time. `String.fromCharCode(...bytes)` overflows the argument stack on
+  // inputs this seam genuinely sees — a request body digest, an exported key — so the loop is the
+  // implementation, not a style choice. (Same reason as `secrets/src/crypto/envelope.ts`.)
+  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.
+ */
+export function base64UrlDecode(value: string): Uint8Array {
+  if (!BASE64URL_PATTERN.test(value)) {
+    throw new ControlPlaneInvalidCredentialError({
+      detail: "token segment is not unpadded base64url (RFC 4648 §5)",
+    });
+  }
+  // A base64 group is 2, 3 or 4 characters. One leftover character encodes no byte at all, so a
+  // length of 1 mod 4 is unrepresentable rather than merely odd — reject it before `atob` guesses.
+  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: string;
+  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;
+}

package/src/controlPlane/token/claims.ts

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ControlPlaneScope } from "../scope/scope";
+
+/**
+ * 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 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 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 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.
+ */
+export 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.",
+  );
+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 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.",
+  );
+export type ControlPlaneClaims = z.infer<typeof ControlPlaneClaims>;

package/src/controlPlane/token/digest.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { base64UrlEncode } from "./base64url";
+
+/**
+ * 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 async function sha256Base64Url(bytes: ArrayBuffer | Uint8Array): Promise<string> {
+  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.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  let difference = a.length ^ b.length;
+  const width = Math.max(a.length, b.length);
+  for (let i = 0; i < width; i++) {
+    // Past the end `charCodeAt` yields NaN; `|| 0` makes the overrun a zero rather than a branch. The
+    // length xor above is what keeps a NUL-padded string from reading as equal to a shorter one.
+    difference |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return difference === 0;
+}

package/src/controlPlane/token/jws.ts

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { Ed25519PublicJwk } from "../data/connection";
+import { ControlPlaneInvalidCredentialError } from "../error/errors";
+import { base64UrlDecode } from "./base64url";
+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 function parseCompactJws(token: string): ParsedCompactJws {
+  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"),
+    // Verbatim, never re-serialized. Ed25519 signs bytes, and `JSON.stringify` of a parsed object is
+    // not reliably the bytes that were signed — key order and whitespace are the client's, not ours.
+    signingInput: `${encodedHeader}.${encodedClaims}`,
+    signature: base64UrlDecode(encodedSignature),
+  };
+}
+
+/** Decode one JSON segment and validate it, collapsing every failure into the one credential error. */
+function decodeSegment<T>(segment: string, schema: z.ZodType<T>, label: string): T {
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(base64UrlDecode(segment)));
+  } catch (cause) {
+    // A bad segment already threw the right error from `base64UrlDecode`. Rethrow it rather than
+    // wrapping, so the detail keeps naming the step that actually failed.
+    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.
+ */
+export async function verifyEd25519(
+  signingInput: string,
+  signature: Uint8Array,
+  jwk: Ed25519PublicJwk,
+): Promise<boolean> {
+  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;
+  }
+}

package/src/controlPlane/token/mint.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Ed25519PublicJwk } from "../data/connection";
+import { base64UrlEncode } from "./base64url";
+import { ControlPlaneClaims, type ControlPlaneJwsHeader } from "./claims";
+import { sha256Base64Url } from "./digest";
+
+/**
+ * Mint a control-plane token — the management client's half of the seam.
+ *
+ * **This ships because the seam is MIT and is never gated by tier.** "You can build your own client
+ * against your own Worker" has to be true, and it is not true if the only way to produce a token the
+ * Worker accepts is to reverse-engineer the verifier. So the minting side lives here, beside the
+ * verifying side, and the two are tested against each other.
+ *
+ * It is also what the hosted dashboard would use, and what every test in this package uses to sign a
+ * real token rather than assert against a fixture.
+ *
+ * **Nothing here touches a private key store.** The caller supplies an already-imported `CryptoKey`.
+ * Core holds no key material, has no opinion about where a private key lives, and this file would be
+ * the wrong place to acquire one.
+ */
+
+/** One token's worth of claims, minus the parts {@link mintControlPlaneToken} computes. */
+export interface MintControlPlaneToken {
+  /** The signing key, imported for `Ed25519` with `["sign"]` usage. */
+  privateKey: CryptoKey;
+  /** The `kid` naming which registered public key verifies this token. */
+  keyId: string;
+  /** The management client's origin — must equal the `issuer` stored on the connection. */
+  issuer: string;
+  /** The connection this token addresses. */
+  connectionId: string;
+  /** Who, in the management client's own id space, is acting. */
+  subject: string;
+  /** The single operation this token authorizes. One call, one scope. */
+  scope: string;
+  /** The raw request body these claims are bound to. Empty for a request that carries none. */
+  body?: Uint8Array;
+  /** Seconds this token is good for. The Worker caps it, so asking for more only wastes the request. */
+  lifetimeSeconds?: number;
+  /** The clock, injected so a caller can mint a token at a chosen instant. */
+  now?: () => Date;
+  /** The token's unique id. Generated when absent; supply one only to test a replay. */
+  tokenId?: string;
+}
+
+/** Base64url a UTF-8 JSON serialization — the encoding both JWS segments use. */
+function encodeSegment(value: unknown): string {
+  return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+/**
+ * Build and sign a compact JWS the seam will accept.
+ *
+ * The body digest is computed here rather than accepted from the caller, so a client cannot mint a
+ * token whose digest disagrees with the bytes it is about to send. `bodySha256` is null exactly when
+ * the body is empty, which is the same bijection the verifier enforces.
+ */
+export async function mintControlPlaneToken(input: MintControlPlaneToken): Promise<string> {
+  const body = input.body ?? new Uint8Array(0);
+  const issuedAt = Math.floor((input.now?.() ?? new Date()).getTime() / 1000);
+
+  const header: ControlPlaneJwsHeader = { alg: "EdDSA", typ: "JWT", kid: input.keyId };
+  const claims = ControlPlaneClaims.parse({
+    iss: input.issuer,
+    aud: input.connectionId,
+    sub: input.subject,
+    scope: input.scope,
+    jti: input.tokenId ?? crypto.randomUUID(),
+    iat: issuedAt,
+    exp: issuedAt + (input.lifetimeSeconds ?? 60),
+    bodySha256: body.byteLength === 0 ? null : await sha256Base64Url(body),
+  });
+
+  const signingInput = `${encodeSegment(header)}.${encodeSegment(claims)}`;
+  const signature = await crypto.subtle.sign("Ed25519", input.privateKey, new TextEncoder().encode(signingInput));
+  return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`;
+}
+
+/**
+ * Export a generated key pair's public half as the JWK the adopter registers.
+ *
+ * `crv` and `kty` are re-asserted from our own constants rather than trusted from the export, so a
+ * runtime that spelled them differently produces a key this seam still recognizes — or fails here,
+ * where it is obvious, rather than at the first verification.
+ */
+export async function exportPublicJwk(publicKey: CryptoKey): Promise<Ed25519PublicJwk> {
+  const exported = (await crypto.subtle.exportKey("jwk", publicKey)) as { x?: string };
+  if (!exported.x) throw new TypeError("Ed25519 public key export carried no `x` coordinate.");
+  return { kty: "OKP", crv: "Ed25519", x: exported.x };
+}