@coffre/core 0.5.1 → 0.6.0

package/dist/identity.js

@@ -2,6 +2,328 @@ import { BindingInvalid, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_IS
 import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
 import * as oauth from "oauth4webapi";
 import { createLocalJWKSet, createRemoteJWKSet, errors, jwtVerify } from "jose";
+//#region src/identity/github-app.ts
+/** GitHub could not be asked, or refused the app: the message says which, for a person, and carries no credential. */
+var GitHubAppUnavailable = class extends Error {
+	constructor(message, options) {
+		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. */
+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. */
+const TOKEN_MARGIN_MS = 3e5;
+/** Each request, from DNS to the last byte. */
+const DEADLINE_MS = 1e4;
+var GitHubApp = class {
+	appId;
+	webUrl;
+	apiUrl;
+	/** Its OAuth client's ID, which is no secret; null when it was given none. */
+	clientId;
+	#clientSecret;
+	#pkcs8;
+	#fetch;
+	#now;
+	#key = null;
+	#app = null;
+	#tokens = /* @__PURE__ */ new Map();
+	constructor(options, io = {}) {
+		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() {
+		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() {
+		const budget = { left: 40 };
+		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, own) => {
+			const repositories = [];
+			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;
+			}
+		};
+		const listed = [];
+		for (let rest = installations; rest.length > 0;) {
+			const wave = [];
+			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) {
+		const { id, suspended_at: suspended } = record(await this.#asApp(`/repos/${fullName}/installation`, { missing: true }));
+		if (typeof id !== "number" || suspended !== null && suspended !== void 0) return null;
+		return repository(await this.#asInstallation(id, `/repos/${fullName}`, { missing: true }));
+	}
+	async #appInfo(budget) {
+		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) {
+		const answer = await this.#asApp(`/app/installations?per_page=${PAGE}`, { budget });
+		const items = Array.isArray(answer) ? answer : [];
+		return {
+			installations: items.flatMap((item) => {
+				const { id, account, suspended_at: suspended } = record(item);
+				const login = record(account).login;
+				return typeof id === "number" && typeof login === "string" && (suspended === null || suspended === void 0) ? [{
+					id,
+					account: login
+				}] : [];
+			}).sort((a, b) => a.account.localeCompare(b.account)),
+			more: items.length >= PAGE
+		};
+	}
+	async #asApp(path, options = {}) {
+		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, path, options = {}) {
+		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) {
+		const kept = this.#tokens.get(id);
+		return kept !== void 0 && kept.expiresAt - 3e5 > this.#now() ? kept.token : null;
+	}
+	/** https://docs.github.com/en/rest/apps/apps#create-an-installation-access-token-for-an-app */
+	async #issueToken(id, budget) {
+		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() {
+		const key = this.#key ?? (this.#key = await importKey(this.#pkcs8));
+		const now = Math.floor(this.#now() / 1e3);
+		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, request) {
+		if (request.budget !== void 0 && !spend(request.budget)) throw SPENT;
+		let 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");
+function spend(budget) {
+	for (let at = budget; at !== void 0; 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.
+*/
+function pkcs8Of(pem) {
+	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] === void 0) return der;
+	const algorithm = [
+		2,
+		1,
+		0,
+		48,
+		13,
+		6,
+		9,
+		42,
+		134,
+		72,
+		134,
+		247,
+		13,
+		1,
+		1,
+		1,
+		5,
+		0
+	];
+	const octets = [4, ...derLength(der.length)];
+	const body = algorithm.length + octets.length + der.length;
+	const out = new Uint8Array(new ArrayBuffer(1 + derLength(body).length + body));
+	out.set([
+		48,
+		...derLength(body),
+		...algorithm,
+		...octets
+	]);
+	out.set(der, out.length - der.length);
+	return out;
+}
+function derLength(length) {
+	if (length < 128) return [length];
+	const bytes = [];
+	for (let rest = length; rest > 0; rest >>= 8) bytes.unshift(rest & 255);
+	return [128 | bytes.length, ...bytes];
+}
+async function importKey(pkcs8) {
+	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) {
+	return Buffer.from(value).toString("base64url");
+}
+function record(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+/** A repository as GitHub's API answers it, by the IDs a binding names. */
+function repository(value) {
+	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
+	};
+}
+//#endregion
 //#region src/identity/signin/types.ts
 var SigninError = class extends Error {
 	code;
@@ -70,7 +392,9 @@ var GitHubSigninProvider = class {
 		const user = await this.#api(token, "/user");
 		if (typeof user?.id !== "number") throw new SigninError("invalid_response", `${label} did not say who signed in`);
 		const organization = this.config.organization;
-		if (organization !== null && !await this.#isMember(token, organization)) throw new SigninError("not_in_organization", `only members of the ${organization} organization may sign in with ${label}`);
+		const standing = organization === null ? "member" : await this.#membership(token, organization);
+		if (standing === "unseen") throw new SigninError("not_in_organization", `${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(token, "/user/emails");
 		const emails = (Array.isArray(listed) ? listed : []).filter((entry) => entry.verified && typeof entry.email === "string").sort((a, b) => Number(b.primary) - Number(a.primary)).map((entry) => entry.email.trim().toLowerCase());
 		return {
@@ -101,12 +425,20 @@ var GitHubSigninProvider = class {
 		if (typeof body.access_token !== "string" || body.access_token === "") throw new SigninError("invalid_response", `${label} returned no access token`);
 		return body.access_token;
 	}
-	async #isMember(token, organization) {
+	/**
+	* 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, organization) {
 		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);
 		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(token, path) {
 		const response = await this.#send(`${this.config.apiUrl}${path}`, { headers: apiHeaders(token) });
@@ -389,19 +721,59 @@ function microsoft(options) {
 		brand: "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 } })
+*/
 function github(options) {
 	const id = checkId(options.id ?? "github");
+	const how = (() => {
+		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`).
+*/
+function githubApp(options) {
+	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) {
 	return url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
 }
@@ -473,9 +845,13 @@ function workloadsConfig(options, publicUrl) {
 	if (!limiter(options.limits?.perSource) || !limiter(options.limits?.total)) throw new Error("workloads need their limits, per source and in total: on Workers, two rate-limiting bindings; on Node, processLimits()");
 	const loopback = options.allowLoopbackIssuersForDevelopment === true;
 	if (loopback && !isLoopback(new URL(publicUrl))) throw new Error(`workloads.allowLoopbackIssuersForDevelopment is for an instance on loopback, and ${publicUrl} is not one: turn it off`);
+	const app = options.github;
+	if (app !== void 0 && !(app instanceof GitHubApp)) throw new Error("workloads.github is the deployment's GitHub App: githubApp({ appId, privateKey })");
+	if (app !== void 0 && 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
+		limits: options.limits,
+		github: app ?? null
 	};
 }
 /** A deployment's own provider is checked like coffre's: it is only typed, not trusted. */
@@ -830,4 +1206,4 @@ function refusalOf(error) {
 	return new WorkloadTokenRefused("signature", "the token does not verify");
 }
 //#endregion
-export { ACCESS_JWT_HEADER, AccessIdentityVerifier, BindingInvalid, CLOCK_TOLERANCE_SECONDS, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, GitHubSigninProvider, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_TOKEN_AGE_SECONDS, MAX_TOKEN_BYTES, OidcSigninProvider, REQUIRED_CLAIMS, SigninError, WORKLOAD_ALGORITHMS, WORKLOAD_PROFILES, WorkloadTokenRefused, canonicalClaims, checkBinding, checkFetchUrl, claimValues, cloudflareAccess, decodeWorkloadToken, defaultIssuer, defineSignin, deriveKey, differingClaims, fullRef, generateToken, github, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, google, hashToken, isCoffreToken, issuedRefusal, microsoft, oidc, publicOrigin, seal, signin, toPrincipal, tokenHint, tokenKind, unseal, verifyWorkloadToken, workflowRef };
+export { ACCESS_JWT_HEADER, AccessIdentityVerifier, BindingInvalid, CLOCK_TOLERANCE_SECONDS, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, GitHubApp, GitHubAppUnavailable, GitHubSigninProvider, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_LISTING_REQUESTS, MAX_TOKEN_AGE_SECONDS, MAX_TOKEN_BYTES, OidcSigninProvider, REQUIRED_CLAIMS, SigninError, TOKEN_MARGIN_MS, WORKLOAD_ALGORITHMS, WORKLOAD_PROFILES, WorkloadTokenRefused, canonicalClaims, checkBinding, checkFetchUrl, claimValues, cloudflareAccess, decodeWorkloadToken, defaultIssuer, defineSignin, deriveKey, differingClaims, fullRef, generateToken, github, githubApp, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, google, hashToken, isCoffreToken, issuedRefusal, microsoft, oidc, pkcs8Of, publicOrigin, seal, signin, toPrincipal, tokenHint, tokenKind, unseal, verifyWorkloadToken, workflowRef };

package/dist/schemas.d.ts

@@ -29,11 +29,11 @@ export declare const principalType: z.ZodEnum<{
 }>;
 export declare const principalId: z.ZodString;
 export declare const instanceRole: z.ZodEnum<{
-  member: "member";
-  auditor: "auditor";
   developer: "developer";
-  admin: "admin";
+  auditor: "auditor";
   owner: "owner";
+  member: "member";
+  admin: "admin";
 }>;
 /** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
 export declare const scopeFilter: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{

package/dist/schemas.js

@@ -1,4 +1,4 @@
-import { r as INSTANCE_ROLE_NAMES } from "./access-pnJ-u4x2.js";
+import { r as INSTANCE_ROLE_NAMES } from "./access-DvwZzqRR.js";
 import { PROJECT_PAGES } from "./pages.js";
 import { z } from "zod";
 //#region src/schemas.ts

package/dist/vault.d.ts

@@ -1,4 +1,4 @@
-import { _ as Role, b as ServiceSetting, c as InstanceRole, i as GrantPlace, t as CredentialScope, v as Scope } from "./access-CwsFLfTz.js";
+import { _ as Role, b as ServiceSetting, c as InstanceRole, i as GrantPlace, t as CredentialScope, v as Scope } from "./access-BpcBLDW9.js";
 //#region src/access-fault.d.ts
 /**
  * Why the vault's members and grants do not follow from its log, as facts
@@ -138,27 +138,33 @@ export interface Vault {
     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. */
+  /**
+   * 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;
@@ -191,12 +197,21 @@ 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[];
+    /**
+     * 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
@@ -248,8 +263,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. */
@@ -407,22 +426,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;
 };
@@ -439,6 +455,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 & {
   actor: string;
@@ -446,11 +468,22 @@ 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;