@installagent/sdk 0.6.0 → 0.8.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/access-check.d.ts +32 -0
- package/dist/access-check.js +339 -0
- 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 +6 -0
- package/dist/index.js +6 -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/pr-open.d.ts +3 -1
- package/dist/pr-open.js +9 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +9 -0
- package/package.json +1 -1
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
|
+
}
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
/**
|
|
3
|
+
* `ia gcp inspect` (2026-10-25): a READ-ONLY report on one Google Cloud
|
|
4
|
+
* project, so a technician sees what a setup step will meet before running
|
|
5
|
+
* it. Every gcloud call carries `--account=` and `--project=` — this machine
|
|
6
|
+
* often has a client account active (see AGENT.md), and an implicit default
|
|
7
|
+
* is how a command lands in the wrong project. Nothing here writes to GCP.
|
|
8
|
+
*
|
|
9
|
+
* Each section fails on its own: admin@ often lacks one permission on a
|
|
10
|
+
* client project (serviceusage on half our org), and the other sections are
|
|
11
|
+
* still worth having. Human members of the IAM policy are masked to their
|
|
12
|
+
* domain (client PII); service accounts and the operator's own account stay
|
|
13
|
+
* whole. The Monitoring access token goes straight into a request header and
|
|
14
|
+
* is never logged, returned or printed.
|
|
15
|
+
*/
|
|
16
|
+
/** The org policies a setup step trips over (DWD key, Gmail push grant). */
|
|
17
|
+
export declare const GCP_INSPECT_POLICIES: readonly ["iam.disableServiceAccountKeyCreation", "iam.allowedPolicyMemberDomains"];
|
|
18
|
+
/** APIs a client setup usually needs; the report flags each as on or off. */
|
|
19
|
+
export declare const GCP_INSPECT_KEY_APIS: readonly ["gmail.googleapis.com", "pubsub.googleapis.com", "iam.googleapis.com", "monitoring.googleapis.com", "generativelanguage.googleapis.com", "drive.googleapis.com"];
|
|
20
|
+
/** A user-managed key older than this is flagged for rotation. */
|
|
21
|
+
export declare const GCP_KEY_MAX_AGE_DAYS = 90;
|
|
22
|
+
export type GcpSection<T> = {
|
|
23
|
+
ok: true;
|
|
24
|
+
data: T;
|
|
25
|
+
} | {
|
|
26
|
+
ok: false;
|
|
27
|
+
error: string;
|
|
28
|
+
};
|
|
29
|
+
export interface GcpProjectInfo {
|
|
30
|
+
projectId: string;
|
|
31
|
+
projectNumber: string;
|
|
32
|
+
name: string;
|
|
33
|
+
/** e.g. `organization/123` or `folder/456`; null for a project with no parent. */
|
|
34
|
+
parent: string | null;
|
|
35
|
+
lifecycleState: string;
|
|
36
|
+
}
|
|
37
|
+
export interface GcpApisInfo {
|
|
38
|
+
enabled: string[];
|
|
39
|
+
/** Each of GCP_INSPECT_KEY_APIS with its state. */
|
|
40
|
+
key: {
|
|
41
|
+
service: string;
|
|
42
|
+
enabled: boolean;
|
|
43
|
+
}[];
|
|
44
|
+
}
|
|
45
|
+
export interface GcpPolicyState {
|
|
46
|
+
constraint: string;
|
|
47
|
+
/** `enforced` / `not enforced` for a boolean policy; `allow all`, `deny all`, `N allowed` for a list policy. */
|
|
48
|
+
state: string;
|
|
49
|
+
}
|
|
50
|
+
export interface GcpKeyInfo {
|
|
51
|
+
/** The key id (the last segment of its resource name) — an id, not key material. */
|
|
52
|
+
id: string;
|
|
53
|
+
createdAt: string;
|
|
54
|
+
ageDays: number;
|
|
55
|
+
disabled: boolean;
|
|
56
|
+
/** True when ageDays > GCP_KEY_MAX_AGE_DAYS. */
|
|
57
|
+
old: boolean;
|
|
58
|
+
}
|
|
59
|
+
export interface GcpServiceAccountInfo {
|
|
60
|
+
email: string;
|
|
61
|
+
disabled: boolean;
|
|
62
|
+
/** Project-level roles bound to this service account. */
|
|
63
|
+
roles: string[];
|
|
64
|
+
/** User-managed keys only (Google-managed keys rotate themselves). */
|
|
65
|
+
keys: GcpSection<GcpKeyInfo[]>;
|
|
66
|
+
}
|
|
67
|
+
export interface GcpIamInfo {
|
|
68
|
+
/** Roles the operator's own account holds on the project (directly, not through a group). */
|
|
69
|
+
yourRoles: string[];
|
|
70
|
+
/** Every binding, human members masked to `user:…@domain`. */
|
|
71
|
+
bindings: {
|
|
72
|
+
role: string;
|
|
73
|
+
members: string[];
|
|
74
|
+
}[];
|
|
75
|
+
}
|
|
76
|
+
export interface GcpApiCaller {
|
|
77
|
+
/** `oauth2:<project number>-…`, `serviceaccount:<unique id>`, `apikey:…`, or the raw kind. */
|
|
78
|
+
credential: string;
|
|
79
|
+
calls: number;
|
|
80
|
+
/** For an OAuth client: true when its project number is this project's number. */
|
|
81
|
+
ownedHere: boolean | null;
|
|
82
|
+
}
|
|
83
|
+
export interface GcpApiCallsInfo {
|
|
84
|
+
service: string;
|
|
85
|
+
hours: number;
|
|
86
|
+
callers: GcpApiCaller[];
|
|
87
|
+
}
|
|
88
|
+
export interface GcpInspectResult {
|
|
89
|
+
project: string;
|
|
90
|
+
account: string;
|
|
91
|
+
info: GcpSection<GcpProjectInfo>;
|
|
92
|
+
apis: GcpSection<GcpApisInfo>;
|
|
93
|
+
policies: GcpSection<GcpPolicyState[]>;
|
|
94
|
+
serviceAccounts: GcpSection<GcpServiceAccountInfo[]>;
|
|
95
|
+
iam: GcpSection<GcpIamInfo>;
|
|
96
|
+
/** Who called `service` in the window (Cloud Monitoring request_count by credential). */
|
|
97
|
+
apiCalls: GcpSection<GcpApiCallsInfo>;
|
|
98
|
+
}
|
|
99
|
+
export interface GcpInspectOptions {
|
|
100
|
+
project: string;
|
|
101
|
+
/** The gcloud account every call runs as, e.g. admin@installagent.com. */
|
|
102
|
+
account: string;
|
|
103
|
+
/** The API whose callers the report counts. Default gmail.googleapis.com. */
|
|
104
|
+
service?: string;
|
|
105
|
+
/** The window for the call count, 1–168 hours. Default 24. */
|
|
106
|
+
hours?: number;
|
|
107
|
+
execFileImpl?: ExecFileFn;
|
|
108
|
+
fetchImpl?: typeof fetch;
|
|
109
|
+
now?: () => Date;
|
|
110
|
+
}
|
|
111
|
+
export declare function validateGcpTarget(project: string, account: string): void;
|
|
112
|
+
/** Every gcloud call of `ia gcp` goes through here, so none can miss the two flags. */
|
|
113
|
+
export declare function gcloudArgs(args: readonly string[], project: string, account: string): string[];
|
|
114
|
+
/** `user:jane@acme.com` → `user:…@acme.com`. Service accounts and `account` itself stay whole. */
|
|
115
|
+
export declare function maskMember(member: string, account: string): string;
|
|
116
|
+
/** Hides everything an id could be misused with: only the OAuth project number survives. */
|
|
117
|
+
export declare function maskCredential(credentialId: string): string;
|
|
118
|
+
export declare function describePolicy(raw: unknown): string;
|
|
119
|
+
export declare function gcpInspect(options: GcpInspectOptions): Promise<GcpInspectResult>;
|
|
120
|
+
/** True for a failure that no project change can fix: no gcloud, or the login expired. */
|
|
121
|
+
export declare function isGcloudLoginFailure(error: unknown): boolean;
|
|
122
|
+
/**
|
|
123
|
+
* stderr only — stdout of print-access-token is the token itself. `account`
|
|
124
|
+
* fills in the login command; without it the command says `<account>`.
|
|
125
|
+
*/
|
|
126
|
+
export declare function describeInspectFailure(error: unknown, account?: string): string;
|