@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.45 → 5.0.0-alpha.450
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/README.md +21 -5
- package/dist/index.d.mts +89 -36
- package/dist/index.mjs +413 -21
- package/package.json +32 -26
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# `@theholocron/holocron-plugin-cloudflare`
|
|
4
4
|
|
|
5
5
|
Cloudflare plugin for [Holocron](../cli). Implements the `dns`, `deployment`,
|
|
6
|
-
and `
|
|
6
|
+
`workers` and `tunnels` capabilities against the
|
|
7
7
|
[Cloudflare v4 API](https://developers.cloudflare.com/api/).
|
|
8
8
|
|
|
9
9
|
## Install
|
|
@@ -22,7 +22,7 @@ Token resolution order:
|
|
|
22
22
|
2. `HOLOCRON_CLOUDFLARE_TOKEN` env var
|
|
23
23
|
3. `CLOUDFLARE_API_TOKEN` env var (the standard Cloudflare variable name)
|
|
24
24
|
4. Keyring `cloudflare.<org>` — tried first when an org is active via `--org`, `HOLOCRON_ORG`, or `org` in `holocron.config.ts`
|
|
25
|
-
5. Keyring `cloudflare` — unnamespaced fallback; set via `holocron
|
|
25
|
+
5. Keyring `cloudflare` — unnamespaced fallback; set via `holocron new token cloudflare <token>`
|
|
26
26
|
|
|
27
27
|
Generate a scoped API token at **dash.cloudflare.com/profile/api-tokens**.
|
|
28
28
|
|
|
@@ -63,9 +63,10 @@ Any combination of capabilities can be enabled together:
|
|
|
63
63
|
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
The `deployment` and `
|
|
67
|
-
is resolvable — either passed explicitly in options or set
|
|
68
|
-
`CLOUDFLARE_ACCOUNT_ID` env var
|
|
66
|
+
The `deployment`, `workers` and `tunnels` capabilities are only exposed when `accountId`
|
|
67
|
+
is resolvable — either passed explicitly in options or set as the
|
|
68
|
+
`HOLOCRON_CLOUDFLARE_ACCOUNT_ID` (or `CLOUDFLARE_ACCOUNT_ID`) env var or in a `credentials` provider's Environment (the option wins, then the
|
|
69
|
+
environment, then the provider).
|
|
69
70
|
|
|
70
71
|
## `dns` capability
|
|
71
72
|
|
|
@@ -104,6 +105,21 @@ route-write call when nothing changed. Zone ids are cached per plugin
|
|
|
104
105
|
instance for the lifetime of the process — the `workers` capability's own
|
|
105
106
|
cache, separate from `dns`'s.
|
|
106
107
|
|
|
108
|
+
## `tunnels` capability
|
|
109
|
+
|
|
110
|
+
Named [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/): a stable
|
|
111
|
+
public hostname that reaches a port on this machine, for a webhook that has to find a development instance. It needs a
|
|
112
|
+
token with **Cloudflare Tunnel: Edit** (account).
|
|
113
|
+
|
|
114
|
+
| Method | What it does |
|
|
115
|
+
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
116
|
+
| `ensureTunnel` | Finds the tunnel by name or makes it, and makes its configuration serve `hostname` at `service`. Other hostnames' rules are kept and the catch-all (`http_status:404`) stays last. Returns the tunnel id and the `CNAME` target (`<id>.cfargotunnel.com`). |
|
|
117
|
+
| `tunnelToken` | The token `cloudflared` runs the tunnel with. A credential: never printed or stored. |
|
|
118
|
+
| `whoami` | How many tunnels the token can see, for `holocron doctor`. |
|
|
119
|
+
|
|
120
|
+
`ensureTunnel` is idempotent: a tunnel that already serves the hostname is not rewritten. The DNS record for the
|
|
121
|
+
hostname is the `dns` provider's job.
|
|
122
|
+
|
|
107
123
|
### Preview deployment setup
|
|
108
124
|
|
|
109
125
|
When `preview: true` (or `preview: { project, domain }`) is set in a repo's deploy config, `holocron setup` calls:
|
package/dist/index.d.mts
CHANGED
|
@@ -1,15 +1,19 @@
|
|
|
1
|
-
import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, ResolveTokenInput, WikiProxyConfig, Workers } from "@theholocron/cli";
|
|
1
|
+
import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, EnsuredTunnel, PluginToken, ResolveTokenInput, TunnelRoute, Tunnels, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, WikiProxyConfig, WorkerScriptState, Workers } from "@theholocron/cli";
|
|
2
2
|
import { CloudflareClient, CloudflareClient as CloudflareClient$1, CloudflareClientOptions, createCloudflareClient } from "@theholocron/cloudflare-client";
|
|
3
|
-
|
|
4
|
-
declare const resolveToken: (
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
+
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
5
|
+
/** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
|
|
6
|
+
export declare const tokens: PluginToken[];
|
|
7
|
+
/** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
|
|
8
|
+
export declare class CloudflareDeployment implements Deployment {
|
|
8
9
|
private readonly client;
|
|
9
10
|
private readonly accountId;
|
|
11
|
+
/** The capability this class provides, always `"deployment"`. */
|
|
10
12
|
readonly key: "deployment";
|
|
13
|
+
/** The provider name, `"cloudflare"`. */
|
|
11
14
|
readonly providerName = "cloudflare";
|
|
12
15
|
constructor(client: () => CloudflareClient, accountId: string);
|
|
16
|
+
/** Lists the account's Pages projects. */
|
|
13
17
|
listProjects(): Promise<DeploymentProject[]>;
|
|
14
18
|
ensureProject(input: {
|
|
15
19
|
name: string;
|
|
@@ -17,31 +21,44 @@ declare class CloudflareDeployment implements Deployment {
|
|
|
17
21
|
repo?: string;
|
|
18
22
|
rootDirectory?: string;
|
|
19
23
|
}): Promise<DeploymentProject>;
|
|
24
|
+
/** Returns the project as it is now; Pages has no REST setting for the requested options, so `settings` is ignored. */
|
|
20
25
|
updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
|
|
26
|
+
/** Lists the names of the environment variables set for the production or preview target. */
|
|
21
27
|
listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
|
|
28
|
+
/** Sets a plain-text environment variable on the production or preview target, keeping the others. */
|
|
22
29
|
setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
|
|
23
30
|
triggerDeployment(input: {
|
|
24
31
|
projectId: string;
|
|
25
32
|
branch: string;
|
|
26
33
|
target?: DeploymentTrigger;
|
|
27
34
|
}): Promise<DeploymentRecord>;
|
|
35
|
+
/** Fetches a deployment by an id of the form `projectName:deploymentId`; throws a 400 `ProviderApiError` for any other form. */
|
|
28
36
|
getDeployment(deploymentId: string): Promise<DeploymentRecord>;
|
|
29
37
|
listPreviewDeployments(projectId: string, branch: string): Promise<DeploymentRecord[]>;
|
|
30
38
|
deletePreviewDeployments(projectId: string, deploymentIds: string[]): Promise<number>;
|
|
31
39
|
ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
|
|
32
40
|
private getProjectByName;
|
|
33
41
|
}
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
declare class CloudflareDns implements Dns {
|
|
42
|
+
/** The Cloudflare implementation of the `dns` capability; finds a domain's zone by walking from the domain up to its apex. */
|
|
43
|
+
export declare class CloudflareDns implements Dns {
|
|
37
44
|
private readonly client;
|
|
45
|
+
/** The capability this class provides, always `"dns"`. */
|
|
38
46
|
readonly key: "dns";
|
|
47
|
+
/** The provider name, `"cloudflare"`. */
|
|
39
48
|
readonly providerName = "cloudflare";
|
|
40
49
|
private readonly zoneCache;
|
|
41
50
|
constructor(client: () => CloudflareClient);
|
|
51
|
+
/** Lists the DNS records in the zone that holds the domain. */
|
|
42
52
|
listRecords(domain: string): Promise<DnsRecord[]>;
|
|
53
|
+
/** Updates the first record of the same type and name, or creates the record when there is none; returns the stored record. */
|
|
43
54
|
upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
|
|
55
|
+
/** Deletes the DNS record with this id from the zone that holds the domain. */
|
|
44
56
|
deleteRecord(domain: string, id: string): Promise<void>;
|
|
57
|
+
/** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
|
|
58
|
+
whoami(): Promise<{
|
|
59
|
+
ok: boolean;
|
|
60
|
+
zones: number;
|
|
61
|
+
}>;
|
|
45
62
|
/**
|
|
46
63
|
* Walk from full domain up to apex to find the Cloudflare zone.
|
|
47
64
|
* E.g. "api.staging.example.com" tries:
|
|
@@ -51,40 +68,61 @@ declare class CloudflareDns implements Dns {
|
|
|
51
68
|
*/
|
|
52
69
|
private resolveZone;
|
|
53
70
|
}
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
declare class CloudflareWorkers implements Workers {
|
|
71
|
+
/** The Cloudflare implementation of the `tunnels` capability, backed by Cloudflare Tunnel in one account. */
|
|
72
|
+
export declare class CloudflareTunnels implements Tunnels {
|
|
57
73
|
private readonly client;
|
|
58
74
|
private readonly accountId;
|
|
75
|
+
/** The capability this class provides, always `"tunnels"`. */
|
|
76
|
+
readonly key: "tunnels";
|
|
77
|
+
/** The provider name, `"cloudflare"`. */
|
|
78
|
+
readonly providerName = "cloudflare";
|
|
79
|
+
constructor(client: () => Pick<CloudflareClient$1, "tunnels">, accountId: string);
|
|
80
|
+
/** Finds the tunnel by name or makes it, then rewrites its routes only when they do not already serve the hostname. */
|
|
81
|
+
ensureTunnel(route: TunnelRoute): Promise<EnsuredTunnel>;
|
|
82
|
+
/** The token `cloudflared` runs the tunnel with. */
|
|
83
|
+
tunnelToken(tunnelId: string): Promise<string>;
|
|
84
|
+
/** `holocron doctor` has no specific tunnel to check: lists the ones the token can see. */
|
|
85
|
+
whoami(): Promise<{
|
|
86
|
+
ok: boolean;
|
|
87
|
+
tunnels: number;
|
|
88
|
+
}>;
|
|
89
|
+
}
|
|
90
|
+
/** The Cloudflare implementation of the `workers` capability, backed by Workers scripts and routes in one account. */
|
|
91
|
+
export declare class CloudflareWorkers implements Workers {
|
|
92
|
+
private readonly client;
|
|
93
|
+
private readonly accountId;
|
|
94
|
+
/** The capability this class provides, always `"workers"`. */
|
|
59
95
|
readonly key: "workers";
|
|
96
|
+
/** The provider name, `"cloudflare"`. */
|
|
60
97
|
readonly providerName = "cloudflare";
|
|
61
98
|
private readonly zoneCache;
|
|
62
99
|
constructor(client: () => Pick<CloudflareClient$1, "workers" | "zones">, accountId: string);
|
|
63
100
|
upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
|
|
101
|
+
/** `holocron doctor` has no specific script to check — lists every script the token can see instead. */
|
|
102
|
+
whoami(): Promise<{
|
|
103
|
+
ok: boolean;
|
|
104
|
+
scripts: number;
|
|
105
|
+
}>;
|
|
64
106
|
deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
|
|
107
|
+
setSecret(script: string, name: string, value: string): Promise<void>;
|
|
108
|
+
secretNames(script: string): Promise<string[]>;
|
|
109
|
+
/**
|
|
110
|
+
* Whether the script exists, which routes in the zone of `host` point at it, and the names of its secrets. Reads
|
|
111
|
+
* only, and asks Cloudflare for names, so no value is ever fetched.
|
|
112
|
+
*/
|
|
113
|
+
inspectScript(name: string, host: string): Promise<WorkerScriptState>;
|
|
65
114
|
/** Idempotent create-or-update for one route pattern — shared by both public methods. */
|
|
66
115
|
private upsertRoute;
|
|
67
116
|
private resolveZone;
|
|
68
117
|
}
|
|
69
|
-
//#endregion
|
|
70
|
-
//#region src/verify-token.d.ts
|
|
71
|
-
interface VerifyTokenSuccess {
|
|
72
|
-
ok: true;
|
|
73
|
-
subject: string;
|
|
74
|
-
}
|
|
75
|
-
interface VerifyTokenFailure {
|
|
76
|
-
ok: false;
|
|
77
|
-
message: string;
|
|
78
|
-
}
|
|
79
|
-
type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
|
|
80
118
|
interface VerifyTokenOptions {
|
|
81
119
|
baseUrl?: string;
|
|
82
120
|
fetch?: typeof fetch;
|
|
83
121
|
}
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
interface CloudflarePluginOptions extends ResolveTokenInput {
|
|
122
|
+
/** 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. */
|
|
123
|
+
export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
124
|
+
/** Options for the Cloudflare plugin: how the API token is resolved, the account, and test overrides. */
|
|
125
|
+
export interface CloudflarePluginOptions extends ResolveTokenInput {
|
|
88
126
|
/**
|
|
89
127
|
* Cloudflare account ID. Required for Pages (deployment) operations;
|
|
90
128
|
* optional for DNS-only use.
|
|
@@ -92,27 +130,42 @@ interface CloudflarePluginOptions extends ResolveTokenInput {
|
|
|
92
130
|
accountId?: string;
|
|
93
131
|
/** Override base URL for tests. */
|
|
94
132
|
baseUrl?: string;
|
|
133
|
+
/** The `fetch` to use instead of the global one, for tests. */
|
|
95
134
|
fetch?: typeof fetch;
|
|
96
135
|
}
|
|
97
|
-
|
|
136
|
+
/** The shared state the Cloudflare plugin's capabilities and probes are built from. */
|
|
137
|
+
export interface PluginContext {
|
|
138
|
+
/** The options the plugin was created with, with `accountId` falling back to `CLOUDFLARE_ACCOUNT_ID` in the environment, then in the `credentials` providers' variables. */
|
|
98
139
|
options: CloudflarePluginOptions;
|
|
99
140
|
/** Memoized client — the token is resolved on first use, not at plugin load. */
|
|
100
141
|
client: () => CloudflareClient;
|
|
101
142
|
/** Memoized token resolver — shared by the client and the Workers capability. */
|
|
102
143
|
token: () => string;
|
|
103
144
|
}
|
|
104
|
-
|
|
105
|
-
declare function
|
|
106
|
-
|
|
107
|
-
declare function
|
|
108
|
-
|
|
145
|
+
/** Builds the plugin context from its options; the API token is resolved lazily on the first client use. */
|
|
146
|
+
export declare function createContext(options?: CloudflarePluginOptions): PluginContext;
|
|
147
|
+
/** Builds the `dns` capability for a context. */
|
|
148
|
+
export declare function dns(ctx: PluginContext): Dns;
|
|
149
|
+
/** Builds the `deployment` capability for a context; throws when no account id is set. */
|
|
150
|
+
export declare function deployment(ctx: PluginContext): Deployment;
|
|
151
|
+
/** Builds the `workers` capability for a context; throws when no account id is set. */
|
|
152
|
+
export declare function workersCapability(ctx: PluginContext): Workers;
|
|
153
|
+
/** Builds the `tunnels` capability for a context; throws when no account id is set. */
|
|
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 the `connection` and `token` probes. */
|
|
156
|
+
export declare function createPlugin(options?: CloudflarePluginOptions): {
|
|
109
157
|
name: string;
|
|
158
|
+
probes: {
|
|
159
|
+
token: import("@theholocron/cli").Probe;
|
|
160
|
+
connection: import("@theholocron/cli").Probe;
|
|
161
|
+
};
|
|
110
162
|
capabilities: {
|
|
111
163
|
deployment?: (() => Deployment) | undefined;
|
|
112
164
|
workers?: (() => Workers) | undefined;
|
|
165
|
+
tunnels?: (() => Tunnels) | undefined;
|
|
113
166
|
dns: () => Dns;
|
|
114
167
|
};
|
|
115
168
|
};
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
export {
|
|
169
|
+
/** One-line hint printed by `holocron new token cloudflare` when no token is supplied or the supplied one is rejected. */
|
|
170
|
+
export declare const AUTH_HINT: string;
|
|
171
|
+
export { AuthError, type CloudflareClient, type CloudflareClientOptions, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createCloudflareClient };
|
package/dist/index.mjs
CHANGED
|
@@ -1,23 +1,68 @@
|
|
|
1
|
-
import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
|
|
1
|
+
import { AuthError, DEFAULT_TOKEN_ROTATION, ProviderApiError, connectionProbe, createResolveToken, resolveValue, tokenExpectations, tokenRotationRows } from "@theholocron/cli";
|
|
2
|
+
import { PREFIX } from "@theholocron/env-utils/lookup";
|
|
3
|
+
import { errorMessage } from "@theholocron/misc-utils";
|
|
2
4
|
import { createCloudflareClient } from "@theholocron/cloudflare-client";
|
|
3
|
-
|
|
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. This is the plugin's `tokens` declaration, read through `tokenExpectations()`; change it and
|
|
19
|
+
* that table together.
|
|
20
|
+
*/
|
|
21
|
+
const EXPECTED = {
|
|
22
|
+
rotation: {
|
|
23
|
+
maxAgeDays: 90,
|
|
24
|
+
warnDays: 14
|
|
25
|
+
},
|
|
26
|
+
permissions: {
|
|
27
|
+
local: EVERYTHING,
|
|
28
|
+
dev: EVERYTHING,
|
|
29
|
+
ci: {
|
|
30
|
+
zone: "absent",
|
|
31
|
+
dns: "absent",
|
|
32
|
+
routes: "absent",
|
|
33
|
+
scripts: "absent",
|
|
34
|
+
pages: "required",
|
|
35
|
+
tunnels: "absent"
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
};
|
|
39
|
+
// src/auth.ts
|
|
40
|
+
/** 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
41
|
const resolveToken = createResolveToken({
|
|
5
42
|
envName: "HOLOCRON_CLOUDFLARE_TOKEN",
|
|
6
43
|
vendorEnvName: "CLOUDFLARE_API_TOKEN",
|
|
7
44
|
keyringService: "cloudflare",
|
|
8
|
-
errorMessage: "no Cloudflare API token found. Pass --token <TOKEN>, set HOLOCRON_CLOUDFLARE_TOKEN / CLOUDFLARE_API_TOKEN, or run: holocron
|
|
45
|
+
errorMessage: "no Cloudflare API token found. Pass --token <TOKEN>, set HOLOCRON_CLOUDFLARE_TOKEN / CLOUDFLARE_API_TOKEN, or run: holocron new token cloudflare <TOKEN>"
|
|
9
46
|
});
|
|
10
|
-
|
|
11
|
-
|
|
47
|
+
/** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
|
|
48
|
+
const tokens = [{
|
|
49
|
+
...resolveToken.token,
|
|
50
|
+
expect: EXPECTED
|
|
51
|
+
}];
|
|
52
|
+
// src/capabilities/deployment.ts
|
|
53
|
+
/** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
|
|
12
54
|
var CloudflareDeployment = class {
|
|
13
55
|
client;
|
|
14
56
|
accountId;
|
|
57
|
+
/** The capability this class provides, always `"deployment"`. */
|
|
15
58
|
key = "deployment";
|
|
59
|
+
/** The provider name, `"cloudflare"`. */
|
|
16
60
|
providerName = "cloudflare";
|
|
17
61
|
constructor(client, accountId) {
|
|
18
62
|
this.client = client;
|
|
19
63
|
this.accountId = accountId;
|
|
20
64
|
}
|
|
65
|
+
/** Lists the account's Pages projects. */
|
|
21
66
|
async listProjects() {
|
|
22
67
|
return (await this.client().pages.listProjects(this.accountId)).map(mapProject);
|
|
23
68
|
}
|
|
@@ -29,14 +74,17 @@ var CloudflareDeployment = class {
|
|
|
29
74
|
production_branch: "main"
|
|
30
75
|
}));
|
|
31
76
|
}
|
|
77
|
+
/** Returns the project as it is now; Pages has no REST setting for the requested options, so `settings` is ignored. */
|
|
32
78
|
async updateProjectSettings(projectId, settings) {
|
|
33
79
|
return mapProject(await this.client().pages.getProject(this.accountId, projectId));
|
|
34
80
|
}
|
|
81
|
+
/** Lists the names of the environment variables set for the production or preview target. */
|
|
35
82
|
async listEnvVars(projectId, target) {
|
|
36
83
|
const project = await this.client().pages.getProject(this.accountId, projectId);
|
|
37
84
|
const envConfig = target === "production" ? project.deployment_configs.production : project.deployment_configs.preview;
|
|
38
85
|
return Object.keys(envConfig.env_vars);
|
|
39
86
|
}
|
|
87
|
+
/** Sets a plain-text environment variable on the production or preview target, keeping the others. */
|
|
40
88
|
async setEnvVar(projectId, target, name, value) {
|
|
41
89
|
const cfg = (await this.client().pages.getProject(this.accountId, projectId)).deployment_configs;
|
|
42
90
|
const scope = target === "production" ? "production" : "preview";
|
|
@@ -55,6 +103,7 @@ var CloudflareDeployment = class {
|
|
|
55
103
|
async triggerDeployment(input) {
|
|
56
104
|
return mapDeployment(await this.client().pages.createDeployment(this.accountId, input.projectId, input.branch), input.projectId, input.branch, input.target);
|
|
57
105
|
}
|
|
106
|
+
/** Fetches a deployment by an id of the form `projectName:deploymentId`; throws a 400 `ProviderApiError` for any other form. */
|
|
58
107
|
async getDeployment(deploymentId) {
|
|
59
108
|
const sep = deploymentId.indexOf(":");
|
|
60
109
|
if (sep === -1) throw new ProviderApiError(`Invalid Cloudflare Pages deployment id "${deploymentId}" — expected "projectName:deploymentId"`, 400, void 0);
|
|
@@ -114,20 +163,24 @@ function normalizeStatus(status) {
|
|
|
114
163
|
default: return "error";
|
|
115
164
|
}
|
|
116
165
|
}
|
|
117
|
-
|
|
118
|
-
|
|
166
|
+
// src/capabilities/dns.ts
|
|
167
|
+
/** The Cloudflare implementation of the `dns` capability; finds a domain's zone by walking from the domain up to its apex. */
|
|
119
168
|
var CloudflareDns = class {
|
|
120
169
|
client;
|
|
170
|
+
/** The capability this class provides, always `"dns"`. */
|
|
121
171
|
key = "dns";
|
|
172
|
+
/** The provider name, `"cloudflare"`. */
|
|
122
173
|
providerName = "cloudflare";
|
|
123
174
|
zoneCache = /* @__PURE__ */ new Map();
|
|
124
175
|
constructor(client) {
|
|
125
176
|
this.client = client;
|
|
126
177
|
}
|
|
178
|
+
/** Lists the DNS records in the zone that holds the domain. */
|
|
127
179
|
async listRecords(domain) {
|
|
128
180
|
const zoneId = await this.resolveZone(domain);
|
|
129
181
|
return (await this.client().dns.list(zoneId)).map(mapRecord);
|
|
130
182
|
}
|
|
183
|
+
/** Updates the first record of the same type and name, or creates the record when there is none; returns the stored record. */
|
|
131
184
|
async upsertRecord(domain, record) {
|
|
132
185
|
const client = this.client();
|
|
133
186
|
const zoneId = await this.resolveZone(domain);
|
|
@@ -150,10 +203,18 @@ var CloudflareDns = class {
|
|
|
150
203
|
...record.proxied !== void 0 ? { proxied: record.proxied } : {}
|
|
151
204
|
}));
|
|
152
205
|
}
|
|
206
|
+
/** Deletes the DNS record with this id from the zone that holds the domain. */
|
|
153
207
|
async deleteRecord(domain, id) {
|
|
154
208
|
const zoneId = await this.resolveZone(domain);
|
|
155
209
|
await this.client().dns.delete(zoneId, id);
|
|
156
210
|
}
|
|
211
|
+
/** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
|
|
212
|
+
async whoami() {
|
|
213
|
+
return {
|
|
214
|
+
ok: true,
|
|
215
|
+
zones: (await this.client().zones.list()).length
|
|
216
|
+
};
|
|
217
|
+
}
|
|
157
218
|
/**
|
|
158
219
|
* Walk from full domain up to apex to find the Cloudflare zone.
|
|
159
220
|
* E.g. "api.staging.example.com" tries:
|
|
@@ -182,15 +243,75 @@ function mapRecord(raw) {
|
|
|
182
243
|
type: raw.type,
|
|
183
244
|
name: raw.name,
|
|
184
245
|
content: raw.content,
|
|
185
|
-
ttl: raw.ttl
|
|
246
|
+
ttl: raw.ttl,
|
|
247
|
+
...raw.proxied !== void 0 ? { proxied: raw.proxied } : {}
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
// src/capabilities/tunnels.ts
|
|
251
|
+
/** The rule a tunnel needs last: anything no other rule matches is answered with a 404 by the connector itself. */
|
|
252
|
+
const CATCH_ALL = { service: "http_status:404" };
|
|
253
|
+
/**
|
|
254
|
+
* The ingress rules with `hostname` served at `service`: the rule for the hostname is replaced where it is or added
|
|
255
|
+
* after the others, every other hostname's rule is kept, and the rule without a hostname closes the list.
|
|
256
|
+
*/
|
|
257
|
+
function withRoute(current, hostname, service) {
|
|
258
|
+
const rule = {
|
|
259
|
+
hostname,
|
|
260
|
+
service
|
|
186
261
|
};
|
|
262
|
+
const named = current.filter((r) => r.hostname !== void 0);
|
|
263
|
+
const at = named.findIndex((r) => r.hostname === hostname);
|
|
264
|
+
return [...at === -1 ? [...named, rule] : named.map((r, i) => i === at ? rule : r), current.find((r) => r.hostname === void 0) ?? CATCH_ALL];
|
|
187
265
|
}
|
|
188
|
-
|
|
189
|
-
|
|
266
|
+
/** The Cloudflare implementation of the `tunnels` capability, backed by Cloudflare Tunnel in one account. */
|
|
267
|
+
var CloudflareTunnels = class {
|
|
268
|
+
client;
|
|
269
|
+
accountId;
|
|
270
|
+
/** The capability this class provides, always `"tunnels"`. */
|
|
271
|
+
key = "tunnels";
|
|
272
|
+
/** The provider name, `"cloudflare"`. */
|
|
273
|
+
providerName = "cloudflare";
|
|
274
|
+
constructor(client, accountId) {
|
|
275
|
+
this.client = client;
|
|
276
|
+
this.accountId = accountId;
|
|
277
|
+
}
|
|
278
|
+
/** Finds the tunnel by name or makes it, then rewrites its routes only when they do not already serve the hostname. */
|
|
279
|
+
async ensureTunnel(route) {
|
|
280
|
+
const { tunnels } = this.client();
|
|
281
|
+
const found = (await tunnels.list(this.accountId)).find((t) => t.name === route.name);
|
|
282
|
+
const tunnel = found ?? await tunnels.create(this.accountId, { name: route.name });
|
|
283
|
+
const current = (await tunnels.getConfig(this.accountId, tunnel.id)).config?.ingress ?? [];
|
|
284
|
+
const wanted = withRoute(current, route.hostname, route.service);
|
|
285
|
+
const configured = JSON.stringify(wanted) !== JSON.stringify(current);
|
|
286
|
+
if (configured) await tunnels.putConfig(this.accountId, tunnel.id, { ingress: wanted });
|
|
287
|
+
return {
|
|
288
|
+
id: tunnel.id,
|
|
289
|
+
name: tunnel.name,
|
|
290
|
+
created: found === void 0,
|
|
291
|
+
configured,
|
|
292
|
+
target: `${tunnel.id}.cfargotunnel.com`
|
|
293
|
+
};
|
|
294
|
+
}
|
|
295
|
+
/** The token `cloudflared` runs the tunnel with. */
|
|
296
|
+
tunnelToken(tunnelId) {
|
|
297
|
+
return this.client().tunnels.token(this.accountId, tunnelId);
|
|
298
|
+
}
|
|
299
|
+
/** `holocron doctor` has no specific tunnel to check: lists the ones the token can see. */
|
|
300
|
+
async whoami() {
|
|
301
|
+
return {
|
|
302
|
+
ok: true,
|
|
303
|
+
tunnels: (await this.client().tunnels.list(this.accountId)).length
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
};
|
|
307
|
+
// src/capabilities/workers.ts
|
|
308
|
+
/** The Cloudflare implementation of the `workers` capability, backed by Workers scripts and routes in one account. */
|
|
190
309
|
var CloudflareWorkers = class {
|
|
191
310
|
client;
|
|
192
311
|
accountId;
|
|
312
|
+
/** The capability this class provides, always `"workers"`. */
|
|
193
313
|
key = "workers";
|
|
314
|
+
/** The provider name, `"cloudflare"`. */
|
|
194
315
|
providerName = "cloudflare";
|
|
195
316
|
zoneCache = /* @__PURE__ */ new Map();
|
|
196
317
|
constructor(client, accountId) {
|
|
@@ -203,12 +324,45 @@ var CloudflareWorkers = class {
|
|
|
203
324
|
await this.client().workers.putScript(this.accountId, scriptName, script);
|
|
204
325
|
await this.upsertRoute(`${hostname}/*`, scriptName);
|
|
205
326
|
}
|
|
327
|
+
/** `holocron doctor` has no specific script to check — lists every script the token can see instead. */
|
|
328
|
+
async whoami() {
|
|
329
|
+
return {
|
|
330
|
+
ok: true,
|
|
331
|
+
scripts: (await this.client().workers.listScripts(this.accountId)).length
|
|
332
|
+
};
|
|
333
|
+
}
|
|
206
334
|
async deployScript(name, config) {
|
|
207
335
|
await this.client().workers.putScript(this.accountId, name, config.code);
|
|
208
336
|
for (const [secretName, value] of Object.entries(config.secrets ?? {})) await this.client().workers.putSecret(this.accountId, name, secretName, value);
|
|
209
337
|
for (const pattern of config.routes ?? []) await this.upsertRoute(pattern, name);
|
|
210
338
|
return { scriptName: name };
|
|
211
339
|
}
|
|
340
|
+
async setSecret(script, name, value) {
|
|
341
|
+
await this.client().workers.putSecret(this.accountId, script, name, value);
|
|
342
|
+
}
|
|
343
|
+
async secretNames(script) {
|
|
344
|
+
return (await this.client().workers.listSecrets(this.accountId, script)).map((secret) => secret.name);
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* Whether the script exists, which routes in the zone of `host` point at it, and the names of its secrets. Reads
|
|
348
|
+
* only, and asks Cloudflare for names, so no value is ever fetched.
|
|
349
|
+
*/
|
|
350
|
+
async inspectScript(name, host) {
|
|
351
|
+
const client = this.client();
|
|
352
|
+
if (!(await client.workers.listScripts(this.accountId)).some((s) => s.id === name)) return {
|
|
353
|
+
exists: false,
|
|
354
|
+
routes: [],
|
|
355
|
+
bindingNames: []
|
|
356
|
+
};
|
|
357
|
+
const zoneId = await this.resolveZone(host);
|
|
358
|
+
const routes = await client.workers.listRoutes(zoneId);
|
|
359
|
+
const secrets = await client.workers.listSecrets(this.accountId, name);
|
|
360
|
+
return {
|
|
361
|
+
exists: true,
|
|
362
|
+
routes: routes.filter((r) => r.script === name).map((r) => r.pattern),
|
|
363
|
+
bindingNames: secrets.map((secret) => secret.name)
|
|
364
|
+
};
|
|
365
|
+
}
|
|
212
366
|
/** Idempotent create-or-update for one route pattern — shared by both public methods. */
|
|
213
367
|
async upsertRoute(pattern, scriptName) {
|
|
214
368
|
const hostname = pattern.split("/")[0];
|
|
@@ -251,8 +405,218 @@ function generateProxyScript(config) {
|
|
|
251
405
|
`};`
|
|
252
406
|
].join("\n");
|
|
253
407
|
}
|
|
254
|
-
|
|
255
|
-
|
|
408
|
+
// src/probes/token/parse-token-args.ts
|
|
409
|
+
/** Reads the words after the probe name: `--layer <word>`, `--token-name <VAR>` and any number of zone names. */
|
|
410
|
+
function parseTokenArgs(args) {
|
|
411
|
+
const zones = [];
|
|
412
|
+
let layer;
|
|
413
|
+
let tokenName;
|
|
414
|
+
for (let i = 0; i < args.length; i++) {
|
|
415
|
+
const arg = args[i];
|
|
416
|
+
if (arg === "--layer") layer = args[++i];
|
|
417
|
+
else if (arg.startsWith("--layer=")) layer = arg.slice(8);
|
|
418
|
+
else if (arg === "--token-name") tokenName = args[++i];
|
|
419
|
+
else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
|
|
420
|
+
else if (!arg.startsWith("--")) zones.push(arg);
|
|
421
|
+
}
|
|
422
|
+
return {
|
|
423
|
+
...layer ? { layer } : {},
|
|
424
|
+
...tokenName ? { tokenName } : {},
|
|
425
|
+
zones
|
|
426
|
+
};
|
|
427
|
+
}
|
|
428
|
+
// src/probes/token/token.ts
|
|
429
|
+
/** The most zones whose DNS and Workers routes are read, so a token that sees many does not make many requests. */
|
|
430
|
+
const MAX_ZONES = 5;
|
|
431
|
+
/** How many names to show before "(+N more)". */
|
|
432
|
+
const SHOWN = 5;
|
|
433
|
+
/** `a, b, c (+2 more)`. */
|
|
434
|
+
function summarise(names) {
|
|
435
|
+
return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Reads one list and says what came back. Cloudflare answers a token without the permission in one of two ways (a 401 or
|
|
439
|
+
* 403, or an empty list), so an empty list is `none`: the token cannot see any, or there are none. A request that fails
|
|
440
|
+
* for another reason (the network, a 5xx) is an `error`.
|
|
441
|
+
*/
|
|
442
|
+
async function reach(read, noun) {
|
|
443
|
+
try {
|
|
444
|
+
const items = await read();
|
|
445
|
+
if (items.length === 0) return {
|
|
446
|
+
kind: "none",
|
|
447
|
+
detail: `no ${noun} visible (none exist, or the token cannot see them)`
|
|
448
|
+
};
|
|
449
|
+
const names = items.map((i) => i.name).filter((n) => typeof n === "string");
|
|
450
|
+
return {
|
|
451
|
+
kind: "has",
|
|
452
|
+
detail: names.length > 0 ? `${items.length} ${noun}: ${summarise(names)}` : `${items.length} ${noun}`
|
|
453
|
+
};
|
|
454
|
+
} catch (err) {
|
|
455
|
+
if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
|
|
456
|
+
kind: "none",
|
|
457
|
+
detail: `no access (${err.status})`
|
|
458
|
+
};
|
|
459
|
+
return {
|
|
460
|
+
kind: "error",
|
|
461
|
+
detail: errorMessage(err)
|
|
462
|
+
};
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
/**
|
|
466
|
+
* One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
|
|
467
|
+
* judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
|
|
468
|
+
* permission that is rightly absent is a bare `ok`.
|
|
469
|
+
*/
|
|
470
|
+
function rowFor({ label, outcome }, rule) {
|
|
471
|
+
if (outcome.kind === "error") return {
|
|
472
|
+
status: "fail",
|
|
473
|
+
label,
|
|
474
|
+
detail: outcome.detail
|
|
475
|
+
};
|
|
476
|
+
const has = outcome.kind === "has";
|
|
477
|
+
if (rule === "required") return has ? {
|
|
478
|
+
status: "ok",
|
|
479
|
+
label,
|
|
480
|
+
detail: outcome.detail
|
|
481
|
+
} : {
|
|
482
|
+
status: "fail",
|
|
483
|
+
label,
|
|
484
|
+
detail: outcome.detail
|
|
485
|
+
};
|
|
486
|
+
if (rule === "absent") return has ? {
|
|
487
|
+
status: "fail",
|
|
488
|
+
label,
|
|
489
|
+
detail: outcome.detail
|
|
490
|
+
} : {
|
|
491
|
+
status: "ok",
|
|
492
|
+
label
|
|
493
|
+
};
|
|
494
|
+
return {
|
|
495
|
+
status: has ? "ok" : "info",
|
|
496
|
+
label,
|
|
497
|
+
detail: outcome.detail
|
|
498
|
+
};
|
|
499
|
+
}
|
|
500
|
+
/**
|
|
501
|
+
* The `token` probe: tries each permission Holocron uses with the Cloudflare API token and reports which ones the token
|
|
502
|
+
* has. It only reads (a list per permission), so it changes nothing. The token is the one the plugin resolves, so
|
|
503
|
+
* `--token cloudflare=<token>` or `--environment <layer>` checks another one; the account id is the plugin's own.
|
|
504
|
+
*
|
|
505
|
+
* A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
|
|
506
|
+
* `local`) with `--token-name` (the declared token the Environment held, so the expectations are that token's own), 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
|
|
507
|
+
* two groups, what it should have and what it should not, where a missing or extra permission fails. The other words
|
|
508
|
+
* limit the zone checks to those zones; otherwise up to five are read. How the token is chosen is in `holocron probe --help`.
|
|
509
|
+
*/
|
|
510
|
+
function tokenProbe(ctx) {
|
|
511
|
+
return {
|
|
512
|
+
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.",
|
|
513
|
+
writes: false,
|
|
514
|
+
acceptsToken: true,
|
|
515
|
+
async run(probe) {
|
|
516
|
+
const token = ctx.token();
|
|
517
|
+
probe.secret(token);
|
|
518
|
+
const client = ctx.client();
|
|
519
|
+
const { layer, tokenName, zones: wanted } = parseTokenArgs(probe.args ?? []);
|
|
520
|
+
const expectation = layer ? tokenExpectations(tokens, {
|
|
521
|
+
layer,
|
|
522
|
+
...tokenName ? { envName: tokenName } : {}
|
|
523
|
+
})[0] : void 0;
|
|
524
|
+
const rules = expectation?.rules;
|
|
525
|
+
if (layer && !rules) probe.say({
|
|
526
|
+
status: "info",
|
|
527
|
+
label: layer,
|
|
528
|
+
detail: "no expectations are declared for it, so the token is only described"
|
|
529
|
+
});
|
|
530
|
+
const now = (ctx.now ?? (() => /* @__PURE__ */ new Date()))();
|
|
531
|
+
const rotation = expectation?.rotation ?? DEFAULT_TOKEN_ROTATION;
|
|
532
|
+
let lifetime;
|
|
533
|
+
try {
|
|
534
|
+
const verified = await client.tokens.verify();
|
|
535
|
+
probe.say({
|
|
536
|
+
status: "ok",
|
|
537
|
+
label: "token",
|
|
538
|
+
detail: `${verified.id} (${verified.status})`
|
|
539
|
+
});
|
|
540
|
+
lifetime = {
|
|
541
|
+
...verified.not_before ? { createdAt: verified.not_before } : {},
|
|
542
|
+
...verified.expires_on ? { expiresAt: verified.expires_on } : {}
|
|
543
|
+
};
|
|
544
|
+
} catch {}
|
|
545
|
+
const rotationRows = tokenRotationRows(lifetime, rotation, now);
|
|
546
|
+
const sayRotation = () => {
|
|
547
|
+
probe.say({
|
|
548
|
+
status: "heading",
|
|
549
|
+
label: "Rotation"
|
|
550
|
+
});
|
|
551
|
+
for (const row of rotationRows) probe.say(row);
|
|
552
|
+
};
|
|
553
|
+
const tried = [];
|
|
554
|
+
let zones = [];
|
|
555
|
+
const zoneOutcome = await reach(async () => {
|
|
556
|
+
zones = wanted.length > 0 ? (await Promise.all(wanted.map((name) => client.zones.list({ name })))).flat() : await client.zones.list({ per_page: MAX_ZONES });
|
|
557
|
+
return zones.map((z) => ({ name: z.name }));
|
|
558
|
+
}, "zones");
|
|
559
|
+
tried.push({
|
|
560
|
+
label: "Zone: Read",
|
|
561
|
+
permission: "zone",
|
|
562
|
+
outcome: zoneOutcome
|
|
563
|
+
});
|
|
564
|
+
if (zoneOutcome.kind !== "error") {
|
|
565
|
+
for (const zone of zones.slice(0, MAX_ZONES)) {
|
|
566
|
+
tried.push({
|
|
567
|
+
label: `DNS: Edit (${zone.name})`,
|
|
568
|
+
permission: "dns",
|
|
569
|
+
outcome: await reach(() => client.dns.list(zone.id), "records")
|
|
570
|
+
});
|
|
571
|
+
tried.push({
|
|
572
|
+
label: `Workers Routes: Edit (${zone.name})`,
|
|
573
|
+
permission: "routes",
|
|
574
|
+
outcome: await reach(async () => (await client.workers.listRoutes(zone.id)).map((r) => ({ name: r.pattern })), "routes")
|
|
575
|
+
});
|
|
576
|
+
}
|
|
577
|
+
const account = ctx.options.accountId;
|
|
578
|
+
if (account) {
|
|
579
|
+
tried.push({
|
|
580
|
+
label: "Workers Scripts: Edit",
|
|
581
|
+
permission: "scripts",
|
|
582
|
+
outcome: await reach(async () => (await client.workers.listScripts(account)).map((s) => ({ name: s.id })), "scripts")
|
|
583
|
+
});
|
|
584
|
+
tried.push({
|
|
585
|
+
label: "Pages: Edit",
|
|
586
|
+
permission: "pages",
|
|
587
|
+
outcome: await reach(() => client.pages.listProjects(account), "projects")
|
|
588
|
+
});
|
|
589
|
+
tried.push({
|
|
590
|
+
label: "Cloudflare Tunnel: Edit",
|
|
591
|
+
permission: "tunnels",
|
|
592
|
+
outcome: await reach(() => client.tunnels.list(account), "tunnels")
|
|
593
|
+
});
|
|
594
|
+
} else probe.say({
|
|
595
|
+
status: rules ? "fail" : "info",
|
|
596
|
+
label: "account permissions",
|
|
597
|
+
detail: "no account id: set HOLOCRON_CLOUDFLARE_ACCOUNT_ID or the plugin's accountId option to check them"
|
|
598
|
+
});
|
|
599
|
+
}
|
|
600
|
+
if (!rules) {
|
|
601
|
+
for (const t of tried) probe.say(rowFor(t, void 0));
|
|
602
|
+
sayRotation();
|
|
603
|
+
return;
|
|
604
|
+
}
|
|
605
|
+
for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
|
|
606
|
+
const inGroup = tried.filter((t) => rules[t.permission] === rule);
|
|
607
|
+
if (inGroup.length === 0) continue;
|
|
608
|
+
probe.say({
|
|
609
|
+
status: "heading",
|
|
610
|
+
label: heading
|
|
611
|
+
});
|
|
612
|
+
for (const t of inGroup) probe.say(rowFor(t, rule));
|
|
613
|
+
}
|
|
614
|
+
sayRotation();
|
|
615
|
+
}
|
|
616
|
+
};
|
|
617
|
+
}
|
|
618
|
+
// src/verify-token.ts
|
|
619
|
+
/** 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. */
|
|
256
620
|
async function verifyToken(token, opts = {}) {
|
|
257
621
|
const client = createCloudflareClient({
|
|
258
622
|
token,
|
|
@@ -267,21 +631,26 @@ async function verifyToken(token, opts = {}) {
|
|
|
267
631
|
};
|
|
268
632
|
} catch {}
|
|
269
633
|
try {
|
|
634
|
+
const names = (await client.zones.list()).map((z) => z.name);
|
|
635
|
+
if (names.length === 0) return {
|
|
636
|
+
ok: true,
|
|
637
|
+
subject: "no zones visible"
|
|
638
|
+
};
|
|
270
639
|
return {
|
|
271
640
|
ok: true,
|
|
272
|
-
subject: `
|
|
641
|
+
subject: `zones: ${names.length <= 5 ? names.join(", ") : `${names.slice(0, 5).join(", ")} (+${names.length - 5} more)`}`
|
|
273
642
|
};
|
|
274
643
|
} catch (err) {
|
|
275
644
|
return {
|
|
276
645
|
ok: false,
|
|
277
|
-
message:
|
|
646
|
+
message: errorMessage(err)
|
|
278
647
|
};
|
|
279
648
|
}
|
|
280
649
|
}
|
|
281
|
-
|
|
282
|
-
|
|
650
|
+
// src/index.ts
|
|
651
|
+
/** Builds the plugin context from its options; the API token is resolved lazily on the first client use. */
|
|
283
652
|
function createContext(options = {}) {
|
|
284
|
-
const accountId = options.accountId ??
|
|
653
|
+
const accountId = options.accountId ?? resolveValue(["CLOUDFLARE_ACCOUNT_ID"], options.env, { prefix: PREFIX });
|
|
285
654
|
const opts = {
|
|
286
655
|
...options,
|
|
287
656
|
accountId
|
|
@@ -299,30 +668,53 @@ function createContext(options = {}) {
|
|
|
299
668
|
})
|
|
300
669
|
};
|
|
301
670
|
}
|
|
671
|
+
/** Builds the `dns` capability for a context. */
|
|
302
672
|
function dns(ctx) {
|
|
303
673
|
return new CloudflareDns(ctx.client);
|
|
304
674
|
}
|
|
675
|
+
/** Builds the `deployment` capability for a context; throws when no account id is set. */
|
|
305
676
|
function deployment(ctx) {
|
|
306
677
|
if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Pages deployments — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
|
|
307
678
|
return new CloudflareDeployment(ctx.client, ctx.options.accountId);
|
|
308
679
|
}
|
|
680
|
+
/** Builds the `workers` capability for a context; throws when no account id is set. */
|
|
309
681
|
function workersCapability(ctx) {
|
|
310
682
|
if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Workers — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
|
|
311
683
|
return new CloudflareWorkers(ctx.client, ctx.options.accountId);
|
|
312
684
|
}
|
|
685
|
+
/** Builds the `tunnels` capability for a context; throws when no account id is set. */
|
|
686
|
+
function tunnelsCapability(ctx) {
|
|
687
|
+
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");
|
|
688
|
+
return new CloudflareTunnels(ctx.client, ctx.options.accountId);
|
|
689
|
+
}
|
|
690
|
+
/** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and the `connection` and `token` probes. */
|
|
313
691
|
function createPlugin(options = {}) {
|
|
314
692
|
const ctx = createContext(options);
|
|
315
693
|
return {
|
|
316
694
|
name: "@theholocron/holocron-plugin-cloudflare",
|
|
695
|
+
probes: {
|
|
696
|
+
token: tokenProbe(ctx),
|
|
697
|
+
connection: connectionProbe({
|
|
698
|
+
provider: "Cloudflare",
|
|
699
|
+
url: options.baseUrl ?? "https://api.cloudflare.com",
|
|
700
|
+
fetch: options.fetch,
|
|
701
|
+
token: () => resolveToken(options),
|
|
702
|
+
verify: (token) => verifyToken(token, {
|
|
703
|
+
baseUrl: options.baseUrl,
|
|
704
|
+
fetch: options.fetch
|
|
705
|
+
})
|
|
706
|
+
})
|
|
707
|
+
},
|
|
317
708
|
capabilities: {
|
|
318
709
|
dns: () => dns(ctx),
|
|
319
710
|
...ctx.options.accountId ? {
|
|
320
711
|
deployment: () => deployment(ctx),
|
|
321
|
-
workers: () => workersCapability(ctx)
|
|
712
|
+
workers: () => workersCapability(ctx),
|
|
713
|
+
tunnels: () => tunnelsCapability(ctx)
|
|
322
714
|
} : {}
|
|
323
715
|
}
|
|
324
716
|
};
|
|
325
717
|
}
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, verifyToken, workersCapability };
|
|
718
|
+
/** One-line hint printed by `holocron new token cloudflare` when no token is supplied or the supplied one is rejected. */
|
|
719
|
+
const AUTH_HINT = "create an API token at https://dash.cloudflare.com/profile/api-tokens with Zone:Read, DNS:Edit, Cloudflare Pages:Edit, Workers Scripts:Edit (account-level), Workers Routes:Edit (zone-level) and, for tunnels, Cloudflare Tunnel:Edit (account-level) permissions, then run: holocron new token cloudflare <TOKEN>";
|
|
720
|
+
export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareTunnels, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, tokens, tunnelsCapability, verifyToken, workersCapability };
|
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.450",
|
|
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",
|
|
@@ -8,12 +8,12 @@
|
|
|
8
8
|
"holocron",
|
|
9
9
|
"plugin"
|
|
10
10
|
],
|
|
11
|
-
"homepage": "https://
|
|
11
|
+
"homepage": "https://docs.theholocron.dev/holocron/plugins/cloudflare/",
|
|
12
12
|
"bugs": "https://github.com/theholocron/holocron/issues",
|
|
13
13
|
"repository": {
|
|
14
14
|
"type": "git",
|
|
15
15
|
"url": "git+https://github.com/theholocron/holocron.git",
|
|
16
|
-
"directory": "
|
|
16
|
+
"directory": "plugins/holocron-plugin-cloudflare"
|
|
17
17
|
},
|
|
18
18
|
"license": "MIT",
|
|
19
19
|
"author": "Newton Koumantzelis",
|
|
@@ -29,29 +29,35 @@
|
|
|
29
29
|
"files": [
|
|
30
30
|
"dist"
|
|
31
31
|
],
|
|
32
|
+
"dependencies": {
|
|
33
|
+
"@theholocron/env-utils": "^1.17.0-alpha.4"
|
|
34
|
+
},
|
|
32
35
|
"devDependencies": {
|
|
33
|
-
"@theholocron/cloudflare-client": "^1.25.0",
|
|
34
|
-
"@theholocron/eslint-config": "^8.4.5",
|
|
35
|
-
"@theholocron/http-client": "^1.25.0",
|
|
36
|
-
"@theholocron/tsconfig": "^8.4.5",
|
|
37
|
-
"@theholocron/tsdown-config": "^8.4.5",
|
|
38
|
-
"@theholocron/vitest-config": "^8.4.5",
|
|
39
36
|
"@types/node": "^26",
|
|
40
|
-
"@vitest/coverage-v8": "^
|
|
41
|
-
"@vitest/eslint-plugin": "^1.6.
|
|
42
|
-
"chalk": "^6.0.
|
|
43
|
-
"eslint": "^10.
|
|
44
|
-
"eslint-plugin-n": "^18.
|
|
45
|
-
"globals": "^17.
|
|
46
|
-
"tsdown": "^0.
|
|
47
|
-
"tsx": "4.23.
|
|
37
|
+
"@vitest/coverage-v8": "^5.1.0",
|
|
38
|
+
"@vitest/eslint-plugin": "^1.6.28",
|
|
39
|
+
"chalk": "^6.0.1",
|
|
40
|
+
"eslint": "^10.14.0",
|
|
41
|
+
"eslint-plugin-n": "^18.5.0",
|
|
42
|
+
"globals": "^17.14.0",
|
|
43
|
+
"tsdown": "^0.23.5",
|
|
44
|
+
"tsx": "4.23.15",
|
|
48
45
|
"typescript": "^5.9.3",
|
|
49
|
-
"vitest": "^
|
|
50
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
46
|
+
"vitest": "^5.1.0",
|
|
47
|
+
"@theholocron/cli": "5.0.0-alpha.450",
|
|
48
|
+
"@theholocron/cloudflare-client": "^1.58.0-alpha.35",
|
|
49
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.17",
|
|
50
|
+
"@theholocron/http-client": "^1.58.0-alpha.35",
|
|
51
|
+
"@theholocron/kyber": "5.0.0-alpha.450",
|
|
52
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.17",
|
|
53
|
+
"@theholocron/misc-utils": "^1.17.0-alpha.4",
|
|
54
|
+
"@theholocron/tsdown-config": "^8.9.0-alpha.17",
|
|
55
|
+
"@theholocron/tsconfig": "^8.9.0-alpha.17"
|
|
51
56
|
},
|
|
52
57
|
"peerDependencies": {
|
|
53
|
-
"@theholocron/cloudflare-client": "^1.
|
|
54
|
-
"@theholocron/
|
|
58
|
+
"@theholocron/cloudflare-client": "^1.53.1",
|
|
59
|
+
"@theholocron/misc-utils": "^1.16.0",
|
|
60
|
+
"@theholocron/cli": "5.0.0-alpha.450"
|
|
55
61
|
},
|
|
56
62
|
"peerDependenciesMeta": {
|
|
57
63
|
"@theholocron/cloudflare-client": {}
|
|
@@ -63,11 +69,11 @@
|
|
|
63
69
|
"access": "public"
|
|
64
70
|
},
|
|
65
71
|
"scripts": {
|
|
66
|
-
"
|
|
67
|
-
"
|
|
72
|
+
"build": "tsdown",
|
|
73
|
+
"lint:code": "eslint .",
|
|
74
|
+
"test:unit": "vitest run --coverage",
|
|
68
75
|
"test:watch": "vitest",
|
|
69
|
-
"
|
|
70
|
-
"
|
|
71
|
-
"verification.unitTests": "holocron run verification.unitTests --"
|
|
76
|
+
"typecheck": "tsc --noEmit",
|
|
77
|
+
"validate:plugin": "tsx scripts/validate.mjs"
|
|
72
78
|
}
|
|
73
79
|
}
|