@coffre/core 0.4.6 → 0.5.0

package/dist/workloads.js

@@ -4,15 +4,18 @@
 * 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 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 `deploy.yml`,
-* pushed to `main` of `acme/api`:
+* 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
+* `acme/api`, pushed or dispatched on `main`, or run for a pull request
+* into `main`:
 *
 *   { profile: 'github', issuer: 'https://token.actions.githubusercontent.com',
 *     claims: { repository_owner_id: '9919', repository_id: '41532',
-*               workflow_ref: 'acme/api/.github/workflows/deploy.yml@refs/heads/main',
-*               ref: 'refs/heads/main', event_name: 'push' } }
+*               workflow_ref: 'acme/api/.github/workflows/ci.yml@refs/heads/main',
+*               ref: 'refs/heads/main',
+*               event_name: ['pull_request', 'push', 'workflow_dispatch'] } }
 */
 const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
 const GITLAB_ISSUER = "https://gitlab.com";
@@ -57,23 +60,62 @@ const REQUIRED_CLAIMS = {
 	custom: ["sub"]
 };
 /**
-* Events triggered by someone with write access, at a ref the binding names
-* exactly. `pull_request`, `pull_request_target`, `workflow_run` and the
-* rest are refused, even when their ref happens to match: their runs can
-* carry a stranger's code.
+* The events a GitHub binding may trust. The first four are started by
+* someone with write access, at the ref the binding names. The last two
+* can run code nobody reviewed, so the owner opts in to each:
+*
+* - `pull_request` runs the pull request's own code and workflow file, at
+*   `refs/pull/<n>/merge`; a binding matches it by the branch it merges
+*   into. Forks get no ID token, unless the repository sends write tokens
+*   to their pull requests (a setting of private repositories), so this
+*   trusts whoever can push a branch to the repository.
+* - `workflow_run` runs the default branch's workflow, but a fork's pull
+*   request can start it: the run is as safe as what it does with the
+*   code and artifacts of the run that started it.
+*
+* `pull_request_target` and the rest are refused, even when their ref
+* happens to match: they exist to act on anyone's pull request, with the
+* base repository's tokens.
 */
 const GITHUB_EVENTS = [
 	"push",
 	"workflow_dispatch",
 	"schedule",
-	"release"
+	"release",
+	"pull_request",
+	"workflow_run"
 ];
+/**
+* What trusting each of the last two events exposes, as the UI, the CLI and
+* the approval page say it when one is chosen.
+*/
+const EVENT_EXPOSURE = {
+	pull_request: "Anyone who can push a branch to the repository can open a pull request and run their own code as this service account, unreviewed. Pull requests from forks get no ID token, unless the repository sends them write tokens.",
+	workflow_run: "A fork's pull request can start workflow_run. The workflow comes from the default branch, so this is safe unless it runs code or artifacts from the run that started it."
+};
 /** Pipelines that run the project's own code, at its own ref: never a merge request's. */
 const GITLAB_PIPELINE_SOURCES = [
 	"push",
 	"web",
 	"schedule"
 ];
+/** The claim that says what started the run, which a binding may name several values of, and why the others are refused. */
+const GITHUB_EVENT = {
+	name: "event_name",
+	values: GITHUB_EVENTS,
+	why: "other events can run a stranger's code"
+};
+const EVENT_CLAIM = {
+	github: GITHUB_EVENT,
+	"github-reusable": GITHUB_EVENT,
+	"github-reusable-organization": GITHUB_EVENT,
+	gitlab: {
+		name: "pipeline_source",
+		values: GITLAB_PIPELINE_SOURCES,
+		why: "merge-request pipelines name another project"
+	},
+	custom: null
+};
 /** At most this many live bindings per service, and claims per binding. */
 const MAX_BINDINGS = 16;
 const MAX_CLAIMS = 16;
@@ -133,11 +175,19 @@ function checkBinding(input, options = {}) {
 	if (forced !== null && !forced.includes(profile)) throw new BindingInvalid(`${issuer} signs only for the ${forced[0]} profile${forced.length > 1 ? "s" : ""}`);
 	const entries = Object.entries(input.claims);
 	if (entries.length > 16) throw new BindingInvalid(`a binding names at most 16 claims`);
+	const event = EVENT_CLAIM[profile];
 	const claims = {};
 	for (const [name, value] of entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
 		if (!CLAIM_NAME.test(name)) throw new BindingInvalid(`"${name}" is not a claim name a binding can match`);
 		if (RESERVED.has(name)) throw new BindingInvalid(`a binding never names "${name}": the exchange checks it`);
-		if (typeof value !== "string" || value.length === 0) throw new BindingInvalid(`claim ${name} must be a nonempty string`);
+		if (name === event?.name) {
+			const given = Array.isArray(value) ? value : [value];
+			if (given.length === 0 || given.some((each) => !event.values.includes(each))) throw new BindingInvalid(`${name} must be one or more of ${event.values.join(", ")}: ${event.why}`);
+			const values = event.values.filter((each) => given.includes(each));
+			claims[name] = values.length === 1 ? values[0] : values;
+			continue;
+		}
+		if (typeof value !== "string" || value.length === 0) throw new BindingInvalid(`claim ${name} must be a nonempty string${Array.isArray(value) && event !== null ? `: only ${event.name} lists several` : ""}`);
 		if (new TextEncoder().encode(value).length > 256) throw new BindingInvalid(`claim ${name} is longer than 256 bytes`);
 		claims[name] = value;
 	}
@@ -152,27 +202,80 @@ function checkBinding(input, options = {}) {
 		claims
 	};
 }
+/** A claim's values, one or several. */
+function claimValues(value) {
+	return value === void 0 ? [] : typeof value === "string" ? [value] : value;
+}
+/** What a ref must be for each event: the branch or tag it runs at, or for a pull request, the branch it merges into. */
+const EVENT_REFS = {
+	release: {
+		prefix: "refs/tags/",
+		why: "a release runs at its tag: refs/tags/<tag>"
+	},
+	schedule: {
+		prefix: "refs/heads/",
+		why: "a schedule runs on the default branch: refs/heads/<branch>"
+	},
+	workflow_run: {
+		prefix: "refs/heads/",
+		why: "a workflow_run runs on the default branch: refs/heads/<branch>"
+	},
+	pull_request: {
+		prefix: "refs/heads/",
+		why: "a pull request matches by the branch it merges into: refs/heads/<branch>"
+	}
+};
 function checkGitHub(profile, claims) {
-	for (const id of ["repository_owner_id", "repository_id"]) if (claims[id] !== void 0 && !DIGITS.test(claims[id])) throw new BindingInvalid(`${id} is GitHub's numeric ID, not a name`);
-	const event = claims.event_name;
-	if (!GITHUB_EVENTS.includes(event)) throw new BindingInvalid(`event_name must be one of ${GITHUB_EVENTS.join(", ")}: other events can run a stranger's code`);
+	for (const id of ["repository_owner_id", "repository_id"]) {
+		const value = claims[id];
+		if (value !== void 0 && !DIGITS.test(value)) throw new BindingInvalid(`${id} is GitHub's numeric ID, not a name`);
+	}
+	const events = claimValues(claims.event_name);
 	const ref = claims.ref;
 	if (!REF.test(ref)) throw new BindingInvalid("ref is a full ref: refs/heads/<branch> or refs/tags/<tag>");
-	if (event === "release" && !ref.startsWith("refs/tags/")) throw new BindingInvalid("a release runs at its tag: refs/tags/<tag>");
-	if (event === "schedule" && !ref.startsWith("refs/heads/")) throw new BindingInvalid("a schedule runs on the default branch: refs/heads/<branch>");
+	for (const event of events) {
+		const rule = EVENT_REFS[event];
+		if (rule !== void 0 && !ref.startsWith(rule.prefix)) throw new BindingInvalid(rule.why);
+	}
+	const workflow = claims.workflow_ref;
 	if (profile === "github") {
-		if (!WORKFLOW.test(claims.workflow_ref) || !claims.workflow_ref.endsWith(`@${ref}`)) throw new BindingInvalid("workflow_ref is <owner>/<repository>/.github/workflows/<file>@<ref>, at the binding's ref");
+		if (!WORKFLOW.test(workflow) || !workflow.endsWith(`@${ref}`)) throw new BindingInvalid("workflow_ref is <owner>/<repository>/.github/workflows/<file>@<ref>, at the binding's ref");
 		return;
 	}
 	if (!WORKFLOW.test(claims.job_workflow_ref)) throw new BindingInvalid("job_workflow_ref is <owner>/<repository>/.github/workflows/<file>@<ref>");
 	if (!SHA.test(claims.job_workflow_sha)) throw new BindingInvalid("job_workflow_sha is the called workflow's full commit SHA");
-	if (claims.workflow_ref !== void 0 && !WORKFLOW.test(claims.workflow_ref)) throw new BindingInvalid("workflow_ref, which narrows the binding to one caller, is <owner>/<repository>/.github/workflows/<file>@<ref>");
+	if (workflow !== void 0 && !WORKFLOW.test(workflow)) throw new BindingInvalid("workflow_ref, which narrows the binding to one caller, is <owner>/<repository>/.github/workflows/<file>@<ref>");
 }
 function checkGitLab(claims) {
 	for (const id of ["namespace_id", "project_id"]) if (!DIGITS.test(claims[id])) throw new BindingInvalid(`${id} is GitLab's numeric ID, not a path`);
 	if (claims.ref_type !== "branch" && claims.ref_type !== "tag") throw new BindingInvalid("ref_type is branch or tag");
 	if (claims.ref.startsWith("refs/")) throw new BindingInvalid("GitLab's ref is the branch or tag name, without refs/");
-	if (!GITLAB_PIPELINE_SOURCES.includes(claims.pipeline_source)) throw new BindingInvalid(`pipeline_source must be one of ${GITLAB_PIPELINE_SOURCES.join(", ")}: merge-request pipelines name another project`);
+}
+/**
+* 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. A GitHub `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 in, are read as
+* `refs/heads/<base_ref>`.
+*/
+function differingClaims(profile, expected, token) {
+	const claims = profile.startsWith("github") ? atBaseBranch(token) : token;
+	return Object.entries(expected).filter(([name, value]) => {
+		const actual = claims[name];
+		return typeof actual !== "string" || !claimValues(value).includes(actual);
+	}).map(([name]) => name);
+}
+function atBaseBranch(claims) {
+	const { event_name: event, ref, base_ref: base, workflow_ref: workflow } = claims;
+	if (event !== "pull_request" || typeof ref !== "string" || typeof base !== "string" || base === "") return claims;
+	const at = `refs/heads/${base}`;
+	const file = typeof workflow === "string" && workflow.endsWith(`@${ref}`) ? `${workflow.slice(0, -ref.length)}${at}` : workflow;
+	return {
+		...claims,
+		ref: at,
+		workflow_ref: file
+	};
 }
 /** The claims as the MAC and the database hold them: JSON, sorted by name. */
 function canonicalClaims(claims) {
@@ -210,11 +313,23 @@ function checkFetchUrl(value, what, options) {
 function fullRef(kind, name) {
 	return `refs/${kind === "branch" ? "heads" : "tags"}/${name}`;
 }
+/** The GitHub events a binding at a branch, or at a tag, may name. */
+function githubEventsAt(kind) {
+	return GITHUB_EVENTS.filter((event) => EVENT_REFS[event] === void 0 || EVENT_REFS[event].prefix === fullRef(kind, ""));
+}
 /** A workflow file at a ref, as GitHub's tokens name it: `acme/api/.github/workflows/deploy.yml@refs/heads/main`. */
 function workflowRef(repository, file, ref) {
 	return `${repository}/.github/workflows/${file.replace(/^\.github\/workflows\//, "")}@${ref}`;
 }
-/** A workflow of the repository, run by `event` at `ref`. */
+function started(input, one, many) {
+	const single = input[one];
+	const list = input[many];
+	if (single !== void 0 && list !== void 0) throw new BindingInvalid(`name ${one} or ${many}, not both`);
+	if (single !== void 0) return single;
+	if (list === void 0) throw new BindingInvalid(`name ${one} or ${many}`);
+	return list;
+}
+/** A workflow of the repository, run at `ref` by any of `events`; a pull request, by the branch it merges into. */
 function githubWorkflow(input) {
 	return {
 		profile: "github",
@@ -223,7 +338,7 @@ function githubWorkflow(input) {
 			repository_id: input.repositoryId,
 			workflow_ref: workflowRef(input.repository, input.workflow, input.ref),
 			ref: input.ref,
-			event_name: input.event
+			event_name: started(input, "event", "events")
 		}
 	};
 }
@@ -237,7 +352,7 @@ function githubReusable(input) {
 		repository_owner_id: input.ownerId,
 		...input.repositoryId === null ? {} : { repository_id: input.repositoryId },
 		ref: input.ref,
-		event_name: input.event,
+		event_name: started(input, "event", "events"),
 		job_workflow_ref: input.called,
 		job_workflow_sha: input.sha
 	};
@@ -247,7 +362,7 @@ function githubReusable(input) {
 		claims
 	};
 }
-/** A GitLab project's pipelines from `source`, at a branch or tag. */
+/** A GitLab project's pipelines from any of `sources`, at a branch or tag. */
 function gitlabProject(input) {
 	return {
 		profile: "gitlab",
@@ -256,9 +371,9 @@ function gitlabProject(input) {
 			project_id: input.projectId,
 			ref_type: input.refType,
 			ref: input.ref,
-			pipeline_source: input.source
+			pipeline_source: started(input, "source", "sources")
 		}
 	};
 }
 //#endregion
-export { BindingInvalid, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, canonicalClaims, checkBinding, checkFetchUrl, defaultIssuer, fullRef, githubReusable, githubWorkflow, gitlabProject, workflowRef };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/core",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
   "repository": {
@@ -84,7 +84,7 @@
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/conformance": "0.4.6"
+    "@coffre/conformance": "0.5.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/access-conversion.ts

@@ -0,0 +1,202 @@
+import {
+  admits,
+  allows,
+  assignableToEnvironment,
+  EVERYWHERE,
+  INSTANCE_ROLES,
+  instanceRoleGrants,
+  normalScope,
+  roleGrants,
+  ROLES,
+  type GrantPlace,
+  type InstanceRole,
+  type Place,
+  type Role,
+  type Scope,
+} from './access.ts';
+
+/**
+ * How the vault replaces the grants on every project of 0.4 (`*`, and `*`
+ * on one environment slug) with what 0.5 has instead: a person's instance
+ * role and its scope, and project grants. Pure, so the vault converts with
+ * it and anyone can read what it does to each case.
+ *
+ * Nobody ends up holding more than before, anywhere, at any time. Where the
+ * new model cannot say exactly what a grant said, it says less:
+ *
+ *   developer on *            Developer, everywhere
+ *   developer on dev in each  Developer, environments only dev
+ *   auditor on *              Auditor, everywhere
+ *   viewer on *               viewer on each project there is now
+ *   maintainer on *           Developer, everywhere, and maintainer on each project there is now
+ *   owner on *, as an owner   Owner (an owner of 0.4 is an Admin)
+ *   any, for a service        the same role on each project, or each environment of the slug, there is now
+ *
+ * What a grant leaves to project grants reaches the projects there are
+ * now, not those made later (`narrowed`, `later-projects`). A place holds
+ * one grant: where they hold one already that neither it nor the new one
+ * holds all of, for as long, a project's goes on to each of its
+ * environments instead, the one that does not read the log first
+ * (`environments`: not environments made later, nor, for an auditor, the
+ * project's own entries). Only where neither can, or on an environment, is
+ * something lost, the one that reads kept (`lost`):
+ *
+ *   viewer on *, auditor on billing      auditor on billing, viewer on each of billing's environments
+ *   viewer on *, developer on billing    developer on billing
+ *   maintainer on *, access-manager on billing, as a service
+ *                                        maintainer on billing: access-manager there is lost
+ */
+
+/** A grant on every project of 0.4: on all of each (`environmentSlug` null), or on the environment of one slug in each. */
+export type EveryProjectGrant = { environmentSlug: string | null; role: Role; expiresAt: number | null };
+
+export type ConversionInput = {
+  /** A person may hold an instance role; a service account holds grants only. */
+  person: boolean;
+  /** Their instance role before: `admin` for an owner of 0.4, `member` for anyone else. */
+  role: InstanceRole;
+  /** Their live grants on every project. */
+  everyProject: readonly EveryProjectGrant[];
+  /** Their live grants on projects and environments. */
+  grants: readonly (GrantPlace & { role: Role; expiresAt: number | null })[];
+  /** The projects there are now, deleted ones left out, with their environments. */
+  projects: readonly { id: string; environments: readonly { id: string; slug: string }[] }[];
+};
+
+/** A project grant the conversion gives: new, or in place of the one they held there (`replaces`). */
+export type ConvertedGrant = { projectId: string; environmentId: string | null; role: Role; expiresAt: number | null; replaces: Role | null };
+
+/** Where the conversion gives less than a grant on every project did, each naming the grant it comes of. */
+export type Narrowed =
+  /** It reaches the projects there are now as project grants, and none made later. */
+  | { kind: 'later-projects'; grant: EveryProjectGrant }
+  /**
+   * `role` on this project, the grant's or the one they held there, is on
+   * each of its environments instead: not on environments made later, nor
+   * on the project's own log entries.
+   */
+  | { kind: 'environments'; grant: EveryProjectGrant; projectId: string; role: Role }
+  /** No grant here holds both: `kept` stays (until `keptUntil`), and what `lost` held beyond it is gone. */
+  | { kind: 'lost'; grant: EveryProjectGrant; projectId: string; environmentId: string | null; lost: Role; kept: Role; keptUntil: number | null };
+
+export type Conversion = { role: InstanceRole; scope: Scope; grants: ConvertedGrant[]; narrowed: Narrowed[] };
+
+type Held = GrantPlace & { role: Role; expiresAt: number | null };
+type Wanted = { role: Role; expiresAt: number | null };
+type At = { project: ConversionInput['projects'][number]; environment: { id: string; slug: string } | null };
+
+export function convertEveryProjectGrants(input: ConversionInput): Conversion {
+  const { role, scope } = input.person ? instanceRoleFor(input.role, input.everyProject) : { role: input.role, scope: EVERYWHERE };
+  const before = new Map(input.grants.map((grant) => [placeKey(grant), grant]));
+  const held = new Map<string, Held>(before);
+  const given = new Map<string, ConvertedGrant>();
+  const narrowed: Narrowed[] = [];
+
+  const give = (at: At, wanted: Wanted) => {
+    const place = { projectId: at.project.id, environmentId: at.environment?.id ?? null, role: wanted.role, expiresAt: wanted.expiresAt };
+    held.set(placeKey(place), place);
+    given.set(placeKey(place), { ...place, replaces: before.get(placeKey(place))?.role ?? null });
+  };
+  // What `grant` held at `at`, as `wanted`, added to what they hold there already.
+  const settle = (grant: EveryProjectGrant, at: At, wanted: Wanted) => {
+    const place: Place = at.environment === null
+      ? { projectId: at.project.id }
+      : { projectId: at.project.id, environmentId: at.environment.id, environmentSlug: at.environment.slug };
+    if (holdsAlready(role, scope, [...held.values()], wanted, place)) return;
+    const existing = held.get(at.environment?.id ?? at.project.id);
+    if (existing === undefined || (within(existing.role, wanted.role) && outlasts(wanted.expiresAt, existing.expiresAt))) {
+      give(at, wanted);
+      return;
+    }
+    // One place, one grant, and neither holds the other for as long: on a
+    // project, one of them goes on to its environments, as far as it reached
+    // but for environments made later; the one that reads no log first, as
+    // an environment's grant reads none of its project's entries.
+    if (at.environment === null) {
+      const down = [wanted, existing]
+        .filter((candidate) => assignableToEnvironment(candidate.role))
+        .sort((a, b) => Number(roleGrants(a.role, 'audit.read')) - Number(roleGrants(b.role, 'audit.read')))[0];
+      if (down !== undefined) {
+        if (down === existing) give(at, wanted);
+        narrowed.push({ kind: 'environments', grant, projectId: at.project.id, role: down.role });
+        for (const environment of at.project.environments) settle(grant, { project: at.project, environment }, { role: down.role, expiresAt: down.expiresAt });
+        return;
+      }
+    }
+    // Nothing holds both: the one that reads stays, else the one they had.
+    const keep = !roleGrants(wanted.role, 'secret.read') || roleGrants(existing.role, 'secret.read') ? existing : wanted;
+    const lose = keep === existing ? wanted : existing;
+    if (keep === wanted) give(at, wanted);
+    narrowed.push({ kind: 'lost', grant, projectId: at.project.id, environmentId: at.environment?.id ?? null, lost: lose.role, kept: keep.role, keptUntil: keep.expiresAt });
+  };
+
+  for (const grant of input.everyProject) {
+    if (byRole(role, scope, grant)) continue;
+    narrowed.push({ kind: 'later-projects', grant });
+    for (const project of input.projects) {
+      const reached = grant.environmentSlug === null
+        ? [null]
+        : project.environments.filter((environment) => environment.slug === grant.environmentSlug);
+      for (const environment of reached) settle(grant, { project, environment }, grant);
+    }
+  }
+  return { role, scope, grants: [...given.values()], narrowed };
+}
+
+/**
+ * The strongest instance role a person's lasting grants on every project
+ * add up to, never more than they held: an owner of 0.4 (an Admin) who
+ * read, wrote and retired secrets everywhere is an Owner; anyone else is a
+ * Developer or an Auditor where those grants were on all of every project,
+ * or on some environment slugs (Developer first), or stays as they were.
+ */
+function instanceRoleFor(previous: InstanceRole, everyProject: readonly EveryProjectGrant[]): { role: InstanceRole; scope: Scope } {
+  const lasting = everyProject.filter((grant) => grant.expiresAt === null);
+  const all = lasting.find((grant) => grant.environmentSlug === null)?.role;
+  if (previous === 'admin') {
+    const adds = all === undefined ? [] : ROLES[all].permissions;
+    const owner = INSTANCE_ROLES.owner.permissions.every((permission) => instanceRoleGrants('admin', permission) || (adds as readonly string[]).includes(permission));
+    return { role: owner ? 'owner' : 'admin', scope: EVERYWHERE };
+  }
+  if (previous !== 'member') return { role: previous, scope: EVERYWHERE };
+  const fits = (role: InstanceRole, held: Role) => INSTANCE_ROLES[role].permissions.every((permission) => roleGrants(held, permission));
+  const candidates = ['developer', 'auditor'] as const;
+  for (const role of candidates) if (all !== undefined && fits(role, all)) return { role, scope: EVERYWHERE };
+  for (const role of candidates) {
+    const only = lasting.filter((grant) => grant.environmentSlug !== null && fits(role, grant.role)).map((grant) => grant.environmentSlug!);
+    if (only.length > 0) return { role, scope: normalScope({ projects: 'all', environments: { only } }) };
+  }
+  return { role: 'member', scope: EVERYWHERE };
+}
+
+/** Whether the instance role, in its scope, holds all a grant on every project did, wherever it did, for good. */
+function byRole(role: InstanceRole, scope: Scope, grant: EveryProjectGrant): boolean {
+  const covered = scope.projects === 'all' && (grant.environmentSlug === null ? scope.environments === 'all' : admits(scope.environments, grant.environmentSlug));
+  return covered && ROLES[grant.role].permissions.every((permission) => instanceRoleGrants(role, permission));
+}
+
+/** Whether every permission of the grant's role is held at `at` already, by the role or by grants lasting as long. */
+function holdsAlready(
+  role: InstanceRole,
+  scope: Scope,
+  held: readonly Held[],
+  grant: Wanted,
+  at: Place,
+): boolean {
+  const lasting = held.filter((other) => outlasts(other.expiresAt, grant.expiresAt));
+  return ROLES[grant.role].permissions.every((permission) => allows({ isRootAdmin: false, role, scope, grants: lasting }, permission, at));
+}
+
+/** Whether `role` holds nothing `wider` does not. */
+function within(role: Role, wider: Role): boolean {
+  return ROLES[role].permissions.every((permission) => roleGrants(wider, permission));
+}
+
+/** Whether an end of `a` comes no sooner than one of `b`; null is never. */
+function outlasts(a: number | null, b: number | null): boolean {
+  return a === null || (b !== null && a >= b);
+}
+
+function placeKey(place: GrantPlace): string {
+  return place.environmentId ?? place.projectId!;
+}

package/src/access-fault.ts

@@ -1,4 +1,4 @@
-import { everyProjectPath, grantKind, type GrantPlace } from './access.ts';
+import type { GrantPlace } from './access.ts';
 
 /**
  * Why the vault's members and grants do not follow from its log, as facts
@@ -25,12 +25,13 @@ export type AccessFault =
    */
   | { kind: 'tampered-member'; principal: string; why: 'mac' | 'stale' };
 
-export type FaultGrant = GrantPlace & { principal: string; role: string };
+/** A grant a fault names; `environmentSlug` only on a grant on every project of 0.4, which names no project. */
+export type FaultGrant = GrantPlace & { environmentSlug?: string | null; principal: string; role: string };
 
 /** How to name a principal (`user:ada@…`) and a place; ids by default. */
 export type FaultNames = {
   principal?: (principal: string) => string;
-  /** Asked only of a project's or an environment's place: a grant on every project is named by its path. */
+  /** Asked only of a project's or an environment's place: a grant on every project of 0.4 is named by its path. */
   place?: (projectId: string, environmentId: string | null) => string;
 };
 
@@ -43,7 +44,8 @@ export function describeAccessFault(fault: AccessFault, names: FaultNames = {}):
       environmentId === null ? projectId : `${projectId}/${environmentId}`);
   const grant = (held: FaultGrant) => {
     const { principal, projectId, environmentId, environmentSlug, role } = held;
-    const place = grantKind(held) === 'every-project' ? everyProjectPath(environmentSlug) : where(projectId ?? 'no project', environmentId);
+    const everyProject = projectId === null && environmentId === null;
+    const place = everyProject ? (environmentSlug == null ? '*' : `*/${environmentSlug}`) : where(projectId ?? 'no project', environmentId);
     return `${who(principal)} as ${role} on ${place}`;
   };
   switch (fault.kind) {