@theholocron/holocron-plugin-github 5.0.0-alpha.433 → 5.0.0-alpha.435

package/dist/index.d.mts

@@ -377,6 +377,12 @@ export declare function syncTeams(client: GitHubClient, repo: string, teams: Tea
  * Returns the base64 ciphertext to send as `encrypted_value`.
  */
 export declare function encryptSecret(publicKeyBase64: string, value: string): Promise<string>;
+/**
+ * Every token this plugin takes, for `holocron doctor tokens`, with what each layer's token must and must not be able
+ * to do. The release token is `optional`: only CI's release workflow reads it (from the org secret), so a development
+ * environment has no reason to hold it.
+ */
+export declare const tokens: PluginToken[];
 /** Options for `verifyToken`. */
 interface VerifyTokenOptions {
   /** Overrides the API base URL, for tests. */
@@ -432,6 +438,7 @@ export declare function projects(ctx: PluginContext): Projects;
 export declare function createPlugin(options: GitHubPluginOptions): {
   name: string;
   probes: {
+    token: import("@theholocron/cli").Probe;
     connection: import("@theholocron/cli").Probe;
   };
   capabilities: {
@@ -448,9 +455,4 @@ export declare function createPlugin(options: GitHubPluginOptions): {
  * is supplied or the supplied token is rejected.
  */
 export declare const AUTH_HINT: string;
-/**
- * Every token this plugin takes, for `holocron doctor secrets --verify`. The release token is `optional`: only CI's release
- * workflow reads it (from the org secret), so a development environment has no reason to hold it.
- */
-export declare const tokens: PluginToken[];
 export { type Auth, AuthError, type CanonicalLabel, type GitHubClientOptions, type NormalizedTeamEntry, type ProjectsOptions, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createFeatureResolver, createGitHubClient };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { AuthError, MissingTokenError, ProviderApiError, connectionProbe, createFeatureResolver, pickByCreation, readKeysLimited, reportProgress } from "@theholocron/cli";
+import { AuthError, MissingTokenError, ProviderApiError, connectionProbe, createFeatureResolver, pickByCreation, readKeysLimited, reportProgress, tokenExpectations } from "@theholocron/cli";
 import { createGitHubClient, createGitHubClient as createGitHubClient$1 } from "@theholocron/github-client";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -2143,6 +2143,378 @@ async function ensureDir(path) {
 		throw err;
 	}
 }
+// src/probes/token/expectations.ts
+/** The same rules in every layer that runs the workflow: a laptop (`local` inherits `dev`) and CI. */
+function everywhere(rules) {
+	return { permissions: {
+		local: rules,
+		dev: rules,
+		ci: rules
+	} };
+}
+/**
+* What each GitHub token is meant to carry, by its `envName`, the same as the GitHub tokens table in
+* `docs/src/content/docs/tokens.mdx`. This is the plugin's `tokens` declaration, read through `tokenExpectations()`;
+* change it and that table together.
+*
+* Every token CI uses (the `sync-repo`, `sync-secrets`, `reconcile-projects` and `check-tokens` workflows read all of
+* them) is declared with the same permissions in `local`, `dev` and `ci`, so the probe checks that a `ci` token is no
+* broader than its `dev` one rather than assuming a split the workflows do not allow. The release token is held by CI
+* only, so it has no `local` or `dev` entry. A narrow token must not reach administration or secrets; the admin token
+* must not reach organization secrets (that is `HOLOCRON_SECRETS_TOKEN`'s alone).
+*/
+const EXPECTED = {
+	HOLOCRON_READ_TOKEN: everywhere({
+		contents: "required",
+		actions: "required",
+		administration: "absent",
+		secrets: "absent",
+		environments: "absent"
+	}),
+	HOLOCRON_ISSUES_TOKEN: everywhere({
+		issues: "required",
+		administration: "absent",
+		secrets: "absent",
+		environments: "absent"
+	}),
+	HOLOCRON_SYNC_TOKEN: everywhere({
+		actions: "required",
+		contents: "required",
+		"pull-requests": "required",
+		administration: "absent",
+		secrets: "absent"
+	}),
+	HOLOCRON_RELEASE_TOKEN: { permissions: { ci: {
+		contents: "required",
+		issues: "required",
+		"pull-requests": "required",
+		administration: "absent",
+		secrets: "absent"
+	} } },
+	HOLOCRON_ADMIN_TOKEN: everywhere({
+		administration: "required",
+		secrets: "required",
+		environments: "required",
+		issues: "required",
+		"custom-properties": "required",
+		"actions-variables": "required",
+		"org-secrets": "absent"
+	}),
+	HOLOCRON_SECRETS_TOKEN: everywhere({
+		"org-secrets": "required",
+		administration: "absent"
+	}),
+	HOLOCRON_DEPLOY_TOKEN: everywhere({
+		pages: "required",
+		administration: "required",
+		secrets: "absent",
+		"org-secrets": "absent"
+	}),
+	HOLOCRON_USER_SYNC_TOKEN: everywhere({
+		"user-sync-contents": "required",
+		administration: "absent",
+		secrets: "absent"
+	}),
+	HOLOCRON_ORG_TOKEN: everywhere({
+		"org-administration": "required",
+		"org-members": "required",
+		"org-variables": "required",
+		"org-secrets": "absent"
+	})
+};
+// src/tokens.ts
+/** Adds what a layer's token must and must not be able to do (`EXPECTED`, by `envName`) to a token. */
+function declared(token) {
+	return {
+		...token,
+		expect: EXPECTED[token.envName]
+	};
+}
+/**
+* Every token this plugin takes, for `holocron doctor tokens`, with what each layer's token must and must not be able
+* to do. The release token is `optional`: only CI's release workflow reads it (from the org secret), so a development
+* environment has no reason to hold it.
+*/
+const tokens = [
+	declared(resolveReadToken.token),
+	declared(resolveIssuesToken.token),
+	declared(resolveSyncToken.token),
+	declared({
+		...resolveReleaseToken.token,
+		optional: true
+	}),
+	declared(resolveAdminToken.token),
+	declared(resolveSecretsToken.token),
+	declared(resolveDeployToken.token),
+	declared(resolveUserSyncToken.token),
+	declared(resolveOrgToken.token)
+];
+// src/probes/token/parse-token-args.ts
+/** Reads the words after the probe name: `--layer <word>` and `--token-name <VAR>`, in either spelling. */
+function parseTokenArgs(args) {
+	let layer;
+	let tokenName;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--layer") layer = args[++i];
+		else if (arg.startsWith("--layer=")) layer = arg.slice(8);
+		else if (arg === "--token-name") tokenName = args[++i];
+		else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
+	}
+	return {
+		...layer ? { layer } : {},
+		...tokenName ? { tokenName } : {}
+	};
+}
+// src/probes/token/permissions.ts
+/**
+* Every permission the GitHub plugin's tokens are declared against, by the name the declaration uses, with one read
+* that needs it. A read proves the token can see the area, not that it can write to it: GitHub exposes no list of a
+* fine-grained token's permissions, so the write half of `read/write` is taken from the permission table in
+* `docs/src/content/docs/tokens.mdx`. On a public repository the `contents`, `actions`, `issues` and `pull-requests`
+* reads succeed for any token, so only the other permissions can prove a permission absent. Names with more than one
+* word are hyphenated, not underscored: `holocron probe docs tokens` strips `_` (Markdown emphasis) from a table cell
+* before it compares the id with the declaration.
+*/
+const PERMISSIONS = {
+	contents: {
+		label: "Contents",
+		path: "/repos/{r}/contents"
+	},
+	actions: {
+		label: "Actions",
+		path: "/repos/{r}/actions/runs?per_page=1"
+	},
+	issues: {
+		label: "Issues",
+		path: "/repos/{r}/issues?per_page=1"
+	},
+	"pull-requests": {
+		label: "Pull requests",
+		path: "/repos/{r}/pulls?per_page=1"
+	},
+	administration: {
+		label: "Administration",
+		path: "/repos/{r}/actions/permissions"
+	},
+	secrets: {
+		label: "Secrets",
+		path: "/repos/{r}/actions/secrets?per_page=1"
+	},
+	environments: {
+		label: "Environments",
+		path: "/repos/{r}/environments?per_page=1"
+	},
+	"actions-variables": {
+		label: "Variables",
+		path: "/repos/{r}/actions/variables?per_page=1"
+	},
+	"custom-properties": {
+		label: "Custom properties",
+		path: "/repos/{r}/properties/values"
+	},
+	pages: {
+		label: "Pages",
+		path: "/repos/{r}/pages"
+	},
+	"org-administration": {
+		label: "Organization: Administration",
+		path: "/orgs/{o}/actions/permissions"
+	},
+	"org-members": {
+		label: "Organization: Members",
+		path: "/orgs/{o}/members?per_page=1"
+	},
+	"org-variables": {
+		label: "Organization: Variables",
+		path: "/orgs/{o}/actions/variables?per_page=1"
+	},
+	"org-secrets": {
+		label: "Organization: Secrets",
+		path: "/orgs/{o}/actions/secrets?per_page=1"
+	},
+	"user-sync-contents": {
+		label: "Contents (.github-private)",
+		path: "/repos/{o}/.github-private/contents"
+	}
+};
+// src/probes/token/token.ts
+/** The token checked when none is named: the one the plugin reads with by default. */
+const DEFAULT_TOKEN = "HOLOCRON_READ_TOKEN";
+/** Does one GET with the token; the response headers are returned for the caller that wants them. */
+async function get(ctx, token, path) {
+	return ctx.fetch(`${ctx.baseUrl}${path}`, { headers: {
+		authorization: `Bearer ${token}`,
+		accept: "application/vnd.github+json",
+		"x-github-api-version": "2022-11-28",
+		"user-agent": "holocron-probe"
+	} });
+}
+/**
+* One read for one permission. GitHub answers a token without the permission with a 403, or a 404 for something it will
+* not admit exists, so both are `none`; a 2xx is `has`. Any other status, or a request that did not go through, is an
+* `error`, which is a failure whatever the layer expects.
+*/
+async function reach(ctx, token, permission) {
+	const [owner = ""] = ctx.repo.split("/");
+	const path = PERMISSIONS[permission].path.replaceAll("{r}", ctx.repo).replaceAll("{o}", owner);
+	try {
+		const res = await get(ctx, token, path);
+		if (res.ok) return {
+			kind: "has",
+			detail: `read ${path.split("?")[0]}`
+		};
+		if (res.status === 403 || res.status === 404) return {
+			kind: "none",
+			detail: `no access (${res.status})`
+		};
+		return {
+			kind: "error",
+			detail: `${res.status} ${res.statusText}`.trim()
+		};
+	} catch (err) {
+		return {
+			kind: "error",
+			detail: errorMessage(err)
+		};
+	}
+}
+/**
+* One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
+* judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
+* permission that is rightly absent is a bare `ok`.
+*/
+function rowFor({ label, outcome }, rule) {
+	if (outcome.kind === "error") return {
+		status: "fail",
+		label,
+		detail: outcome.detail
+	};
+	const has = outcome.kind === "has";
+	if (rule === "required") return {
+		status: has ? "ok" : "fail",
+		label,
+		detail: outcome.detail
+	};
+	if (rule === "absent") return has ? {
+		status: "fail",
+		label,
+		detail: outcome.detail
+	} : {
+		status: "ok",
+		label
+	};
+	return {
+		status: has ? "ok" : "info",
+		label,
+		detail: outcome.detail
+	};
+}
+/**
+* The `token` probe: `holocron probe github token` tries each permission Holocron uses with one of the plugin's nine
+* tokens and reports which ones the token reaches. It only reads (one GET per permission), so it changes nothing, and a
+* read proves the token can see an area, not that it can write there.
+*
+* GitHub lists scopes only for a classic token (the `X-OAuth-Scopes` header on any response), so a classic token's scopes
+* are shown. A fine-grained token has no list, so the permissions are found by trying them; the first row says which kind
+* was read. With `--environment <layer>` the CLI runs the probe once for each token the Environment holds and hands it
+* `--token-name <envName>` (and the token itself as `cliToken`); by hand, `--token-name` picks which token the plugin
+* resolves (default `HOLOCRON_READ_TOKEN`).
+*
+* With no layer the token is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
+* `local`), the results are judged against what that token is meant to carry in that layer (the plugin's `tokens`
+* declaration, read with `tokenExpectations()`) and shown in two groups, what it should have and what it should not,
+* where a missing or extra permission fails.
+*/
+function tokenProbe(ctx) {
+	return {
+		summary: "Try each GitHub permission Holocron uses (contents, actions, issues, administration, secrets, ...) with one of the plugin's tokens and report which it reaches; for a ci or dev Environment, check it against what that layer should carry. Read-only.",
+		writes: false,
+		acceptsToken: true,
+		async run(probe) {
+			const { layer, tokenName } = parseTokenArgs(probe.args ?? []);
+			const envName = tokenName ?? DEFAULT_TOKEN;
+			const token = ctx.resolve(envName);
+			if (token === void 0) {
+				probe.say({
+					status: "fail",
+					label: envName,
+					detail: `not a GitHub token; use one of: ${ctx.tokenNames.join(", ")}`
+				});
+				return;
+			}
+			probe.secret(token);
+			let identity;
+			try {
+				identity = await get(ctx, token, "/user");
+			} catch (err) {
+				probe.say({
+					status: "fail",
+					label: "token",
+					detail: errorMessage(err)
+				});
+				return;
+			}
+			if (identity.status === 401) {
+				probe.say({
+					status: "fail",
+					label: "token",
+					detail: "rejected by GitHub (401): expired, revoked or not a token"
+				});
+				return;
+			}
+			const scopes = identity.headers.get("x-oauth-scopes");
+			probe.say({
+				status: "ok",
+				label: "token",
+				detail: scopes === null ? "fine-grained (GitHub lists no permissions for one, so each is tried with a read)" : `classic (scopes: ${scopes === "" ? "none" : scopes}); each permission is also tried with a read`
+			});
+			const declared = layer ? tokenExpectations(tokens, {
+				layer,
+				envName
+			})[0] : void 0;
+			if (layer && !declared) probe.say({
+				status: "info",
+				label: layer,
+				detail: "no expectations are declared for this token there, so it is only described"
+			});
+			const rules = declared?.rules ?? {};
+			const names = declared ? Object.keys(rules) : Object.keys(PERMISSIONS);
+			const tried = [];
+			for (const permission of names) tried.push({
+				label: PERMISSIONS[permission].label,
+				permission,
+				outcome: await reach(ctx, token, permission)
+			});
+			if (!declared) {
+				for (const t of tried) probe.say(rowFor(t, void 0));
+				return;
+			}
+			for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
+				const inGroup = tried.filter((t) => rules[t.permission] === rule);
+				if (inGroup.length === 0) continue;
+				probe.say({
+					status: "heading",
+					label: heading
+				});
+				for (const t of inGroup) probe.say(rowFor(t, rule));
+			}
+		}
+	};
+}
+// src/token-resolvers.ts
+/** Each token's resolver by its environment variable (`HOLOCRON_ADMIN_TOKEN`), which is what `--token-name` carries. */
+const TOKEN_RESOLVERS = {
+	HOLOCRON_READ_TOKEN: resolveReadToken,
+	HOLOCRON_ISSUES_TOKEN: resolveIssuesToken,
+	HOLOCRON_SYNC_TOKEN: resolveSyncToken,
+	HOLOCRON_RELEASE_TOKEN: resolveReleaseToken,
+	HOLOCRON_ADMIN_TOKEN: resolveAdminToken,
+	HOLOCRON_SECRETS_TOKEN: resolveSecretsToken,
+	HOLOCRON_DEPLOY_TOKEN: resolveDeployToken,
+	HOLOCRON_USER_SYNC_TOKEN: resolveUserSyncToken,
+	HOLOCRON_ORG_TOKEN: resolveOrgToken
+};
 // src/verify-token.ts
 /** Checks a token against `GET /user` and returns who it belongs to, or why it failed. */
 async function verifyToken(token, opts = {}) {
@@ -2271,16 +2643,25 @@ function createPlugin(options) {
 	}
 	return {
 		name: "@theholocron/holocron-plugin-github",
-		probes: { connection: connectionProbe({
-			provider: "GitHub",
-			url: options.baseUrl ?? "https://api.github.com",
-			fetch: options.fetch,
-			token: () => resolveReadToken(options),
-			verify: (token) => verifyToken(token, {
-				baseUrl: options.baseUrl,
-				fetch: options.fetch
+		probes: {
+			token: tokenProbe({
+				repo: options.repo,
+				baseUrl: (options.baseUrl ?? "https://api.github.com").replace(/\/$/, ""),
+				fetch: options.fetch ?? fetch,
+				resolve: (envName) => TOKEN_RESOLVERS[envName]?.(options),
+				tokenNames: Object.keys(TOKEN_RESOLVERS)
+			}),
+			connection: connectionProbe({
+				provider: "GitHub",
+				url: options.baseUrl ?? "https://api.github.com",
+				fetch: options.fetch,
+				token: () => resolveReadToken(options),
+				verify: (token) => verifyToken(token, {
+					baseUrl: options.baseUrl,
+					fetch: options.fetch
+				})
 			})
-		}) },
+		},
 		capabilities: {
 			source: () => source(makeCtx(resolveAdminToken), makeOrgClient(), makeUserSyncClient()),
 			ci: () => ci(makeCtx(resolveReadToken)),
@@ -2296,22 +2677,4 @@ function createPlugin(options) {
 * is supplied or the supplied token is rejected.
 */
 const AUTH_HINT = "generate fine-grained Personal Access Tokens at https://github.com/settings/tokens (one per feature — see docs/tokens.md for required scopes per operation), then run: holocron new token github.<feature> <PAT>";
-/**
-* Every token this plugin takes, for `holocron doctor secrets --verify`. The release token is `optional`: only CI's release
-* workflow reads it (from the org secret), so a development environment has no reason to hold it.
-*/
-const tokens = [
-	resolveReadToken.token,
-	resolveIssuesToken.token,
-	resolveSyncToken.token,
-	{
-		...resolveReleaseToken.token,
-		optional: true
-	},
-	resolveAdminToken.token,
-	resolveSecretsToken.token,
-	resolveDeployToken.token,
-	resolveUserSyncToken.token,
-	resolveOrgToken.token
-];
 export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubProjects, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, projects, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSecretsToken, resolveSyncToken, resolveUserSyncToken, secrets, source, syncLabels, syncTeams, tokens, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.433",
+  "version": "5.0.0-alpha.435",
   "description": "Holocron plugin for GitHub. Implements source, ci, secrets, environments, and issues capabilities against the GitHub REST API.",
   "keywords": [
     "ci",
@@ -44,21 +44,21 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^5.1.0",
-    "@theholocron/cli": "5.0.0-alpha.433",
-    "@theholocron/eslint-config": "^8.9.0-alpha.17",
     "@theholocron/fs-utils": "^1.17.0-alpha.4",
-    "@theholocron/http-client": "^1.58.0-alpha.29",
+    "@theholocron/github-client": "^1.58.0-alpha.31",
+    "@theholocron/cli": "5.0.0-alpha.435",
     "@theholocron/misc-utils": "^1.17.0-alpha.4",
-    "@theholocron/github-client": "^1.58.0-alpha.29",
+    "@theholocron/http-client": "^1.58.0-alpha.31",
+    "@theholocron/tsconfig": "^8.9.0-alpha.17",
     "@theholocron/tsdown-config": "^8.9.0-alpha.17",
     "@theholocron/vitest-config": "^8.9.0-alpha.17",
-    "@theholocron/tsconfig": "^8.9.0-alpha.17"
+    "@theholocron/eslint-config": "^8.9.0-alpha.17"
   },
   "peerDependencies": {
     "@theholocron/fs-utils": "^1.16.0",
     "@theholocron/github-client": "^1.58.0",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.433"
+    "@theholocron/cli": "5.0.0-alpha.435"
   },
   "engines": {
     "node": ">=22"