@coffre/core 0.5.1 → 0.6.1

package/dist/{access-CwsFLfTz.d.ts → access-BpcBLDW9.d.ts}

@@ -166,7 +166,7 @@ declare function assignableToEnvironment(role: Role): boolean;
 declare const INSTANCE_ROLES: {
   readonly member: {
     readonly name: "Member";
-    readonly description: "Only what projects grant.";
+    readonly description: "None.";
     readonly permissions: readonly [];
   };
   readonly auditor: {
@@ -186,7 +186,7 @@ declare const INSTANCE_ROLES: {
   };
   readonly owner: {
     readonly name: "Owner";
-    readonly description: "Everything an admin does, and read every secret.";
+    readonly description: "Everything, every secret included.";
     readonly permissions: readonly ["secret.read", "secret.write", "secret.archive", "audit.read", "environment.manage", "grant.manage", "project.manage"];
   };
 };
@@ -196,6 +196,16 @@ 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;
+/**
+ * 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.
+ */
+declare function ownsInstance(standing: {
+  role: InstanceRole;
+  scope: Scope;
+}): 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
@@ -303,8 +313,6 @@ declare function isCredentialScope(value: unknown): value is CredentialScope;
  * 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;
@@ -342,8 +350,8 @@ declare function allows(holder: Holdings, permission: Permission, place: Place):
  */
 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
+ * 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.
@@ -404,7 +412,7 @@ declare function issuesCredential(holder: Holdings, setting: ServiceSetting | nu
  * 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.
  */
@@ -417,4 +425,4 @@ declare function readsWholeLog(holder: Holdings): boolean;
  */
 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 };
+export { instanceRoleGrants as A, ownsInstance as B, allows as C, givesService as D, credentialScopeInWords as E, issuesCredential as F, setsUpServices as G, roleGrants as H, makesProjects as I, ConversionInput as J, unscoped as K, managesService as L, isInstanceRole as M, isRole as N, grantKind as O, isScope as P, convertEveryProjectGrants as Q, mayManageAccess as R, admits as S, covers as T, runsInstance as U, readsWholeLog as V, scopeInWords as W, EveryProjectGrant as X, ConvertedGrant as Y, Narrowed 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, Conversion 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 };

package/dist/{access-pnJ-u4x2.js → access-DvwZzqRR.js}

@@ -137,7 +137,6 @@ function byRole(role, scope, grant) {
 function holdsAlready(role, scope, held, grant, at) {
 	const lasting = held.filter((other) => outlasts(other.expiresAt, grant.expiresAt));
 	return ROLES[grant.role].permissions.every((permission) => allows({
-		isRootAdmin: false,
 		role,
 		scope,
 		grants: lasting
@@ -241,7 +240,7 @@ function assignableToEnvironment(role) {
 const INSTANCE_ROLES = {
 	member: {
 		name: "Member",
-		description: "Only what projects grant.",
+		description: "None.",
 		permissions: []
 	},
 	auditor: {
@@ -266,7 +265,7 @@ const INSTANCE_ROLES = {
 	},
 	owner: {
 		name: "Owner",
-		description: "Everything an admin does, and read every secret.",
+		description: "Everything, every secret included.",
 		permissions: [...PERMISSIONS]
 	}
 };
@@ -281,6 +280,15 @@ function instanceRoleGrants(role, permission) {
 function administers(role) {
 	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.
+*/
+function ownsInstance(standing) {
+	return standing.role === "owner" && unscoped(standing.scope);
+}
 /** Every project and every environment. */
 const EVERYWHERE = {
 	projects: "all",
@@ -387,7 +395,6 @@ function isCredentialScope(value) {
 }
 /** Someone who holds nothing: a stranger, a removed member, a tampered row. */
 const NOTHING = {
-	isRootAdmin: false,
 	role: "member",
 	scope: EVERYWHERE,
 	grants: []
@@ -416,7 +423,6 @@ function covers(grant, place) {
 */
 function allows(holder, permission, place) {
 	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);
 }
@@ -434,14 +440,14 @@ function mayManageAccess(actor, place) {
 	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
+* 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.
 */
 function runsInstance(holder) {
-	return holder.isRootAdmin || administers(holder.role) && unscoped(holder.scope);
+	return administers(holder.role) && unscoped(holder.scope);
 }
 /**
 * Whether `holder` may give a service account `role` at `place`: where
@@ -500,12 +506,12 @@ function issuesCredential(holder, setting, actor, account, scope) {
 * 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.
 */
 function readsWholeLog(holder) {
-	return holder.isRootAdmin || instanceRoleGrants(holder.role, "audit.read") && unscoped(holder.scope);
+	return instanceRoleGrants(holder.role, "audit.read") && unscoped(holder.scope);
 }
 /**
 * Whether the holder may make a project: an Admin or Owner whose scope
@@ -514,9 +520,8 @@ function readsWholeLog(holder) {
 * hold the project around them.
 */
 function makesProjects(holder) {
-	if (holder.isRootAdmin) return true;
 	const { projects, environments } = holder.scope;
 	return administers(holder.role) && environments === "all" && (projects === "all" || "except" in projects);
 }
 //#endregion
-export { roleGrants as A, isScope as C, mayManageAccess as D, managesService as E, convertEveryProjectGrants as F, scopeInWords as M, setsUpServices as N, normalScope as O, unscoped as P, isRole as S, makesProjects as T, grantKind as _, NOTHING as a, isCredentialScope as b, ROLES as c, admits as d, allows as f, givesService as g, credentialScopeInWords as h, MAX_SCOPE_PLACES as i, runsInstance as j, readsWholeLog as k, ROLE_NAMES as l, covers as m, INSTANCE_ROLES as n, PERMISSIONS as o, assignableToEnvironment as p, INSTANCE_ROLE_NAMES as r, PROJECT_ONLY_PERMISSIONS as s, EVERYWHERE as t, administers as u, inScope as v, issuesCredential as w, isInstanceRole as x, instanceRoleGrants as y };
+export { readsWholeLog as A, isScope as C, mayManageAccess as D, managesService as E, unscoped as F, convertEveryProjectGrants as I, runsInstance as M, scopeInWords as N, normalScope as O, setsUpServices as P, isRole as S, makesProjects as T, grantKind as _, NOTHING as a, isCredentialScope as b, ROLES as c, admits as d, allows as f, givesService as g, credentialScopeInWords as h, MAX_SCOPE_PLACES as i, roleGrants as j, ownsInstance as k, ROLE_NAMES as l, covers as m, INSTANCE_ROLES as n, PERMISSIONS as o, assignableToEnvironment as p, INSTANCE_ROLE_NAMES as r, PROJECT_ONLY_PERMISSIONS as s, EVERYWHERE as t, administers as u, inScope as v, issuesCredential as w, isInstanceRole as x, instanceRoleGrants as y };

package/dist/access.d.ts

@@ -1,2 +1,2 @@
-import { A as instanceRoleGrants, B as readsWholeLog, C as allows, D as givesService, E as credentialScopeInWords, F as issuesCredential, G as unscoped, H as runsInstance, I as makesProjects, J as ConvertedGrant, K as Conversion, L as managesService, M as isInstanceRole, N as isRole, O as grantKind, P as isScope, R as mayManageAccess, S as admits, T as covers, U as scopeInWords, V as roleGrants, W as setsUpServices, X as Narrowed, Y as EveryProjectGrant, Z as convertEveryProjectGrants, _ as Role, a as Holdings, b as ServiceSetting, c as InstanceRole, d as PERMISSIONS, f as PROJECT_ONLY_PERMISSIONS, g as ROLE_NAMES, h as ROLES, i as GrantPlace, j as isCredentialScope, k as inScope, l as MAX_SCOPE_PLACES, m as Place, n as EVERYWHERE, o as INSTANCE_ROLES, p as Permission, q as ConversionInput, r as Filter, s as INSTANCE_ROLE_NAMES, t as CredentialScope, u as NOTHING, v as Scope, w as assignableToEnvironment, x as administers, y as ServiceAccount, z as normalScope } from "./access-CwsFLfTz.js";
-export { type Conversion, type ConversionInput, type ConvertedGrant, CredentialScope, EVERYWHERE, type EveryProjectGrant, Filter, GrantPlace, Holdings, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, InstanceRole, MAX_SCOPE_PLACES, NOTHING, type Narrowed, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, Permission, Place, ROLES, ROLE_NAMES, Role, Scope, ServiceAccount, ServiceSetting, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, givesService, grantKind, inScope, instanceRoleGrants, isCredentialScope, isInstanceRole, isRole, isScope, issuesCredential, makesProjects, managesService, mayManageAccess, normalScope, readsWholeLog, roleGrants, runsInstance, scopeInWords, setsUpServices, unscoped };
+import { A as instanceRoleGrants, B as ownsInstance, C as allows, D as givesService, E as credentialScopeInWords, F as issuesCredential, G as setsUpServices, H as roleGrants, I as makesProjects, J as ConversionInput, K as unscoped, L as managesService, M as isInstanceRole, N as isRole, O as grantKind, P as isScope, Q as convertEveryProjectGrants, R as mayManageAccess, S as admits, T as covers, U as runsInstance, V as readsWholeLog, W as scopeInWords, X as EveryProjectGrant, Y as ConvertedGrant, Z as Narrowed, _ as Role, a as Holdings, b as ServiceSetting, c as InstanceRole, d as PERMISSIONS, f as PROJECT_ONLY_PERMISSIONS, g as ROLE_NAMES, h as ROLES, i as GrantPlace, j as isCredentialScope, k as inScope, l as MAX_SCOPE_PLACES, m as Place, n as EVERYWHERE, o as INSTANCE_ROLES, p as Permission, q as Conversion, r as Filter, s as INSTANCE_ROLE_NAMES, t as CredentialScope, u as NOTHING, v as Scope, w as assignableToEnvironment, x as administers, y as ServiceAccount, z as normalScope } from "./access-BpcBLDW9.js";
+export { type Conversion, type ConversionInput, type ConvertedGrant, CredentialScope, EVERYWHERE, type EveryProjectGrant, Filter, GrantPlace, Holdings, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, InstanceRole, MAX_SCOPE_PLACES, NOTHING, type Narrowed, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, Permission, Place, ROLES, ROLE_NAMES, Role, Scope, ServiceAccount, ServiceSetting, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, givesService, grantKind, inScope, instanceRoleGrants, isCredentialScope, isInstanceRole, isRole, isScope, issuesCredential, makesProjects, managesService, mayManageAccess, normalScope, ownsInstance, readsWholeLog, roleGrants, runsInstance, scopeInWords, setsUpServices, unscoped };

package/dist/access.js

@@ -1,2 +1,2 @@
-import { A as roleGrants, C as isScope, D as mayManageAccess, E as managesService, F as convertEveryProjectGrants, M as scopeInWords, N as setsUpServices, O as normalScope, P as unscoped, S as isRole, T as makesProjects, _ as grantKind, a as NOTHING, b as isCredentialScope, c as ROLES, d as admits, f as allows, g as givesService, h as credentialScopeInWords, i as MAX_SCOPE_PLACES, j as runsInstance, k as readsWholeLog, l as ROLE_NAMES, m as covers, n as INSTANCE_ROLES, o as PERMISSIONS, p as assignableToEnvironment, r as INSTANCE_ROLE_NAMES, s as PROJECT_ONLY_PERMISSIONS, t as EVERYWHERE, u as administers, v as inScope, w as issuesCredential, x as isInstanceRole, y as instanceRoleGrants } from "./access-pnJ-u4x2.js";
-export { EVERYWHERE, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, MAX_SCOPE_PLACES, NOTHING, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_NAMES, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, givesService, grantKind, inScope, instanceRoleGrants, isCredentialScope, isInstanceRole, isRole, isScope, issuesCredential, makesProjects, managesService, mayManageAccess, normalScope, readsWholeLog, roleGrants, runsInstance, scopeInWords, setsUpServices, unscoped };
+import { A as readsWholeLog, C as isScope, D as mayManageAccess, E as managesService, F as unscoped, I as convertEveryProjectGrants, M as runsInstance, N as scopeInWords, O as normalScope, P as setsUpServices, S as isRole, T as makesProjects, _ as grantKind, a as NOTHING, b as isCredentialScope, c as ROLES, d as admits, f as allows, g as givesService, h as credentialScopeInWords, i as MAX_SCOPE_PLACES, j as roleGrants, k as ownsInstance, l as ROLE_NAMES, m as covers, n as INSTANCE_ROLES, o as PERMISSIONS, p as assignableToEnvironment, r as INSTANCE_ROLE_NAMES, s as PROJECT_ONLY_PERMISSIONS, t as EVERYWHERE, u as administers, v as inScope, w as issuesCredential, x as isInstanceRole, y as instanceRoleGrants } from "./access-DvwZzqRR.js";
+export { EVERYWHERE, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, MAX_SCOPE_PLACES, NOTHING, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_NAMES, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, givesService, grantKind, inScope, instanceRoleGrants, isCredentialScope, isInstanceRole, isRole, isScope, issuesCredential, makesProjects, managesService, mayManageAccess, normalScope, ownsInstance, readsWholeLog, roleGrants, runsInstance, scopeInWords, setsUpServices, unscoped };

package/dist/identity.d.ts

@@ -1,5 +1,120 @@
 import { BindingClaims, BindingInvalid, BindingPolicy, ClaimValue, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, Starts, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, claimValues, defaultIssuer, differingClaims, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, workflowRef } from "./workloads.js";
 import { JSONWebKeySet, JWTPayload } from "jose";
+//#region src/identity/github-app.d.ts
+/**
+ * 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 declare class GitHubAppUnavailable extends Error {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/** Requests one listing makes at most, tokens included: well under a Worker's subrequest limit. */
+export declare 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 declare const TOKEN_MARGIN_MS: number;
+export declare class GitHubApp {
+  #private;
+  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;
+  constructor(options: {
+    appId: string;
+    apiUrl: string;
+    webUrl?: string;
+    pkcs8: Uint8Array<ArrayBuffer>;
+    client?: {
+      clientId: string;
+      clientSecret: string;
+    };
+  }, io?: {
+    fetch?: typeof fetch;
+    now?: () => number;
+  });
+  /** Its OAuth client, for `github({ app })`; null when it was given none. */
+  signinClient(): {
+    clientId: string;
+    clientSecret: string;
+  } | null;
+  /** Every repository of every account the app is installed on, as many as `MAX_LISTING_REQUESTS` reach. */
+  repositories(): Promise<GitHubAppRepositories>;
+  /** `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. */
+  repository(fullName: string): Promise<GitHubRepository | null>;
+}
+/**
+ * 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 declare function pkcs8Of(pem: string): Uint8Array<ArrayBuffer>;
+//#endregion
 //#region src/identity/signin/types.d.ts
 /**
  * What a provider reports about the person who just signed in.
@@ -216,6 +331,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. */
 export type RateLimiter = {
@@ -232,6 +356,7 @@ export type WorkloadLimits = {
 export type WorkloadsConfig = {
   allowLoopback: boolean;
   limits: WorkloadLimits;
+  github: GitHubApp | null;
 };
 /**
  * MCP clients, Claude among them, acting as the people who connect them,
@@ -303,14 +428,32 @@ export declare function microsoft(options: Credentials & {
   label?: string;
   tenant: string;
 }): OidcSigninProvider;
-/** GitHub accounts; with `organization`, only that organization's members. */
-export declare function github(options: Credentials & {
+/**
+ * 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 declare function github(options: {
   id?: string;
   label?: string;
   organization?: string;
+} & ((Credentials & {
   webUrl?: string;
   apiUrl?: string;
-}): GitHubSigninProvider;
+}) | {
+  app: GitHubApp;
+})): GitHubSigninProvider;
+/**
+ * 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 declare function githubApp(options: GitHubAppOptions): GitHubApp;
 export declare function publicOrigin(value: string): string;
 /** Sign-in configuration, checked: at least one provider, each whole, ids unique, lifetimes sane. */
 export declare function defineSignin(options: {