@theholocron/holocron-plugin-sentry 5.0.0-alpha.436 → 5.0.0-alpha.437

package/dist/index.d.mts

@@ -12,7 +12,10 @@ export declare const resolveComlinkToken: import("@theholocron/cli").FeatureReso
  * fallback only helps if the general token happens to carry the scopes; otherwise Sentry's answer names what is missing.
  */
 export declare function resolveRelayToken(input?: ResolveTokenInput): string;
-/** Every token this plugin takes, for `holocron doctor secrets --verify`: the general one and the Comlink relay's own. */
+/**
+ * Every token this plugin takes, for `holocron doctor secrets --verify`, each with what its layer's token must and must not be
+ * able to do: the general one, the Comlink relay's own and the CI release token.
+ */
 export declare const tokens: PluginToken[];
 /** Options for the Sentry `errors` capability. */
 interface SentryErrorsOptions {
@@ -97,6 +100,7 @@ export declare function errors(ctx: PluginContext): Errors;
 export declare function createPlugin(options: SentryPluginOptions): {
   name: string;
   probes: {
+    token: import("@theholocron/cli").Probe;
     connection: import("@theholocron/cli").Probe;
   };
   capabilities: {

package/dist/index.mjs

@@ -1,8 +1,45 @@
-import { AuthError, ProviderApiError, connectionProbe, createFeatureResolver, createResolveToken } from "@theholocron/cli";
+import { AuthError, ProviderApiError, connectionProbe, createFeatureResolver, createResolveToken, tokenExpectations } from "@theholocron/cli";
 import { createEnvLookup, holocronEnv } from "@theholocron/env-utils/lookup";
 import { randomUUID } from "node:crypto";
-import { createSentryClient } from "@theholocron/sentry-client";
 import { errorMessage } from "@theholocron/misc-utils";
+import { createSentryClient } from "@theholocron/sentry-client";
+// src/probes/token/expectations.ts
+const READS = {
+	org: "required",
+	projects: "required"
+};
+/**
+* The general token provisions projects and their DSNs and lives on a laptop (`local` inherits `dev`): it needs
+* `org:read` and `project:read`. `project:write` has no read that proves it, so it is not probed; the permission table
+* in `docs/src/content/docs/tokens.mdx` lists it. This is the plugin's `tokens` declaration, read through
+* `tokenExpectations()`; change it and that table together.
+*/
+const GENERAL = { permissions: {
+	local: READS,
+	dev: READS
+} };
+const RELAY_READS = {
+	org: "required",
+	projects: "required",
+	alerts: "required"
+};
+/**
+* The Comlink relay's token makes an integration and an alert rule, so on top of the general token's reads it needs
+* `alerts:read`. Its write scopes (`org:write`, `alerts:write`) and `event:read` are not probed, as no read proves them.
+*/
+const COMLINK = { permissions: {
+	local: RELAY_READS,
+	dev: RELAY_READS
+} };
+/**
+* The release token only creates a release and uploads sourcemaps (an organization token with `org:ci`), so it must not
+* read the organization, its projects or its alert rules: a leak from CI cannot reach them.
+*/
+const RELEASE = { permissions: { ci: {
+	org: "absent",
+	projects: "absent",
+	alerts: "absent"
+} } };
 // src/auth.ts
 /** Resolves the Sentry token from `--token`, `HOLOCRON_SENTRY_TOKEN`, `SENTRY_AUTH_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
 const resolveToken = createResolveToken({
@@ -32,8 +69,34 @@ function resolveRelayToken(input = {}) {
 		return resolveToken(input);
 	}
 }
-/** Every token this plugin takes, for `holocron doctor secrets --verify`: the general one and the Comlink relay's own. */
-const tokens = [resolveToken.token, resolveComlinkToken.token];
+/**
+* The token only `release.yml` reads (sentry-cli makes the release and uploads sourcemaps): an organization token with
+* `org:ci` held in the `ci` layer. The plugin never resolves it, so it is `optional` and `verifiable: false` (the
+* plugin's `verifyToken` lists organizations, which this token must not be able to do); it is declared so the probe and
+* `holocron probe sentry token --environment ci` can find it and check that it reaches nothing else.
+*/
+const releaseToken = {
+	envName: "HOLOCRON_SENTRY_RELEASE_TOKEN",
+	keyringKey: "sentry.release",
+	optional: true,
+	verifiable: false,
+	expect: RELEASE
+};
+/**
+* Every token this plugin takes, for `holocron doctor secrets --verify`, each with what its layer's token must and must not be
+* able to do: the general one, the Comlink relay's own and the CI release token.
+*/
+const tokens = [
+	{
+		...resolveToken.token,
+		expect: GENERAL
+	},
+	{
+		...resolveComlinkToken.token,
+		expect: COMLINK
+	},
+	releaseToken
+];
 // src/capabilities/relay.ts
 /** What the integration needs to read: the alert's event. It is also why reading its secret needs the same scope. */
 const INTEGRATION_SCOPES = ["event:read"];
@@ -575,6 +638,163 @@ function sentryProbes(deps) {
 		"send-error": sendErrorProbe(deps)
 	};
 }
+// src/probes/token/parse-token-args.ts
+/** Reads `--layer <word>` and `--token-name <VAR>` (either spelling). Anything else, and a flag with no value, is ignored. */
+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/token.ts
+/** How many names to show before "(+N more)". */
+const SHOWN = 5;
+/** `a, b, c (+2 more)`. */
+function summarise(names) {
+	return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
+}
+/**
+* Reads one list and says what came back. Sentry answers a token without the scope with a 401 or 403, and an empty
+* list may only mean there are none, so an empty list is `none` too. Any other failure (the network, a 404, a 5xx) is an
+* `error`.
+*/
+async function reach(read, noun) {
+	try {
+		const items = await read();
+		if (items.length === 0) return {
+			kind: "none",
+			detail: `no ${noun} visible (none exist, or the token cannot see them)`
+		};
+		const names = items.map((i) => i.slug ?? i.name).filter((n) => typeof n === "string");
+		return {
+			kind: "has",
+			detail: names.length > 0 ? `${items.length} ${noun}: ${summarise(names)}` : `${items.length} ${noun}`
+		};
+	} catch (err) {
+		if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
+			kind: "none",
+			detail: `no access (${err.status})`
+		};
+		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 has ? {
+		status: "ok",
+		label,
+		detail: outcome.detail
+	} : {
+		status: "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: reads what Holocron reads from Sentry (the organizations, the projects and the alert rules) with a
+* token and reports which of them it reaches. It only reads, so it changes nothing. The token is the one the plugin
+* resolves, so `--token sentry=<token>` or `--environment <layer>` checks another one; the organization is the
+* provider's `org` option. A write scope (`project:write`, `org:write`, `alerts:write`) has no read that proves it, so it
+* is not probed.
+*
+* A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
+* `local`), the results are judged against what that layer's token is meant to carry (the plugin's `tokens`
+* declaration, read with `tokenExpectations()` and narrowed to the token `--token-name` names, which the CLI passes for
+* each declared token the Environment holds) 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 Sentry read Holocron uses (organizations, projects, alert rules) with a token 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 token = ctx.token();
+			probe.secret(token);
+			const client = ctx.client();
+			const rules = layer ? tokenExpectations(tokens, {
+				layer,
+				...tokenName ? { envName: tokenName } : {}
+			})[0]?.rules : void 0;
+			if (layer && !rules) probe.say({
+				status: "info",
+				label: layer,
+				detail: "no expectations are declared for it, so the token is only described"
+			});
+			const tried = [{
+				label: "Organizations: Read",
+				permission: "org",
+				outcome: await reach(() => client.auth.organizations(), "organizations")
+			}];
+			const org = ctx.org;
+			if (org) {
+				tried.push({
+					label: "Projects: Read",
+					permission: "projects",
+					outcome: await reach(() => client.projects.list(org), "projects")
+				});
+				tried.push({
+					label: "Alert rules: Read",
+					permission: "alerts",
+					outcome: await reach(() => client.workflows.list(org), "alert rules")
+				});
+			} else probe.say({
+				status: rules ? "fail" : "info",
+				label: "projects and alert rules",
+				detail: "no org: set `org` in the sentry provider's options to check them"
+			});
+			if (!rules) {
+				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/verify-token.ts
 /** Checks a Sentry token by listing its organizations; the success subject is `org:` and the first organization's slug, the failure carries the error message. */
 async function verifyToken(token, opts = {}) {
@@ -632,6 +852,11 @@ function createPlugin(options) {
 				client: ctx.relayClient,
 				fetch: options.fetch
 			}),
+			token: tokenProbe({
+				org: options.org,
+				client: ctx.client,
+				token: () => resolveToken(options)
+			}),
 			connection: connectionProbe({
 				provider: "Sentry",
 				url: options.baseUrl ?? "https://sentry.io",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-sentry",
-  "version": "5.0.0-alpha.436",
+  "version": "5.0.0-alpha.437",
   "description": "Holocron plugin for Sentry. Implements the errors capability against Sentry's management API — project provisioning and DSN retrieval.",
   "keywords": [
     "errors",
@@ -45,18 +45,18 @@
     "typescript": "^5.9.3",
     "vitest": "^5.1.0",
     "@theholocron/eslint-config": "^8.9.0-alpha.17",
-    "@theholocron/http-client": "^1.58.0-alpha.32",
+    "@theholocron/cli": "5.0.0-alpha.437",
     "@theholocron/misc-utils": "^1.17.0-alpha.4",
     "@theholocron/sentry-client": "^1.58.0-alpha.32",
     "@theholocron/tsconfig": "^8.9.0-alpha.17",
     "@theholocron/tsdown-config": "^8.9.0-alpha.17",
     "@theholocron/vitest-config": "^8.9.0-alpha.17",
-    "@theholocron/cli": "5.0.0-alpha.436"
+    "@theholocron/http-client": "^1.58.0-alpha.32"
   },
   "peerDependencies": {
     "@theholocron/misc-utils": "^1.16.0",
     "@theholocron/sentry-client": "^1.56.0",
-    "@theholocron/cli": "5.0.0-alpha.436"
+    "@theholocron/cli": "5.0.0-alpha.437"
   },
   "peerDependenciesMeta": {
     "@theholocron/sentry-client": {}