@coffre/core 0.4.6 → 0.5.0

package/src/access.ts

@@ -1,9 +1,11 @@
 /**
- * Who may do what: seven permissions and the six roles that bundle them.
+ * Who may do what: seven permissions, the six project roles a grant names,
+ * and the five instance roles a person holds across every project.
  *
  * 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.
+ * one role for one member on one place, a person's instance role names one
+ * role and its scope, and a check is a lookup in this file, so authorisation
+ * stays something you can read end to end.
  */
 
 export const PERMISSIONS = [
@@ -85,50 +87,221 @@ export function assignableToEnvironment(role: Role): boolean {
   );
 }
 
+/**
+ * A person's role on the whole instance: what they hold in every project
+ * their scope covers, before any grant. Service accounts are always
+ * members, and hold only what their grants give. Admins and owners also
+ * run the instance (`runsInstance`) when nothing narrows their scope.
+ */
+export const INSTANCE_ROLES = {
+  member: {
+    name: 'Member',
+    description: 'Only what projects grant.',
+    permissions: [],
+  },
+  auditor: {
+    name: 'Auditor',
+    description: 'Read the audit log. No secret values.',
+    permissions: ['audit.read'],
+  },
+  developer: {
+    name: 'Developer',
+    description: 'Read and write secrets.',
+    permissions: ['secret.read', 'secret.write'],
+  },
+  admin: {
+    name: 'Admin',
+    description: 'Manage people, service accounts, projects and access. No secret values.',
+    permissions: ['audit.read', 'environment.manage', 'grant.manage', 'project.manage'],
+  },
+  owner: {
+    name: 'Owner',
+    description: 'Everything an admin does, and read every secret.',
+    permissions: [...PERMISSIONS],
+  },
+} as const satisfies Record<string, {
+  name: string;
+  description: string;
+  permissions: readonly Permission[];
+}>;
+
+export type InstanceRole = keyof typeof INSTANCE_ROLES;
+
+export const INSTANCE_ROLE_NAMES = Object.keys(INSTANCE_ROLES) as InstanceRole[];
+
+export function isInstanceRole(value: string): value is InstanceRole {
+  return Object.hasOwn(INSTANCE_ROLES, value);
+}
+
+export function instanceRoleGrants(role: InstanceRole, permission: Permission): boolean {
+  return (INSTANCE_ROLES[role].permissions as readonly Permission[]).includes(permission);
+}
+
+/** The roles that manage people and access: Admin, and Owner, which adds every secret. */
+export function administers(role: InstanceRole): boolean {
+  return role === 'admin' || role === 'owner';
+}
+
+/**
+ * Which projects, or environments, a scope takes in: all of them, only
+ * those listed, or all but those listed. Projects are listed by id, so a
+ * rename keeps them; environments by slug, so `dev` is the `dev` of every
+ * project, the ones made later too.
+ */
+export type Filter = 'all' | { only: string[] } | { except: string[] };
+
+/**
+ * Where a person's instance role applies: the projects it reaches, and the
+ * environments in them, by slug. A grant reaches past it; nothing else does.
+ *
+ *   { projects: 'all', environments: { only: ['dev'] } }       every project's dev
+ *   { projects: { except: [billing] }, environments: 'all' }   all but billing
+ */
+export type Scope = { projects: Filter; environments: Filter };
+
+/** Every project and every environment. */
+export const EVERYWHERE: Scope = { projects: 'all', environments: 'all' };
+
+/** Whether a scope narrows nothing. */
+export function unscoped(scope: Scope): boolean {
+  return scope.projects === 'all' && scope.environments === 'all';
+}
+
+/** Whether a filter takes in a project's id or an environment's slug; one not read (null) is in none that lists. */
+export function admits(filter: Filter, value: string | null | undefined): boolean {
+  if (filter === 'all') return true;
+  if (value == null) return false;
+  return 'only' in filter ? filter.only.includes(value) : !filter.except.includes(value);
+}
+
+/**
+ * One way to write each scope, which the vault seals and the log replays:
+ * lists sorted, without repeats; an empty `except` is `all`. An empty
+ * `only` stays: it takes in nothing.
+ */
+export function normalScope(scope: Scope): Scope {
+  const normal = (filter: Filter): Filter => {
+    if (filter === 'all') return 'all';
+    if ('only' in filter) return { only: [...new Set(filter.only)].sort() };
+    return filter.except.length === 0 ? 'all' : { except: [...new Set(filter.except)].sort() };
+  };
+  return { projects: normal(scope.projects), environments: normal(scope.environments) };
+}
+
+/** Whether `value` is a scope as `normalScope` writes it, and as the vault stores it. */
+export function isScope(value: unknown): value is Scope {
+  const isFilter = (filter: unknown): filter is Filter => {
+    if (filter === 'all') return true;
+    if (typeof filter !== 'object' || filter === null || Array.isArray(filter)) return false;
+    const keys = Object.keys(filter);
+    if (keys.length !== 1 || (keys[0] !== 'only' && keys[0] !== 'except')) return false;
+    const list = (filter as Record<string, unknown>)[keys[0]];
+    return Array.isArray(list) && list.every((item) => typeof item === 'string' && item.length > 0);
+  };
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const { projects, environments, ...rest } = value as Record<string, unknown>;
+  return Object.keys(rest).length === 0 && isFilter(projects) && isFilter(environments);
+}
+
+/**
+ * A scope in words, its projects named as the caller has them (slugs, at
+ * the API's edges): `All projects`, `All projects · dev only`,
+ * `web, api`, `All projects but billing · all but prod`.
+ */
+export function scopeInWords(scope: Scope): string {
+  const list = (names: string[]) => names.join(', ');
+  const { projects, environments } = scope;
+  const where = projects === 'all'
+    ? 'All projects'
+    : 'only' in projects
+      ? (projects.only.length === 0 ? 'No projects' : list(projects.only))
+      : `All projects but ${list(projects.except)}`;
+  if (environments === 'all') return where;
+  if ('only' in environments) return `${where} · ${environments.only.length === 0 ? 'no environments' : `${list(environments.only)} only`}`;
+  return `${where} · all but ${list(environments.except)}`;
+}
+
 /**
  * A place a permission applies to: a project, or one of its environments,
- * named by its slug too, which grants on every project match by. A slug
- * not read (null) matches no grant on a slug.
+ * named by its slug too, which a scope matches environments by. A slug not
+ * read (null) is in no scope that names environments.
  */
 export type Place =
   | { projectId: string; environmentId?: null }
   | { projectId: string; environmentId: string; environmentSlug: string | null };
 
 /**
- * Where a grant applies, by the fields it fills (`grantKind`):
- *
- *   market        projectId
- *   market/dev    projectId and environmentId
- *   *             neither: every project, the ones created later too
- *   *, on dev     environmentSlug only: the environment of that slug in every project
+ * Whether a scope takes in a place. A project as a whole is in it only when
+ * the scope keeps all of its environments: a role scoped to `dev` reaches
+ * every `dev`, never a project around one.
+ */
+export function inScope(scope: Scope, place: Place): boolean {
+  if (!admits(scope.projects, place.projectId)) return false;
+  if (place.environmentId == null) return scope.environments === 'all';
+  return admits(scope.environments, place.environmentSlug);
+}
+
+/**
+ * Where a grant applies: a project (`environmentId` null), or one of its
+ * environments, which names its project too.
  */
 export type GrantPlace = {
-  /** The project, also of an environment's grant; null only on every project. */
   projectId: string | null;
   environmentId: string | null;
-  /** On every project, the one environment slug it covers; null for all of them, and on a project's grant. */
-  environmentSlug: string | null;
 };
 
 /**
  * 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.
+ * environment row is gone reads, or neither, as the grants on every project
+ * of 0.4 read until the vault replaces them. Null covers nothing.
  */
-export function grantKind(grant: GrantPlace): 'project' | 'environment' | 'every-project' | null {
-  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';
+export function grantKind(grant: GrantPlace): 'project' | 'environment' | null {
+  if (grant.projectId === null) return null;
+  return grant.environmentId === null ? 'project' : 'environment';
 }
 
-/** Every project, as a path names it. */
-export const EVERY_PROJECT = '*';
+/**
+ * What a service account's token or trust binding carries, its scope:
+ * grants as the account's are, a role on a project or an environment, each
+ * one the account held and its issuer could give when it was issued.
+ * Nothing changes it after. A request made with it holds what both it and
+ * the account hold now (`allows`), so narrowing the account narrows it, and
+ * a grant the account gets later reaches no credential issued before:
+ *
+ *   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
+ */
+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;
 
-/** A grant on every project as a path: `*`, or `*` and the environment slug it covers in each. */
-export function everyProjectPath(environmentSlug: string | null): string {
-  return environmentSlug === null ? EVERY_PROJECT : `${EVERY_PROJECT}/${environmentSlug}`;
+/**
+ * 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`.
+ */
+export function credentialScopeInWords(scope: Readonly<Record<string, string>>): string {
+  const byRole = new Map<string, string[]>();
+  for (const [path, role] of Object.entries(scope)) byRole.set(role, [...(byRole.get(role) ?? []), path]);
+  return [...byRole].map(([role, paths]) => `${role} on ${paths.join(', ')}`).join('; ') || 'nothing';
+}
+
+/** Whether `value` is a credential's scope as the app stores it and the vault reads it: one grant a place, each role one that place takes. */
+export function isCredentialScope(value: unknown): value is CredentialScope {
+  if (!Array.isArray(value)) return false;
+  const places = new Set<string>();
+  return value.every((grant: unknown) => {
+    if (typeof grant !== 'object' || grant === null || Array.isArray(grant)) return false;
+    const { projectId, environmentId, role, ...rest } = grant as Record<string, unknown>;
+    if (Object.keys(rest).length > 0 || typeof projectId !== 'string' || typeof role !== 'string' || !isRole(role)) return false;
+    if (environmentId !== null && (typeof environmentId !== 'string' || !assignableToEnvironment(role))) return false;
+    const place = `${projectId}/${environmentId ?? ''}`;
+    if (places.has(place)) return false;
+    places.add(place);
+    return true;
+  });
 }
 
 /**
@@ -140,22 +313,25 @@ export function everyProjectPath(environmentSlug: string | null): string {
 export type Holdings = {
   /** Named in the vault's configuration: everything, everywhere. */
   isRootAdmin: boolean;
-  /** Root admins and active users with the instance `owner` role. */
-  isOwner: boolean;
+  /** `member` for service accounts, and for anyone not active. */
+  role: InstanceRole;
+  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. */
+  credentialScope?: CredentialScope | null;
 };
 
+/** Someone who holds nothing: a stranger, a removed member, a tampered row. */
+export const NOTHING: Holdings = { isRootAdmin: false, role: 'member', scope: EVERYWHERE, grants: [] };
+
 /**
  * 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.
+ * An environment's grant never reaches up to its project.
  */
 export function covers(grant: GrantPlace, place: Place): boolean {
   switch (grantKind(grant)) {
@@ -163,34 +339,155 @@ export function covers(grant: GrantPlace, place: Place): boolean {
       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`.
+ * Whether `holder` may do `permission` at `place`: their instance role
+ * gives its permissions inside its scope, a grant that covers the place
+ * gives its role's there, and they add up. A Developer scoped to `dev` with
+ * `viewer` on `billing` reads and writes every `dev`, and reads all of
+ * `billing`.
  */
 export function allows(holder: Holdings, permission: Permission, place: Place): boolean {
+  if (holder.credentialScope != null && !holdsAt(holder.credentialScope, permission, place)) return false;
   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));
+  if (instanceRoleGrants(holder.role, permission) && inScope(holder.scope, place)) return true;
+  return holdsAt(holder.grants, 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));
 }
 
 /**
- * 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.
+ * Whether the actor may give or take grants at this place: with
+ * `grant.manage` there, from a project grant or an instance role whose
+ * scope takes it in. A grant on a project reaches all its environments, so
+ * an admin scoped to `dev` manages `market/dev`'s grants, not `market`'s.
  */
-export function mayManageAccess(actor: Holdings, place: GrantPlace): boolean {
-  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 });
+export function mayManageAccess(actor: Holdings, place: Place): boolean {
+  return allows(actor, 'grant.manage', place);
 }
+
+/**
+ * Whether the holder runs the instance: a root admin, or an Admin or Owner
+ * whose scope narrows nothing. They add and remove people, set instance
+ * roles, and change the instance's settings; they read its whole log too
+ * (`readsWholeLog`). A scoped Admin manages only inside its scope, so it
+ * does none of these.
+ */
+export function runsInstance(holder: Holdings): boolean {
+  return holder.isRootAdmin || (administers(holder.role) && unscoped(holder.scope));
+}
+
+/**
+ * Who may set up service accounts themselves, the instance's setting: a
+ * scope as a role's is, projects by id and environments by slug, which
+ * only those who run the instance change. Inside it, any person gives a
+ * service account what they hold, never more (`givesService`). Everywhere,
+ * unless it says otherwise:
+ *
+ *   { projects: 'all', environments: { except: ['prod'] } }   CI for dev and staging; prod's takes an Admin
+ */
+export type ServiceSetting = Scope;
+
+/**
+ * Whether `holder` may give a service account `role` at `place`: where
+ * they manage access, as anyone may; or inside the setting, where they hold
+ * 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.
+ */
+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));
+}
+
+/** Whether `holder` gives a service account anything anywhere among `places`: whether they set any up. */
+export function setsUpServices(holder: Holdings, setting: ServiceSetting | null, places: readonly Place[]): boolean {
+  if (runsInstance(holder)) return true;
+  return places.some((place) => ROLE_NAMES.some((role) => givesService(holder, setting, role, place)));
+}
+
+/** A service account as `managesService` weighs it: its live grants, where they are, and who admitted it. */
+export type ServiceAccount = {
+  grants: readonly { role: Role; place: Place }[];
+  /** The member who admitted it last (`user:…`), as its row says. */
+  admittedBy: string | null;
+};
+
+/**
+ * Whether `holder`, the member `actor`, manages a service account: issues
+ * and revokes its tokens, adds and removes its trust bindings, changes its
+ * grants and removes it. A credential for it reads everything it holds, so
+ * they must reach every grant it holds, as if giving it (`givesService`):
+ * a Developer on `dev` manages an account on `market/dev`, and not one that
+ * holds `market/prod` too. One that holds nothing, only the person who
+ * admitted it: anyone else's token for it would read whatever it is given
+ * next. Those who run the instance manage every one.
+ */
+export function managesService(holder: Holdings, setting: ServiceSetting | null, actor: string, account: ServiceAccount): boolean {
+  if (runsInstance(holder)) return true;
+  if (account.grants.length === 0) return setting !== null && account.admittedBy === actor;
+  return account.grants.every((grant) => givesService(holder, setting, grant.role, grant.place));
+}
+
+/**
+ * Whether `holder`, the member `actor`, may issue a token or a trust
+ * binding of `account` whose scope is `scope`: they manage the account
+ * (`managesService`), and each grant of the scope is one they could give it
+ * (`givesService`) and one it holds, every permission of its role there.
+ * For an account that holds `developer` on `market/dev`, a Developer of
+ * `dev` issues `developer` or `viewer` there; nobody issues `market/prod`
+ * for it, or `maintainer` on `market/dev`, until the account holds them.
+ */
+export function issuesCredential(
+  holder: Holdings,
+  setting: ServiceSetting | null,
+  actor: string,
+  account: ServiceAccount,
+  scope: ServiceAccount['grants'],
+): boolean {
+  if (!managesService(holder, setting, actor, account)) return false;
+  const held: Holdings = { ...NOTHING, grants: account.grants.map(({ role, place }) => ({ projectId: place.projectId, environmentId: place.environmentId ?? null, role })) };
+  return scope.every(({ role, place }) =>
+    givesService(holder, setting, role, place) && ROLES[role].permissions.every((permission) => allows(held, permission, place)));
+}
+
+/**
+ * Whether the holder reads the whole log, the instance's own entries
+ * (sign-ins, people, service accounts, settings) with every project's, and
+ * verifies it: whoever holds `audit.read` by an instance role whose scope
+ * narrows nothing, an Auditor's included, and a root admin. Reading, not
+ * running: an Auditor of the whole instance changes nothing it reads about.
+ * Anyone else reads the places they hold `audit.read` in.
+ */
+export function readsWholeLog(holder: Holdings): boolean {
+  return holder.isRootAdmin || (instanceRoleGrants(holder.role, 'audit.read') && unscoped(holder.scope));
+}
+
+/**
+ * Whether the holder may make a project: an Admin or Owner whose scope
+ * takes the new one in as a whole. A scope listing only some projects does
+ * not list the new one; one that keeps only some environments does not
+ * hold the project around them.
+ */
+export function makesProjects(holder: Holdings): boolean {
+  if (holder.isRootAdmin) return true;
+  const { projects, environments } = holder.scope;
+  return administers(holder.role) && environments === 'all' && (projects === 'all' || 'except' in projects);
+}
+
+export {
+  convertEveryProjectGrants,
+  type Conversion,
+  type ConversionInput,
+  type ConvertedGrant,
+  type EveryProjectGrant,
+  type Narrowed,
+} from './access-conversion.ts';