@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.425 → 5.0.0-alpha.427

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.
package/dist/index.d.mts CHANGED
@@ -2,7 +2,7 @@ import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, Deployme
2
2
  import { CloudflareClient, CloudflareClient as CloudflareClient$1, CloudflareClientOptions, createCloudflareClient } from "@theholocron/cloudflare-client";
3
3
  /** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
4
4
  export declare const resolveToken: import("@theholocron/cli").TokenResolver;
5
- /** Every token this plugin takes, for `holocron doctor tokens`. */
5
+ /** Every token this plugin takes, for `holocron doctor tokens`, with what each layer's token must and must not be able to do. */
6
6
  export declare const tokens: PluginToken[];
7
7
  /** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
8
8
  export declare class CloudflareDeployment implements Deployment {
@@ -152,10 +152,11 @@ export declare function deployment(ctx: PluginContext): Deployment;
152
152
  export declare function workersCapability(ctx: PluginContext): Workers;
153
153
  /** Builds the `tunnels` capability for a context; throws when no account id is set. */
154
154
  export declare function tunnelsCapability(ctx: PluginContext): Tunnels;
155
- /** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and a `connection` probe. */
155
+ /** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and the `connection` and `token` probes. */
156
156
  export declare function createPlugin(options?: CloudflarePluginOptions): {
157
157
  name: string;
158
158
  probes: {
159
+ token: import("@theholocron/cli").Probe;
159
160
  connection: import("@theholocron/cli").Probe;
160
161
  };
161
162
  capabilities: {
package/dist/index.mjs CHANGED
@@ -1,7 +1,34 @@
1
1
  import { AuthError, ProviderApiError, connectionProbe, createResolveToken, resolveValue } from "@theholocron/cli";
2
2
  import { PREFIX } from "@theholocron/env-utils/lookup";
3
- import { createCloudflareClient } from "@theholocron/cloudflare-client";
4
3
  import { errorMessage } from "@theholocron/misc-utils";
4
+ import { createCloudflareClient } from "@theholocron/cloudflare-client";
5
+ // src/probes/token/expectations.ts
6
+ const EVERYTHING = {
7
+ zone: "required",
8
+ dns: "required",
9
+ routes: "required",
10
+ scripts: "required",
11
+ pages: "required",
12
+ tunnels: "required"
13
+ };
14
+ /**
15
+ * What each layer's Cloudflare token is meant to carry, the same as "What each Cloudflare token needs" in
16
+ * `docs/src/content/docs/tokens.mdx`: a laptop (`local` inherits `dev`) runs everything, CI only deploys Pages, so a
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.
19
+ */
20
+ const EXPECTED_BY_LAYER = {
21
+ local: EVERYTHING,
22
+ dev: EVERYTHING,
23
+ ci: {
24
+ zone: "absent",
25
+ dns: "absent",
26
+ routes: "absent",
27
+ scripts: "absent",
28
+ pages: "required",
29
+ tunnels: "absent"
30
+ }
31
+ };
5
32
  // src/auth.ts
6
33
  /** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
7
34
  const resolveToken = createResolveToken({
@@ -10,8 +37,11 @@ const resolveToken = createResolveToken({
10
37
  keyringService: "cloudflare",
11
38
  errorMessage: "no Cloudflare API token found. Pass --token <TOKEN>, set HOLOCRON_CLOUDFLARE_TOKEN / CLOUDFLARE_API_TOKEN, or run: holocron new token cloudflare <TOKEN>"
12
39
  });
13
- /** Every token this plugin takes, for `holocron doctor tokens`. */
14
- const tokens = [resolveToken.token];
40
+ /** Every token this plugin takes, for `holocron doctor tokens`, with what each layer's token must and must not be able to do. */
41
+ const tokens = [{
42
+ ...resolveToken.token,
43
+ expect: EXPECTED_BY_LAYER
44
+ }];
15
45
  // src/capabilities/deployment.ts
16
46
  /** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
17
47
  var CloudflareDeployment = class {
@@ -368,6 +398,191 @@ function generateProxyScript(config) {
368
398
  `};`
369
399
  ].join("\n");
370
400
  }
401
+ // src/probes/token/parse-token-args.ts
402
+ /** Reads the words after the probe name: `--layer <word>` and any number of zone names. */
403
+ function parseTokenArgs(args) {
404
+ const zones = [];
405
+ let layer;
406
+ for (let i = 0; i < args.length; i++) {
407
+ const arg = args[i];
408
+ if (arg === "--layer") layer = args[++i];
409
+ else if (arg.startsWith("--layer=")) layer = arg.slice(8);
410
+ else if (!arg.startsWith("--")) zones.push(arg);
411
+ }
412
+ return {
413
+ ...layer ? { layer } : {},
414
+ zones
415
+ };
416
+ }
417
+ // src/probes/token/token.ts
418
+ /** The most zones whose DNS and Workers routes are read, so a token that sees many does not make many requests. */
419
+ const MAX_ZONES = 5;
420
+ /** How many names to show before "(+N more)". */
421
+ const SHOWN = 5;
422
+ /** `a, b, c (+2 more)`. */
423
+ function summarise(names) {
424
+ return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
425
+ }
426
+ /**
427
+ * Reads one list and says what came back. Cloudflare answers a token without the permission in one of two ways (a 401 or
428
+ * 403, or an empty list), so an empty list is `none`: the token cannot see any, or there are none. A request that fails
429
+ * for another reason (the network, a 5xx) is an `error`.
430
+ */
431
+ async function reach(read, noun) {
432
+ try {
433
+ const items = await read();
434
+ if (items.length === 0) return {
435
+ kind: "none",
436
+ detail: `no ${noun} visible (none exist, or the token cannot see them)`
437
+ };
438
+ const names = items.map((i) => i.name).filter((n) => typeof n === "string");
439
+ return {
440
+ kind: "has",
441
+ detail: names.length > 0 ? `${items.length} ${noun}: ${summarise(names)}` : `${items.length} ${noun}`
442
+ };
443
+ } catch (err) {
444
+ if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
445
+ kind: "none",
446
+ detail: `no access (${err.status})`
447
+ };
448
+ return {
449
+ kind: "error",
450
+ detail: errorMessage(err)
451
+ };
452
+ }
453
+ }
454
+ /**
455
+ * One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
456
+ * judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
457
+ * permission that is rightly absent is a bare `ok`.
458
+ */
459
+ function rowFor({ label, outcome }, rule) {
460
+ if (outcome.kind === "error") return {
461
+ status: "fail",
462
+ label,
463
+ detail: outcome.detail
464
+ };
465
+ const has = outcome.kind === "has";
466
+ if (rule === "required") return has ? {
467
+ status: "ok",
468
+ label,
469
+ detail: outcome.detail
470
+ } : {
471
+ status: "fail",
472
+ label,
473
+ detail: outcome.detail
474
+ };
475
+ if (rule === "absent") return has ? {
476
+ status: "fail",
477
+ label,
478
+ detail: outcome.detail
479
+ } : {
480
+ status: "ok",
481
+ label
482
+ };
483
+ return {
484
+ status: has ? "ok" : "info",
485
+ label,
486
+ detail: outcome.detail
487
+ };
488
+ }
489
+ /**
490
+ * The `token` probe: tries each permission Holocron uses with the Cloudflare API token and reports which ones the token
491
+ * has. It only reads (a list per permission), so it changes nothing. The token is the one the plugin resolves, so
492
+ * `--token cloudflare=<token>` or `--environment <layer>` checks another one; the account id is the plugin's own.
493
+ *
494
+ * A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
495
+ * `local`), the results are judged against what that layer's token is meant to carry (`EXPECTED_BY_LAYER`) and shown in
496
+ * two groups, what it should have and what it should not, where a missing or extra permission fails. The other words
497
+ * limit the zone checks to those zones; otherwise up to five are read. How the token is chosen is in `holocron probe --help`.
498
+ */
499
+ function tokenProbe(ctx) {
500
+ return {
501
+ summary: "Try each Cloudflare permission Holocron uses (zones, DNS, Workers routes and scripts, Pages, tunnels) with a token and report which it has; for a ci or dev Environment, check it against what that layer should carry. Read-only.",
502
+ writes: false,
503
+ acceptsToken: true,
504
+ async run(probe) {
505
+ const token = ctx.token();
506
+ probe.secret(token);
507
+ const client = ctx.client();
508
+ const { layer, zones: wanted } = parseTokenArgs(probe.args ?? []);
509
+ const rules = layer ? EXPECTED_BY_LAYER[layer] : void 0;
510
+ if (layer && !rules) probe.say({
511
+ status: "info",
512
+ label: layer,
513
+ detail: "no expectations are declared for it, so the token is only described"
514
+ });
515
+ try {
516
+ const verified = await client.tokens.verify();
517
+ probe.say({
518
+ status: "ok",
519
+ label: "token",
520
+ detail: `${verified.id} (${verified.status})`
521
+ });
522
+ } catch {}
523
+ const tried = [];
524
+ let zones = [];
525
+ const zoneOutcome = await reach(async () => {
526
+ zones = wanted.length > 0 ? (await Promise.all(wanted.map((name) => client.zones.list({ name })))).flat() : await client.zones.list({ per_page: MAX_ZONES });
527
+ return zones.map((z) => ({ name: z.name }));
528
+ }, "zones");
529
+ tried.push({
530
+ label: "Zone: Read",
531
+ permission: "zone",
532
+ outcome: zoneOutcome
533
+ });
534
+ if (zoneOutcome.kind !== "error") {
535
+ for (const zone of zones.slice(0, MAX_ZONES)) {
536
+ tried.push({
537
+ label: `DNS: Edit (${zone.name})`,
538
+ permission: "dns",
539
+ outcome: await reach(() => client.dns.list(zone.id), "records")
540
+ });
541
+ tried.push({
542
+ label: `Workers Routes: Edit (${zone.name})`,
543
+ permission: "routes",
544
+ outcome: await reach(async () => (await client.workers.listRoutes(zone.id)).map((r) => ({ name: r.pattern })), "routes")
545
+ });
546
+ }
547
+ const account = ctx.options.accountId;
548
+ if (account) {
549
+ tried.push({
550
+ label: "Workers Scripts: Edit",
551
+ permission: "scripts",
552
+ outcome: await reach(async () => (await client.workers.listScripts(account)).map((s) => ({ name: s.id })), "scripts")
553
+ });
554
+ tried.push({
555
+ label: "Pages: Edit",
556
+ permission: "pages",
557
+ outcome: await reach(() => client.pages.listProjects(account), "projects")
558
+ });
559
+ tried.push({
560
+ label: "Cloudflare Tunnel: Edit",
561
+ permission: "tunnels",
562
+ outcome: await reach(() => client.tunnels.list(account), "tunnels")
563
+ });
564
+ } else probe.say({
565
+ status: rules ? "fail" : "info",
566
+ label: "account permissions",
567
+ detail: "no account id: set HOLOCRON_CLOUDFLARE_ACCOUNT_ID or the plugin's accountId option to check them"
568
+ });
569
+ }
570
+ if (!rules) {
571
+ for (const t of tried) probe.say(rowFor(t, void 0));
572
+ return;
573
+ }
574
+ for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
575
+ const inGroup = tried.filter((t) => rules[t.permission] === rule);
576
+ if (inGroup.length === 0) continue;
577
+ probe.say({
578
+ status: "heading",
579
+ label: heading
580
+ });
581
+ for (const t of inGroup) probe.say(rowFor(t, rule));
582
+ }
583
+ }
584
+ };
585
+ }
371
586
  // src/verify-token.ts
372
587
  /** Checks a Cloudflare API token, first by the token-verify endpoint and otherwise by listing zones; resolves to a description of what it found, or the failure message. */
373
588
  async function verifyToken(token, opts = {}) {
@@ -440,21 +655,24 @@ function tunnelsCapability(ctx) {
440
655
  if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Tunnels — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
441
656
  return new CloudflareTunnels(ctx.client, ctx.options.accountId);
442
657
  }
443
- /** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and a `connection` probe. */
658
+ /** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and the `connection` and `token` probes. */
444
659
  function createPlugin(options = {}) {
445
660
  const ctx = createContext(options);
446
661
  return {
447
662
  name: "@theholocron/holocron-plugin-cloudflare",
448
- probes: { connection: connectionProbe({
449
- provider: "Cloudflare",
450
- url: options.baseUrl ?? "https://api.cloudflare.com",
451
- fetch: options.fetch,
452
- token: () => resolveToken(options),
453
- verify: (token) => verifyToken(token, {
454
- baseUrl: options.baseUrl,
455
- fetch: options.fetch
663
+ probes: {
664
+ token: tokenProbe(ctx),
665
+ connection: connectionProbe({
666
+ provider: "Cloudflare",
667
+ url: options.baseUrl ?? "https://api.cloudflare.com",
668
+ fetch: options.fetch,
669
+ token: () => resolveToken(options),
670
+ verify: (token) => verifyToken(token, {
671
+ baseUrl: options.baseUrl,
672
+ fetch: options.fetch
673
+ })
456
674
  })
457
- }) },
675
+ },
458
676
  capabilities: {
459
677
  dns: () => dns(ctx),
460
678
  ...ctx.options.accountId ? {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-cloudflare",
3
- "version": "5.0.0-alpha.425",
3
+ "version": "5.0.0-alpha.427",
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",
@@ -44,20 +44,20 @@
44
44
  "tsx": "4.23.15",
45
45
  "typescript": "^5.9.3",
46
46
  "vitest": "^5.1.0",
47
- "@theholocron/cli": "5.0.0-alpha.425",
48
47
  "@theholocron/cloudflare-client": "^1.58.0-alpha.29",
48
+ "@theholocron/cli": "5.0.0-alpha.427",
49
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
49
50
  "@theholocron/http-client": "^1.58.0-alpha.29",
50
- "@theholocron/misc-utils": "^1.17.0-alpha.4",
51
+ "@theholocron/kyber": "5.0.0-alpha.427",
51
52
  "@theholocron/tsconfig": "^8.9.0-alpha.17",
52
- "@theholocron/kyber": "5.0.0-alpha.425",
53
- "@theholocron/eslint-config": "^8.9.0-alpha.17",
53
+ "@theholocron/vitest-config": "^8.9.0-alpha.17",
54
54
  "@theholocron/tsdown-config": "^8.9.0-alpha.17",
55
- "@theholocron/vitest-config": "^8.9.0-alpha.17"
55
+ "@theholocron/misc-utils": "^1.17.0-alpha.4"
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.425"
60
+ "@theholocron/cli": "5.0.0-alpha.427"
61
61
  },
62
62
  "peerDependenciesMeta": {
63
63
  "@theholocron/cloudflare-client": {}