@mtndev/cli 1.1.0 → 2.0.1

package/esm/commands/aws/iam/setup-acl/utils.js

@@ -0,0 +1,298 @@
+import { runAws } from "../../utils/exec-aws.js";
+import { resolvePolicyPath } from "../../utils/resolve-policy-path.js";
+//#region src/commands/aws/iam/setup-acl/utils.js
+/**
+* The five ACL groups managed by setup-acl.
+*/
+const ACL_GROUPS = [
+	"acl-admin-do-not-use",
+	"acl-iam-full-access",
+	"acl-power-users",
+	"acl-read-only",
+	"acl-s3-restrictions"
+];
+/**
+* Custom managed policies published from bundled JSON documents.
+* @type {Array<{ name: string; fileName: string }>}
+*/
+const CUSTOM_POLICIES = [
+	{
+		name: "UserAdminsWriteList",
+		fileName: "user-admins-write-list.json"
+	},
+	{
+		name: "UserAdminsDenyList",
+		fileName: "user-admins-deny-list.json"
+	},
+	{
+		name: "UserAdminsSelfServiceIAM",
+		fileName: "user-admins-self-service-iam.json"
+	},
+	{
+		name: "UserAdminsDenyRegionsList",
+		fileName: "user-admins-deny-regions-list.json"
+	},
+	{
+		name: "sts-federation",
+		fileName: "sts-federation.json"
+	},
+	{
+		name: "S3RestrictionsDenyNonS3Services",
+		fileName: "s3-restrictions-deny-non-s3-services.json"
+	}
+];
+/**
+* Create an IAM group if it does not already exist.
+* @param {{ name: string; profile?: string; verbose?: boolean }} params
+*/
+function ensureGroup(params) {
+	const { name, profile, verbose } = params;
+	let exists = true;
+	try {
+		runAws({
+			profile,
+			args: [
+				"iam",
+				"get-group",
+				"--group-name",
+				name
+			],
+			verbose
+		});
+	} catch {
+		exists = false;
+	}
+	if (exists) {
+		console.log(`  Group exists: ${name}`);
+		return;
+	}
+	console.log(`  Create group: ${name}`);
+	runAws({
+		profile,
+		args: [
+			"iam",
+			"create-group",
+			"--group-name",
+			name,
+			"--path",
+			"/"
+		],
+		expectJson: false,
+		verbose
+	});
+}
+/**
+* Create or update a customer-managed policy from a bundled JSON document.
+* Handles the IAM five-version limit by pruning the oldest non-default version.
+* @param {{ name: string; fileName: string; accountId: string; profile?: string; verbose?: boolean }} params
+*/
+function publishPolicy(params) {
+	const { name, fileName, accountId, profile, verbose } = params;
+	const arn = `arn:aws:iam::${accountId}:policy/${name}`;
+	const file = resolvePolicyPath(fileName);
+	let exists = true;
+	try {
+		runAws({
+			profile,
+			args: [
+				"iam",
+				"get-policy",
+				"--policy-arn",
+				arn
+			],
+			verbose
+		});
+	} catch {
+		exists = false;
+	}
+	if (!exists) {
+		console.log(`  Create policy: ${name}`);
+		runAws({
+			profile,
+			args: [
+				"iam",
+				"create-policy",
+				"--policy-name",
+				name,
+				"--policy-document",
+				`file://${file}`,
+				"--description",
+				`ACL: ${name}`
+			],
+			expectJson: false,
+			verbose
+		});
+		return;
+	}
+	if ((Number.parseInt(runAws({
+		profile,
+		args: [
+			"iam",
+			"list-policy-versions",
+			"--policy-arn",
+			arn,
+			"--query",
+			"length(Versions[?IsDefaultVersion==`false`])",
+			"--output",
+			"text"
+		],
+		expectJson: false,
+		verbose
+	}), 10) || 0) >= 4) {
+		const oldest = runAws({
+			profile,
+			args: [
+				"iam",
+				"list-policy-versions",
+				"--policy-arn",
+				arn,
+				"--query",
+				"Versions[?IsDefaultVersion==`false`] | sort_by(@, &CreateDate)[0].VersionId",
+				"--output",
+				"text"
+			],
+			expectJson: false,
+			verbose
+		});
+		console.log(`  Prune oldest version of ${name}: ${oldest}`);
+		runAws({
+			profile,
+			args: [
+				"iam",
+				"delete-policy-version",
+				"--policy-arn",
+				arn,
+				"--version-id",
+				oldest
+			],
+			expectJson: false,
+			verbose
+		});
+	}
+	console.log(`  Update policy: ${name}`);
+	runAws({
+		profile,
+		args: [
+			"iam",
+			"create-policy-version",
+			"--policy-arn",
+			arn,
+			"--policy-document",
+			`file://${file}`,
+			"--set-as-default"
+		],
+		expectJson: false,
+		verbose
+	});
+}
+/**
+* @param {{ group: string; arn: string; profile?: string; verbose?: boolean }} params
+* @returns {boolean}
+*/
+function isPolicyAttached(params) {
+	const { group, arn, profile, verbose } = params;
+	const out = runAws({
+		profile,
+		args: [
+			"iam",
+			"list-attached-group-policies",
+			"--group-name",
+			group,
+			"--query",
+			`AttachedPolicies[?PolicyArn=='${arn}'].PolicyArn`,
+			"--output",
+			"text"
+		],
+		expectJson: false,
+		verbose
+	});
+	return Boolean(out);
+}
+/**
+* Attach a policy to a group if not already attached.
+* @param {{ group: string; arn: string; profile?: string; verbose?: boolean }} params
+*/
+function attach(params) {
+	const { group, arn, profile, verbose } = params;
+	const policyName = arn.split("/").pop() ?? arn;
+	if (isPolicyAttached({
+		group,
+		arn,
+		profile,
+		verbose
+	})) {
+		console.log(`  [${group}] already attached: ${policyName}`);
+		return;
+	}
+	console.log(`  [${group}] attach: ${policyName}`);
+	runAws({
+		profile,
+		args: [
+			"iam",
+			"attach-group-policy",
+			"--group-name",
+			group,
+			"--policy-arn",
+			arn
+		],
+		expectJson: false,
+		verbose
+	});
+}
+/**
+* Detach a (legacy) policy from a group if it is currently attached.
+* @param {{ group: string; arn: string; profile?: string; verbose?: boolean }} params
+*/
+function detach(params) {
+	const { group, arn, profile, verbose } = params;
+	const policyName = arn.split("/").pop() ?? arn;
+	if (!isPolicyAttached({
+		group,
+		arn,
+		profile,
+		verbose
+	})) return;
+	console.log(`  [${group}] detach legacy: ${policyName}`);
+	runAws({
+		profile,
+		args: [
+			"iam",
+			"detach-group-policy",
+			"--group-name",
+			group,
+			"--policy-arn",
+			arn
+		],
+		expectJson: false,
+		verbose
+	});
+}
+/**
+* Print the attached policies for each ACL group.
+* @param {{ profile?: string; verbose?: boolean }} params
+*/
+function printFinalState(params) {
+	const { profile, verbose } = params;
+	for (const group of ACL_GROUPS) {
+		console.log("");
+		console.log(`=== ${group} ===`);
+		const table = runAws({
+			profile,
+			args: [
+				"iam",
+				"list-attached-group-policies",
+				"--group-name",
+				group,
+				"--query",
+				"AttachedPolicies[].PolicyName",
+				"--output",
+				"table"
+			],
+			expectJson: false,
+			verbose
+		});
+		console.log(table);
+	}
+}
+//#endregion
+export { ACL_GROUPS, CUSTOM_POLICIES, attach, detach, ensureGroup, printFinalState, publishPolicy };

package/esm/commands/aws/iam/users/handler.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `aws iam users` handler: interactively create IAM users and assign ACL groups.
+ * @param {unknown} options
+ */
+export function usersCommand(options: unknown): Promise<void>;

package/esm/commands/aws/iam/users/handler.js

@@ -0,0 +1,56 @@
+import { getCallerIdentity, requireCommands } from "../../utils/exec-aws.js";
+import { resolveProfile } from "../../utils/resolve-profile.js";
+import { usersOptionsSchema } from "./schema.js";
+import { createUsersInteractive } from "./utils.js";
+import chalk from "chalk";
+import { ZodError } from "zod";
+//#region src/commands/aws/iam/users/handler.js
+/**
+* `aws iam users` handler: interactively create IAM users and assign ACL groups.
+* @param {unknown} options
+*/
+async function usersCommand(options) {
+	try {
+		const { accountName, profile: profileOption, verbose } = usersOptionsSchema.parse(options);
+		requireCommands(["aws"]);
+		const profile = await resolveProfile({ profile: profileOption });
+		console.log(chalk.blue("\nAWS IAM user management"));
+		console.log("");
+		console.log("Caller:");
+		const identity = getCallerIdentity({
+			profile,
+			verbose
+		});
+		console.log(`  Account: ${identity.Account}`);
+		console.log(`  Arn:     ${identity.Arn}`);
+		console.log("");
+		await createUsersInteractive({
+			accountName,
+			profile,
+			identity,
+			verbose
+		});
+		console.log("Done.");
+	} catch (error) {
+		if (error instanceof ZodError) {
+			console.error(chalk.red("\n❌ Invalid command options:"));
+			error.errors.forEach((err) => {
+				console.error(chalk.red(`   ${err.path.join(".")}: ${err.message}`));
+			});
+			process.exit(1);
+		}
+		const verbose = options?.verbose || false;
+		console.error(chalk.red("\n❌ iam users failed:"));
+		if (error instanceof Error) {
+			console.error(chalk.red(`   ${error.message}`));
+			if (verbose && error.stack) {
+				console.error(chalk.gray("\nStack trace:"));
+				console.error(chalk.gray(error.stack));
+			}
+		} else console.error(chalk.red(`   ${String(error)}`));
+		console.error(chalk.yellow("\n💡 Requires the AWS CLI and a profile with IAM write access.\n"));
+		process.exit(1);
+	}
+}
+//#endregion
+export { usersCommand };

package/esm/commands/aws/iam/users/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./handler.js";
+export * from "./schema.js";
+export * from "./utils.js";

package/esm/commands/aws/iam/users/index.js

@@ -0,0 +1,4 @@
+import { usersOptionsSchema } from "./schema.js";
+import { buildUsername, createCliAccessKey, createUsersInteractive, ensureAclGroupsExist, ensureUser, ensureUserInGroup, inferAccountName, isValidSlug, normalizeIdentifier, normalizeSlug, parseMdUsername, roleToGroup } from "./utils.js";
+import { usersCommand } from "./handler.js";
+export { buildUsername, createCliAccessKey, createUsersInteractive, ensureAclGroupsExist, ensureUser, ensureUserInGroup, inferAccountName, isValidSlug, normalizeIdentifier, normalizeSlug, parseMdUsername, roleToGroup, usersCommand, usersOptionsSchema };

package/esm/commands/aws/iam/users/schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Zod schema for `aws iam users` options.
+ */
+export const usersOptionsSchema: z.ZodObject<{
+    accountName: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodString>;
+    verbose: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    verbose: boolean;
+    profile?: string | undefined;
+    accountName?: string | undefined;
+}, {
+    profile?: string | undefined;
+    verbose?: boolean | undefined;
+    accountName?: string | undefined;
+}>;
+export type UsersOptions = z.infer<typeof usersOptionsSchema>;
+import { z } from "zod";

package/esm/commands/aws/iam/users/schema.js

@@ -0,0 +1,16 @@
+import { profileField, verboseField } from "../../schema.js";
+import { z } from "zod";
+//#region src/commands/aws/iam/users/schema.js
+/**
+* Zod schema for `aws iam users` options.
+*/
+const usersOptionsSchema = z.object({
+	accountName: z.string().optional().describe("AWS account slug used in md-{identifier}-{account}-{role}"),
+	profile: profileField,
+	verbose: verboseField
+});
+/**
+* @typedef {z.infer<typeof usersOptionsSchema>} UsersOptions
+*/
+//#endregion
+export { usersOptionsSchema };

package/esm/commands/aws/iam/users/utils.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Map a user role to its ACL group.
+ * @param {string} role
+ * @returns {string}
+ */
+export function roleToGroup(role: string): string;
+/**
+ * Lowercase and hyphenate a raw value into a slug.
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeSlug(value: string): string;
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isValidSlug(value: string): boolean;
+/**
+ * Build the canonical IAM username.
+ * @param {{ identifier: string; accountName: string; role: string }} params
+ * @returns {string}
+ */
+export function buildUsername(params: {
+    identifier: string;
+    accountName: string;
+    role: string;
+}): string;
+/**
+ * Strip md- prefix, role suffix, and account suffix from a raw identifier.
+ * @param {{ raw: string; accountName: string; role: string }} params
+ * @returns {string}
+ */
+export function normalizeIdentifier(params: {
+    raw: string;
+    accountName: string;
+    role: string;
+}): string;
+/**
+ * Parse an md-{identifier}-{account}-{role} username into parts.
+ * Identifier is the first segment; account is everything between it and the role
+ * (so multi-segment account slugs still work).
+ * @param {string} name - Profile name or IAM user name
+ * @returns {{ identifier: string; accountName: string; role: string } | null}
+ */
+export function parseMdUsername(name: string): {
+    identifier: string;
+    accountName: string;
+    role: string;
+} | null;
+/**
+ * Infer the AWS account slug from the caller IAM user / profile name.
+ * Prefers the ARN username, then the profile string.
+ * @param {{
+ *   profile?: string;
+ *   identity?: { Arn?: string };
+ * }} params
+ * @returns {string | null}
+ */
+export function inferAccountName(params: {
+    profile?: string;
+    identity?: {
+        Arn?: string;
+    };
+}): string | null;
+/**
+ * Create the IAM user if it does not exist.
+ * @param {{ username: string; profile?: string; verbose?: boolean }} params
+ */
+export function ensureUser(params: {
+    username: string;
+    profile?: string;
+    verbose?: boolean;
+}): void;
+/**
+ * Add the user to the group if not already a member.
+ * @param {{ username: string; group: string; profile?: string; verbose?: boolean }} params
+ */
+export function ensureUserInGroup(params: {
+    username: string;
+    group: string;
+    profile?: string;
+    verbose?: boolean;
+}): void;
+/**
+ * Create a CLI access key for the user and print a one-line setup command.
+ * @param {{ username: string; profile?: string; verbose?: boolean }} params
+ * @returns {boolean} False when the user already has the maximum number of keys
+ */
+export function createCliAccessKey(params: {
+    username: string;
+    profile?: string;
+    verbose?: boolean;
+}): boolean;
+/**
+ * Verify the required ACL groups exist before creating users.
+ * @param {{ profile?: string; verbose?: boolean }} params
+ * @returns {boolean}
+ */
+export function ensureAclGroupsExist(params: {
+    profile?: string;
+    verbose?: boolean;
+}): boolean;
+/**
+ * Interactively create IAM users, assign ACL groups, and print CLI credentials.
+ * @param {{
+ *   accountName?: string;
+ *   profile?: string;
+ *   identity?: { Arn?: string };
+ *   verbose?: boolean;
+ * }} params
+ */
+export function createUsersInteractive(params: {
+    accountName?: string;
+    profile?: string;
+    identity?: {
+        Arn?: string;
+    };
+    verbose?: boolean;
+}): Promise<void>;