@installagent/sdk 0.5.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 +6 -1
- package/dist/index.js +6 -1
- 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/portal-admin.d.ts +24 -0
- package/dist/portal-admin.js +29 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +6 -0
- package/package.json +1 -1
|
@@ -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;
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
import { execFailureDetail, execFileAsync } from "./exec.js";
|
|
2
|
+
import { GCP_PROJECT_PATTERN } from "./gcp-service-account-key.js";
|
|
3
|
+
/**
|
|
4
|
+
* `ia gcp inspect` (2026-10-25): a READ-ONLY report on one Google Cloud
|
|
5
|
+
* project, so a technician sees what a setup step will meet before running
|
|
6
|
+
* it. Every gcloud call carries `--account=` and `--project=` — this machine
|
|
7
|
+
* often has a client account active (see AGENT.md), and an implicit default
|
|
8
|
+
* is how a command lands in the wrong project. Nothing here writes to GCP.
|
|
9
|
+
*
|
|
10
|
+
* Each section fails on its own: admin@ often lacks one permission on a
|
|
11
|
+
* client project (serviceusage on half our org), and the other sections are
|
|
12
|
+
* still worth having. Human members of the IAM policy are masked to their
|
|
13
|
+
* domain (client PII); service accounts and the operator's own account stay
|
|
14
|
+
* whole. The Monitoring access token goes straight into a request header and
|
|
15
|
+
* is never logged, returned or printed.
|
|
16
|
+
*/
|
|
17
|
+
/** The org policies a setup step trips over (DWD key, Gmail push grant). */
|
|
18
|
+
export const GCP_INSPECT_POLICIES = [
|
|
19
|
+
"iam.disableServiceAccountKeyCreation",
|
|
20
|
+
"iam.allowedPolicyMemberDomains",
|
|
21
|
+
];
|
|
22
|
+
/** APIs a client setup usually needs; the report flags each as on or off. */
|
|
23
|
+
export const GCP_INSPECT_KEY_APIS = [
|
|
24
|
+
"gmail.googleapis.com",
|
|
25
|
+
"pubsub.googleapis.com",
|
|
26
|
+
"iam.googleapis.com",
|
|
27
|
+
"monitoring.googleapis.com",
|
|
28
|
+
"generativelanguage.googleapis.com",
|
|
29
|
+
"drive.googleapis.com",
|
|
30
|
+
];
|
|
31
|
+
/** A user-managed key older than this is flagged for rotation. */
|
|
32
|
+
export const GCP_KEY_MAX_AGE_DAYS = 90;
|
|
33
|
+
const EMAIL = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
|
|
34
|
+
const SERVICE = /^[a-z0-9.-]+\.googleapis\.com$/;
|
|
35
|
+
export function validateGcpTarget(project, account) {
|
|
36
|
+
if (!GCP_PROJECT_PATTERN.test(project)) {
|
|
37
|
+
throw new Error(`invalid GCP project "${project}" — pass the project ID (lowercase letters, digits, hyphens), not its name or number`);
|
|
38
|
+
}
|
|
39
|
+
if (!EMAIL.test(account)) {
|
|
40
|
+
throw new Error(`invalid gcloud account "${account}" — pass the Google account the commands run as, e.g. admin@installagent.com`);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/** Every gcloud call of `ia gcp` goes through here, so none can miss the two flags. */
|
|
44
|
+
export function gcloudArgs(args, project, account) {
|
|
45
|
+
return [...args, `--account=${account}`, `--project=${project}`, "--quiet"];
|
|
46
|
+
}
|
|
47
|
+
/** `user:jane@acme.com` → `user:…@acme.com`. Service accounts and `account` itself stay whole. */
|
|
48
|
+
export function maskMember(member, account) {
|
|
49
|
+
const match = member.match(/^((?:deleted:)?(?:user|group)):([^@?]+)@([^?]+)(\?.*)?$/);
|
|
50
|
+
if (!match)
|
|
51
|
+
return member;
|
|
52
|
+
if (`${match[2]}@${match[3]}`.toLowerCase() === account.toLowerCase())
|
|
53
|
+
return member;
|
|
54
|
+
return `${match[1]}:…@${match[3]}`;
|
|
55
|
+
}
|
|
56
|
+
/** Hides everything an id could be misused with: only the OAuth project number survives. */
|
|
57
|
+
export function maskCredential(credentialId) {
|
|
58
|
+
const oauth = credentialId.match(/^oauth2:(\d+)-/);
|
|
59
|
+
if (oauth)
|
|
60
|
+
return `oauth2:${oauth[1]}-…`;
|
|
61
|
+
const sa = credentialId.match(/^serviceaccount:(\d+)$/);
|
|
62
|
+
if (sa)
|
|
63
|
+
return credentialId;
|
|
64
|
+
const kind = credentialId.split(":")[0];
|
|
65
|
+
return kind ? `${kind}:…` : "unknown";
|
|
66
|
+
}
|
|
67
|
+
export function describePolicy(raw) {
|
|
68
|
+
const policy = (raw ?? {});
|
|
69
|
+
if (policy.booleanPolicy)
|
|
70
|
+
return policy.booleanPolicy.enforced ? "enforced" : "not enforced";
|
|
71
|
+
const list = policy.listPolicy;
|
|
72
|
+
if (list) {
|
|
73
|
+
if (list.allValues === "ALLOW")
|
|
74
|
+
return "allow all";
|
|
75
|
+
if (list.allValues === "DENY")
|
|
76
|
+
return "deny all";
|
|
77
|
+
const allowed = list.allowedValues?.length ?? 0;
|
|
78
|
+
const denied = list.deniedValues?.length ?? 0;
|
|
79
|
+
if (allowed)
|
|
80
|
+
return `${allowed} allowed`;
|
|
81
|
+
if (denied)
|
|
82
|
+
return `${denied} denied`;
|
|
83
|
+
}
|
|
84
|
+
return "not set (Google default)";
|
|
85
|
+
}
|
|
86
|
+
export async function gcpInspect(options) {
|
|
87
|
+
const project = options.project.trim();
|
|
88
|
+
const account = options.account.trim();
|
|
89
|
+
validateGcpTarget(project, account);
|
|
90
|
+
const service = options.service?.trim() || "gmail.googleapis.com";
|
|
91
|
+
if (!SERVICE.test(service)) {
|
|
92
|
+
throw new Error(`invalid service "${service}" — expected e.g. gmail.googleapis.com`);
|
|
93
|
+
}
|
|
94
|
+
const hours = options.hours ?? 24;
|
|
95
|
+
if (!Number.isInteger(hours) || hours < 1 || hours > 168) {
|
|
96
|
+
throw new Error(`--hours must be a whole number from 1 to 168 (got ${hours})`);
|
|
97
|
+
}
|
|
98
|
+
const exec = options.execFileImpl ?? execFileAsync;
|
|
99
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
100
|
+
const now = options.now ?? (() => new Date());
|
|
101
|
+
const gcloud = async (args) => (await exec("gcloud", gcloudArgs(args, project, account))).stdout;
|
|
102
|
+
const gcloudJson = async (args) => JSON.parse((await gcloud([...args, "--format=json"])) || "null");
|
|
103
|
+
const [info, apis, policies, iamRaw] = await Promise.all([
|
|
104
|
+
section(account, async () => {
|
|
105
|
+
const raw = await gcloudJson(["projects", "describe", project]);
|
|
106
|
+
return {
|
|
107
|
+
projectId: raw.projectId,
|
|
108
|
+
projectNumber: String(raw.projectNumber),
|
|
109
|
+
name: raw.name ?? "",
|
|
110
|
+
parent: raw.parent?.type && raw.parent.id ? `${raw.parent.type}/${raw.parent.id}` : null,
|
|
111
|
+
lifecycleState: raw.lifecycleState ?? "",
|
|
112
|
+
};
|
|
113
|
+
}),
|
|
114
|
+
section(account, async () => {
|
|
115
|
+
const out = await gcloud(["services", "list", "--enabled", "--format=value(config.name)"]);
|
|
116
|
+
const enabled = out
|
|
117
|
+
.split("\n")
|
|
118
|
+
.map((line) => line.trim())
|
|
119
|
+
.filter(Boolean)
|
|
120
|
+
.sort();
|
|
121
|
+
return {
|
|
122
|
+
enabled,
|
|
123
|
+
key: GCP_INSPECT_KEY_APIS.map((s) => ({ service: s, enabled: enabled.includes(s) })),
|
|
124
|
+
};
|
|
125
|
+
}),
|
|
126
|
+
section(account, () => Promise.all(GCP_INSPECT_POLICIES.map(async (constraint) => {
|
|
127
|
+
// The legacy surface: it works without the orgpolicy API enabled on
|
|
128
|
+
// the quota project, which the newer `gcloud org-policies` needs.
|
|
129
|
+
const raw = await gcloudJson([
|
|
130
|
+
"resource-manager",
|
|
131
|
+
"org-policies",
|
|
132
|
+
"describe",
|
|
133
|
+
constraint,
|
|
134
|
+
"--effective",
|
|
135
|
+
]);
|
|
136
|
+
return { constraint, state: describePolicy(raw) };
|
|
137
|
+
}))),
|
|
138
|
+
section(account, () => gcloudJson([
|
|
139
|
+
"projects",
|
|
140
|
+
"get-iam-policy",
|
|
141
|
+
project,
|
|
142
|
+
])),
|
|
143
|
+
]);
|
|
144
|
+
const bindings = iamRaw.ok ? (iamRaw.data?.bindings ?? []) : [];
|
|
145
|
+
const iam = iamRaw.ok
|
|
146
|
+
? {
|
|
147
|
+
ok: true,
|
|
148
|
+
data: {
|
|
149
|
+
yourRoles: bindings
|
|
150
|
+
.filter((b) => (b.members ?? []).includes(`user:${account}`))
|
|
151
|
+
.map((b) => b.role)
|
|
152
|
+
.sort(),
|
|
153
|
+
bindings: bindings.map((b) => ({
|
|
154
|
+
role: b.role,
|
|
155
|
+
members: (b.members ?? []).map((m) => maskMember(m, account)),
|
|
156
|
+
})),
|
|
157
|
+
},
|
|
158
|
+
}
|
|
159
|
+
: iamRaw;
|
|
160
|
+
const serviceAccounts = await section(account, async () => {
|
|
161
|
+
const list = (await gcloudJson([
|
|
162
|
+
"iam",
|
|
163
|
+
"service-accounts",
|
|
164
|
+
"list",
|
|
165
|
+
])) ?? [];
|
|
166
|
+
return Promise.all(list.map(async (sa) => {
|
|
167
|
+
const member = `serviceAccount:${sa.email}`;
|
|
168
|
+
const keys = await section(account, async () => {
|
|
169
|
+
const raw = (await gcloudJson([
|
|
170
|
+
"iam",
|
|
171
|
+
"service-accounts",
|
|
172
|
+
"keys",
|
|
173
|
+
"list",
|
|
174
|
+
`--iam-account=${sa.email}`,
|
|
175
|
+
"--managed-by=user",
|
|
176
|
+
])) ?? [];
|
|
177
|
+
return raw.map((key) => {
|
|
178
|
+
const createdAt = key.validAfterTime ?? "";
|
|
179
|
+
const ageDays = createdAt
|
|
180
|
+
? Math.floor((now().getTime() - Date.parse(createdAt)) / 86_400_000)
|
|
181
|
+
: 0;
|
|
182
|
+
return {
|
|
183
|
+
id: key.name.split("/").pop() ?? key.name,
|
|
184
|
+
createdAt,
|
|
185
|
+
ageDays,
|
|
186
|
+
disabled: key.disabled === true,
|
|
187
|
+
old: ageDays > GCP_KEY_MAX_AGE_DAYS,
|
|
188
|
+
};
|
|
189
|
+
});
|
|
190
|
+
});
|
|
191
|
+
return {
|
|
192
|
+
email: sa.email,
|
|
193
|
+
disabled: sa.disabled === true,
|
|
194
|
+
roles: bindings
|
|
195
|
+
.filter((b) => (b.members ?? []).includes(member))
|
|
196
|
+
.map((b) => b.role)
|
|
197
|
+
.sort(),
|
|
198
|
+
keys,
|
|
199
|
+
};
|
|
200
|
+
}));
|
|
201
|
+
});
|
|
202
|
+
const projectNumber = info.ok ? info.data.projectNumber : null;
|
|
203
|
+
const apiCalls = await section(account, async () => {
|
|
204
|
+
const tokenOut = await gcloud(["auth", "print-access-token"]);
|
|
205
|
+
const token = tokenOut.trim();
|
|
206
|
+
if (!token)
|
|
207
|
+
throw new Error("gcloud returned no access token");
|
|
208
|
+
const end = now();
|
|
209
|
+
const start = new Date(end.getTime() - hours * 3_600_000);
|
|
210
|
+
const params = new URLSearchParams({
|
|
211
|
+
filter: `metric.type="serviceruntime.googleapis.com/api/request_count" AND resource.labels.service="${service}"`,
|
|
212
|
+
"interval.startTime": start.toISOString(),
|
|
213
|
+
"interval.endTime": end.toISOString(),
|
|
214
|
+
"aggregation.alignmentPeriod": `${hours * 3600}s`,
|
|
215
|
+
"aggregation.perSeriesAligner": "ALIGN_SUM",
|
|
216
|
+
"aggregation.crossSeriesReducer": "REDUCE_SUM",
|
|
217
|
+
"aggregation.groupByFields": "resource.labels.credential_id",
|
|
218
|
+
});
|
|
219
|
+
const response = await fetchImpl(`https://monitoring.googleapis.com/v3/projects/${project}/timeSeries?${params}`, { headers: { Authorization: `Bearer ${token}` } });
|
|
220
|
+
const body = (await response.json().catch(() => ({})));
|
|
221
|
+
if (!response.ok || body.error) {
|
|
222
|
+
throw new Error(`Cloud Monitoring ${response.status} ${body.error?.status ?? ""}`.trim() +
|
|
223
|
+
(response.status === 403 ? " — the account needs monitoring.timeSeries.list here" : ""));
|
|
224
|
+
}
|
|
225
|
+
const callers = (body.timeSeries ?? [])
|
|
226
|
+
.map((series) => {
|
|
227
|
+
const raw = series.resource?.labels?.credential_id ?? "";
|
|
228
|
+
const calls = (series.points ?? []).reduce((sum, p) => sum + Number(p.value?.int64Value ?? 0), 0);
|
|
229
|
+
const oauth = raw.match(/^oauth2:(\d+)-/);
|
|
230
|
+
return {
|
|
231
|
+
credential: maskCredential(raw),
|
|
232
|
+
calls,
|
|
233
|
+
ownedHere: oauth && projectNumber ? oauth[1] === projectNumber : null,
|
|
234
|
+
};
|
|
235
|
+
})
|
|
236
|
+
.sort((a, b) => b.calls - a.calls);
|
|
237
|
+
return { service, hours, callers };
|
|
238
|
+
});
|
|
239
|
+
return { project, account, info, apis, policies, serviceAccounts, iam, apiCalls };
|
|
240
|
+
}
|
|
241
|
+
async function section(account, run) {
|
|
242
|
+
try {
|
|
243
|
+
return { ok: true, data: await run() };
|
|
244
|
+
}
|
|
245
|
+
catch (error) {
|
|
246
|
+
return { ok: false, error: describeInspectFailure(error, account) };
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
/** True for a failure that no project change can fix: no gcloud, or the login expired. */
|
|
250
|
+
export function isGcloudLoginFailure(error) {
|
|
251
|
+
const { code, detail } = execFailureDetail(error);
|
|
252
|
+
return code === "ENOENT" || LOGIN_EXPIRED.test(detail);
|
|
253
|
+
}
|
|
254
|
+
const LOGIN_EXPIRED = /reauthentication|cannot prompt|do not currently have an active account/i;
|
|
255
|
+
/**
|
|
256
|
+
* stderr only — stdout of print-access-token is the token itself. `account`
|
|
257
|
+
* fills in the login command; without it the command says `<account>`.
|
|
258
|
+
*/
|
|
259
|
+
export function describeInspectFailure(error, account) {
|
|
260
|
+
const { code, detail } = execFailureDetail(error);
|
|
261
|
+
const login = `gcloud auth login ${account?.trim() || "<account>"}`;
|
|
262
|
+
if (code === "ENOENT") {
|
|
263
|
+
return `gcloud CLI not found — install the Google Cloud SDK, then \`${login}\``;
|
|
264
|
+
}
|
|
265
|
+
if (LOGIN_EXPIRED.test(detail)) {
|
|
266
|
+
return `gcloud login expired — run \`${login}\` in your own terminal, then retry`;
|
|
267
|
+
}
|
|
268
|
+
const reason = httpErrorSummary(detail) ?? firstLine(detail);
|
|
269
|
+
if (/PERMISSION_DENIED|403|does not have .*permission/i.test(detail)) {
|
|
270
|
+
return `no permission — ${reason}`;
|
|
271
|
+
}
|
|
272
|
+
return reason;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* gcloud's "HttpError accessing <url>: response: <headers>, content <json>"
|
|
276
|
+
* puts the reason after the headers, past where firstLine cuts it.
|
|
277
|
+
*/
|
|
278
|
+
function httpErrorSummary(detail) {
|
|
279
|
+
if (!/HttpError accessing/.test(detail))
|
|
280
|
+
return null;
|
|
281
|
+
const code = detail.match(/"code":\s*(\d{3})/)?.[1];
|
|
282
|
+
const status = detail.match(/"status":\s*"([A-Z_]+)"/)?.[1];
|
|
283
|
+
const message = detail.match(/"message":\s*"((?:[^"\\]|\\.)*)"/)?.[1];
|
|
284
|
+
if (!code && !message)
|
|
285
|
+
return null;
|
|
286
|
+
const head = `HTTP ${code ?? "error"}${status ? ` ${status}` : ""}`;
|
|
287
|
+
return (message ? `${head}: ${message}` : head).slice(0, 300);
|
|
288
|
+
}
|
|
289
|
+
function firstLine(text) {
|
|
290
|
+
const line = text.split("\n").find((l) => l.trim()) ?? text;
|
|
291
|
+
return line.trim().slice(0, 300);
|
|
292
|
+
}
|
|
@@ -7,6 +7,8 @@ export interface MintGcpServiceAccountKeyOptions {
|
|
|
7
7
|
project: string;
|
|
8
8
|
/** Existing service-account email, e.g. `<name>@<project>.iam.gserviceaccount.com`. */
|
|
9
9
|
serviceAccountEmail: string;
|
|
10
|
+
/** The gcloud account to run as (`--account`). Default: gcloud's active account. */
|
|
11
|
+
account?: string;
|
|
10
12
|
/** Injectable for tests; defaults to real `execFile("gcloud", ...)`. */
|
|
11
13
|
execFileImpl?: ExecFileFn;
|
|
12
14
|
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
/**
|
|
3
|
+
* `ia gcp setup` (2026-10-25): bring one Google Cloud project to the state a
|
|
4
|
+
* client build needs — the project itself, billing, the APIs, Service Usage
|
|
5
|
+
* Admin for a team account, and one service account with NO roles.
|
|
6
|
+
*
|
|
7
|
+
* Plan by default: it only reads, then lists each step as `done` (nothing
|
|
8
|
+
* to do), `todo` (with the exact gcloud command), `blocked` (with the
|
|
9
|
+
* reason) or `unknown` (a read failed; not a blocker). `apply: true` runs the
|
|
10
|
+
* todo steps in order and stops at the first failure. Every step is
|
|
11
|
+
* check-then-skip, so a re-run after a failure continues where it stopped.
|
|
12
|
+
* It never deletes, never grants a role to the service account, never
|
|
13
|
+
* grants anything to an address outside installagent.com, and never mints a
|
|
14
|
+
* key (that is `ia secrets mint gcp-service-account-key --to-op`).
|
|
15
|
+
*/
|
|
16
|
+
export declare const GCP_TEAM_DOMAIN = "installagent.com";
|
|
17
|
+
export declare const SERVICE_USAGE_ADMIN = "roles/serviceusage.serviceUsageAdmin";
|
|
18
|
+
export type GcpStepStatus = "done" | "todo" | "blocked" | "unknown" | "ran" | "failed" | "skipped";
|
|
19
|
+
export interface GcpStep {
|
|
20
|
+
id: "project" | "billing" | "apis" | "service-usage-admin" | "service-account";
|
|
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 GcpSetupOptions {
|
|
28
|
+
project: string;
|
|
29
|
+
account: string;
|
|
30
|
+
/** Create the project when it does not exist. Needs `organization` or `folder`. */
|
|
31
|
+
create?: boolean;
|
|
32
|
+
organization?: string;
|
|
33
|
+
folder?: string;
|
|
34
|
+
/** Display name for a new project. Default: the project ID. */
|
|
35
|
+
name?: string;
|
|
36
|
+
/** Billing account to link when billing is off, e.g. 0X0X0X-0X0X0X-0X0X0X. */
|
|
37
|
+
billing?: string;
|
|
38
|
+
/** APIs to enable. Default: gmail.googleapis.com. */
|
|
39
|
+
apis?: string[];
|
|
40
|
+
/** A team account (…@installagent.com) to give Service Usage Admin. */
|
|
41
|
+
grantServiceUsage?: string;
|
|
42
|
+
/** Service-account name (the part before @). Created with no roles. */
|
|
43
|
+
serviceAccount?: string;
|
|
44
|
+
apply?: boolean;
|
|
45
|
+
execFileImpl?: ExecFileFn;
|
|
46
|
+
}
|
|
47
|
+
export interface GcpSetupResult {
|
|
48
|
+
project: string;
|
|
49
|
+
account: string;
|
|
50
|
+
applied: boolean;
|
|
51
|
+
/** False when a step is blocked (plan) or failed (apply). */
|
|
52
|
+
ok: boolean;
|
|
53
|
+
steps: GcpStep[];
|
|
54
|
+
nextSteps: string[];
|
|
55
|
+
}
|
|
56
|
+
/** One gcloud command as text a technician can paste, with the forced flags. */
|
|
57
|
+
export declare function formatGcloud(args: readonly string[]): string;
|
|
58
|
+
export declare function gcpSetup(options: GcpSetupOptions): Promise<GcpSetupResult>;
|