@coffre/core 0.5.1 → 0.6.0

package/src/identity/signin/config.ts

@@ -17,6 +17,7 @@
  * Each returns a `SigninProvider`, and a provider that speaks neither can be
  * one of the deployment's own, in the same list.
  */
+import { GitHubApp, pkcs8Of, type GitHubAppOptions } from '../github-app.ts';
 import { GitHubSigninProvider } from './github.ts';
 import { OidcSigninProvider } from './oidc.ts';
 import type { SigninBrand, SigninProvider } from './types.ts';
@@ -95,6 +96,15 @@ export type WorkloadsOptions = {
    * loopback too, so no instance anyone else can reach ever trusts one.
    */
   allowLoopbackIssuersForDevelopment?: boolean;
+  /**
+   * The deployment's own GitHub App, `githubApp(…)`, installed on its
+   * organizations: where an owner trusts a workflow, the pages list the
+   * repositories it is installed on, private ones too, and a repository
+   * typed by name resolves through it (docs/github-app.md). The same value
+   * may sign people in, `github({ app })`. Left out, repositories are typed,
+   * and only public ones' IDs are looked up.
+   */
+  github?: GitHubApp;
 };
 
 /** Cloudflare's rate-limiting binding, as coffre calls it; `processLimits()` has the same shape. */
@@ -102,7 +112,7 @@ export type RateLimiter = { limit(options: { key: string }): Promise<{ success:
 
 export type WorkloadLimits = { perSource: RateLimiter; total: RateLimiter };
 
-export type WorkloadsConfig = { allowLoopback: boolean; limits: WorkloadLimits };
+export type WorkloadsConfig = { allowLoopback: boolean; limits: WorkloadLimits; github: GitHubApp | null };
 
 /**
  * MCP clients, Claude among them, acting as the people who connect them,
@@ -241,28 +251,63 @@ export function microsoft(
   });
 }
 
-/** GitHub accounts; with `organization`, only that organization's members. */
+/**
+ * GitHub accounts; with `organization`, only that organization's members.
+ * Through an OAuth app, or a GitHub App's OAuth client, by its credentials;
+ * or the deployment's GitHub App, `github({ app })`, the same value its
+ * `workloads.github` lists repositories with:
+ *
+ *   const app = githubApp({ appId, privateKey, clientId, clientSecret });
+ *   signin({ providers: [github({ app, organization: 'acme' })], workloads: { limits, github: app } })
+ */
 export function github(
-  options: Credentials & {
-    id?: string;
-    label?: string;
-    organization?: string;
-    webUrl?: string;
-    apiUrl?: string;
-  },
+  options: { id?: string; label?: string; organization?: string } & (
+    | (Credentials & { webUrl?: string; apiUrl?: string })
+    | { app: GitHubApp }
+  ),
 ): GitHubSigninProvider {
   const id = checkId(options.id ?? 'github');
+  const how = ((): Credentials & { webUrl?: string; apiUrl?: string } => {
+    if (!('app' in options)) return options;
+    const client = options.app instanceof GitHubApp ? options.app.signinClient() : null;
+    if (client === null) {
+      throw new Error(`sign-in provider ${id} signs in with the GitHub App's OAuth client: githubApp({ appId, privateKey, clientId, clientSecret })`);
+    }
+    return { ...client, webUrl: options.app.webUrl, apiUrl: options.app.apiUrl };
+  })();
   return new GitHubSigninProvider({
     id,
     label: options.label ?? 'GitHub',
     brand: 'github',
-    ...credentials(id, options),
-    webUrl: baseUrl(options.webUrl ?? 'https://github.com', `sign-in provider ${id} web URL`),
-    apiUrl: baseUrl(options.apiUrl ?? 'https://api.github.com', `sign-in provider ${id} API URL`),
+    ...credentials(id, how),
+    webUrl: baseUrl(how.webUrl ?? 'https://github.com', `sign-in provider ${id} web URL`),
+    apiUrl: baseUrl(how.apiUrl ?? 'https://api.github.com', `sign-in provider ${id} API URL`),
     organization: options.organization?.trim() || null,
   });
 }
 
+/**
+ * The deployment's GitHub App, checked where it is written: its numeric ID
+ * and private key, and its OAuth client when it signs people in too. One
+ * value, passed to each side that uses it: `github({ app })` and
+ * `workloads.github` (`../github-app.ts`).
+ */
+export function githubApp(options: GitHubAppOptions): GitHubApp {
+  const appId = String(options.appId ?? '').trim();
+  if (!/^[1-9][0-9]{0,19}$/.test(appId)) throw new Error('githubApp(…).appId must be the app\'s numeric ID (its settings page, "App ID"), not its client ID');
+  const [clientId, clientSecret] = [options.clientId?.trim() || null, options.clientSecret || null];
+  if ((clientId === null) !== (clientSecret === null)) {
+    throw new Error('githubApp(…) takes its OAuth client whole, clientId and clientSecret, or neither');
+  }
+  return new GitHubApp({
+    appId,
+    pkcs8: pkcs8Of(options.privateKey),
+    webUrl: baseUrl(options.webUrl ?? 'https://github.com', 'githubApp(…).webUrl'),
+    apiUrl: baseUrl(options.apiUrl ?? 'https://api.github.com', 'githubApp(…).apiUrl'),
+    ...(clientId === null || clientSecret === null ? {} : { client: { clientId, clientSecret } }),
+  });
+}
+
 function isLoopback(url: URL): boolean {
   return url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '[::1]';
 }
@@ -370,7 +415,15 @@ function workloadsConfig(options: WorkloadsOptions, publicUrl: string): Workload
       `workloads.allowLoopbackIssuersForDevelopment is for an instance on loopback, and ${publicUrl} is not one: turn it off`,
     );
   }
-  return { allowLoopback: loopback, limits: options.limits };
+  const app = options.github;
+  if (app !== undefined && !(app instanceof GitHubApp)) {
+    throw new Error('workloads.github is the deployment\'s GitHub App: githubApp({ appId, privateKey })');
+  }
+  // Its repositories' IDs are trusted under github.com's issuer, the one the lookup and the pages bind to.
+  if (app !== undefined && app.apiUrl !== 'https://api.github.com' && !isLoopback(new URL(app.apiUrl))) {
+    throw new Error('workloads.github is for github.com: GitHub Enterprise Server is not supported yet; sign in with its app, and leave workloads.github out');
+  }
+  return { allowLoopback: loopback, limits: options.limits, github: app ?? null };
 }
 
 /** A deployment's own provider is checked like coffre's: it is only typed, not trusted. */

package/src/identity/signin/github.ts

@@ -86,12 +86,16 @@ export class GitHubSigninProvider implements SigninProvider {
     }
 
     const organization = this.config.organization;
-    if (organization !== null && !(await this.#isMember(token, organization))) {
+    const standing = organization === null ? 'member' : await this.#membership(token, organization);
+    if (standing === 'unseen') {
       throw new SigninError(
         'not_in_organization',
-        `only members of the ${organization} organization may sign in with ${label}`,
+        `${label} would not show ${organization}'s members to coffre: a GitHub App needs the Members organization permission, read, and to be installed on ${organization}; an OAuth app, the organization's approval`,
       );
     }
+    if (standing === 'outside') {
+      throw new SigninError('not_in_organization', `only members of the ${organization} organization may sign in with ${label}`);
+    }
 
     const listed = await this.#api<GitHubEmail[]>(token, '/user/emails');
     const emails = (Array.isArray(listed) ? listed : [])
@@ -136,17 +140,25 @@ export class GitHubSigninProvider implements SigninProvider {
     return body.access_token;
   }
 
-  async #isMember(token: string, organization: string): Promise<boolean> {
+  /**
+   * Whether the person is an active member: `outside` when GitHub says they
+   * are not (404), `unseen` when it will not say (403), which a GitHub App's
+   * user token gets without the Members permission or an installation on
+   * the organization, and an OAuth app's where the organization restricts
+   * it. Either way, no sign-in.
+   */
+  async #membership(token: string, organization: string): Promise<'member' | 'outside' | 'unseen'> {
     const response = await this.#send(
       `${this.config.apiUrl}/user/memberships/orgs/${encodeURIComponent(organization)}`,
       { headers: apiHeaders(token) },
     );
-    if (response.status === 404 || response.status === 403) return false;
+    if (response.status === 404) return 'outside';
+    if (response.status === 403) return 'unseen';
     const body = (await readJson(response)) as { state?: unknown } | null;
     if (!response.ok || body === null) {
       throw new SigninError('invalid_response', `${this.config.label} answered the membership check with ${response.status}`);
     }
-    return body.state === 'active';
+    return body.state === 'active' ? 'member' : 'outside';
   }
 
   async #api<T>(token: string, path: string): Promise<T | null> {

package/src/identity/workloads.ts

@@ -15,6 +15,12 @@
  *               workflow_ref: 'acme/api/.github/workflows/ci.yml@refs/heads/main',
  *               ref: 'refs/heads/main',
  *               event_name: ['pull_request', 'push', 'workflow_dispatch'] } }
+ *
+ * A GitHub binding may also name `environment`, the GitHub environment its
+ * job runs in, so that the environment's protection rules (its required
+ * reviewers, the branches it deploys) gate every run that signs in. GitHub
+ * changes `sub` for such a job, `repo:acme/api:environment:production`, but
+ * no GitHub binding matches `sub`: `ref` and `workflow_ref` stay as they were.
  */
 
 export const GITHUB_ISSUER = 'https://token.actions.githubusercontent.com';
@@ -106,6 +112,13 @@ const DIGITS = /^[1-9][0-9]{0,19}$/;
 const SHA = /^[0-9a-f]{40}$/;
 const REF = /^refs\/(heads|tags)\/\S{1,200}$/;
 const WORKFLOW = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/\.github\/workflows\/[^@\s]+\.ya?ml@\S+$/;
+/**
+ * A GitHub environment's name, as GitHub takes one: at most 255 characters,
+ * none a control character, and no space at either end, which GitHub would
+ * not keep. GitHub documents no narrower set: `production`, `Staging EU`
+ * and `prod/eu:1` are all names.
+ */
+const ENVIRONMENT = /^(?! )[^\p{Cc}]{1,255}(?<! )$/u;
 
 /** A claim a binding names: one value, or, for what started the run, any of several. */
 export type ClaimValue = string | string[];
@@ -209,6 +222,9 @@ function checkGitHub(profile: WorkloadProfile, claims: BindingClaims): void {
     const value = claims[id];
     if (value !== undefined && !DIGITS.test(value as string)) throw new BindingInvalid(`${id} is GitHub's numeric ID, not a name`);
   }
+  if (claims.environment !== undefined && !ENVIRONMENT.test(claims.environment as string)) {
+    throw new BindingInvalid('environment is a GitHub environment\'s name: at most 255 characters, no control character, no space at either end');
+  }
   const events = claimValues(claims.event_name);
   const ref = claims.ref as string;
   if (!REF.test(ref)) throw new BindingInvalid('ref is a full ref: refs/heads/<branch> or refs/tags/<tag>');
@@ -245,17 +261,24 @@ function checkGitLab(claims: BindingClaims): void {
 /**
  * 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>`.
+ * value, or one of its values. On GitHub's profiles, two readings:
+ *
+ * - A `pull_request` run, at `refs/pull/<n>/merge`, counts as a run at the
+ *   branch it merges into: its `ref`, and the ref its `workflow_ref` ends
+ *   in, are read as `refs/heads/<base_ref>`.
+ * - `environment` matches whatever its case: GitHub's environment names are
+ *   case-insensitive, so `Production` and `production` are one environment,
+ *   under the same protection rules.
  */
 export function differingClaims(profile: WorkloadProfile, expected: BindingClaims, token: Record<string, unknown>): string[] {
-  const claims = profile.startsWith('github') ? atBaseBranch(token) : token;
+  const github = profile.startsWith('github');
+  const claims = github ? atBaseBranch(token) : token;
   return Object.entries(expected)
     .filter(([name, value]) => {
       const actual = claims[name];
-      return typeof actual !== 'string' || !claimValues(value).includes(actual);
+      if (typeof actual !== 'string') return true;
+      if (github && name === 'environment') return actual.toLowerCase() !== (value as string).toLowerCase();
+      return !claimValues(value).includes(actual);
     })
     .map(([name]) => name);
 }
@@ -351,13 +374,18 @@ function started(input: Record<string, unknown>, one: string, many: string): Cla
   return list as string[];
 }
 
-/** A workflow of the repository, run at `ref` by any of `events`; a pull request, by the branch it merges into. */
+/**
+ * A workflow of the repository, run at `ref` by any of `events`; a pull
+ * request, by the branch it merges into. An `environment` narrows it to the
+ * jobs that run in that GitHub environment.
+ */
 export function githubWorkflow(input: {
   repository: string;
   repositoryId: string;
   ownerId: string;
   workflow: string;
   ref: string;
+  environment?: string;
 } & Starts<'event', 'events'>): Omit<BindingPolicy, 'issuer'> {
   return {
     profile: 'github',
@@ -367,14 +395,21 @@ export function githubWorkflow(input: {
       workflow_ref: workflowRef(input.repository, input.workflow, input.ref),
       ref: input.ref,
       event_name: started(input, 'event', 'events'),
+      ...inEnvironment(input.environment),
     },
   };
 }
 
+/** The `environment` claim, when one is named. */
+function inEnvironment(environment: string | undefined): BindingClaims {
+  return environment === undefined ? {} : { environment };
+}
+
 /**
  * A reusable workflow at one commit, called at `ref`: from one repository,
  * or, with `repositoryId` null, from any repository of the organization. A
- * `caller` workflow narrows it to one calling workflow.
+ * `caller` workflow narrows it to one calling workflow, and an
+ * `environment` to the jobs that run in that GitHub environment.
  */
 export function githubReusable(input: {
   repositoryId: string | null;
@@ -383,6 +418,7 @@ export function githubReusable(input: {
   called: string;
   sha: string;
   caller?: { repository: string; workflow: string };
+  environment?: string;
 } & Starts<'event', 'events'>): Omit<BindingPolicy, 'issuer'> {
   const claims: BindingClaims = {
     repository_owner_id: input.ownerId,
@@ -391,6 +427,7 @@ export function githubReusable(input: {
     event_name: started(input, 'event', 'events'),
     job_workflow_ref: input.called,
     job_workflow_sha: input.sha,
+    ...inEnvironment(input.environment),
   };
   if (input.caller !== undefined) claims.workflow_ref = workflowRef(input.caller.repository, input.caller.workflow, input.ref);
   return { profile: input.repositoryId === null ? 'github-reusable-organization' : 'github-reusable', claims };

package/src/vault.ts

@@ -56,20 +56,30 @@ export interface Vault {
   endReferences(input: EndReferencesInput): Promise<Outcome<{ seqs: number[] }>>;
 
   /**
-   * What one principal holds right now: the app asks once per request. A
-   * decision, its rows checked: lists of who holds what read the rows
-   * themselves, and need not ask.
+   * What one principal holds right now: the app asks once per request,
+   * and at sign-in for each verified email. A decision, its rows checked:
+   * lists of who holds what read the rows themselves, and need not ask.
+   * A person the vault's `owners` names who is no Owner of all of it
+   * becomes one here, logged (`reason: 'owners'`).
    */
   access(principal: string): Promise<Access>;
-  /** Set roles at several places for one principal: all of it, or none. */
-  setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[] }>>;
+  /**
+   * Set roles at several places for one principal: all of it, or none.
+   * With `admit`, a service account that is not a member is admitted
+   * first, in the same decision, as `admit` would: `admitted` says so.
+   */
+  setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[]; admitted?: Admitted }>>;
   /**
    * 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; role: InstanceRole; scope: Scope; generation: number }>>;
-  /** Remove a member: revoke every grant and refuse them until admitted again, from `generation` on. */
+  admit(input: AdmitInput): Promise<Outcome<Admitted>>;
+  /**
+   * Remove a member: revoke every grant and refuse them until admitted
+   * again, from `generation` on. An Owner, only an Owner of the whole
+   * instance removes, and never the last.
+   */
   remove(input: RemoveInput): Promise<Outcome<{ revoked: Grant[]; generation: number }>>;
   /**
    * The instance's settings, as the vault's newest `settings.change` entry
@@ -96,10 +106,22 @@ export interface Vault {
   /**
    * What the vault's configuration says, which the app shows: the keys its
    * checkpoints verify under, by the key id each checkpoint names (the one
-   * it signs with now, and those of the KEKs it replaced), and the root
-   * admins, as principals.
+   * it signs with now, and those of the KEKs it replaced).
    */
-  about(): Promise<{ checkpointKeys: Record<string, CheckpointKey>; rootAdmins: string[] }>;
+  about(): Promise<{
+    checkpointKeys: Record<string, CheckpointKey>;
+    /**
+     * The emails of those the deployment names Owners of the whole instance
+     * (`owners`), lowercased: the vault makes them Owners, and refuses to
+     * demote or remove them. Absent from a vault of 0.5, which names none.
+     */
+    owners?: string[];
+    /**
+     * @deprecated Always empty: an app of 0.5, deployed after this vault,
+     * lists and checks root admins here until it is. Gone in 0.7.
+     */
+    rootAdmins: [];
+  }>;
   /**
    * What an escrowed vault key is checked against: the vault key it wraps
    * under now, and each one's check, as the vault wrote it. None of it is
@@ -150,8 +172,12 @@ export type RefusalCode =
   | 'ended'
   /** Not allowed to manage access, members or the log. */
   | 'not_allowed'
-  /** Root admins come from the vault's configuration and cannot be changed. */
-  | 'root_admin'
+  /**
+   * The change would leave the instance without an Owner of all of it: the
+   * last one is not demoted, narrowed or removed, by anyone, until another
+   * is made.
+   */
+  | 'last_owner'
   /** 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. */
@@ -282,22 +308,19 @@ export type Access = {
   /**
    * `unknown` for someone never admitted, `tampered` for a member whose row
    * fails the vault's integrity check: refused everything, as `removed` is.
-   * Root admins are always active.
    */
   status: 'active' | 'removed' | 'unknown' | 'tampered';
   /** Advanced by removal, even if the app cannot commit its credential revocations. */
   generation: number;
-  isRootAdmin: 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.
+   * for service accounts and anyone not active. 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. */
+  /** When the status last changed, and who changed it; null for strangers. */
   since: string | null;
   by: string | null;
 };
@@ -317,6 +340,12 @@ export type SetAccessInput = Correlation & Through & {
   actor: string;
   principal: string;
   changes: GrantChange[];
+  /**
+   * Admit the principal, a service account, unless it is a member: a
+   * grant refused admits nobody. A vault older than this refuses one that
+   * is not a member, `not_a_member`, and admits nobody either.
+   */
+  admit?: boolean;
 };
 
 export type AdmitInput = Correlation & Through & {
@@ -325,12 +354,19 @@ export type AdmitInput = Correlation & Through & {
   /**
    * 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.
+   * Changing it takes someone who runs the instance, about someone else;
+   * making someone an Owner, or changing an Owner's, an Owner of the whole
+   * instance, who may change their own too. It never leaves the instance
+   * without an Owner of all of it (`last_owner`), nor demotes one the
+   * deployment names (`owners`; `not_allowed`).
    */
   role?: InstanceRole;
   scope?: Scope;
 };
 
+/** A member as `admit` left them; `created` when they were not one before. */
+export type Admitted = { created: boolean; role: InstanceRole; scope: Scope; generation: number };
+
 export type RemoveInput = Correlation & Through & {
   actor: string;
   principal: string;