@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.426 → 5.0.0-alpha.428

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.mjs +78 -46
  2. package/package.json +6 -6
package/dist/index.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { AuthError, ProviderApiError, connectionProbe, createResolveToken, resolveValue } from "@theholocron/cli";
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken, resolveValue, tokenExpectations } from "@theholocron/cli";
2
2
  import { PREFIX } from "@theholocron/env-utils/lookup";
3
3
  import { errorMessage } from "@theholocron/misc-utils";
4
4
  import { createCloudflareClient } from "@theholocron/cloudflare-client";
@@ -15,9 +15,10 @@ const EVERYTHING = {
15
15
  * What each layer's Cloudflare token is meant to carry, the same as "What each Cloudflare token needs" in
16
16
  * `docs/src/content/docs/tokens.mdx`: a laptop (`local` inherits `dev`) runs everything, CI only deploys Pages, so a
17
17
  * leak from CI cannot change DNS, Workers or a tunnel. A layer not listed (`prod`) has no declared expectations and its
18
- * token is only reported. Change this and that table together.
18
+ * token is only reported. This is the plugin's `tokens` declaration, read through `tokenExpectations()`; change it and
19
+ * that table together.
19
20
  */
20
- const EXPECTED_BY_LAYER = {
21
+ const EXPECTED = { permissions: {
21
22
  local: EVERYTHING,
22
23
  dev: EVERYTHING,
23
24
  ci: {
@@ -28,7 +29,7 @@ const EXPECTED_BY_LAYER = {
28
29
  pages: "required",
29
30
  tunnels: "absent"
30
31
  }
31
- };
32
+ } };
32
33
  // src/auth.ts
33
34
  /** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
34
35
  const resolveToken = createResolveToken({
@@ -40,7 +41,7 @@ const resolveToken = createResolveToken({
40
41
  /** Every token this plugin takes, for `holocron doctor tokens`, with what each layer's token must and must not be able to do. */
41
42
  const tokens = [{
42
43
  ...resolveToken.token,
43
- expect: EXPECTED_BY_LAYER
44
+ expect: EXPECTED
44
45
  }];
45
46
  // src/capabilities/deployment.ts
46
47
  /** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
@@ -452,39 +453,39 @@ async function reach(read, noun) {
452
453
  }
453
454
  }
454
455
  /**
455
- * Reports an outcome. With no rule it only describes (`ok` for access, `info` for none). With the layer's rule it judges:
456
- * a required permission that is missing fails, and a permission the layer must not have fails when the token has it.
456
+ * One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
457
+ * judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
458
+ * permission that is rightly absent is a bare `ok`.
457
459
  */
458
- function report(probe, label, outcome, rule, layer) {
459
- if (outcome.kind === "error") return probe.say({
460
+ function rowFor({ label, outcome }, rule) {
461
+ if (outcome.kind === "error") return {
460
462
  status: "fail",
461
463
  label,
462
464
  detail: outcome.detail
463
- });
465
+ };
464
466
  const has = outcome.kind === "has";
465
- if (rule === "required") return probe.say(has ? {
467
+ if (rule === "required") return has ? {
466
468
  status: "ok",
467
469
  label,
468
470
  detail: outcome.detail
469
471
  } : {
470
472
  status: "fail",
471
473
  label,
472
- detail: `${outcome.detail}; the ${layer} token needs it`
473
- });
474
- if (rule === "absent") return probe.say(has ? {
474
+ detail: outcome.detail
475
+ };
476
+ if (rule === "absent") return has ? {
475
477
  status: "fail",
476
478
  label,
477
- detail: `${outcome.detail}; the ${layer} token must not have it`
479
+ detail: outcome.detail
478
480
  } : {
479
481
  status: "ok",
480
- label,
481
- detail: `not present, as the ${layer} token should be`
482
- });
483
- probe.say({
482
+ label
483
+ };
484
+ return {
484
485
  status: has ? "ok" : "info",
485
486
  label,
486
487
  detail: outcome.detail
487
- });
488
+ };
488
489
  }
489
490
  /**
490
491
  * The `token` probe: tries each permission Holocron uses with the Cloudflare API token and reports which ones the token
@@ -492,8 +493,9 @@ function report(probe, label, outcome, rule, layer) {
492
493
  * `--token cloudflare=<token>` or `--environment <layer>` checks another one; the account id is the plugin's own.
493
494
  *
494
495
  * A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
495
- * `local`), the same results are judged against what that layer's token is meant to carry (`EXPECTED_BY_LAYER`), and a
496
- * missing or extra permission fails. The other words limit the zone checks to those zones; otherwise up to five are read.
496
+ * `local`), the results are judged against what that layer's token is meant to carry (the plugin's `tokens` declaration, read with `tokenExpectations()`) and shown in
497
+ * two groups, what it should have and what it should not, where a missing or extra permission fails. The other words
498
+ * limit the zone checks to those zones; otherwise up to five are read. How the token is chosen is in `holocron probe --help`.
497
499
  */
498
500
  function tokenProbe(ctx) {
499
501
  return {
@@ -505,12 +507,11 @@ function tokenProbe(ctx) {
505
507
  probe.secret(token);
506
508
  const client = ctx.client();
507
509
  const { layer, zones: wanted } = parseTokenArgs(probe.args ?? []);
508
- const rules = layer ? EXPECTED_BY_LAYER[layer] : void 0;
509
- const ruleFor = (permission) => rules?.[permission];
510
- if (layer) probe.say({
510
+ const rules = layer ? tokenExpectations(tokens, { layer })[0]?.rules : void 0;
511
+ if (layer && !rules) probe.say({
511
512
  status: "info",
512
513
  label: layer,
513
- detail: rules ? `checking against what the ${layer} token should carry (docs: tokens, what each Cloudflare token needs)` : `no expectations are declared for ${layer}, so the token is only described`
514
+ detail: "no expectations are declared for it, so the token is only described"
514
515
  });
515
516
  try {
516
517
  const verified = await client.tokens.verify();
@@ -519,36 +520,67 @@ function tokenProbe(ctx) {
519
520
  label: "token",
520
521
  detail: `${verified.id} (${verified.status})`
521
522
  });
522
- } catch {
523
- probe.say({
524
- status: "info",
525
- label: "token",
526
- detail: "not a user-level token, so it is judged by what it can reach below"
527
- });
528
- }
523
+ } catch {}
524
+ const tried = [];
529
525
  let zones = [];
530
526
  const zoneOutcome = await reach(async () => {
531
527
  zones = wanted.length > 0 ? (await Promise.all(wanted.map((name) => client.zones.list({ name })))).flat() : await client.zones.list({ per_page: MAX_ZONES });
532
528
  return zones.map((z) => ({ name: z.name }));
533
529
  }, "zones");
534
- report(probe, "Zone: Read", zoneOutcome, ruleFor("zone"), layer);
535
- if (zoneOutcome.kind === "error") return;
536
- for (const zone of zones.slice(0, MAX_ZONES)) {
537
- report(probe, `DNS: Edit (${zone.name})`, await reach(() => client.dns.list(zone.id), "records"), ruleFor("dns"), layer);
538
- report(probe, `Workers Routes: Edit (${zone.name})`, await reach(async () => (await client.workers.listRoutes(zone.id)).map((r) => ({ name: r.pattern })), "routes"), ruleFor("routes"), layer);
539
- }
540
- const account = ctx.options.accountId;
541
- if (!account) {
542
- probe.say({
543
- status: layer && rules ? "fail" : "info",
530
+ tried.push({
531
+ label: "Zone: Read",
532
+ permission: "zone",
533
+ outcome: zoneOutcome
534
+ });
535
+ if (zoneOutcome.kind !== "error") {
536
+ for (const zone of zones.slice(0, MAX_ZONES)) {
537
+ tried.push({
538
+ label: `DNS: Edit (${zone.name})`,
539
+ permission: "dns",
540
+ outcome: await reach(() => client.dns.list(zone.id), "records")
541
+ });
542
+ tried.push({
543
+ label: `Workers Routes: Edit (${zone.name})`,
544
+ permission: "routes",
545
+ outcome: await reach(async () => (await client.workers.listRoutes(zone.id)).map((r) => ({ name: r.pattern })), "routes")
546
+ });
547
+ }
548
+ const account = ctx.options.accountId;
549
+ if (account) {
550
+ tried.push({
551
+ label: "Workers Scripts: Edit",
552
+ permission: "scripts",
553
+ outcome: await reach(async () => (await client.workers.listScripts(account)).map((s) => ({ name: s.id })), "scripts")
554
+ });
555
+ tried.push({
556
+ label: "Pages: Edit",
557
+ permission: "pages",
558
+ outcome: await reach(() => client.pages.listProjects(account), "projects")
559
+ });
560
+ tried.push({
561
+ label: "Cloudflare Tunnel: Edit",
562
+ permission: "tunnels",
563
+ outcome: await reach(() => client.tunnels.list(account), "tunnels")
564
+ });
565
+ } else probe.say({
566
+ status: rules ? "fail" : "info",
544
567
  label: "account permissions",
545
568
  detail: "no account id: set HOLOCRON_CLOUDFLARE_ACCOUNT_ID or the plugin's accountId option to check them"
546
569
  });
570
+ }
571
+ if (!rules) {
572
+ for (const t of tried) probe.say(rowFor(t, void 0));
547
573
  return;
548
574
  }
549
- report(probe, "Workers Scripts: Edit", await reach(async () => (await client.workers.listScripts(account)).map((s) => ({ name: s.id })), "scripts"), ruleFor("scripts"), layer);
550
- report(probe, "Pages: Edit", await reach(() => client.pages.listProjects(account), "projects"), ruleFor("pages"), layer);
551
- report(probe, "Cloudflare Tunnel: Edit", await reach(() => client.tunnels.list(account), "tunnels"), ruleFor("tunnels"), layer);
575
+ for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
576
+ const inGroup = tried.filter((t) => rules[t.permission] === rule);
577
+ if (inGroup.length === 0) continue;
578
+ probe.say({
579
+ status: "heading",
580
+ label: heading
581
+ });
582
+ for (const t of inGroup) probe.say(rowFor(t, rule));
583
+ }
552
584
  }
553
585
  };
554
586
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-cloudflare",
3
- "version": "5.0.0-alpha.426",
3
+ "version": "5.0.0-alpha.428",
4
4
  "description": "Holocron plugin for Cloudflare. Implements the dns capability against Cloudflare's REST API — zone resolution, DNS record management.",
5
5
  "keywords": [
6
6
  "cloudflare",
@@ -45,19 +45,19 @@
45
45
  "typescript": "^5.9.3",
46
46
  "vitest": "^5.1.0",
47
47
  "@theholocron/cloudflare-client": "^1.58.0-alpha.29",
48
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
48
49
  "@theholocron/http-client": "^1.58.0-alpha.29",
50
+ "@theholocron/kyber": "5.0.0-alpha.428",
49
51
  "@theholocron/tsconfig": "^8.9.0-alpha.17",
50
- "@theholocron/eslint-config": "^8.9.0-alpha.17",
51
52
  "@theholocron/misc-utils": "^1.17.0-alpha.4",
52
- "@theholocron/tsdown-config": "^8.9.0-alpha.17",
53
- "@theholocron/kyber": "5.0.0-alpha.426",
54
53
  "@theholocron/vitest-config": "^8.9.0-alpha.17",
55
- "@theholocron/cli": "5.0.0-alpha.426"
54
+ "@theholocron/tsdown-config": "^8.9.0-alpha.17",
55
+ "@theholocron/cli": "5.0.0-alpha.428"
56
56
  },
57
57
  "peerDependencies": {
58
58
  "@theholocron/cloudflare-client": "^1.53.1",
59
59
  "@theholocron/misc-utils": "^1.16.0",
60
- "@theholocron/cli": "5.0.0-alpha.426"
60
+ "@theholocron/cli": "5.0.0-alpha.428"
61
61
  },
62
62
  "peerDependenciesMeta": {
63
63
  "@theholocron/cloudflare-client": {}