@coffre/core 0.4.6 → 0.5.0

package/dist/access-CwsFLfTz.d.ts

@@ -0,0 +1,420 @@
+//#region src/access-conversion.d.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. */
+type EveryProjectGrant = {
+  environmentSlug: string | null;
+  role: Role;
+  expiresAt: number | null;
+};
+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`). */
+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. */
+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;
+};
+type Conversion = {
+  role: InstanceRole;
+  scope: Scope;
+  grants: ConvertedGrant[];
+  narrowed: Narrowed[];
+};
+declare function convertEveryProjectGrants(input: ConversionInput): Conversion;
+//#endregion
+//#region src/access.d.ts
+/**
+ * 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, 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.
+ */
+declare const PERMISSIONS: readonly ["secret.read", "secret.write", "secret.archive", "audit.read", "environment.manage", "grant.manage", "project.manage"];
+type Permission = (typeof PERMISSIONS)[number];
+/**
+ * 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.
+ */
+declare const PROJECT_ONLY_PERMISSIONS: readonly Permission[];
+declare const ROLES: {
+  readonly viewer: {
+    readonly name: "Viewer";
+    readonly description: "Read secret values.";
+    readonly permissions: readonly ["secret.read"];
+  };
+  readonly developer: {
+    readonly name: "Developer";
+    readonly description: "Read and write secrets.";
+    readonly permissions: readonly ["secret.read", "secret.write"];
+  };
+  readonly maintainer: {
+    readonly name: "Maintainer";
+    readonly description: "Read, write and retire secrets, and manage environments.";
+    readonly permissions: readonly ["secret.read", "secret.write", "secret.archive", "environment.manage"];
+  };
+  readonly 'access-manager': {
+    readonly name: "Access manager";
+    readonly description: "Manage who has access. Cannot read secret values.";
+    readonly permissions: readonly ["grant.manage"];
+  };
+  readonly auditor: {
+    readonly name: "Auditor";
+    readonly description: "Read the audit log. Cannot read secret values.";
+    readonly permissions: readonly ["audit.read"];
+  };
+  readonly owner: {
+    readonly name: "Owner";
+    readonly description: "Everything, including reading secret values.";
+    readonly permissions: readonly ["secret.read", "secret.write", "secret.archive", "audit.read", "environment.manage", "grant.manage", "project.manage"];
+  };
+};
+type Role = keyof typeof ROLES;
+declare const ROLE_NAMES: Role[];
+declare function isRole(value: string): value is Role;
+declare function roleGrants(role: Role, permission: Permission): boolean;
+/** Roles that hold a project-only permission can only be granted on a project. */
+declare 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.
+ */
+declare const INSTANCE_ROLES: {
+  readonly member: {
+    readonly name: "Member";
+    readonly description: "Only what projects grant.";
+    readonly permissions: readonly [];
+  };
+  readonly auditor: {
+    readonly name: "Auditor";
+    readonly description: "Read the audit log. No secret values.";
+    readonly permissions: readonly ["audit.read"];
+  };
+  readonly developer: {
+    readonly name: "Developer";
+    readonly description: "Read and write secrets.";
+    readonly permissions: readonly ["secret.read", "secret.write"];
+  };
+  readonly admin: {
+    readonly name: "Admin";
+    readonly description: "Manage people, service accounts, projects and access. No secret values.";
+    readonly permissions: readonly ["audit.read", "environment.manage", "grant.manage", "project.manage"];
+  };
+  readonly owner: {
+    readonly name: "Owner";
+    readonly description: "Everything an admin does, and read every secret.";
+    readonly permissions: readonly ["secret.read", "secret.write", "secret.archive", "audit.read", "environment.manage", "grant.manage", "project.manage"];
+  };
+};
+type InstanceRole = keyof typeof INSTANCE_ROLES;
+declare const INSTANCE_ROLE_NAMES: InstanceRole[];
+declare function isInstanceRole(value: string): value is InstanceRole;
+declare function instanceRoleGrants(role: InstanceRole, permission: Permission): boolean;
+/** The roles that manage people and access: Admin, and Owner, which adds every secret. */
+declare function administers(role: InstanceRole): boolean;
+/**
+ * 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.
+ */
+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
+ */
+type Scope = {
+  projects: Filter;
+  environments: Filter;
+};
+/** Every project and every environment. */
+declare const EVERYWHERE: Scope;
+/** Whether a scope narrows nothing. */
+declare function unscoped(scope: Scope): boolean;
+/** Whether a filter takes in a project's id or an environment's slug; one not read (null) is in none that lists. */
+declare function admits(filter: Filter, value: string | null | undefined): boolean;
+/**
+ * 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.
+ */
+declare function normalScope(scope: Scope): Scope;
+/** Whether `value` is a scope as `normalScope` writes it, and as the vault stores it. */
+declare function isScope(value: unknown): value is Scope;
+/**
+ * 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`.
+ */
+declare function scopeInWords(scope: Scope): string;
+/**
+ * A place a permission applies to: a project, or one of its environments,
+ * named by its slug too, which a scope matches environments by. A slug not
+ * read (null) is in no scope that names environments.
+ */
+type Place = {
+  projectId: string;
+  environmentId?: null;
+} | {
+  projectId: string;
+  environmentId: string;
+  environmentSlug: string | null;
+};
+/**
+ * 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.
+ */
+declare function inScope(scope: Scope, place: Place): boolean;
+/**
+ * Where a grant applies: a project (`environmentId` null), or one of its
+ * environments, which names its project too.
+ */
+type GrantPlace = {
+  projectId: string | null;
+  environmentId: 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 neither, as the grants on every project
+ * of 0.4 read until the vault replaces them. Null covers nothing.
+ */
+declare function grantKind(grant: GrantPlace): 'project' | 'environment' | null;
+/**
+ * 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
+ */
+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. */
+declare const MAX_SCOPE_PLACES = 1000;
+/**
+ * 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`.
+ */
+declare function credentialScopeInWords(scope: Readonly<Record<string, string>>): string;
+/** 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. */
+declare function isCredentialScope(value: unknown): value is CredentialScope;
+/**
+ * What someone holds: everything a permission check reads. The app builds
+ * it from what the vault says once per request; the vault builds it from
+ * its own store. Both then ask the same functions below, so the rules
+ * cannot drift apart.
+ */
+type Holdings = {
+  /** Named in the vault's configuration: everything, everywhere. */
+  isRootAdmin: 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. */
+declare const NOTHING: Holdings;
+/**
+ * Whether a grant at `grant` reaches `place`:
+ *
+ *   market        market and each of its environments
+ *   market/dev    market/dev
+ *
+ * An environment's grant never reaches up to its project.
+ */
+declare function covers(grant: GrantPlace, place: Place): boolean;
+/**
+ * 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`.
+ */
+declare function allows(holder: Holdings, permission: Permission, place: Place): boolean;
+/**
+ * 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.
+ */
+declare function mayManageAccess(actor: Holdings, place: Place): boolean;
+/**
+ * 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.
+ */
+declare function runsInstance(holder: Holdings): boolean;
+/**
+ * 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
+ */
+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.
+ */
+declare function givesService(holder: Holdings, setting: ServiceSetting | null, role: Role, place: Place): boolean;
+/** Whether `holder` gives a service account anything anywhere among `places`: whether they set any up. */
+declare function setsUpServices(holder: Holdings, setting: ServiceSetting | null, places: readonly Place[]): boolean;
+/** A service account as `managesService` weighs it: its live grants, where they are, and who admitted it. */
+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.
+ */
+declare function managesService(holder: Holdings, setting: ServiceSetting | null, actor: string, account: ServiceAccount): boolean;
+/**
+ * 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.
+ */
+declare function issuesCredential(holder: Holdings, setting: ServiceSetting | null, actor: string, account: ServiceAccount, scope: ServiceAccount['grants']): boolean;
+/**
+ * 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.
+ */
+declare function readsWholeLog(holder: Holdings): boolean;
+/**
+ * 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.
+ */
+declare function makesProjects(holder: Holdings): boolean;
+//#endregion
+export { instanceRoleGrants as A, readsWholeLog as B, allows as C, givesService as D, credentialScopeInWords as E, issuesCredential as F, unscoped as G, runsInstance as H, makesProjects as I, ConvertedGrant as J, Conversion as K, managesService as L, isInstanceRole as M, isRole as N, grantKind as O, isScope as P, mayManageAccess as R, admits as S, covers as T, scopeInWords as U, roleGrants as V, setsUpServices as W, Narrowed as X, EveryProjectGrant as Y, convertEveryProjectGrants as Z, Role as _, Holdings as a, ServiceSetting as b, InstanceRole as c, PERMISSIONS as d, PROJECT_ONLY_PERMISSIONS as f, ROLE_NAMES as g, ROLES as h, GrantPlace as i, isCredentialScope as j, inScope as k, MAX_SCOPE_PLACES as l, Place as m, EVERYWHERE as n, INSTANCE_ROLES as o, Permission as p, ConversionInput as q, Filter as r, INSTANCE_ROLE_NAMES as s, CredentialScope as t, NOTHING as u, Scope as v, assignableToEnvironment as w, administers as x, ServiceAccount as y, normalScope as z };