@coffre/core 0.6.2 → 0.8.0

package/dist/workloads.d.ts

@@ -4,10 +4,11 @@
  * their platform signs for them (docs/design/oidc.md).
  *
  * A binding names a profile, an issuer, and claims a token must carry, each
- * a top-level string matched exactly. The event that started the run may
- * be any of several: a list. The profile sets the minimum: the server
- * refuses a binding that lacks a claim its profile requires, from the UI,
- * the CLI or the API alike. Say a service is bound to `ci.yml` of
+ * a string matched exactly, at the top of the token or nested in it
+ * (`claimAt`). The event that started the run may be any of several: a
+ * list. The profile sets the minimum: the server refuses a binding that
+ * lacks a claim its profile requires, from the UI, the CLI or the API
+ * alike. Say a service is bound to `ci.yml` of
  * `acme/api`, pushed or dispatched on `main`, or run for a pull request
  * into `main`:
  *
@@ -72,7 +73,12 @@ export declare const MAX_CLAIM_BYTES = 256;
 /** A claim a binding names: one value, or, for what started the run, any of several. */
 export type ClaimValue = string | string[];
 export type BindingClaims = Record<string, ClaimValue>;
-/** What makes a binding, checked: its profile, its issuer as a URL, and its claims, sorted. */
+/**
+ * What makes a binding, checked: its profile, its issuer, and its claims,
+ * sorted. The issuer is a URL coffre may fetch, unless the binding carries
+ * its keys (`uploaded`): then coffre fetches nothing, and it is any string,
+ * matched exactly, such as a private Kubernetes cluster's.
+ */
 export type BindingPolicy = {
   profile: WorkloadProfile;
   issuer: string;
@@ -84,9 +90,13 @@ export declare class BindingInvalid extends Error {
 }
 /** The issuer a profile means when none is given: github.com's or gitlab.com's. A GitHub Enterprise Server or a self-managed GitLab names its own. */
 export declare function defaultIssuer(profile: WorkloadProfile): string | null;
+/** The longest issuer a binding with uploaded keys names, in bytes. */
+export declare const MAX_ISSUER_BYTES = 400;
 /**
  * Check a binding against its profile, and return it as stored: the
- * issuer as given, the claims sorted by name. Throws `BindingInvalid`.
+ * issuer as given, the claims sorted by name. With `uploaded`, the binding
+ * carries its issuer's keys, and its issuer need not be a URL coffre can
+ * fetch. Throws `BindingInvalid`.
  */
 export declare function checkBinding(input: {
   profile: string;
@@ -94,13 +104,29 @@ export declare function checkBinding(input: {
   claims: Record<string, unknown>;
 }, options?: {
   allowLoopback?: boolean;
+  uploaded?: boolean;
 }): BindingPolicy;
 /** A claim's values, one or several. */
 export declare function claimValues(value: ClaimValue | undefined): string[];
+/**
+ * A claim of a token, by the name a binding gives it: a top-level claim, or
+ * one nested in objects, its path joined by dots. A key may hold dots of
+ * its own, as Kubernetes' `kubernetes.io` does, so a name is read every way
+ * its dots can split it, and names a claim only when exactly one of those
+ * readings reaches a value; none, or several, and it names nothing. In
+ *
+ *   { "sub": "system:serviceaccount:ci:deploy",
+ *     "kubernetes.io": { "namespace": "ci", "serviceaccount": { "name": "deploy", "uid": "4f1c…" } } }
+ *
+ * `kubernetes.io.serviceaccount.uid` is `4f1c…`, `kubernetes.io` an object,
+ * and `kubernetes.io.pod` nothing.
+ */
+export declare function claimAt(claims: Record<string, unknown>, name: string): unknown;
 /**
  * The claims of a verified token that differ from what a binding expects,
  * by name: none when it matches. A claim matches when the token carries its
- * value, or one of its values. On GitHub's profiles, two readings:
+ * value, or one of its values, where `claimAt` reads it. On GitHub's
+ * profiles, two readings:
  *
  * - A `pull_request` run, at `refs/pull/<n>/merge`, counts as a run at the
  *   branch it merges into: its `ref`, and the ref its `workflow_ref` ends

package/dist/workloads.js

@@ -4,10 +4,11 @@
 * their platform signs for them (docs/design/oidc.md).
 *
 * A binding names a profile, an issuer, and claims a token must carry, each
-* a top-level string matched exactly. The event that started the run may
-* be any of several: a list. The profile sets the minimum: the server
-* refuses a binding that lacks a claim its profile requires, from the UI,
-* the CLI or the API alike. Say a service is bound to `ci.yml` of
+* a string matched exactly, at the top of the token or nested in it
+* (`claimAt`). The event that started the run may be any of several: a
+* list. The profile sets the minimum: the server refuses a binding that
+* lacks a claim its profile requires, from the UI, the CLI or the API
+* alike. Say a service is bound to `ci.yml` of
 * `acme/api`, pushed or dispatched on `main`, or run for a pull request
 * into `main`:
 *
@@ -170,16 +171,21 @@ function defaultIssuer(profile) {
 	if (profile === "gitlab") return GITLAB_ISSUER;
 	return profile === "custom" ? null : GITHUB_ISSUER;
 }
+/** The longest issuer a binding with uploaded keys names, in bytes. */
+const MAX_ISSUER_BYTES = 400;
 /**
 * Check a binding against its profile, and return it as stored: the
-* issuer as given, the claims sorted by name. Throws `BindingInvalid`.
+* issuer as given, the claims sorted by name. With `uploaded`, the binding
+* carries its issuer's keys, and its issuer need not be a URL coffre can
+* fetch. Throws `BindingInvalid`.
 */
 function checkBinding(input, options = {}) {
 	const profile = input.profile;
 	if (!WORKLOAD_PROFILES.includes(profile)) throw new BindingInvalid(`unknown profile "${input.profile}": one of ${WORKLOAD_PROFILES.join(", ")}`);
 	const issuer = input.issuer ?? defaultIssuer(profile);
 	if (issuer === null) throw new BindingInvalid("a custom binding names its issuer");
-	checkFetchUrl(issuer, "the issuer", {
+	if (options.uploaded === true) checkIssuerName(issuer);
+	else checkFetchUrl(issuer, "the issuer", {
 		allowLoopback: options.allowLoopback,
 		path: true,
 		query: false
@@ -215,6 +221,17 @@ function checkBinding(input, options = {}) {
 		claims
 	};
 }
+/**
+* An issuer whose keys a binding carries: any string a token's `iss` can
+* be, matched exactly, so none with a control character or a space at
+* either end. Never github.com's or gitlab.com's, whose keys change when
+* they rotate them: coffre fetches those.
+*/
+function checkIssuerName(issuer) {
+	if (issuer === "" || /^\s|\s$/.test(issuer) || /\p{Cc}/u.test(issuer)) throw new BindingInvalid("the issuer is its tokens' iss, exactly: no control character, no space at either end");
+	if (new TextEncoder().encode(issuer).length > 400) throw new BindingInvalid(`the issuer is longer than 400 bytes`);
+	if (issuer === "https://token.actions.githubusercontent.com" || issuer === "https://gitlab.com") throw new BindingInvalid(`${issuer} publishes its keys and rotates them: coffre fetches them, so upload none`);
+}
 /** A claim's values, one or several. */
 function claimValues(value) {
 	return value === void 0 ? [] : typeof value === "string" ? [value] : value;
@@ -266,9 +283,43 @@ function checkGitLab(claims) {
 	if (claims.ref.startsWith("refs/")) throw new BindingInvalid("GitLab's ref is the branch or tag name, without refs/");
 }
 /**
+* A claim of a token, by the name a binding gives it: a top-level claim, or
+* one nested in objects, its path joined by dots. A key may hold dots of
+* its own, as Kubernetes' `kubernetes.io` does, so a name is read every way
+* its dots can split it, and names a claim only when exactly one of those
+* readings reaches a value; none, or several, and it names nothing. In
+*
+*   { "sub": "system:serviceaccount:ci:deploy",
+*     "kubernetes.io": { "namespace": "ci", "serviceaccount": { "name": "deploy", "uid": "4f1c…" } } }
+*
+* `kubernetes.io.serviceaccount.uid` is `4f1c…`, `kubernetes.io` an object,
+* and `kubernetes.io.pod` nothing.
+*/
+function claimAt(claims, name) {
+	const parts = name.split(".");
+	let found;
+	let readings = 0;
+	const walk = (at, from) => {
+		if (readings > 1) return;
+		if (from === parts.length) {
+			found = at;
+			readings++;
+			return;
+		}
+		if (typeof at !== "object" || at === null || Array.isArray(at)) return;
+		for (let to = from + 1; to <= parts.length; to++) {
+			const key = parts.slice(from, to).join(".");
+			if (Object.hasOwn(at, key)) walk(at[key], to);
+		}
+	};
+	walk(claims, 0);
+	return readings === 1 ? found : void 0;
+}
+/**
 * The claims of a verified token that differ from what a binding expects,
 * by name: none when it matches. A claim matches when the token carries its
-* value, or one of its values. On GitHub's profiles, two readings:
+* value, or one of its values, where `claimAt` reads it. On GitHub's
+* profiles, two readings:
 *
 * - A `pull_request` run, at `refs/pull/<n>/merge`, counts as a run at the
 *   branch it merges into: its `ref`, and the ref its `workflow_ref` ends
@@ -281,7 +332,7 @@ function differingClaims(profile, expected, token) {
 	const github = profile.startsWith("github");
 	const claims = github ? atBaseBranch(token) : token;
 	return Object.entries(expected).filter(([name, value]) => {
-		const actual = claims[name];
+		const actual = claimAt(claims, name);
 		if (typeof actual !== "string") return true;
 		if (github && name === "environment") return actual.toLowerCase() !== value.toLowerCase();
 		return !claimValues(value).includes(actual);
@@ -408,4 +459,4 @@ function gitlabProject(input) {
 	};
 }
 //#endregion
-export { BindingInvalid, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, canonicalClaims, checkBinding, checkFetchUrl, claimValues, defaultIssuer, differingClaims, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, workflowRef };
+export { BindingInvalid, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_ISSUER_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, canonicalClaims, checkBinding, checkFetchUrl, claimAt, claimValues, defaultIssuer, differingClaims, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, workflowRef };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/core",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
   "repository": {
@@ -52,6 +52,11 @@
       "types": "./dist/mcp.d.ts",
       "default": "./dist/mcp.js"
     },
+    "./recipe": {
+      "coffre:source": "./src/recipe.ts",
+      "types": "./dist/recipe.d.ts",
+      "default": "./dist/recipe.js"
+    },
     "./schemas": {
       "coffre:source": "./src/schemas.ts",
       "types": "./dist/schemas.d.ts",
@@ -84,7 +89,7 @@
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/conformance": "0.6.2"
+    "@coffre/conformance": "0.8.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/access.ts

@@ -282,12 +282,37 @@ export function grantKind(grant: GrantPlace): 'project' | 'environment' | null {
  *   account   developer on market/dev, then viewer on market/prod too
  *   token     developer on market/dev, issued before market/prod
  *   request   reads and writes market/dev, never market/prod
+ *
+ * A person's personal token carries one too, each grant one they held when
+ * they made it (`delegable` roles only), and is weighed the same way
+ * against what they hold now, by their instance role or their grants.
  */
 export type CredentialScope = readonly (GrantPlace & { role: Role })[];
 
 /** The most places a scope asked for names: far more than any credential needs, and a bound on what a request makes the app check. */
 export const MAX_SCOPE_PLACES = 1000;
 
+/**
+ * Whether a personal token's scope may name `role`: one that manages no
+ * access. A token acting as its person reaches their secrets and places,
+ * never who holds them, so it cannot hand anyone, itself included, more
+ * than it was given. A project's Owner who wants a token for all of it
+ * names `maintainer`.
+ */
+export function delegable(role: Role): boolean {
+  return !roleGrants(role, 'grant.manage');
+}
+
+/** The roles a personal token's scope may name, in catalogue order. */
+export const DELEGABLE_ROLES: readonly Role[] = ROLE_NAMES.filter(delegable);
+
+/**
+ * The longest a personal token lasts: a week. It is for an afternoon's
+ * script or agent, and whoever needs it longer makes another, as a person,
+ * rather than keep one around.
+ */
+export const MAX_PERSONAL_TOKEN_MINUTES = 7 * 24 * 60;
+
 /**
  * A credential's scope, by path as the API names it, in words, each role
  * with its places: `developer on market/dev, api/dev; viewer on market/prod`.
@@ -326,7 +351,13 @@ export type Holdings = {
   scope: Scope;
   /** Live grants only. */
   grants: readonly (GrantPlace & { role: Role })[];
-  /** The scope of the credential a request came in on, past which nothing reaches; absent or null for a session's. */
+  /**
+   * The scope of the credential a request came in on, past which nothing
+   * reaches; absent or null for a session's. A scope names places, so a
+   * request made with one holds nothing of the instance's own: it does not
+   * run the instance, read its whole log or make projects, whatever its
+   * holder's instance role.
+   */
   credentialScope?: CredentialScope | null;
 };
 
@@ -365,6 +396,17 @@ export function allows(holder: Holdings, permission: Permission, place: Place):
   return holdsAt(holder.grants, permission, place);
 }
 
+/**
+ * Whether the credential a request came in on, a scoped token or binding,
+ * leaves `permission` at `place` to its holder: always, for a session. A
+ * personal config's owner holds its every permission by reading its parent
+ * (docs/design/forking.md), and a token of theirs is still held to the
+ * role its scope names there: a viewer's token reads it, and writes nothing.
+ */
+export function withinCredential(holder: Holdings, permission: Permission, place: Place): boolean {
+  return holder.credentialScope == null || holdsAt(holder.credentialScope, permission, place);
+}
+
 /** Whether a grant among `grants` covers `place` with a role that holds `permission`. */
 function holdsAt(grants: readonly (GrantPlace & { role: Role })[], permission: Permission, place: Place): boolean {
   return grants.some((grant) => covers(grant, place) && roleGrants(grant.role, permission));
@@ -388,7 +430,7 @@ export function mayManageAccess(actor: Holdings, place: Place): boolean {
  * does none of these.
  */
 export function runsInstance(holder: Holdings): boolean {
-  return administers(holder.role) && unscoped(holder.scope);
+  return holder.credentialScope == null && administers(holder.role) && unscoped(holder.scope);
 }
 
 /**
@@ -408,11 +450,13 @@ export type ServiceSetting = Scope;
  * everything `role` does. A Developer on `market/dev` gives viewer or
  * developer there, never maintainer; a grant on `market` takes holding it
  * on all of `market`. `setting` is null for a service account, which sets
- * up none.
+ * up none; a request on a credential with a scope sets none up either,
+ * since what it set up would outlive it.
  */
 export function givesService(holder: Holdings, setting: ServiceSetting | null, role: Role, place: Place): boolean {
   if (mayManageAccess(holder, place)) return true;
-  return setting !== null && inScope(setting, place) && ROLES[role].permissions.every((permission) => allows(holder, permission, place));
+  return setting !== null && holder.credentialScope == null && inScope(setting, place)
+    && ROLES[role].permissions.every((permission) => allows(holder, permission, place));
 }
 
 /** Whether `holder` gives a service account anything anywhere among `places`: whether they set any up. */
@@ -475,7 +519,7 @@ export function issuesCredential(
  * Anyone else reads the places they hold `audit.read` in.
  */
 export function readsWholeLog(holder: Holdings): boolean {
-  return instanceRoleGrants(holder.role, 'audit.read') && unscoped(holder.scope);
+  return holder.credentialScope == null && instanceRoleGrants(holder.role, 'audit.read') && unscoped(holder.scope);
 }
 
 /**
@@ -486,7 +530,7 @@ export function readsWholeLog(holder: Holdings): boolean {
  */
 export function makesProjects(holder: Holdings): boolean {
   const { projects, environments } = holder.scope;
-  return administers(holder.role) && environments === 'all' && (projects === 'all' || 'except' in projects);
+  return holder.credentialScope == null && administers(holder.role) && environments === 'all' && (projects === 'all' || 'except' in projects);
 }
 
 export {

package/src/context.ts

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+
 /**
  * The binding context for a secret's ciphertext.
  *
@@ -9,11 +11,17 @@
  * These are immutable UUIDs, never names. Binding to `project/environment/key`
  * names would mean that renaming an environment or a secret key makes every
  * existing ciphertext permanently undecryptable.
+ *
+ * A personal config's values are bound to their owner too, `owner`, which
+ * only the vault's wrap of the data key carries (docs/design/forking.md,
+ * section 4): a forged owner column fails to open, rather than granting.
  */
 export type SecretContext = {
   projectId: string;
   environmentId: string;
   secretId: string;
+  /** A personal config's owner, as `ownerKey` hashes them. */
+  owner?: string;
 };
 
 /**
@@ -31,11 +39,25 @@ function assertUuid(value: string, field: string): void {
   }
 }
 
-/** Throw unless every field is a lowercase UUID. */
+/** Throw unless every field is a lowercase UUID, and an owner a lowercase SHA-256. */
 export function checkContext(ctx: SecretContext): void {
   assertUuid(ctx.projectId, 'projectId');
   assertUuid(ctx.environmentId, 'environmentId');
   assertUuid(ctx.secretId, 'secretId');
+  if (ctx.owner !== undefined && (typeof ctx.owner !== 'string' || !OWNER_RE.test(ctx.owner))) {
+    throw new Error(`context.owner must be a lowercase SHA-256, got: ${String(ctx.owner)}`);
+  }
+}
+
+const OWNER_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * A personal config's owner as its values' context binds them: the SHA-256
+ * of the member, `user:ada@acme.example`. Hashed, so it joins the AAD as
+ * unambiguously as a UUID: an email can hold the separator.
+ */
+export function ownerKey(member: string): string {
+  return createHash('sha256').update(member, 'utf8').digest('hex');
 }
 
 /**
@@ -48,7 +70,7 @@ export function checkContext(ctx: SecretContext): void {
 export function encodeAad(ctx: SecretContext): Buffer {
   checkContext(ctx);
   return Buffer.from(
-    `${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}`,
+    `${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}${ctx.owner === undefined ? '' : `|owner:${ctx.owner}`}`,
     'utf8',
   );
 }

package/src/identity/tokens.ts

@@ -1,8 +1,11 @@
 import { createHash, randomBytes } from 'node:crypto';
 
 /**
- * Bearer credentials coffre issues itself: browser sessions, CLI sessions and
- * service tokens.
+ * Bearer credentials coffre issues itself: browser sessions, CLI sessions,
+ * service tokens, personal tokens, which act as the person who made
+ * them within the scope they named, and handles, which reach nothing but
+ * the credential proxy (`@coffre/server/plugins/credential-proxy`): the
+ * stand-in a person's app holds in place of a secret's value.
  *
  * A token is a kind prefix and 32 random bytes, e.g.
  * `coffre_cli_Qm9Y...`. The prefix tells a person (or a secret scanner) what a
@@ -11,15 +14,17 @@ import { createHash, randomBytes } from 'node:crypto';
  * right tool here, unlike for passwords: 256 bits of randomness leave nothing
  * to brute-force.
  */
-export type CredentialKind = 'browser' | 'cli' | 'service';
+export type CredentialKind = 'browser' | 'cli' | 'service' | 'personal' | 'handle';
 
 const PREFIX: Record<CredentialKind, string> = {
   browser: 'coffre_web_',
   cli: 'coffre_cli_',
   service: 'coffre_svc_',
+  personal: 'coffre_pat_',
+  handle: 'coffre_use_',
 };
 
-const TOKEN = /^coffre_(web|cli|svc)_[A-Za-z0-9_-]{43}$/;
+const TOKEN = /^coffre_(web|cli|svc|pat|use)_[A-Za-z0-9_-]{43}$/;
 
 export function generateToken(kind: CredentialKind): string {
   return PREFIX[kind] + randomBytes(32).toString('base64url');

package/src/identity/workload-token.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 
-import { createLocalJWKSet, errors, jwtVerify, type JSONWebKeySet, type JWTPayload } from 'jose';
+import { createLocalJWKSet, errors, importJWK, jwtVerify, type JSONWebKeySet, type JWK, type JWTPayload } from 'jose';
 
 export type { JSONWebKeySet };
 
@@ -30,6 +30,8 @@ export type WorkloadRefusal =
   | 'expired'
   /** Its `iat` is more than an hour ago, or not yet. */
   | 'too_old'
+  /** It lives longer than an hour, `exp` − `iat`, where its binding carries its keys. */
+  | 'too_long'
   /** Its `nbf` is still to come. */
   | 'not_yet_valid'
   /** Its audience is not this instance alone. */
@@ -96,28 +98,34 @@ export function decodeWorkloadToken(token: string): DecodedToken {
  * algorithms fixed and nothing taken from the header but `alg` and `kid`;
  * the issuer exactly; `exp`, `nbf` and `iat` within the tolerance, `iat` at
  * most an hour old; and the audience, this instance's public URL alone.
- * Returns the verified claims.
+ * With `maxLifetime`, in seconds, a token whose `exp` is further than that
+ * from its `iat` is refused too. Returns the verified claims.
  */
 export async function verifyWorkloadToken(
   token: string,
   keys: JSONWebKeySet,
-  expected: { issuer: string; audience: string; now: Date },
+  expected: { issuer: string; audience: string; now: Date; maxLifetime?: number },
 ): Promise<JWTPayload & DecodedToken['claims']> {
+  const options = {
+    algorithms: [...WORKLOAD_ALGORITHMS],
+    issuer: expected.issuer,
+    // For exp and nbf; iat's bounds are issuedRefusal's, since jose would stretch the hour by the tolerance too.
+    clockTolerance: CLOCK_TOLERANCE_SECONDS,
+    requiredClaims: ['iss', 'sub', 'exp', 'iat'],
+    currentDate: expected.now,
+  };
   let payload: JWTPayload;
   try {
-    ({ payload } = await jwtVerify(token, createLocalJWKSet(keys), {
-      algorithms: [...WORKLOAD_ALGORITHMS],
-      issuer: expected.issuer,
-      // For exp and nbf; iat's bounds are issuedRefusal's, since jose would stretch the hour by the tolerance too.
-      clockTolerance: CLOCK_TOLERANCE_SECONDS,
-      requiredClaims: ['iss', 'sub', 'exp', 'iat'],
-      currentDate: expected.now,
-    }));
+    ({ payload } = await jwtVerify(token, createLocalJWKSet(keys), options));
   } catch (error) {
-    throw refusalOf(error);
+    if (!(error instanceof errors.JWKSMultipleMatchingKeys)) throw refusalOf(error);
+    payload = await anyKey(token, error, options);
   }
   const issued = issuedRefusal(payload.iat!, expected.now.getTime() / 1000);
   if (issued !== null) throw issued;
+  if (expected.maxLifetime !== undefined && payload.exp! - payload.iat! > expected.maxLifetime) {
+    throw new WorkloadTokenRefused('too_long', `the token lives longer than ${expected.maxLifetime / 60} minutes, from its iat to its exp: ask for a shorter one`);
+  }
   const { aud } = payload;
   if (!(aud === expected.audience || (Array.isArray(aud) && aud.length === 1 && aud[0] === expected.audience))) {
     throw new WorkloadTokenRefused('audience', `the token is for ${JSON.stringify(aud ?? null)}, not ${expected.audience} alone`);
@@ -139,6 +147,22 @@ export function issuedRefusal(iat: number, now: number): WorkloadTokenRefused |
   return null;
 }
 
+/**
+ * A token that names no key, or one several keys share, verified by
+ * whichever of them signed it: a set may hold several, as while its issuer
+ * rotates. At most `MAX_KEYS` tries, each a signature check alone.
+ */
+async function anyKey(token: string, matching: errors.JWKSMultipleMatchingKeys, options: Parameters<typeof jwtVerify>[2]): Promise<JWTPayload> {
+  for await (const key of matching) {
+    try {
+      return (await jwtVerify(token, key, options)).payload;
+    } catch (error) {
+      if (!(error instanceof errors.JWSSignatureVerificationFailed)) throw refusalOf(error);
+    }
+  }
+  throw new WorkloadTokenRefused('signature', "the token's signature does not verify");
+}
+
 function refusalOf(error: unknown): WorkloadTokenRefused {
   if (error instanceof errors.JWKSNoMatchingKey) return new WorkloadTokenRefused('unknown_key', "the token's key is not among the issuer's");
   if (error instanceof errors.JWTExpired) {
@@ -161,3 +185,124 @@ function refusalOf(error: unknown): WorkloadTokenRefused {
   if (error instanceof errors.JOSEError) return new WorkloadTokenRefused('signature', `the token does not verify: ${error.code}`);
   return new WorkloadTokenRefused('signature', 'the token does not verify');
 }
+
+/** At most this many keys in a set, fetched or uploaded. */
+export const MAX_KEYS = 32;
+
+/** One key of an uploaded set, as an owner sees it: its `kid`, its algorithm, and its RFC 7638 thumbprint. */
+export type KeySummary = { kid: string | null; alg: (typeof WORKLOAD_ALGORITHMS)[number]; thumbprint: string };
+
+/**
+ * A key set uploaded with a binding, as the binding keeps it: its public
+ * keys alone, as canonical JSON, and that JSON's SHA-256, in hex, which
+ * stands in the binding where a URL would and so is under its MAC.
+ */
+export type UploadedKeys = { jwks: string; digest: string; keys: KeySummary[] };
+
+/** A key set that cannot be uploaded, said so an owner can fix it. */
+export class KeysInvalid extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KeysInvalid';
+  }
+}
+
+/** Members that only a private or a symmetric key has. */
+const PRIVATE_MEMBERS = ['d', 'p', 'q', 'dp', 'dq', 'qi', 'oth', 'k'];
+
+/**
+ * An issuer's public keys, as uploaded for a binding: a JWKS, `{ "keys": [
+ * … ] }`, of RSA keys of 2048 bits or more, for RS256, and P-256 keys, for
+ * ES256, each kept with only the members that verify (`kty`, `kid`, `use`,
+ * `alg` and the key), in the order of their thumbprints, so that one set
+ * however listed has one digest. An RSA key's parameters are checked
+ * before jose sees them, since it takes some that verify anything: an
+ * exponent of 1 makes every signature its message. Keys for encryption are
+ * left out, as from a fetched set; a private or a symmetric key refuses the
+ * whole set, since coffre keeps no secret of an issuer's. Throws
+ * `KeysInvalid`.
+ */
+export async function uploadedKeys(value: unknown): Promise<UploadedKeys> {
+  const listed = (value as { keys?: unknown } | null)?.keys;
+  if (typeof value !== 'object' || value === null || !Array.isArray(listed)) throw new KeysInvalid('the keys are a JWKS: { "keys": [ … ] }');
+  if (listed.length > MAX_KEYS) throw new KeysInvalid(`a key set holds at most ${MAX_KEYS} keys`);
+  const keys: JWK[] = [];
+  for (const [i, given] of listed.entries()) {
+    if (typeof given !== 'object' || given === null || Array.isArray(given)) throw new KeysInvalid(`key ${i + 1} is not a JWK`);
+    const jwk = given as Record<string, unknown>;
+    const named = typeof jwk.kid === 'string' ? `key ${jwk.kid}` : `key ${i + 1}`;
+    if (PRIVATE_MEMBERS.some((member) => member in jwk)) {
+      throw new KeysInvalid(`${named} is a private or a secret key: upload the issuer's public keys only`);
+    }
+    if (jwk.use === 'enc') continue;
+    if (jwk.use !== undefined && jwk.use !== 'sig') throw new KeysInvalid(`${named} has use ${JSON.stringify(jwk.use)}: sig, or none`);
+    if (jwk.kid !== undefined && (typeof jwk.kid !== 'string' || jwk.kid === '' || jwk.kid.length > 256)) throw new KeysInvalid(`key ${i + 1}'s kid is not a string`);
+    if (jwk.kid !== undefined && keys.some((key) => key.kid === jwk.kid)) throw new KeysInvalid(`two keys are ${named}`);
+    let alg: KeySummary['alg'];
+    let key: JWK;
+    if (jwk.kty === 'RSA' && (jwk.alg === undefined || jwk.alg === 'RS256')) {
+      alg = 'RS256';
+      const [n, e] = [integer(jwk.n), integer(jwk.e)];
+      if (n === null || e === null) throw new KeysInvalid(`${named} is an RSA key without n and e, each a base64url integer in its fewest bytes`);
+      // The modulus's bits counted from its highest set bit, as jose counts them when it verifies.
+      if (n.toString(2).length < 2048) throw new KeysInvalid(`${named} is an RSA key under 2048 bits`);
+      if (n % 2n === 0n) throw new KeysInvalid(`${named} is not a valid RSA key`);
+      // As NIST SP 800-56B has it: odd, above 2^16, below 2^256.
+      if (e % 2n === 0n || e <= 65536n || e >= 2n ** 256n) throw new KeysInvalid(`${named}'s exponent is not one an RSA key signs with: odd, from 65537`);
+      key = { kty: 'RSA', ...kidAndUse(jwk), alg, n: jwk.n as string, e: jwk.e as string };
+    } else if (jwk.kty === 'EC' && jwk.crv === 'P-256' && (jwk.alg === undefined || jwk.alg === 'ES256')) {
+      alg = 'ES256';
+      if (!coordinate(jwk.x) || !coordinate(jwk.y)) throw new KeysInvalid(`${named} is an EC key without x and y, each 32 bytes in base64url`);
+      key = { kty: 'EC', ...kidAndUse(jwk), alg, crv: 'P-256', x: jwk.x, y: jwk.y };
+    } else {
+      throw new KeysInvalid(`${named} is not an RSA key for RS256 or a P-256 key for ES256, the two coffre accepts`);
+    }
+    try {
+      await importJWK(key, alg);
+    } catch {
+      throw new KeysInvalid(`${named} is not a valid ${key.kty} key`);
+    }
+    keys.push(key);
+  }
+  if (keys.length === 0) throw new KeysInvalid('the key set holds no key that signs');
+  // By thumbprint, then whole: two kids may name the same key.
+  const sorted = keys.map((key) => [`${thumbprint(key)} ${JSON.stringify(key)}`, key] as const).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const jwks = JSON.stringify({ keys: sorted.map(([, key]) => key) });
+  return { jwks, digest: createHash('sha256').update(jwks, 'utf8').digest('hex'), keys: keySummaries(jwks) };
+}
+
+/** The keys of a set `uploadedKeys` kept, as an owner sees them. */
+export function keySummaries(jwks: string): KeySummary[] {
+  return (JSON.parse(jwks) as JSONWebKeySet).keys.map((key) => ({
+    kid: key.kid ?? null,
+    alg: key.kty === 'RSA' ? 'RS256' : 'ES256',
+    thumbprint: thumbprint(key),
+  }));
+}
+
+/** A key's RFC 7638 thumbprint: the SHA-256 of its required members alone, in lexicographic order. */
+function thumbprint(key: JWK): string {
+  const required = key.kty === 'RSA' ? { e: key.e, kty: key.kty, n: key.n } : { crv: key.crv, kty: key.kty, x: key.x, y: key.y };
+  return createHash('sha256').update(JSON.stringify(required), 'utf8').digest('base64url');
+}
+
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+
+/** A P-256 coordinate as JWK writes one: 32 bytes, in base64url exactly, so that one key has one spelling. */
+function coordinate(value: unknown): value is string {
+  if (typeof value !== 'string' || !BASE64URL.test(value)) return false;
+  const bytes = Buffer.from(value, 'base64url');
+  return bytes.length === 32 && bytes.toString('base64url') === value;
+}
+
+/** An unsigned integer as JWK writes one, base64url in its fewest bytes; null for anything else. */
+function integer(value: unknown): bigint | null {
+  if (typeof value !== 'string' || !BASE64URL.test(value)) return null;
+  const bytes = Buffer.from(value, 'base64url');
+  if (bytes.length === 0 || bytes[0] === 0 || bytes.toString('base64url') !== value) return null;
+  return BigInt(`0x${bytes.toString('hex')}`);
+}
+
+function kidAndUse(jwk: Record<string, unknown>): Pick<JWK, 'kid' | 'use'> {
+  return { ...(jwk.kid === undefined ? {} : { kid: jwk.kid as string }), ...(jwk.use === undefined ? {} : { use: 'sig' }) };
+}