@coffre/core 0.5.1 → 0.6.1

package/dist/workloads.d.ts

@@ -16,6 +16,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 declare const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
 export declare const GITLAB_ISSUER = "https://gitlab.com";
@@ -94,10 +100,14 @@ 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>`.
+ * 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 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. */
@@ -129,18 +139,24 @@ export declare function workflowRef(repository: string, file: string, ref: strin
  * 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. */
+/**
+ * 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 declare function githubWorkflow(input: {
   repository: string;
   repositoryId: string;
   ownerId: string;
   workflow: string;
   ref: string;
+  environment?: string;
 } & 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
- * `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 declare function githubReusable(input: {
   repositoryId: string | null;
@@ -152,6 +168,7 @@ export declare function githubReusable(input: {
     repository: string;
     workflow: string;
   };
+  environment?: string;
 } & 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: {

package/dist/workloads.js

@@ -16,6 +16,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.
 */
 const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
 const GITLAB_ISSUER = "https://gitlab.com";
@@ -135,6 +141,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 binding that breaks a rule, said so an owner can fix it. */
 var BindingInvalid = class extends Error {
 	constructor(message) {
@@ -230,6 +243,7 @@ function checkGitHub(profile, claims) {
 		const value = claims[id];
 		if (value !== void 0 && !DIGITS.test(value)) throw new BindingInvalid(`${id} is GitHub's numeric ID, not a name`);
 	}
+	if (claims.environment !== void 0 && !ENVIRONMENT.test(claims.environment)) 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;
 	if (!REF.test(ref)) throw new BindingInvalid("ref is a full ref: refs/heads/<branch> or refs/tags/<tag>");
@@ -254,16 +268,23 @@ function checkGitLab(claims) {
 /**
 * 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.
 */
 function differingClaims(profile, expected, token) {
-	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.toLowerCase();
+		return !claimValues(value).includes(actual);
 	}).map(([name]) => name);
 }
 function atBaseBranch(claims) {
@@ -329,7 +350,11 @@ function started(input, one, many) {
 	if (list === void 0) throw new BindingInvalid(`name ${one} or ${many}`);
 	return list;
 }
-/** A workflow of the repository, run at `ref` by any of `events`; a pull request, by the branch it merges into. */
+/**
+* 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.
+*/
 function githubWorkflow(input) {
 	return {
 		profile: "github",
@@ -338,14 +363,20 @@ function githubWorkflow(input) {
 			repository_id: input.repositoryId,
 			workflow_ref: workflowRef(input.repository, input.workflow, input.ref),
 			ref: input.ref,
-			event_name: started(input, "event", "events")
+			event_name: started(input, "event", "events"),
+			...inEnvironment(input.environment)
 		}
 	};
 }
+/** The `environment` claim, when one is named. */
+function inEnvironment(environment) {
+	return environment === void 0 ? {} : { 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.
 */
 function githubReusable(input) {
 	const claims = {
@@ -354,7 +385,8 @@ function githubReusable(input) {
 		ref: input.ref,
 		event_name: started(input, "event", "events"),
 		job_workflow_ref: input.called,
-		job_workflow_sha: input.sha
+		job_workflow_sha: input.sha,
+		...inEnvironment(input.environment)
 	};
 	if (input.caller !== void 0) claims.workflow_ref = workflowRef(input.caller.repository, input.caller.workflow, input.ref);
 	return {

package/package.json

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

package/src/access-conversion.ts

@@ -184,7 +184,7 @@ function holdsAlready(
   at: Place,
 ): boolean {
   const lasting = held.filter((other) => outlasts(other.expiresAt, grant.expiresAt));
-  return ROLES[grant.role].permissions.every((permission) => allows({ isRootAdmin: false, role, scope, grants: lasting }, permission, at));
+  return ROLES[grant.role].permissions.every((permission) => allows({ role, scope, grants: lasting }, permission, at));
 }
 
 /** Whether `role` holds nothing `wider` does not. */

package/src/access.ts

@@ -96,7 +96,7 @@ export function assignableToEnvironment(role: Role): boolean {
 export const INSTANCE_ROLES = {
   member: {
     name: 'Member',
-    description: 'Only what projects grant.',
+    description: 'None.',
     permissions: [],
   },
   auditor: {
@@ -116,7 +116,7 @@ export const INSTANCE_ROLES = {
   },
   owner: {
     name: 'Owner',
-    description: 'Everything an admin does, and read every secret.',
+    description: 'Everything, every secret included.',
     permissions: [...PERMISSIONS],
   },
 } as const satisfies Record<string, {
@@ -142,6 +142,16 @@ export function administers(role: InstanceRole): boolean {
   return role === 'admin' || role === 'owner';
 }
 
+/**
+ * Whether a role and its scope make someone an Owner of the whole
+ * instance: the one standing the instance always keeps at least one of,
+ * and the one its bootstrap gives while it has none. An Owner scoped to
+ * `market` owns market, not the instance.
+ */
+export function ownsInstance(standing: { role: InstanceRole; scope: Scope }): boolean {
+  return standing.role === 'owner' && unscoped(standing.scope);
+}
+
 /**
  * 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
@@ -311,8 +321,6 @@ export function isCredentialScope(value: unknown): value is CredentialScope {
  * cannot drift apart.
  */
 export 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;
@@ -323,7 +331,7 @@ export type Holdings = {
 };
 
 /** Someone who holds nothing: a stranger, a removed member, a tampered row. */
-export const NOTHING: Holdings = { isRootAdmin: false, role: 'member', scope: EVERYWHERE, grants: [] };
+export const NOTHING: Holdings = { role: 'member', scope: EVERYWHERE, grants: [] };
 
 /**
  * Whether a grant at `grant` reaches `place`:
@@ -353,7 +361,6 @@ export function covers(grant: GrantPlace, place: Place): boolean {
  */
 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 (instanceRoleGrants(holder.role, permission) && inScope(holder.scope, place)) return true;
   return holdsAt(holder.grants, permission, place);
 }
@@ -374,14 +381,14 @@ export 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
+ * Whether the holder runs the instance: 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));
+  return administers(holder.role) && unscoped(holder.scope);
 }
 
 /**
@@ -463,12 +470,12 @@ export function issuesCredential(
  * 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
+ * narrows nothing, an Auditor's included. 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));
+  return instanceRoleGrants(holder.role, 'audit.read') && unscoped(holder.scope);
 }
 
 /**
@@ -478,7 +485,6 @@ export function readsWholeLog(holder: Holdings): boolean {
  * 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);
 }

package/src/identity/github-app.ts

@@ -0,0 +1,347 @@
+/**
+ * The deployment's own GitHub App, made once with `githubApp(…)` and passed
+ * to each side that uses it (docs/github-app.md):
+ *
+ *   const app = githubApp({ appId, privateKey, clientId, clientSecret });
+ *   signin({ providers: [github({ app })], workloads: { limits, github: app } })
+ *
+ * Sign-in uses its OAuth client, `clientId` and `clientSecret`, as it would
+ * an OAuth app's (`github({ app })`). The forge side, `workloads.github`,
+ * uses its ID and private key: it lists the repositories the app is
+ * installed on, private ones too, where an owner trusts a workflow, and
+ * resolves `owner/name` to the IDs a binding names, with Metadata:
+ * read-only, so what it reaches there is the names and IDs of those
+ * repositories. Either side may go without the other: `github({ clientId,
+ * clientSecret })` signs in alone, and an app with no client lists alone.
+ *
+ * The app's private key lives with the app, the rest of the deployment's
+ * configuration, not in the vault: it opens no secret, and the vault's
+ * isolation is for the keys that do. It and the client secret stay in this
+ * object's private fields, and no message, log line or answer carries them,
+ * the JWTs it signs or the installation tokens they buy.
+ *
+ * The object lives as long as its configuration: the isolate's, on Workers,
+ * or the process's. It keeps settled values only (AGENTS.md, "What an
+ * isolate keeps"): the imported key, the app's name, and each
+ * installation's token until shortly before it expires. Concurrent first
+ * calls each import and ask for their own.
+ */
+
+export type GitHubAppOptions = {
+  /** The app's ID, on its settings page ("App ID"): a number, not its client ID. */
+  appId: string | number;
+  /** A private key generated on its settings page: the PEM file, as downloaded. */
+  privateKey: string;
+  /** Its OAuth client, on the same page: for signing people in with it, `github({ app })`. Both, or neither. */
+  clientId?: string;
+  clientSecret?: string;
+  /** https://github.com, or a GitHub Enterprise Server host: where people sign in. */
+  webUrl?: string;
+  /**
+   * https://api.github.com, or `${host}/api/v3` on Enterprise Server. The
+   * forge side takes github.com's only, or the dev IdP's on loopback: an
+   * Enterprise Server's runs sign their tokens under another issuer than
+   * the one its lookups bind to.
+   */
+  apiUrl?: string;
+};
+
+/** A repository, by the IDs a binding names: what `GET /workloads/lookup` answers. */
+export type GitHubRepository = { github: string; repositoryId: string; ownerId: string; private: boolean };
+
+/** What the app reaches: its name and where to install it, the accounts it is installed on, and their repositories. */
+export type GitHubAppRepositories = {
+  app: { name: string; installUrl: string };
+  /** The accounts it is installed on, by login. */
+  installations: string[];
+  /** By name. */
+  repositories: GitHubRepository[];
+  /** More than one listing reaches: the others are typed by name. */
+  truncated: boolean;
+};
+
+/** GitHub could not be asked, or refused the app: the message says which, for a person, and carries no credential. */
+export class GitHubAppUnavailable extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'GitHubAppUnavailable';
+  }
+}
+
+/** GitHub answers 100 per page at most. */
+const PAGE = 100;
+/** Requests one listing makes at most, tokens included: well under a Worker's subrequest limit. */
+export const MAX_LISTING_REQUESTS = 40;
+/** A token GitHub issues for an hour is used until this long before it ends, so that none expires mid-call. */
+export const TOKEN_MARGIN_MS = 5 * 60 * 1000;
+/** Each request, from DNS to the last byte. */
+const DEADLINE_MS = 10_000;
+
+type Installation = { id: number; account: string };
+type Token = { token: string; expiresAt: number };
+
+export class GitHubApp {
+  readonly appId: string;
+  readonly webUrl: string;
+  readonly apiUrl: string;
+  /** Its OAuth client's ID, which is no secret; null when it was given none. */
+  readonly clientId: string | null;
+  readonly #clientSecret: string | null;
+  readonly #pkcs8: Uint8Array<ArrayBuffer>;
+  readonly #fetch: typeof fetch;
+  readonly #now: () => number;
+  #key: CryptoKey | null = null;
+  #app: GitHubAppRepositories['app'] | null = null;
+  readonly #tokens = new Map<number, Token>();
+
+  constructor(
+    options: { appId: string; apiUrl: string; webUrl?: string; pkcs8: Uint8Array<ArrayBuffer>; client?: { clientId: string; clientSecret: string } },
+    io: { fetch?: typeof fetch; now?: () => number } = {},
+  ) {
+    this.appId = options.appId;
+    this.webUrl = options.webUrl ?? 'https://github.com';
+    this.apiUrl = options.apiUrl;
+    this.clientId = options.client?.clientId ?? null;
+    this.#clientSecret = options.client?.clientSecret ?? null;
+    this.#pkcs8 = options.pkcs8;
+    this.#fetch = io.fetch ?? ((input, init) => fetch(input, init));
+    this.#now = io.now ?? Date.now;
+  }
+
+  /** Its OAuth client, for `github({ app })`; null when it was given none. */
+  signinClient(): { clientId: string; clientSecret: string } | null {
+    return this.clientId === null || this.#clientSecret === null ? null : { clientId: this.clientId, clientSecret: this.#clientSecret };
+  }
+
+  /** Every repository of every account the app is installed on, as many as `MAX_LISTING_REQUESTS` reach. */
+  async repositories(): Promise<GitHubAppRepositories> {
+    // Every request the listing makes spends from it, tokens and retries included.
+    const budget: Budget = { left: MAX_LISTING_REQUESTS };
+    this.#app ??= await this.#appInfo(budget);
+    const { installations, more } = await this.#installations(budget);
+    let truncated = more;
+    /** An installation's repositories, its first page paid from `own`, and the rest from what the listing has left. */
+    const list = async (installation: Installation, own: Budget): Promise<GitHubRepository[]> => {
+      const repositories: GitHubRepository[] = [];
+      try {
+        for (let page = 1; ; page++) {
+          const body = record(await this.#asInstallation(installation.id, `/installation/repositories?per_page=${PAGE}&page=${page}`, { budget: own }));
+          const items = Array.isArray(body.repositories) ? body.repositories : [];
+          repositories.push(...items.flatMap((item) => repository(item) ?? []));
+          const total = typeof body.total_count === 'number' ? body.total_count : 0;
+          if (items.length < PAGE || page * PAGE >= total) return repositories;
+        }
+      } catch (error) {
+        if (error !== SPENT) throw error;
+        truncated = true;
+        return repositories;
+      }
+    };
+    // In waves, at once within each: every installation of a wave reserves what its first page can cost at
+    // worst, a token and the page, or a kept token refused, a new one and the page again, so that each one
+    // started finishes its first page. What a wave did not spend goes to the next.
+    const listed: GitHubRepository[][] = [];
+    for (let rest = installations; rest.length > 0; ) {
+      const wave: { installation: Installation; own: Budget }[] = [];
+      for (const installation of rest) {
+        const worst = this.#kept(installation.id) === null ? 2 : 3;
+        if (budget.left < worst) break;
+        budget.left -= worst;
+        wave.push({ installation, own: { left: worst, then: budget } });
+      }
+      if (wave.length === 0) {
+        truncated = true;
+        break;
+      }
+      rest = rest.slice(wave.length);
+      listed.push(...(await Promise.all(wave.map(({ installation, own }) => list(installation, own)))));
+      for (const { own } of wave) budget.left += own.left;
+    }
+    const byId = new Map(listed.flat().map((each) => [each.repositoryId, each]));
+    return {
+      app: this.#app,
+      installations: installations.map(({ account }) => account),
+      repositories: [...byId.values()].sort((a, b) => a.github.localeCompare(b.github)),
+      truncated,
+    };
+  }
+
+  /** `owner/name`'s IDs, when the app is installed on it; null when it is not, its installation is suspended, or GitHub knows no such repository. */
+  async repository(fullName: string): Promise<GitHubRepository | null> {
+    const { id, suspended_at: suspended } = record(await this.#asApp(`/repos/${fullName}/installation`, { missing: true }));
+    if (typeof id !== 'number' || (suspended !== null && suspended !== undefined)) return null;
+    return repository(await this.#asInstallation(id, `/repos/${fullName}`, { missing: true }));
+  }
+
+  async #appInfo(budget: Budget): Promise<GitHubAppRepositories['app']> {
+    const app = record(await this.#asApp('/app', { budget }));
+    if (typeof app.name !== 'string' || typeof app.html_url !== 'string') throw new GitHubAppUnavailable('GitHub answered /app without the app');
+    return { name: app.name, installUrl: `${app.html_url}/installations/new` };
+  }
+
+  /** The installations not suspended, of the first page: `more` when there may be others. */
+  async #installations(budget: Budget): Promise<{ installations: Installation[]; more: boolean }> {
+    const answer = await this.#asApp(`/app/installations?per_page=${PAGE}`, { budget });
+    const items = Array.isArray(answer) ? answer : [];
+    const installations = items.flatMap((item): Installation[] => {
+      const { id, account, suspended_at: suspended } = record(item);
+      const login = record(account).login;
+      return typeof id === 'number' && typeof login === 'string' && (suspended === null || suspended === undefined) ? [{ id, account: login }] : [];
+    });
+    return { installations: installations.sort((a, b) => a.account.localeCompare(b.account)), more: items.length >= PAGE };
+  }
+
+  async #asApp(path: string, options: { missing?: boolean; budget?: Budget } = {}): Promise<unknown> {
+    return this.#call(path, { method: 'GET', token: await this.#jwt(), ...options });
+  }
+
+  /** As the installation, with its token; once more with a fresh one should GitHub refuse the one kept (the app was reinstalled, say). */
+  async #asInstallation(id: number, path: string, options: { missing?: boolean; budget?: Budget } = {}): Promise<unknown> {
+    const kept = this.#kept(id);
+    const fresh = kept === null;
+    const token = kept ?? (await this.#issueToken(id, options.budget));
+    const answer = await this.#call(path, { method: 'GET', token, ...options, refused: !fresh });
+    if (answer !== REFUSED) return answer;
+    return this.#call(path, { method: 'GET', token: await this.#issueToken(id, options.budget), ...options });
+  }
+
+  /** The installation's token, while it has more than `TOKEN_MARGIN_MS` to live. */
+  #kept(id: number): string | null {
+    const kept = this.#tokens.get(id);
+    return kept !== undefined && kept.expiresAt - TOKEN_MARGIN_MS > this.#now() ? kept.token : null;
+  }
+
+  /** https://docs.github.com/en/rest/apps/apps#create-an-installation-access-token-for-an-app */
+  async #issueToken(id: number, budget?: Budget): Promise<string> {
+    this.#tokens.delete(id);
+    const answer = record(await this.#call(`/app/installations/${id}/access_tokens`, { method: 'POST', token: await this.#jwt(), budget }));
+    const expiresAt = typeof answer.expires_at === 'string' ? Date.parse(answer.expires_at) : NaN;
+    if (typeof answer.token !== 'string' || !Number.isFinite(expiresAt)) throw new GitHubAppUnavailable('GitHub issued no installation token');
+    this.#tokens.set(id, { token: answer.token, expiresAt });
+    return answer.token;
+  }
+
+  /**
+   * The app's JWT: RS256 over its ID, for nine minutes, issued a minute
+   * back for a clock running ahead (GitHub refuses more than ten).
+   * https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app
+   */
+  async #jwt(): Promise<string> {
+    const key = this.#key ?? (this.#key = await importKey(this.#pkcs8));
+    const now = Math.floor(this.#now() / 1000);
+    const input = `${base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))}.${base64url(JSON.stringify({ iat: now - 60, exp: now + 540, iss: this.appId }))}`;
+    const signature = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, new TextEncoder().encode(input));
+    return `${input}.${base64url(new Uint8Array(signature))}`;
+  }
+
+  /**
+   * One request, spent from `budget` when it has one, and thrown as
+   * `SPENT` when none is left. A 404 is null where `missing` allows it; a
+   * 401 is `REFUSED` where `refused` asks, for a token to be issued again;
+   * any other answer than a 2xx says GitHub's status and the path, and a
+   * redirect is never followed.
+   */
+  async #call(path: string, request: { method: 'GET' | 'POST'; token: string; missing?: boolean; refused?: boolean; budget?: Budget }): Promise<unknown> {
+    if (request.budget !== undefined && !spend(request.budget)) throw SPENT;
+    let response: Response;
+    try {
+      response = await this.#fetch(`${this.apiUrl}${path}`, {
+        method: request.method,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(DEADLINE_MS),
+        headers: {
+          accept: 'application/vnd.github+json',
+          authorization: `Bearer ${request.token}`,
+          'user-agent': 'coffre',
+          'x-github-api-version': '2022-11-28',
+        },
+      });
+    } catch (cause) {
+      throw new GitHubAppUnavailable('GitHub could not be reached', { cause });
+    }
+    if (response.ok) {
+      try {
+        return await response.json();
+      } catch {
+        throw new GitHubAppUnavailable(`GitHub answered ${path.split('?')[0]} with no JSON`);
+      }
+    }
+    await response.body?.cancel();
+    if (response.status === 404 && request.missing === true) return null;
+    if (response.status === 401 && request.refused === true) return REFUSED;
+    if (response.status === 401) throw new GitHubAppUnavailable(`GitHub refused the app (401): check its app ID and private key`);
+    throw new GitHubAppUnavailable(`GitHub answered ${path.split('?')[0]} with ${response.status}`);
+  }
+}
+
+/** A kept token GitHub refused. */
+const REFUSED = Symbol('refused');
+/** A listing's requests, left to make: an installation's own reserve first, then the listing's. */
+type Budget = { left: number; then?: Budget };
+
+function spend(budget: Budget | undefined): boolean {
+  for (let at = budget; at !== undefined; at = at.then) {
+    if (at.left > 0) {
+      at.left--;
+      return true;
+    }
+  }
+  return false;
+}
+/** None left: the listing stops there, and says it is partial. */
+const SPENT = Symbol('spent');
+
+/**
+ * A private key's PEM as PKCS #8, which Web Crypto imports: GitHub's
+ * download is PKCS #1 (`BEGIN RSA PRIVATE KEY`), wrapped here as an RSA
+ * key's PKCS #8. Escaped newlines, as an environment variable sometimes
+ * holds them, are newlines. Never says what the key was.
+ */
+export function pkcs8Of(pem: string): Uint8Array<ArrayBuffer> {
+  const text = typeof pem === 'string' ? pem.replaceAll('\\n', '\n').trim() : '';
+  const match = /^-----BEGIN (RSA )?PRIVATE KEY-----\s*([A-Za-z0-9+/=\s]+?)\s*-----END \1PRIVATE KEY-----$/.exec(text);
+  if (match === null) {
+    throw new Error('githubApp(…).privateKey must be the app\'s private key, the PEM file GitHub downloads (BEGIN RSA PRIVATE KEY)');
+  }
+  const der = new Uint8Array(Buffer.from(match[2]!.replace(/\s+/g, ''), 'base64'));
+  if (match[1] === undefined) return der;
+  // PrivateKeyInfo: version 0, rsaEncryption with no parameters, and the PKCS #1 key as an octet string.
+  const algorithm = [0x02, 0x01, 0x00, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00];
+  const octets = [0x04, ...derLength(der.length)];
+  const body = algorithm.length + octets.length + der.length;
+  const out = new Uint8Array(new ArrayBuffer(1 + derLength(body).length + body));
+  out.set([0x30, ...derLength(body), ...algorithm, ...octets]);
+  out.set(der, out.length - der.length);
+  return out;
+}
+
+function derLength(length: number): number[] {
+  if (length < 0x80) return [length];
+  const bytes: number[] = [];
+  for (let rest = length; rest > 0; rest >>= 8) bytes.unshift(rest & 0xff);
+  return [0x80 | bytes.length, ...bytes];
+}
+
+async function importKey(pkcs8: Uint8Array<ArrayBuffer>): Promise<CryptoKey> {
+  try {
+    return await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+  } catch {
+    throw new GitHubAppUnavailable('the GitHub App\'s private key is not an RSA private key');
+  }
+}
+
+function base64url(value: string | Uint8Array): string {
+  return Buffer.from(value).toString('base64url');
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+/** A repository as GitHub's API answers it, by the IDs a binding names. */
+function repository(value: unknown): GitHubRepository | null {
+  const { id, full_name: name, owner, private: hidden } = record(value);
+  const ownerId = record(owner).id;
+  if (typeof name !== 'string' || !Number.isSafeInteger(id) || !Number.isSafeInteger(ownerId)) return null;
+  return { github: name, repositoryId: String(id), ownerId: String(ownerId), private: hidden === true };
+}

package/src/identity/index.ts

@@ -1,5 +1,6 @@
 // `@coffre/core/identity`: who is asking, and how coffre's sign-in finds out.
 export * from './auth.ts';
+export * from './github-app.ts';
 export * from './signin/index.ts';
 export * from './tokens.ts';
 export * from './types.ts';