@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.425 → 5.0.0-alpha.426
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 +3 -2
- package/dist/index.mjs +200 -13
- package/package.json +6 -6
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
|
|
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 = [
|
|
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,160 @@ 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
|
+
* 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.
|
|
457
|
+
*/
|
|
458
|
+
function report(probe, label, outcome, rule, layer) {
|
|
459
|
+
if (outcome.kind === "error") return probe.say({
|
|
460
|
+
status: "fail",
|
|
461
|
+
label,
|
|
462
|
+
detail: outcome.detail
|
|
463
|
+
});
|
|
464
|
+
const has = outcome.kind === "has";
|
|
465
|
+
if (rule === "required") return probe.say(has ? {
|
|
466
|
+
status: "ok",
|
|
467
|
+
label,
|
|
468
|
+
detail: outcome.detail
|
|
469
|
+
} : {
|
|
470
|
+
status: "fail",
|
|
471
|
+
label,
|
|
472
|
+
detail: `${outcome.detail}; the ${layer} token needs it`
|
|
473
|
+
});
|
|
474
|
+
if (rule === "absent") return probe.say(has ? {
|
|
475
|
+
status: "fail",
|
|
476
|
+
label,
|
|
477
|
+
detail: `${outcome.detail}; the ${layer} token must not have it`
|
|
478
|
+
} : {
|
|
479
|
+
status: "ok",
|
|
480
|
+
label,
|
|
481
|
+
detail: `not present, as the ${layer} token should be`
|
|
482
|
+
});
|
|
483
|
+
probe.say({
|
|
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 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.
|
|
497
|
+
*/
|
|
498
|
+
function tokenProbe(ctx) {
|
|
499
|
+
return {
|
|
500
|
+
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.",
|
|
501
|
+
writes: false,
|
|
502
|
+
acceptsToken: true,
|
|
503
|
+
async run(probe) {
|
|
504
|
+
const token = ctx.token();
|
|
505
|
+
probe.secret(token);
|
|
506
|
+
const client = ctx.client();
|
|
507
|
+
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({
|
|
511
|
+
status: "info",
|
|
512
|
+
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
|
+
});
|
|
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
|
+
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
|
+
}
|
|
529
|
+
let zones = [];
|
|
530
|
+
const zoneOutcome = await reach(async () => {
|
|
531
|
+
zones = wanted.length > 0 ? (await Promise.all(wanted.map((name) => client.zones.list({ name })))).flat() : await client.zones.list({ per_page: MAX_ZONES });
|
|
532
|
+
return zones.map((z) => ({ name: z.name }));
|
|
533
|
+
}, "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",
|
|
544
|
+
label: "account permissions",
|
|
545
|
+
detail: "no account id: set HOLOCRON_CLOUDFLARE_ACCOUNT_ID or the plugin's accountId option to check them"
|
|
546
|
+
});
|
|
547
|
+
return;
|
|
548
|
+
}
|
|
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);
|
|
552
|
+
}
|
|
553
|
+
};
|
|
554
|
+
}
|
|
371
555
|
// src/verify-token.ts
|
|
372
556
|
/** 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
557
|
async function verifyToken(token, opts = {}) {
|
|
@@ -440,21 +624,24 @@ function tunnelsCapability(ctx) {
|
|
|
440
624
|
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
625
|
return new CloudflareTunnels(ctx.client, ctx.options.accountId);
|
|
442
626
|
}
|
|
443
|
-
/** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and
|
|
627
|
+
/** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and the `connection` and `token` probes. */
|
|
444
628
|
function createPlugin(options = {}) {
|
|
445
629
|
const ctx = createContext(options);
|
|
446
630
|
return {
|
|
447
631
|
name: "@theholocron/holocron-plugin-cloudflare",
|
|
448
|
-
probes: {
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
632
|
+
probes: {
|
|
633
|
+
token: tokenProbe(ctx),
|
|
634
|
+
connection: connectionProbe({
|
|
635
|
+
provider: "Cloudflare",
|
|
636
|
+
url: options.baseUrl ?? "https://api.cloudflare.com",
|
|
637
|
+
fetch: options.fetch,
|
|
638
|
+
token: () => resolveToken(options),
|
|
639
|
+
verify: (token) => verifyToken(token, {
|
|
640
|
+
baseUrl: options.baseUrl,
|
|
641
|
+
fetch: options.fetch
|
|
642
|
+
})
|
|
456
643
|
})
|
|
457
|
-
}
|
|
644
|
+
},
|
|
458
645
|
capabilities: {
|
|
459
646
|
dns: () => dns(ctx),
|
|
460
647
|
...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.
|
|
3
|
+
"version": "5.0.0-alpha.426",
|
|
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",
|
|
49
48
|
"@theholocron/http-client": "^1.58.0-alpha.29",
|
|
50
|
-
"@theholocron/misc-utils": "^1.17.0-alpha.4",
|
|
51
49
|
"@theholocron/tsconfig": "^8.9.0-alpha.17",
|
|
52
|
-
"@theholocron/kyber": "5.0.0-alpha.425",
|
|
53
50
|
"@theholocron/eslint-config": "^8.9.0-alpha.17",
|
|
51
|
+
"@theholocron/misc-utils": "^1.17.0-alpha.4",
|
|
54
52
|
"@theholocron/tsdown-config": "^8.9.0-alpha.17",
|
|
55
|
-
"@theholocron/
|
|
53
|
+
"@theholocron/kyber": "5.0.0-alpha.426",
|
|
54
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.17",
|
|
55
|
+
"@theholocron/cli": "5.0.0-alpha.426"
|
|
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.
|
|
60
|
+
"@theholocron/cli": "5.0.0-alpha.426"
|
|
61
61
|
},
|
|
62
62
|
"peerDependenciesMeta": {
|
|
63
63
|
"@theholocron/cloudflare-client": {}
|