@installagent/sdk 0.6.0 → 0.7.0
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/client-manifest.d.ts +32 -0
- package/dist/client-manifest.js +64 -0
- package/dist/doctor.js +94 -0
- package/dist/env-fill.js +3 -35
- package/dist/env-push.js +3 -16
- package/dist/gcp-dwd.d.ts +73 -0
- package/dist/gcp-dwd.js +269 -0
- package/dist/gcp-inspect.d.ts +126 -0
- package/dist/gcp-inspect.js +292 -0
- package/dist/gcp-service-account-key.d.ts +2 -0
- package/dist/gcp-service-account-key.js +1 -0
- package/dist/gcp-setup.d.ts +58 -0
- package/dist/gcp-setup.js +318 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +5 -0
- package/dist/op-cli.d.ts +14 -0
- package/dist/op-cli.js +35 -3
- package/dist/op-store.d.ts +60 -0
- package/dist/op-store.js +230 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +6 -0
- package/package.json +1 -1
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The two Google Cloud pointers in a client repo's CLIENT.md (client-template,
|
|
3
|
+
* 2026-10-25): `gcp_project` — the project ID that holds the client's OAuth
|
|
4
|
+
* client / service account / Pub/Sub topic — and `gcp_account` — the Google
|
|
5
|
+
* account every gcloud command for it runs as (`--account=`). `none` means
|
|
6
|
+
* the client has no project. repo-lint does NOT require them (its
|
|
7
|
+
* CLIENT_MD_KEYS list is unchanged), so older repos simply lack them;
|
|
8
|
+
* `ia template-sync` lists those repos and `ia doctor` checks the accounts
|
|
9
|
+
* are logged in. CLIENT.md is per-client and never synced, so nothing here
|
|
10
|
+
* writes it.
|
|
11
|
+
*/
|
|
12
|
+
export declare const GCP_MANIFEST_KEYS: readonly ["gcp_project", "gcp_account"];
|
|
13
|
+
export type GcpManifestKey = (typeof GCP_MANIFEST_KEYS)[number];
|
|
14
|
+
export interface GcpManifest {
|
|
15
|
+
/** The project ID, or null when the key is missing, unfilled, invalid or `none`. */
|
|
16
|
+
project: string | null;
|
|
17
|
+
/** The gcloud account, same rules. */
|
|
18
|
+
account: string | null;
|
|
19
|
+
/** True when gcp_project is `none` (the client has no Google Cloud project). */
|
|
20
|
+
none: boolean;
|
|
21
|
+
/** Keys CLIENT.md does not have at all (a repo made before 2026-10-25). */
|
|
22
|
+
missing: GcpManifestKey[];
|
|
23
|
+
/** Keys still holding the template placeholder (or empty). */
|
|
24
|
+
unfilled: GcpManifestKey[];
|
|
25
|
+
/** Keys whose value is not a project ID / an email / `none`. */
|
|
26
|
+
invalid: GcpManifestKey[];
|
|
27
|
+
}
|
|
28
|
+
/** One `key: value` line of CLIENT.md; undefined when the key is absent. */
|
|
29
|
+
export declare function readManifestKey(clientMd: string, key: string): string | undefined;
|
|
30
|
+
export declare function readGcpManifest(clientMd: string): GcpManifest;
|
|
31
|
+
/** The manifest of `<repoDir>/CLIENT.md`, or null when the repo has no CLIENT.md. */
|
|
32
|
+
export declare function readGcpManifestFromRepo(repoDir: string): GcpManifest | null;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { GCP_PROJECT_PATTERN } from "./gcp-service-account-key.js";
|
|
4
|
+
/**
|
|
5
|
+
* The two Google Cloud pointers in a client repo's CLIENT.md (client-template,
|
|
6
|
+
* 2026-10-25): `gcp_project` — the project ID that holds the client's OAuth
|
|
7
|
+
* client / service account / Pub/Sub topic — and `gcp_account` — the Google
|
|
8
|
+
* account every gcloud command for it runs as (`--account=`). `none` means
|
|
9
|
+
* the client has no project. repo-lint does NOT require them (its
|
|
10
|
+
* CLIENT_MD_KEYS list is unchanged), so older repos simply lack them;
|
|
11
|
+
* `ia template-sync` lists those repos and `ia doctor` checks the accounts
|
|
12
|
+
* are logged in. CLIENT.md is per-client and never synced, so nothing here
|
|
13
|
+
* writes it.
|
|
14
|
+
*/
|
|
15
|
+
export const GCP_MANIFEST_KEYS = ["gcp_project", "gcp_account"];
|
|
16
|
+
const EMAIL = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
|
|
17
|
+
/** One `key: value` line of CLIENT.md; undefined when the key is absent. */
|
|
18
|
+
export function readManifestKey(clientMd, key) {
|
|
19
|
+
const match = clientMd.match(new RegExp(`^${key}\\s*:(.*)$`, "m"));
|
|
20
|
+
return match ? match[1].trim() : undefined;
|
|
21
|
+
}
|
|
22
|
+
export function readGcpManifest(clientMd) {
|
|
23
|
+
const result = {
|
|
24
|
+
project: null,
|
|
25
|
+
account: null,
|
|
26
|
+
none: false,
|
|
27
|
+
missing: [],
|
|
28
|
+
unfilled: [],
|
|
29
|
+
invalid: [],
|
|
30
|
+
};
|
|
31
|
+
for (const key of GCP_MANIFEST_KEYS) {
|
|
32
|
+
const value = readManifestKey(clientMd, key);
|
|
33
|
+
if (value === undefined) {
|
|
34
|
+
result.missing.push(key);
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
if (!value || /^<.*>$/.test(value) || value.includes("_HERE")) {
|
|
38
|
+
result.unfilled.push(key);
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
if (value.toLowerCase() === "none") {
|
|
42
|
+
if (key === "gcp_project")
|
|
43
|
+
result.none = true;
|
|
44
|
+
continue;
|
|
45
|
+
}
|
|
46
|
+
const valid = key === "gcp_project" ? GCP_PROJECT_PATTERN.test(value) : EMAIL.test(value);
|
|
47
|
+
if (!valid) {
|
|
48
|
+
result.invalid.push(key);
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
if (key === "gcp_project")
|
|
52
|
+
result.project = value;
|
|
53
|
+
else
|
|
54
|
+
result.account = value;
|
|
55
|
+
}
|
|
56
|
+
return result;
|
|
57
|
+
}
|
|
58
|
+
/** The manifest of `<repoDir>/CLIENT.md`, or null when the repo has no CLIENT.md. */
|
|
59
|
+
export function readGcpManifestFromRepo(repoDir) {
|
|
60
|
+
const path = join(repoDir, "CLIENT.md");
|
|
61
|
+
if (!existsSync(path))
|
|
62
|
+
return null;
|
|
63
|
+
return readGcpManifest(readFileSync(path, "utf8"));
|
|
64
|
+
}
|
package/dist/doctor.js
CHANGED
|
@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
|
|
|
2
2
|
import { join, resolve } from "node:path";
|
|
3
3
|
import { N8N_API_KEY_ENV, N8N_API_URL_ENV } from "./agent-templates.js";
|
|
4
4
|
import { AIRTABLE_API_TOKEN_ENV, GOOGLE_SERVICE_ACCOUNT_KEY_ENV } from "./client-drive.js";
|
|
5
|
+
import { readGcpManifestFromRepo } from "./client-manifest.js";
|
|
5
6
|
import { DOCS_SEARCH_TOKEN_ENV, DOCS_SESSION_ENV, TEAM_DOCS_BASE_URL } from "./docs-search.js";
|
|
6
7
|
import { parseEnvFile } from "./env-file.js";
|
|
7
8
|
import { DEFAULT_TECH_VAULT, opSecretReference, TECH_ENV_VARS, } from "./env-registry.js";
|
|
@@ -101,6 +102,7 @@ export async function doctor(options = {}) {
|
|
|
101
102
|
checks.push(await ghCheck(execFileImpl, env, platform));
|
|
102
103
|
checks.push(await opCheck(execFileImpl, platform));
|
|
103
104
|
checks.push(await gcloudCheck(execFileImpl));
|
|
105
|
+
checks.push(await clientGcpAccountsCheck(workspaceDir, execFileImpl));
|
|
104
106
|
// Technician vars only. Admin vars are all doctor:false today, so this
|
|
105
107
|
// changes nothing now — it is here so that adding a doctor:true infra var
|
|
106
108
|
// later cannot start naming it in every technician's checkup.
|
|
@@ -177,6 +179,89 @@ function lefthookCheck(workspaceDir, fixed) {
|
|
|
177
179
|
"runs without it",
|
|
178
180
|
};
|
|
179
181
|
}
|
|
182
|
+
/**
|
|
183
|
+
* CLIENT.md's `gcp_account` names the Google account every gcloud command for
|
|
184
|
+
* that client runs as. This checks each named account is logged in on this
|
|
185
|
+
* machine (`gcloud auth list` — account names only, never a token), and that
|
|
186
|
+
* the two keys hold a project ID / an email / `none`. Repos without the keys
|
|
187
|
+
* (made before 2026-10-25) are not a problem here — `ia template-sync` lists
|
|
188
|
+
* them — so the check stays quiet until a repo records an account. Read-only.
|
|
189
|
+
*/
|
|
190
|
+
async function clientGcpAccountsCheck(workspaceDir, execFileImpl) {
|
|
191
|
+
const base = {
|
|
192
|
+
id: "workspace/client-gcp-accounts",
|
|
193
|
+
group: "workspace",
|
|
194
|
+
label: "gcloud accounts named in client CLIENT.md files",
|
|
195
|
+
};
|
|
196
|
+
const needed = new Map();
|
|
197
|
+
const invalid = [];
|
|
198
|
+
let unrecorded = 0;
|
|
199
|
+
for (const name of clientCloneNames(workspaceDir)) {
|
|
200
|
+
if (name === "client-template")
|
|
201
|
+
continue;
|
|
202
|
+
const manifest = readGcpManifestFromRepo(join(workspaceDir, "clients", name));
|
|
203
|
+
if (!manifest)
|
|
204
|
+
continue;
|
|
205
|
+
for (const key of manifest.invalid)
|
|
206
|
+
invalid.push(`${name} ${key}`);
|
|
207
|
+
if (manifest.missing.length > 0 || manifest.unfilled.length > 0)
|
|
208
|
+
unrecorded++;
|
|
209
|
+
if (manifest.account)
|
|
210
|
+
needed.set(manifest.account, [...(needed.get(manifest.account) ?? []), name]);
|
|
211
|
+
}
|
|
212
|
+
const unrecordedNote = unrecorded > 0
|
|
213
|
+
? ` ${unrecorded} repo(s) do not record gcp_project/gcp_account yet (\`ia template-sync\` lists them).`
|
|
214
|
+
: "";
|
|
215
|
+
if (invalid.length > 0) {
|
|
216
|
+
return {
|
|
217
|
+
...base,
|
|
218
|
+
status: "warn",
|
|
219
|
+
detail: `CLIENT.md value is not a project ID, an email or \`none\`: ${invalid.join(", ")}.${unrecordedNote}`,
|
|
220
|
+
fixIt: "fix the value in that repo's CLIENT.md (gcp_project = the project ID, gcp_account = an email, or `none`)",
|
|
221
|
+
};
|
|
222
|
+
}
|
|
223
|
+
if (needed.size === 0) {
|
|
224
|
+
return {
|
|
225
|
+
...base,
|
|
226
|
+
status: "ok",
|
|
227
|
+
verboseOnly: true,
|
|
228
|
+
detail: `no client repo names a gcp_account yet.${unrecordedNote}`.trim(),
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
let loggedIn;
|
|
232
|
+
try {
|
|
233
|
+
const { stdout } = await execFileImpl("gcloud", ["auth", "list", "--format=value(account)"]);
|
|
234
|
+
loggedIn = new Set(stdout
|
|
235
|
+
.split("\n")
|
|
236
|
+
.map((line) => (line.split("\t")[0] ?? "").trim().toLowerCase())
|
|
237
|
+
.filter(Boolean));
|
|
238
|
+
}
|
|
239
|
+
catch {
|
|
240
|
+
// tools/gcloud already says why gcloud is unusable; do not repeat it as a second warning.
|
|
241
|
+
return {
|
|
242
|
+
...base,
|
|
243
|
+
status: "ok",
|
|
244
|
+
verboseOnly: true,
|
|
245
|
+
detail: `could not run \`gcloud auth list\` — see the gcloud check.${unrecordedNote}`,
|
|
246
|
+
};
|
|
247
|
+
}
|
|
248
|
+
const absent = [...needed.entries()].filter(([account]) => !loggedIn.has(account.toLowerCase()));
|
|
249
|
+
if (absent.length === 0) {
|
|
250
|
+
return {
|
|
251
|
+
...base,
|
|
252
|
+
status: "ok",
|
|
253
|
+
detail: `every named account is logged in (${[...needed.keys()].join(", ")}).${unrecordedNote}`,
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
return {
|
|
257
|
+
...base,
|
|
258
|
+
status: "warn",
|
|
259
|
+
detail: absent
|
|
260
|
+
.map(([account, repos]) => `${account} (needed by ${repos.join(", ")}) is not logged in to gcloud`)
|
|
261
|
+
.join("; "),
|
|
262
|
+
fixIt: absent.map(([account]) => `gcloud auth login ${account}`).join(" && "),
|
|
263
|
+
};
|
|
264
|
+
}
|
|
180
265
|
/**
|
|
181
266
|
* The root .env is created once from env.example and never overwritten, so
|
|
182
267
|
* vars added to the registry later are silently absent from older files —
|
|
@@ -414,6 +499,15 @@ async function opCheck(execFileImpl, platform) {
|
|
|
414
499
|
fixIt: `needed by \`ia env fill\` — ${opInstallFix(platform)}`,
|
|
415
500
|
};
|
|
416
501
|
}
|
|
502
|
+
// The desktop app integration fails `whoami` but authorizes real calls
|
|
503
|
+
// (see opReachable in op-cli.ts).
|
|
504
|
+
try {
|
|
505
|
+
await execFileImpl("op", ["vault", "list", "--format=json"]);
|
|
506
|
+
return { ...base, status: "ok", detail: "reachable through the 1Password app" };
|
|
507
|
+
}
|
|
508
|
+
catch {
|
|
509
|
+
// fall through to the warning
|
|
510
|
+
}
|
|
417
511
|
return {
|
|
418
512
|
...base,
|
|
419
513
|
status: "warn",
|
package/dist/env-fill.js
CHANGED
|
@@ -3,8 +3,8 @@ import { copyFile, readFile, writeFile } from "node:fs/promises";
|
|
|
3
3
|
import { join, resolve } from "node:path";
|
|
4
4
|
import { parseEnvFile } from "./env-file.js";
|
|
5
5
|
import { ADMIN_ENV_VARS, DEFAULT_TECH_VAULT, envVarsForRole, TECH_ENV_VARS, } from "./env-registry.js";
|
|
6
|
-
import {
|
|
7
|
-
import {
|
|
6
|
+
import { execFileAsync } from "./exec.js";
|
|
7
|
+
import { opReachable } from "./op-cli.js";
|
|
8
8
|
import { detectPlatformInfo } from "./platform.js";
|
|
9
9
|
import { envExampleTemplatePath } from "./templates.js";
|
|
10
10
|
/** Values op read fields are tried in when the registry doesn't pin one. */
|
|
@@ -28,7 +28,7 @@ export async function envFill(options = {}) {
|
|
|
28
28
|
const platform = options.platform ?? detectPlatformInfo();
|
|
29
29
|
const envPath = join(workspaceDir, ".env");
|
|
30
30
|
const adminSkipped = includeAdmin ? 0 : ADMIN_ENV_VARS.length;
|
|
31
|
-
const opReady = await
|
|
31
|
+
const opReady = await opReachable(execFileImpl, platform);
|
|
32
32
|
if (opReady !== true) {
|
|
33
33
|
return {
|
|
34
34
|
ok: false,
|
|
@@ -108,38 +108,6 @@ export async function envFill(options = {}) {
|
|
|
108
108
|
nextSteps,
|
|
109
109
|
};
|
|
110
110
|
}
|
|
111
|
-
/**
|
|
112
|
-
* True when op is installed and can reach the vaults; otherwise the fix-it step.
|
|
113
|
-
*
|
|
114
|
-
* `op whoami` is the obvious probe but NOT a sufficient one: with the desktop
|
|
115
|
-
* app integration on, op 2.35 answers "account is not signed in" to `whoami`
|
|
116
|
-
* while `op read` and `op vault list` both work — the CLI has no session of its
|
|
117
|
-
* own, and the app authorizes each call. Failing preflight there told a
|
|
118
|
-
* technician to enable an integration that was already enabled, and blocked a
|
|
119
|
-
* fill that would have succeeded. So a `whoami` failure falls through to a
|
|
120
|
-
* vault-listing probe, which is what this command actually needs to do.
|
|
121
|
-
*/
|
|
122
|
-
async function opPreflight(execFileImpl, platform) {
|
|
123
|
-
try {
|
|
124
|
-
await execFileImpl("op", ["whoami"]);
|
|
125
|
-
return true;
|
|
126
|
-
}
|
|
127
|
-
catch (error) {
|
|
128
|
-
const { code } = execFailureDetail(error);
|
|
129
|
-
if (code === "ENOENT")
|
|
130
|
-
return opInstallFix(platform);
|
|
131
|
-
try {
|
|
132
|
-
await execFileImpl("op", ["vault", "list", "--format=json"]);
|
|
133
|
-
return true;
|
|
134
|
-
}
|
|
135
|
-
catch (fallbackError) {
|
|
136
|
-
const detail = execFailureDetail(fallbackError);
|
|
137
|
-
if (detail.code === "ENOENT")
|
|
138
|
-
return opInstallFix(platform);
|
|
139
|
-
return `authenticate the 1Password CLI: ${opIntegrationFix(platform)}`;
|
|
140
|
-
}
|
|
141
|
-
}
|
|
142
|
-
}
|
|
143
111
|
async function opRead(execFileImpl, vault, spec) {
|
|
144
112
|
const item = spec.item ?? spec.name;
|
|
145
113
|
const fields = spec.field ? [spec.field] : OP_FIELD_FALLBACKS;
|
package/dist/env-push.js
CHANGED
|
@@ -2,8 +2,8 @@ import { readFile } from "node:fs/promises";
|
|
|
2
2
|
import { join, resolve } from "node:path";
|
|
3
3
|
import { parseEnvFile } from "./env-file.js";
|
|
4
4
|
import { DEFAULT_TECH_VAULT, ENV_VARS } from "./env-registry.js";
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
5
|
+
import { execFileAsync } from "./exec.js";
|
|
6
|
+
import { opReachable } from "./op-cli.js";
|
|
7
7
|
import { detectPlatformInfo } from "./platform.js";
|
|
8
8
|
/**
|
|
9
9
|
* Push the workspace root .env up into the team 1Password vaults via the
|
|
@@ -24,7 +24,7 @@ export async function envPush(options = {}) {
|
|
|
24
24
|
// already holds the grants.
|
|
25
25
|
const platform = options.platform ?? detectPlatformInfo();
|
|
26
26
|
const envPath = join(workspaceDir, ".env");
|
|
27
|
-
const opReady = await
|
|
27
|
+
const opReady = await opReachable(execFileImpl, platform);
|
|
28
28
|
if (opReady !== true) {
|
|
29
29
|
return {
|
|
30
30
|
ok: false,
|
|
@@ -98,19 +98,6 @@ export async function envPush(options = {}) {
|
|
|
98
98
|
nextSteps,
|
|
99
99
|
};
|
|
100
100
|
}
|
|
101
|
-
/** True when op is installed and signed in; otherwise the fix-it next step. */
|
|
102
|
-
async function opPreflight(execFileImpl, platform) {
|
|
103
|
-
try {
|
|
104
|
-
await execFileImpl("op", ["whoami"]);
|
|
105
|
-
return true;
|
|
106
|
-
}
|
|
107
|
-
catch (error) {
|
|
108
|
-
const { code } = execFailureDetail(error);
|
|
109
|
-
if (code === "ENOENT")
|
|
110
|
-
return opInstallFix(platform);
|
|
111
|
-
return `authenticate the 1Password CLI: ${opIntegrationFix(platform)}`;
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
101
|
/** Update the vault item if it exists; create it if it doesn't. Never throws. */
|
|
115
102
|
async function opWrite(execFileImpl, vault, spec, value) {
|
|
116
103
|
const item = spec.item ?? spec.name;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
import { type GcpStepStatus } from "./gcp-setup.js";
|
|
3
|
+
import { type MintToOpOptions, type MintToOpResult } from "./op-store.js";
|
|
4
|
+
/**
|
|
5
|
+
* `ia gcp dwd` (2026-10-26): set up domain-wide delegation for one service
|
|
6
|
+
* account — the account itself (no roles), one key written straight into
|
|
7
|
+
* 1Password (never printed), and the exact text the client's Workspace super
|
|
8
|
+
* admin needs to authorize it.
|
|
9
|
+
*
|
|
10
|
+
* Plan by default: it only reads. `apply: true` creates the account if it is
|
|
11
|
+
* missing, then mints the key into the vault. Check-then-skip: once the
|
|
12
|
+
* account has a user-managed key, a re-run does not mint another one unless
|
|
13
|
+
* `newKey` is set (rotation). It never grants a role to the service account,
|
|
14
|
+
* never changes an org policy (it prints the override command instead), and
|
|
15
|
+
* never touches the Workspace admin console — the client's admin does that.
|
|
16
|
+
*/
|
|
17
|
+
export declare const DWD_ADMIN_CONSOLE_URL = "https://admin.google.com/ac/owl/domainwidedelegation";
|
|
18
|
+
export declare const KEY_CREATION_POLICY = "iam.disableServiceAccountKeyCreation";
|
|
19
|
+
export interface GcpDwdStep {
|
|
20
|
+
id: "service-account" | "key-policy" | "key";
|
|
21
|
+
title: string;
|
|
22
|
+
status: GcpStepStatus;
|
|
23
|
+
/** The gcloud args (without the binary) for a todo/ran/failed step. */
|
|
24
|
+
command?: string[];
|
|
25
|
+
detail?: string;
|
|
26
|
+
}
|
|
27
|
+
export interface GcpDwdOptions {
|
|
28
|
+
project: string;
|
|
29
|
+
account: string;
|
|
30
|
+
/** Service-account name (the part before @). Created with no roles if missing. */
|
|
31
|
+
serviceAccount: string;
|
|
32
|
+
/** OAuth scopes the admin authorizes: `gmail.readonly` or the full URL. At least one. */
|
|
33
|
+
scopes: string[];
|
|
34
|
+
/** 1Password vault the key goes into, e.g. `client-<slug>`. */
|
|
35
|
+
vault: string;
|
|
36
|
+
/** Item title. Default: `<project> - gcp-sa-key - <name>`. */
|
|
37
|
+
opTitle?: string;
|
|
38
|
+
/** Mint a key even when the account already has one (rotation). */
|
|
39
|
+
newKey?: boolean;
|
|
40
|
+
apply?: boolean;
|
|
41
|
+
execFileImpl?: ExecFileFn;
|
|
42
|
+
/** Injectable for tests; defaults to `mintToOnePassword`. */
|
|
43
|
+
mintToOpImpl?: (o: MintToOpOptions) => Promise<MintToOpResult>;
|
|
44
|
+
}
|
|
45
|
+
export interface GcpDwdResult {
|
|
46
|
+
project: string;
|
|
47
|
+
account: string;
|
|
48
|
+
serviceAccountEmail: string;
|
|
49
|
+
/** The service account's numeric unique ID — the Client ID the admin enters. */
|
|
50
|
+
clientId: string | null;
|
|
51
|
+
scopes: string[];
|
|
52
|
+
applied: boolean;
|
|
53
|
+
/** False when a step is blocked (plan) or failed (apply). */
|
|
54
|
+
ok: boolean;
|
|
55
|
+
steps: GcpDwdStep[];
|
|
56
|
+
/** Where the key went: a pointer, never the value. */
|
|
57
|
+
stored: {
|
|
58
|
+
vault: string;
|
|
59
|
+
title: string;
|
|
60
|
+
reference: string;
|
|
61
|
+
details: string[];
|
|
62
|
+
} | null;
|
|
63
|
+
/** Set when a key was minted but not stored: how to revoke it. */
|
|
64
|
+
revoke?: string;
|
|
65
|
+
/** Text for the client's Workspace super admin; null until the Client ID is known. */
|
|
66
|
+
adminText: string[] | null;
|
|
67
|
+
nextSteps: string[];
|
|
68
|
+
}
|
|
69
|
+
/** `gmail.readonly` → `https://www.googleapis.com/auth/gmail.readonly`; full URLs pass through. */
|
|
70
|
+
export declare function normalizeDwdScope(scope: string): string;
|
|
71
|
+
/** The steps the client's Workspace super admin follows. Ids and scopes only, no secret. */
|
|
72
|
+
export declare function dwdAdminText(clientId: string, scopes: readonly string[]): string[];
|
|
73
|
+
export declare function gcpDwd(options: GcpDwdOptions): Promise<GcpDwdResult>;
|
package/dist/gcp-dwd.js
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
import { execFailureDetail, execFileAsync } from "./exec.js";
|
|
2
|
+
import { describeInspectFailure, describePolicy, gcloudArgs, isGcloudLoginFailure, validateGcpTarget, } from "./gcp-inspect.js";
|
|
3
|
+
import { formatGcloud } from "./gcp-setup.js";
|
|
4
|
+
import { mintToOnePassword } from "./op-store.js";
|
|
5
|
+
/**
|
|
6
|
+
* `ia gcp dwd` (2026-10-26): set up domain-wide delegation for one service
|
|
7
|
+
* account — the account itself (no roles), one key written straight into
|
|
8
|
+
* 1Password (never printed), and the exact text the client's Workspace super
|
|
9
|
+
* admin needs to authorize it.
|
|
10
|
+
*
|
|
11
|
+
* Plan by default: it only reads. `apply: true` creates the account if it is
|
|
12
|
+
* missing, then mints the key into the vault. Check-then-skip: once the
|
|
13
|
+
* account has a user-managed key, a re-run does not mint another one unless
|
|
14
|
+
* `newKey` is set (rotation). It never grants a role to the service account,
|
|
15
|
+
* never changes an org policy (it prints the override command instead), and
|
|
16
|
+
* never touches the Workspace admin console — the client's admin does that.
|
|
17
|
+
*/
|
|
18
|
+
export const DWD_ADMIN_CONSOLE_URL = "https://admin.google.com/ac/owl/domainwidedelegation";
|
|
19
|
+
export const KEY_CREATION_POLICY = "iam.disableServiceAccountKeyCreation";
|
|
20
|
+
const SA_NAME = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
|
|
21
|
+
const SCOPE_URL = /^https:\/\/www\.googleapis\.com\/auth\/[a-z0-9._-]+$/;
|
|
22
|
+
const SCOPE_SHORT = /^[a-z][a-z0-9._-]*$/;
|
|
23
|
+
/** Gmail's full-access scope has no googleapis.com/auth form. */
|
|
24
|
+
const GMAIL_FULL_SCOPE = "https://mail.google.com/";
|
|
25
|
+
/** `gmail.readonly` → `https://www.googleapis.com/auth/gmail.readonly`; full URLs pass through. */
|
|
26
|
+
export function normalizeDwdScope(scope) {
|
|
27
|
+
const s = scope.trim();
|
|
28
|
+
if (s === GMAIL_FULL_SCOPE || SCOPE_URL.test(s))
|
|
29
|
+
return s;
|
|
30
|
+
if (SCOPE_SHORT.test(s))
|
|
31
|
+
return `https://www.googleapis.com/auth/${s}`;
|
|
32
|
+
throw new Error(`invalid scope "${s}" — pass e.g. gmail.readonly or https://www.googleapis.com/auth/gmail.readonly`);
|
|
33
|
+
}
|
|
34
|
+
/** The steps the client's Workspace super admin follows. Ids and scopes only, no secret. */
|
|
35
|
+
export function dwdAdminText(clientId, scopes) {
|
|
36
|
+
return [
|
|
37
|
+
"For the Google Workspace super admin:",
|
|
38
|
+
`1. Open ${DWD_ADMIN_CONSOLE_URL}`,
|
|
39
|
+
"2. Click Add new.",
|
|
40
|
+
`3. Client ID: ${clientId}`,
|
|
41
|
+
`4. OAuth scopes (comma-delimited): ${scopes.join(",")}`,
|
|
42
|
+
"5. Click Authorize.",
|
|
43
|
+
"This lets our service account read data for users in your domain, for these scopes only. You can remove it on the same page at any time.",
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
export async function gcpDwd(options) {
|
|
47
|
+
const project = options.project.trim();
|
|
48
|
+
const account = options.account.trim();
|
|
49
|
+
validateGcpTarget(project, account);
|
|
50
|
+
const saName = options.serviceAccount.trim();
|
|
51
|
+
if (!SA_NAME.test(saName)) {
|
|
52
|
+
throw new Error(`invalid service-account name "${saName}" — 6–30 characters: lowercase letters, digits, hyphens`);
|
|
53
|
+
}
|
|
54
|
+
const scopes = [...new Set(options.scopes.map(normalizeDwdScope))];
|
|
55
|
+
if (!scopes.length)
|
|
56
|
+
throw new Error("pass at least one --scope, e.g. --scope gmail.readonly");
|
|
57
|
+
const vault = options.vault.trim();
|
|
58
|
+
if (!vault)
|
|
59
|
+
throw new Error("--to-op needs a 1Password vault, e.g. client-<slug>");
|
|
60
|
+
const exec = options.execFileImpl ?? execFileAsync;
|
|
61
|
+
const mintToOp = options.mintToOpImpl ?? mintToOnePassword;
|
|
62
|
+
const args = (a) => gcloudArgs(a, project, account);
|
|
63
|
+
const read = async (a) => (await exec("gcloud", args(a))).stdout;
|
|
64
|
+
const email = `${saName}@${project}.iam.gserviceaccount.com`;
|
|
65
|
+
const describeSa = async () => JSON.parse(await read(["iam", "service-accounts", "describe", email, "--format=json"])).uniqueId ?? null;
|
|
66
|
+
// ── Plan: reads only ──────────────────────────────────────────────────
|
|
67
|
+
const steps = [];
|
|
68
|
+
let clientId = null;
|
|
69
|
+
let saExists = false;
|
|
70
|
+
try {
|
|
71
|
+
clientId = await describeSa();
|
|
72
|
+
saExists = true;
|
|
73
|
+
steps.push({
|
|
74
|
+
id: "service-account",
|
|
75
|
+
title: `Service account ${email}`,
|
|
76
|
+
status: "done",
|
|
77
|
+
detail: `exists (Client ID ${clientId ?? "unknown"})`,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
catch (error) {
|
|
81
|
+
const { detail } = execFailureDetail(error);
|
|
82
|
+
if (/NOT_FOUND|does not exist/i.test(detail)) {
|
|
83
|
+
steps.push({
|
|
84
|
+
id: "service-account",
|
|
85
|
+
title: `Service account ${email}`,
|
|
86
|
+
status: "todo",
|
|
87
|
+
command: args(["iam", "service-accounts", "create", saName, `--display-name=${saName}`]),
|
|
88
|
+
detail: "will be created with no roles",
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
else {
|
|
92
|
+
steps.push({
|
|
93
|
+
id: "service-account",
|
|
94
|
+
title: `Service account ${email}`,
|
|
95
|
+
status: "blocked",
|
|
96
|
+
detail: isGcloudLoginFailure(error)
|
|
97
|
+
? describeInspectFailure(error, account)
|
|
98
|
+
: `${describeInspectFailure(error, account)}. Does the project exist? ia gcp setup -p ${project} -a ${account} makes it`,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
try {
|
|
103
|
+
const raw = JSON.parse((await read([
|
|
104
|
+
"resource-manager",
|
|
105
|
+
"org-policies",
|
|
106
|
+
"describe",
|
|
107
|
+
KEY_CREATION_POLICY,
|
|
108
|
+
"--effective",
|
|
109
|
+
"--format=json",
|
|
110
|
+
])) || "null");
|
|
111
|
+
const state = describePolicy(raw);
|
|
112
|
+
steps.push(state === "enforced"
|
|
113
|
+
? {
|
|
114
|
+
id: "key-policy",
|
|
115
|
+
title: `Org policy ${KEY_CREATION_POLICY}`,
|
|
116
|
+
status: "blocked",
|
|
117
|
+
detail: `enforced, so no key can be made. An org policy admin can turn it off for this project only (the command is not run by ia): $ ${formatGcloud(args(["resource-manager", "org-policies", "disable-enforce", KEY_CREATION_POLICY]))}`,
|
|
118
|
+
}
|
|
119
|
+
: {
|
|
120
|
+
id: "key-policy",
|
|
121
|
+
title: `Org policy ${KEY_CREATION_POLICY}`,
|
|
122
|
+
status: "done",
|
|
123
|
+
detail: state,
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
catch (error) {
|
|
127
|
+
steps.push({
|
|
128
|
+
id: "key-policy",
|
|
129
|
+
title: `Org policy ${KEY_CREATION_POLICY}`,
|
|
130
|
+
status: "unknown",
|
|
131
|
+
detail: `could not read (${describeInspectFailure(error, account)}); the key step fails clearly if it is enforced`,
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
let existingKeys = saExists ? null : 0;
|
|
135
|
+
let keysNote = "";
|
|
136
|
+
if (saExists) {
|
|
137
|
+
try {
|
|
138
|
+
existingKeys = (await read([
|
|
139
|
+
"iam",
|
|
140
|
+
"service-accounts",
|
|
141
|
+
"keys",
|
|
142
|
+
"list",
|
|
143
|
+
`--iam-account=${email}`,
|
|
144
|
+
"--managed-by=user",
|
|
145
|
+
"--format=value(name)",
|
|
146
|
+
]))
|
|
147
|
+
.split("\n")
|
|
148
|
+
.filter((l) => l.trim()).length;
|
|
149
|
+
}
|
|
150
|
+
catch (error) {
|
|
151
|
+
keysNote = `could not list keys (${describeInspectFailure(error, account)}); `;
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
const title = options.opTitle?.trim() || `${project} - gcp-sa-key - ${saName}`;
|
|
155
|
+
if (existingKeys && !options.newKey) {
|
|
156
|
+
steps.push({
|
|
157
|
+
id: "key",
|
|
158
|
+
title: "Key in 1Password",
|
|
159
|
+
status: "done",
|
|
160
|
+
detail: `${existingKeys} user-managed key(s) exist — no new key. To rotate, pass --new-key, then delete the old key once n8n uses the new one`,
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
else {
|
|
164
|
+
steps.push({
|
|
165
|
+
id: "key",
|
|
166
|
+
title: "Key in 1Password",
|
|
167
|
+
status: "todo",
|
|
168
|
+
detail: `${keysNote}will mint one key into vault "${vault}" as "${title}" (never printed)${existingKeys ? `; ${existingKeys} older key(s) stay until you delete them` : ""}`,
|
|
169
|
+
});
|
|
170
|
+
}
|
|
171
|
+
const blocked = steps.some((s) => s.status === "blocked");
|
|
172
|
+
const todo = steps.some((s) => s.status === "todo");
|
|
173
|
+
const base = { project, account, serviceAccountEmail: email, scopes, stored: null };
|
|
174
|
+
const nextSteps = [];
|
|
175
|
+
if (!options.apply || blocked || !todo) {
|
|
176
|
+
if (blocked)
|
|
177
|
+
nextSteps.push("Fix the blocked step(s), then run the plan again.");
|
|
178
|
+
else if (todo)
|
|
179
|
+
nextSteps.push("Read the steps above, then run the same command with --apply.");
|
|
180
|
+
else
|
|
181
|
+
nextSteps.push('Nothing to do — send the "For the Google Workspace super admin" steps if the client has not had them yet.');
|
|
182
|
+
if (options.apply && blocked)
|
|
183
|
+
nextSteps.push("--apply ran nothing because a step is blocked.");
|
|
184
|
+
return {
|
|
185
|
+
...base,
|
|
186
|
+
clientId,
|
|
187
|
+
applied: false,
|
|
188
|
+
ok: !blocked,
|
|
189
|
+
steps,
|
|
190
|
+
adminText: clientId ? dwdAdminText(clientId, scopes) : null,
|
|
191
|
+
nextSteps,
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
// ── Apply: account first, then the key; stop at the first failure ─────
|
|
195
|
+
let stored = null;
|
|
196
|
+
let revoke;
|
|
197
|
+
let failed = false;
|
|
198
|
+
for (const step of steps) {
|
|
199
|
+
if (step.status !== "todo")
|
|
200
|
+
continue;
|
|
201
|
+
if (failed) {
|
|
202
|
+
step.status = "skipped";
|
|
203
|
+
continue;
|
|
204
|
+
}
|
|
205
|
+
if (step.id === "service-account" && step.command) {
|
|
206
|
+
try {
|
|
207
|
+
await exec("gcloud", step.command);
|
|
208
|
+
step.status = "ran";
|
|
209
|
+
clientId = await describeSa().catch(() => null);
|
|
210
|
+
step.detail = clientId
|
|
211
|
+
? `created with no roles (Client ID ${clientId})`
|
|
212
|
+
: "created with no roles (Client ID not readable yet — run the plan again)";
|
|
213
|
+
}
|
|
214
|
+
catch (error) {
|
|
215
|
+
failed = true;
|
|
216
|
+
step.status = "failed";
|
|
217
|
+
step.detail = describeInspectFailure(error, account);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
else if (step.id === "key") {
|
|
221
|
+
const result = await mintToOp({
|
|
222
|
+
request: {
|
|
223
|
+
type: "gcp-service-account-key",
|
|
224
|
+
project,
|
|
225
|
+
serviceAccountEmail: email,
|
|
226
|
+
account,
|
|
227
|
+
},
|
|
228
|
+
vault,
|
|
229
|
+
title,
|
|
230
|
+
});
|
|
231
|
+
if (result.ok) {
|
|
232
|
+
step.status = "ran";
|
|
233
|
+
step.detail = `stored as ${result.reference}`;
|
|
234
|
+
stored = {
|
|
235
|
+
vault: result.vault,
|
|
236
|
+
title: result.title,
|
|
237
|
+
reference: result.reference,
|
|
238
|
+
details: result.details,
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
else {
|
|
242
|
+
failed = true;
|
|
243
|
+
step.status = "failed";
|
|
244
|
+
step.detail = result.error;
|
|
245
|
+
revoke = result.revoke;
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
if (failed) {
|
|
250
|
+
nextSteps.push("Fix the failed step, then run the same command again: done steps are skipped.");
|
|
251
|
+
if (steps[0].status === "ran")
|
|
252
|
+
nextSteps.push("A new service account can take a minute to appear for key creation.");
|
|
253
|
+
}
|
|
254
|
+
else {
|
|
255
|
+
nextSteps.push('Send the "For the Google Workspace super admin" steps to the client\'s Workspace super admin.');
|
|
256
|
+
nextSteps.push(`In n8n, make the credential from ${stored?.reference ?? "the 1Password item"}.`);
|
|
257
|
+
}
|
|
258
|
+
return {
|
|
259
|
+
...base,
|
|
260
|
+
clientId,
|
|
261
|
+
applied: true,
|
|
262
|
+
ok: !failed,
|
|
263
|
+
steps,
|
|
264
|
+
stored,
|
|
265
|
+
...(revoke ? { revoke } : {}),
|
|
266
|
+
adminText: clientId ? dwdAdminText(clientId, scopes) : null,
|
|
267
|
+
nextSteps,
|
|
268
|
+
};
|
|
269
|
+
}
|