@coffre/core 0.4.6 → 0.5.0

package/dist/access.js

@@ -1,135 +1,2 @@
-//#region src/access.ts
-/**
-* Who may do what: seven permissions and the six roles that bundle them.
-*
-* Deliberately constants and not tables or a policy language. A grant names
-* one role for one member on one place, and a check is a lookup in this file,
-* so authorisation stays something you can read end to end.
-*/
-const PERMISSIONS = [
-	"secret.read",
-	"secret.write",
-	"secret.archive",
-	"audit.read",
-	"environment.manage",
-	"grant.manage",
-	"project.manage"
-];
-/**
-* Permissions that only make sense on a project. Granting
-* `environment.manage` on one environment would be incoherent: what it
-* authorises is creating that environment's siblings.
-*/
-const PROJECT_ONLY_PERMISSIONS = [
-	"environment.manage",
-	"grant.manage",
-	"project.manage"
-];
-const ROLES = {
-	viewer: {
-		name: "Viewer",
-		description: "Read secret values.",
-		permissions: ["secret.read"]
-	},
-	developer: {
-		name: "Developer",
-		description: "Read and write secrets.",
-		permissions: ["secret.read", "secret.write"]
-	},
-	maintainer: {
-		name: "Maintainer",
-		description: "Read, write and retire secrets, and manage environments.",
-		permissions: [
-			"secret.read",
-			"secret.write",
-			"secret.archive",
-			"environment.manage"
-		]
-	},
-	"access-manager": {
-		name: "Access manager",
-		description: "Manage who has access. Cannot read secret values.",
-		permissions: ["grant.manage"]
-	},
-	auditor: {
-		name: "Auditor",
-		description: "Read the audit log. Cannot read secret values.",
-		permissions: ["audit.read"]
-	},
-	owner: {
-		name: "Owner",
-		description: "Everything, including reading secret values.",
-		permissions: [...PERMISSIONS]
-	}
-};
-const ROLE_NAMES = Object.keys(ROLES);
-function isRole(value) {
-	return Object.hasOwn(ROLES, value);
-}
-function roleGrants(role, permission) {
-	return ROLES[role].permissions.includes(permission);
-}
-/** Roles that hold a project-only permission can only be granted on a project. */
-function assignableToEnvironment(role) {
-	return !ROLES[role].permissions.some((permission) => PROJECT_ONLY_PERMISSIONS.includes(permission));
-}
-/**
-* What a grant's fields say it is on, or null when they say nothing
-* coherent: an environment without its project, as a grant whose
-* environment row is gone reads, or a slug beside an id. A grant is on
-* every project only when it names no place at all; anything else that
-* lacks a field covers nothing.
-*/
-function grantKind(grant) {
-	if (grant.environmentId !== null) return grant.projectId !== null && grant.environmentSlug === null ? "environment" : null;
-	if (grant.projectId !== null) return grant.environmentSlug === null ? "project" : null;
-	return "every-project";
-}
-/** Every project, as a path names it. */
-const EVERY_PROJECT = "*";
-/** A grant on every project as a path: `*`, or `*` and the environment slug it covers in each. */
-function everyProjectPath(environmentSlug) {
-	return environmentSlug === null ? "*" : `*/${environmentSlug}`;
-}
-/**
-* Whether a grant at `grant` reaches `place`:
-*
-*   market        market and each of its environments
-*   market/dev    market/dev
-*   *             every project and every environment
-*   *, on dev     each environment whose slug is dev, in every project
-*
-* An environment's grant never reaches up to its project, whether it names
-* the environment or its slug.
-*/
-function covers(grant, place) {
-	switch (grantKind(grant)) {
-		case "environment": return grant.projectId === place.projectId && grant.environmentId === (place.environmentId ?? null);
-		case "project": return grant.projectId === place.projectId;
-		case "every-project": return grant.environmentSlug === null || place.environmentId != null && place.environmentSlug !== null && place.environmentSlug === grant.environmentSlug;
-		case null: return false;
-	}
-}
-/**
-* Whether `holder` may do `permission` at `place`: a grant that covers it
-* gives the role's permissions there, and grants add up. Owners also manage
-* every project. `developer` on `market/prod` does not let anyone rename
-* `market`.
-*/
-function allows(holder, permission, place) {
-	if (holder.isRootAdmin) return true;
-	if (place.environmentId == null && holder.isOwner && PROJECT_ONLY_PERMISSIONS.includes(permission)) return true;
-	return holder.grants.some((grant) => covers(grant, place) && roleGrants(grant.role, permission));
-}
-/**
-* Whether the actor may manage grants at this place: on a project or its
-* environments, with `grant.manage` on the project; on every project, as an
-* instance owner or a root admin only.
-*/
-function mayManageAccess(actor, place) {
-	const kind = grantKind(place);
-	if (kind === "every-project") return actor.isOwner || actor.isRootAdmin;
-	return kind !== null && place.projectId !== null && allows(actor, "grant.manage", { projectId: place.projectId });
-}
-//#endregion
-export { EVERY_PROJECT, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_NAMES, allows, assignableToEnvironment, covers, everyProjectPath, grantKind, isRole, mayManageAccess, roleGrants };
+import { A as roleGrants, C as isScope, D as mayManageAccess, E as managesService, F as convertEveryProjectGrants, M as scopeInWords, N as setsUpServices, O as normalScope, P as unscoped, S as isRole, T as makesProjects, _ as grantKind, a as NOTHING, b as isCredentialScope, c as ROLES, d as admits, f as allows, g as givesService, h as credentialScopeInWords, i as MAX_SCOPE_PLACES, j as runsInstance, k as readsWholeLog, l as ROLE_NAMES, m as covers, n as INSTANCE_ROLES, o as PERMISSIONS, p as assignableToEnvironment, r as INSTANCE_ROLE_NAMES, s as PROJECT_ONLY_PERMISSIONS, t as EVERYWHERE, u as administers, v as inScope, w as issuesCredential, x as isInstanceRole, y as instanceRoleGrants } from "./access-pnJ-u4x2.js";
+export { EVERYWHERE, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, MAX_SCOPE_PLACES, NOTHING, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_NAMES, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, givesService, grantKind, inScope, instanceRoleGrants, isCredentialScope, isInstanceRole, isRole, isScope, issuesCredential, makesProjects, managesService, mayManageAccess, normalScope, readsWholeLog, roleGrants, runsInstance, scopeInWords, setsUpServices, unscoped };

package/dist/identity.d.ts

@@ -1,4 +1,4 @@
-import { BindingClaims, BindingInvalid, BindingPolicy, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, defaultIssuer, fullRef, githubReusable, githubWorkflow, gitlabProject, workflowRef } from "./workloads.js";
+import { BindingClaims, BindingInvalid, BindingPolicy, ClaimValue, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, Starts, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, claimValues, defaultIssuer, differingClaims, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, workflowRef } from "./workloads.js";
 import { JSONWebKeySet, JWTPayload } from "jose";
 //#region src/identity/signin/types.d.ts
 /**
@@ -587,4 +587,4 @@ export declare function verifyWorkloadToken(token: string, keys: JSONWebKeySet,
  */
 export declare function issuedRefusal(iat: number, now: number): WorkloadTokenRefused | null;
 //#endregion
-export { BindingClaims, BindingInvalid, BindingPolicy, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, type JSONWebKeySet, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, defaultIssuer, fullRef, githubReusable, githubWorkflow, gitlabProject, workflowRef };
+export { BindingClaims, BindingInvalid, BindingPolicy, ClaimValue, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, type JSONWebKeySet, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, Starts, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, claimValues, defaultIssuer, differingClaims, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, workflowRef };

package/dist/identity.js

@@ -1,4 +1,4 @@
-import { 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 } from "./workloads.js";
+import { 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 } from "./workloads.js";
 import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
 import * as oauth from "oauth4webapi";
 import { createLocalJWKSet, createRemoteJWKSet, errors, jwtVerify } from "jose";
@@ -830,4 +830,4 @@ function refusalOf(error) {
 	return new WorkloadTokenRefused("signature", "the token does not verify");
 }
 //#endregion
-export { ACCESS_JWT_HEADER, AccessIdentityVerifier, BindingInvalid, CLOCK_TOLERANCE_SECONDS, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, GitHubSigninProvider, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_TOKEN_AGE_SECONDS, MAX_TOKEN_BYTES, OidcSigninProvider, REQUIRED_CLAIMS, SigninError, WORKLOAD_ALGORITHMS, WORKLOAD_PROFILES, WorkloadTokenRefused, canonicalClaims, checkBinding, checkFetchUrl, cloudflareAccess, decodeWorkloadToken, defaultIssuer, defineSignin, deriveKey, fullRef, generateToken, github, githubReusable, githubWorkflow, gitlabProject, google, hashToken, isCoffreToken, issuedRefusal, microsoft, oidc, publicOrigin, seal, signin, toPrincipal, tokenHint, tokenKind, unseal, verifyWorkloadToken, workflowRef };
+export { ACCESS_JWT_HEADER, AccessIdentityVerifier, BindingInvalid, CLOCK_TOLERANCE_SECONDS, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, GitHubSigninProvider, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_TOKEN_AGE_SECONDS, MAX_TOKEN_BYTES, OidcSigninProvider, REQUIRED_CLAIMS, SigninError, WORKLOAD_ALGORITHMS, WORKLOAD_PROFILES, WorkloadTokenRefused, canonicalClaims, checkBinding, checkFetchUrl, claimValues, cloudflareAccess, decodeWorkloadToken, defaultIssuer, defineSignin, deriveKey, differingClaims, fullRef, generateToken, github, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, google, hashToken, isCoffreToken, issuedRefusal, microsoft, oidc, publicOrigin, seal, signin, toPrincipal, tokenHint, tokenKind, unseal, verifyWorkloadToken, workflowRef };

package/dist/schemas.d.ts

@@ -29,9 +29,31 @@ export declare const principalType: z.ZodEnum<{
 }>;
 export declare const principalId: z.ZodString;
 export declare const instanceRole: z.ZodEnum<{
+  member: "member";
+  auditor: "auditor";
+  developer: "developer";
+  admin: "admin";
   owner: "owner";
-  user: "user";
 }>;
+/** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
+export declare const scopeFilter: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{
+  only: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  except: z.ZodArray<z.ZodString>;
+}, z.core.$strict>]>;
+/** Where an instance role applies, as the API takes it: either filter left out is `all`. */
+export declare const scopeInput: z.ZodObject<{
+  projects: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{
+    only: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    except: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>]>>;
+  environments: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{
+    only: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    except: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>]>>;
+}, z.core.$strict>;
 export declare const grantId: z.ZodString;
 export declare const emailAddress: z.ZodString;
 //#endregion

package/dist/schemas.js

@@ -1,3 +1,4 @@
+import { r as INSTANCE_ROLE_NAMES } from "./access-pnJ-u4x2.js";
 import { PROJECT_PAGES } from "./pages.js";
 import { z } from "zod";
 //#region src/schemas.ts
@@ -33,8 +34,19 @@ function shownMember(member) {
 }
 const principalType = z.enum(["user", "service"]);
 const principalId = z.string().trim().min(1).max(320);
-const instanceRole = z.enum(["user", "owner"]);
+const instanceRole = z.enum(INSTANCE_ROLE_NAMES);
+/** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
+const scopeFilter = z.union([
+	z.literal("all"),
+	z.object({ only: z.array(slug).max(200) }).strict(),
+	z.object({ except: z.array(slug).min(1).max(200) }).strict()
+]);
+/** Where an instance role applies, as the API takes it: either filter left out is `all`. */
+const scopeInput = z.object({
+	projects: scopeFilter.optional(),
+	environments: scopeFilter.optional()
+}).strict();
 const grantId = z.string().uuid();
 const emailAddress = z.string().email().max(320);
 //#endregion
-export { TOMBSTONE, displayName, emailAddress, environmentSlug, folderName, grantId, instanceRole, isTombstone, principalId, principalType, secretKey, shownMember, slug, tombstoneOf };
+export { TOMBSTONE, displayName, emailAddress, environmentSlug, folderName, grantId, instanceRole, isTombstone, principalId, principalType, scopeFilter, scopeInput, secretKey, shownMember, slug, tombstoneOf };

package/dist/vault.d.ts

@@ -1,4 +1,4 @@
-import { GrantPlace, Role } from "./access.js";
+import { _ as Role, b as ServiceSetting, c as InstanceRole, i as GrantPlace, t as CredentialScope, v as Scope } from "./access-CwsFLfTz.js";
 //#region src/access-fault.d.ts
 /**
  * Why the vault's members and grants do not follow from its log, as facts
@@ -48,14 +48,16 @@ type AccessFault =
   principal: string;
   why: 'mac' | 'stale';
 };
+/** A grant a fault names; `environmentSlug` only on a grant on every project of 0.4, which names no project. */
 type FaultGrant = GrantPlace & {
+  environmentSlug?: string | null;
   principal: string;
   role: string;
 };
 /** How to name a principal (`user:ada@…`) and a place; ids by default. */
 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;
 };
 /** The fault in a sentence, with whatever names the caller can give. */
@@ -146,13 +148,14 @@ export interface Vault {
     changes: AccessChange[];
   }>>;
   /**
-   * Add a member, bring back a removed one, or change whether they are an
-   * owner. `generation` is theirs now: sessions and tokens of an earlier
-   * one are dead.
+   * Add a member, bring back a removed one, or change a person's instance
+   * role and its scope. `generation` is theirs now: sessions and tokens of
+   * an earlier one are dead.
    */
   admit(input: AdmitInput): Promise<Outcome<{
     created: boolean;
-    owner: boolean;
+    role: InstanceRole;
+    scope: Scope;
     generation: number;
   }>>;
   /** Remove a member: revoke every grant and refuse them until admitted again, from `generation` on. */
@@ -160,6 +163,16 @@ export interface Vault {
     revoked: Grant[];
     generation: number;
   }>>;
+  /**
+   * The instance's settings, as the vault's newest `settings.change` entry
+   * says, by its MAC: an entry is where they live, so each change is logged
+   * by being made. Everywhere, until someone narrows it.
+   */
+  settings(): Promise<Settings>;
+  /** Change the instance's settings: those who run it, never anyone else. */
+  setSettings(input: SetSettingsInput): Promise<Outcome<{
+    settings: Settings;
+  }>>;
   /**
    * Sign the log up to its last entry, in an `audit.checkpoint` entry of
    * the vault's, if the chain recomputes, the vault's entries by their MACs,
@@ -198,7 +211,7 @@ export interface Vault {
    * from it. The links and hashes of the chain are the caller's to
    * recompute through `upTo`, as the app does first; with none, the vault
    * recomputes them all itself. A verdict and nothing else, so anyone may
-   * ask; the app asks for owners.
+   * ask; the app asks for those who read the whole log (`readsWholeLog`).
    */
   verifyLog(input: VerifyLogInput): Promise<LogVerification>;
 }
@@ -207,7 +220,7 @@ export interface Vault {
  * `access_seq` names, and what a finding about them is newer than while it
  * stands.
  */
-export declare const ACCESS_ACTIONS: readonly ["member.add", "member.restore", "member.owner", "member.remove", "access.grant", "access.revoke"];
+export declare const ACCESS_ACTIONS: readonly ["member.add", "member.restore", "member.owner", "member.role", "member.remove", "access.grant", "access.revoke"];
 /** A refusal, already logged by the time the app sees it. */
 export type Refusal = {
   code: RefusalCode;
@@ -237,7 +250,7 @@ export type RefusalCode =
 'not_allowed' |
 /** Root admins come from the vault's configuration and cannot be changed. */
 'root_admin' |
-/** Well-formed, but not something the rules allow: a project role on an environment, an owner token. */
+/** Well-formed, but not something the rules allow: a project role on an environment, a service account with an instance role. */
 'invalid' |
 /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
 'log_broken' |
@@ -311,7 +324,16 @@ type Correlation = {
    */
   credentialId?: string | null;
 };
-export type UnwrapInput = Correlation & {
+/**
+ * The scope of the credential the request came in on, a service token's or
+ * a trust binding's: unlike the correlation, the vault decides on it, and
+ * its principal holds nothing past it (`allows`). Null, or left out, for a
+ * session's, which carries all its member holds.
+ */
+export type Through = {
+  credentialScope?: CredentialScope | null;
+};
+export type UnwrapInput = Correlation & Through & {
   principal: string;
   purpose: Purpose;
   /**
@@ -336,7 +358,7 @@ export type HolderRef = {
   secretId: string;
   path: string;
 };
-export type ReferenceInput = Correlation & {
+export type ReferenceInput = Correlation & Through & {
   principal: string;
   /** `id` is the reference's, a fresh UUID; the vault reads the source by its id. */
   items: {
@@ -347,13 +369,13 @@ export type ReferenceInput = Correlation & {
     };
   }[];
 };
-export type EndReferencesInput = Correlation & {
+export type EndReferencesInput = Correlation & Through & {
   principal: string;
   /** `abandoned`: sealed for a write that stored nothing, so that no row written later revives it. */
   reason: 'replaced' | 'broken' | 'abandoned';
   items: Via[];
 };
-export type WrapInput = Correlation & {
+export type WrapInput = Correlation & Through & {
   principal: string;
   /** `key` is a fresh 32-byte data key, base64. */
   items: {
@@ -361,7 +383,7 @@ export type WrapInput = Correlation & {
     key: string;
   }[];
 };
-export type RewrapInput = Correlation & {
+export type RewrapInput = Correlation & Through & {
   principal: string;
   /** `secret` is the proposed new version; `secretVersionId` is the stored source. */
   items: {
@@ -370,9 +392,8 @@ export type RewrapInput = Correlation & {
   }[];
 };
 /**
- * A grant: on a project, one of its environments (`projectId` is the
- * environment's project), every project, or one environment slug in every
- * project (`GrantPlace` in @coffre/core/access).
+ * A grant: on a project, or one of its environments (`projectId` is the
+ * environment's project; `GrantPlace` in @coffre/core/access).
  */
 export type Grant = GrantPlace & {
   role: Role;
@@ -392,8 +413,13 @@ export type Access = {
   /** Advanced by removal, even if the app cannot commit its credential revocations. */
   generation: number;
   isRootAdmin: boolean;
-  /** Root admins and users admitted as owners, while active. */
-  isOwner: boolean;
+  /**
+   * Their instance role and its scope, while active: `member` everywhere
+   * for service accounts and anyone not active, `owner` everywhere for
+   * root admins. Scopes name projects by id.
+   */
+  role: InstanceRole;
+  scope: Scope;
   /** Live grants only, and none unless active. */
   grants: Grant[];
   /** When the status last changed, and who changed it; null for root admins and strangers. */
@@ -402,30 +428,42 @@ export type Access = {
 };
 /**
  * One place: a role to hold there, with an optional end, or null for none.
- * An environment's place names its project too; `environmentSlug` left out
- * is null.
+ * An environment's place names its project too.
  */
-export type GrantChange = Omit<GrantPlace, 'environmentSlug'> & {
-  environmentSlug?: string | null;
+export type GrantChange = GrantPlace & {
   role: Role | null;
   expiresAt: string | null;
 };
 export type AccessChange = 'created' | 'updated' | 'revoked' | 'unchanged';
-export type SetAccessInput = Correlation & {
+export type SetAccessInput = Correlation & Through & {
   actor: string;
   principal: string;
   changes: GrantChange[];
 };
-export type AdmitInput = Correlation & {
+export type AdmitInput = Correlation & Through & {
   actor: string;
   principal: string;
-  /** Left out, an existing member keeps their role and a new one is not an owner. */
-  owner?: boolean;
+  /**
+   * A person's instance role, and where it applies (everywhere, left out).
+   * Left out, an existing member keeps theirs and a new one is a `member`.
+   * Changing it takes someone who runs the instance, about someone else.
+   */
+  role?: InstanceRole;
+  scope?: Scope;
 };
-export type RemoveInput = Correlation & {
+export type RemoveInput = Correlation & Through & {
   actor: string;
   principal: string;
 };
+/** What the instance's settings hold. */
+export type Settings = {
+  /** Where people set up service accounts themselves (`ServiceSetting` in @coffre/core/access), projects by id. */
+  serviceAccounts: ServiceSetting;
+};
+export type SetSettingsInput = Correlation & Through & {
+  actor: string;
+  settings: Settings;
+};
 /**
  * A prefix of the log the vault signed: every entry up to `seq`, the last
  * of which has `hash`, which pins every byte before it. Kept as the vault's

package/dist/vault.js

@@ -1,4 +1,3 @@
-import { everyProjectPath, grantKind } from "./access.js";
 //#region src/checkpoint.ts
 /** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
 function checkpointMessage(checkpoint) {
@@ -26,7 +25,7 @@ function describeAccessFault(fault, names = {}) {
 	const where = names.place ?? ((projectId, environmentId) => environmentId === null ? projectId : `${projectId}/${environmentId}`);
 	const grant = (held) => {
 		const { principal, projectId, environmentId, environmentSlug, role } = held;
-		const place = grantKind(held) === "every-project" ? everyProjectPath(environmentSlug) : where(projectId ?? "no project", environmentId);
+		const place = projectId === null && environmentId === null ? environmentSlug == null ? "*" : `*/${environmentSlug}` : where(projectId ?? "no project", environmentId);
 		return `${who(principal)} as ${role} on ${place}`;
 	};
 	switch (fault.kind) {
@@ -50,6 +49,7 @@ const ACCESS_ACTIONS = [
 	"member.add",
 	"member.restore",
 	"member.owner",
+	"member.role",
 	"member.remove",
 	"access.grant",
 	"access.revoke"

package/dist/workloads.d.ts

@@ -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'] } }
  */
 export declare const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
 export declare const GITLAB_ISSUER = "https://gitlab.com";
@@ -30,12 +33,29 @@ export declare const WORKLOAD_PROFILES: readonly WorkloadProfile[];
 /** The claims each profile requires; a binding may add more, to narrow it. */
 export declare const REQUIRED_CLAIMS: Record<WorkloadProfile, readonly string[]>;
 /**
- * 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.
+ */
+export declare const GITHUB_EVENTS: readonly ["push", "workflow_dispatch", "schedule", "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.
  */
-export declare const GITHUB_EVENTS: readonly ["push", "workflow_dispatch", "schedule", "release"];
+export declare const EVENT_EXPOSURE: Readonly<Record<string, string>>;
 /** Pipelines that run the project's own code, at its own ref: never a merge request's. */
 export declare const GITLAB_PIPELINE_SOURCES: readonly ["push", "web", "schedule"];
 /** At most this many live bindings per service, and claims per binding. */
@@ -43,7 +63,9 @@ export declare const MAX_BINDINGS = 16;
 export declare const MAX_CLAIMS = 16;
 /** The longest claim value, in bytes. */
 export declare const MAX_CLAIM_BYTES = 256;
-export type BindingClaims = Record<string, string>;
+/** 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. */
 export type BindingPolicy = {
   profile: WorkloadProfile;
@@ -67,6 +89,17 @@ export declare function checkBinding(input: {
 }, options?: {
   allowLoopback?: boolean;
 }): BindingPolicy;
+/** A claim's values, one or several. */
+export declare function claimValues(value: ClaimValue | undefined): string[];
+/**
+ * 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>`.
+ */
+export declare function differingClaims(profile: WorkloadProfile, expected: BindingClaims, token: Record<string, unknown>): string[];
 /** The claims as the MAC and the database hold them: JSON, sorted by name. */
 export declare function canonicalClaims(claims: BindingClaims): string;
 /**
@@ -84,17 +117,26 @@ export declare function checkFetchUrl(value: string, what: string, options: {
 }): URL;
 /** `refs/heads/main`, or `refs/tags/v1`, as GitHub names a ref. */
 export declare function fullRef(kind: 'branch' | 'tag', name: string): string;
+/** The GitHub events a binding at a branch, or at a tag, may name. */
+export declare function githubEventsAt(kind: 'branch' | 'tag'): string[];
 /** A workflow file at a ref, as GitHub's tokens name it: `acme/api/.github/workflows/deploy.yml@refs/heads/main`. */
 export declare function workflowRef(repository: string, file: string, ref: string): string;
-/** A workflow of the repository, run by `event` at `ref`. */
+/**
+ * What started the run, as the presets take it: `event` (`source`, for
+ * GitLab), the one value 0.4.6's presets took, or `events` (`sources`), any
+ * of several. Naming both, or neither, is a type error and, for a caller the
+ * types do not reach, a `BindingInvalid` at run time: a preset never guesses
+ * which one was meant.
+ */
+export type Starts<One extends string, Many extends string> = ({ [K in One]: string; } & { [K in Many]?: never; }) | ({ [K in Many]: string[]; } & { [K in One]?: never; });
+/** A workflow of the repository, run at `ref` by any of `events`; a pull request, by the branch it merges into. */
 export declare function githubWorkflow(input: {
   repository: string;
   repositoryId: string;
   ownerId: string;
   workflow: string;
   ref: string;
-  event: string;
-}): Omit<BindingPolicy, 'issuer'>;
+} & Starts<'event', 'events'>): Omit<BindingPolicy, 'issuer'>;
 /**
  * A reusable workflow at one commit, called at `ref`: from one repository,
  * or, with `repositoryId` null, from any repository of the organization. A
@@ -104,20 +146,18 @@ export declare function githubReusable(input: {
   repositoryId: string | null;
   ownerId: string;
   ref: string;
-  event: string;
   called: string;
   sha: string;
   caller?: {
     repository: string;
     workflow: string;
   };
-}): Omit<BindingPolicy, 'issuer'>;
-/** A GitLab project's pipelines from `source`, at a branch or tag. */
+} & Starts<'event', 'events'>): Omit<BindingPolicy, 'issuer'>;
+/** A GitLab project's pipelines from any of `sources`, at a branch or tag. */
 export declare function gitlabProject(input: {
   namespaceId: string;
   projectId: string;
   refType: 'branch' | 'tag';
   ref: string;
-  source: string;
-}): Omit<BindingPolicy, 'issuer'>;
+} & Starts<'source', 'sources'>): Omit<BindingPolicy, 'issuer'>;
 //#endregion