feat(aws): add IAM to Cloud Explorer

README.md

@@ -61,6 +61,7 @@ cd packages/api && bun run scripts/service-matrix.ts
 | Networking | Networking | Yes (list) | No | No |
 | Integration | API Gateway | Yes (list, create, delete, inspect) | No | No |
 | Provisioning | CloudFormation / Infrastructure as Code | Yes (list, create, delete, inspect) | No | No |
+| Security | Identity | Yes (list, create, delete, inspect) | No | No |
 | Security | Secrets Manager / Key Vault | Yes (legacy page) | Yes (list, create, delete, inspect) | No |
 
 Console Home is available for all three clouds.
@@ -183,6 +184,22 @@ Current gaps:
 
 </details>
 
+<details>
+<summary><strong>Identity</strong></summary>
+
+AWS only, through the generic identity service category.
+
+- List and inspect IAM users.
+- Create and delete IAM users.
+- IAM user paths are supported during creation.
+
+Current gaps:
+
+- Roles, groups, policies, access keys, and other advanced IAM workflows are not exposed yet.
+- No Azure or GCP identity adapter yet.
+
+</details>
+
 <details>
 <summary><strong>API Gateway</strong></summary>
 

packages/api/package.json

@@ -15,6 +15,7 @@
     "@aws-sdk/client-ec2": "^3.1076.0",
     "@aws-sdk/client-dynamodb": "^3.1088.0",
     "@aws-sdk/client-eks": "^3.1076.0",
+    "@aws-sdk/client-iam": "^3.1076.0",
     "@aws-sdk/client-lambda": "^3.1076.0",
     "@aws-sdk/client-rds": "^3.1076.0",
     "@aws-sdk/client-s3": "^3.1076.0",

packages/api/src/adapter-aws/AwsIamAdapter.test.ts

@@ -0,0 +1,160 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    CreateUserCommand,
+    DeleteUserCommand,
+    GetUserCommand,
+    ListUsersCommand,
+    type IAMClient,
+} from '@aws-sdk/client-iam'
+import {AwsIamAdapter} from './AwsIamAdapter'
+
+function fakeClient(handler: (command: unknown) => unknown): IAMClient {
+    return {
+        send: async (command: unknown) => handler(command),
+    } as unknown as IAMClient
+}
+
+const alice = {
+    UserName: 'alice',
+    UserId: 'AIDAALICE',
+    Arn: 'arn:aws:iam::000000000000:user/team/alice',
+    Path: '/team/',
+    CreateDate: new Date('2026-01-02T03:04:05.000Z'),
+}
+
+describe('AwsIamAdapter', () => {
+    test('lists every page and maps IAM users to normalized resources', async () => {
+        const adapter = new AwsIamAdapter(fakeClient((command) => {
+            if (!(command instanceof ListUsersCommand)) throw new Error('Unexpected command')
+            if (!command.input.Marker) return {Users: [alice], IsTruncated: true, Marker: 'next'}
+            return {Users: [{...alice, UserName: 'bob', UserId: 'AIDABOB'}], IsTruncated: false}
+        }))
+
+        const result = await adapter.list()
+
+        expect(result).toHaveLength(2)
+        expect(result[0]).toMatchObject({
+            id: 'alice',
+            name: 'alice',
+            cloud: 'aws',
+            service: 'identity',
+            type: 'iam-user',
+            region: null,
+            createdAt: '2026-01-02T03:04:05.000Z',
+        })
+        expect(result[0].metadata).toMatchObject({
+            identityService: 'iam',
+            userId: 'AIDAALICE',
+            path: '/team/',
+        })
+    })
+
+    test('filters users by search term', async () => {
+        const adapter = new AwsIamAdapter(fakeClient(() => ({
+            Users: [alice, {...alice, UserName: 'bob'}],
+            IsTruncated: false,
+        })))
+
+        const result = await adapter.list({search: 'ALI'})
+
+        expect(result.map((resource) => resource.name)).toEqual(['alice'])
+    })
+
+    test('gets and maps one IAM user', async () => {
+        const adapter = new AwsIamAdapter(fakeClient((command) => {
+            expect(command).toBeInstanceOf(GetUserCommand)
+            return {User: alice}
+        }))
+
+        const result = await adapter.get('alice')
+
+        expect(result?.id).toBe('alice')
+        expect(result?.metadata.arn).toBe(alice.Arn)
+    })
+
+    test('returns null when IAM reports a missing user', async () => {
+        const adapter = new AwsIamAdapter(fakeClient(() => {
+            throw Object.assign(new Error('missing'), {name: 'NoSuchEntityException'})
+        }))
+
+        await expect(adapter.get('missing')).resolves.toBeNull()
+    })
+
+    test('creates an IAM user with an optional path', async () => {
+        const adapter = new AwsIamAdapter(fakeClient((command) => {
+            expect(command).toBeInstanceOf(CreateUserCommand)
+            expect((command as CreateUserCommand).input).toEqual({UserName: 'alice', Path: '/team/'})
+            return {User: alice}
+        }))
+
+        const result = await adapter.create({values: {userName: 'alice', path: '/team/'}})
+
+        expect(result.id).toBe('alice')
+    })
+
+    test('reports an empty create response as a runtime error', async () => {
+        const adapter = new AwsIamAdapter(fakeClient(() => ({})))
+
+        await expect(adapter.create({values: {userName: 'alice'}})).rejects.toMatchObject({
+            name: 'RuntimeError',
+            message: 'AWS IAM did not return the created user',
+        })
+    })
+
+    test('rejects invalid user names before calling IAM', async () => {
+        let called = false
+        const adapter = new AwsIamAdapter(fakeClient(() => {
+            called = true
+            return {}
+        }))
+
+        await expect(adapter.create({values: {userName: 'not valid'}})).rejects.toThrow('Use a valid IAM user name')
+        await expect(adapter.create({values: {userName: 'alice', path: 'team'}})).rejects.toThrow('Use a valid IAM path')
+        expect(called).toBeFalse()
+    })
+
+    test('deletes the requested IAM user', async () => {
+        const adapter = new AwsIamAdapter(fakeClient((command) => {
+            expect(command).toBeInstanceOf(DeleteUserCommand)
+            expect((command as DeleteUserCommand).input.UserName).toBe('alice')
+            return {}
+        }))
+
+        await adapter.delete('alice')
+    })
+
+    test('reports a delete of a missing IAM user as not found', async () => {
+        const adapter = new AwsIamAdapter(fakeClient(() => {
+            throw Object.assign(new Error('The user with name alice cannot be found.'), {name: 'NoSuchEntityException'})
+        }))
+
+        await expect(adapter.delete('alice')).rejects.toMatchObject({
+            name: 'NotFoundError',
+            message: 'IAM user alice not found',
+        })
+    })
+
+    test('reports a delete blocked by attached resources as a conflict', async () => {
+        const adapter = new AwsIamAdapter(fakeClient(() => {
+            throw Object.assign(new Error('Cannot delete entity, must delete access keys first.'), {
+                name: 'DeleteConflictException',
+            })
+        }))
+
+        await expect(adapter.delete('alice')).rejects.toMatchObject({
+            name: 'ConflictError',
+            message: expect.stringContaining('IAM user alice still has attached resources'),
+        })
+    })
+
+    test('returns the AWS IAM schema', () => {
+        const adapter = new AwsIamAdapter(fakeClient(() => ({})))
+
+        expect(adapter.schema()).toMatchObject({
+            cloud: 'aws',
+            service: 'identity',
+            displayName: 'AWS IAM users',
+            actions: ['list', 'create', 'delete', 'inspect'],
+        })
+    })
+})

packages/api/src/adapter-aws/AwsIamAdapter.ts

@@ -0,0 +1,133 @@
+import {
+    CreateUserCommand,
+    DeleteUserCommand,
+    GetUserCommand,
+    ListUsersCommand,
+    type IAMClient,
+    type User,
+} from '@aws-sdk/client-iam'
+import {iam as defaultIam} from '../aws'
+import {
+    awsIamSchema,
+    IAM_PATH_MAX_LENGTH,
+    IAM_PATH_MESSAGE,
+    IAM_PATH_PATTERN,
+    IAM_USER_NAME_MESSAGE,
+    IAM_USER_NAME_PATTERN,
+} from '../cloud-spi/iamSchema'
+import {ConflictError, NotFoundError, RuntimeError, ValidationError} from '../cloud-spi/errors'
+import type {CloudResource, CloudServiceAdapter, CreateResourceInput, ResourceQuery, ServiceSchema} from '../cloud-spi/types'
+
+const MAX_LIST_PAGES = 50
+
+export class AwsIamAdapter implements CloudServiceAdapter {
+    readonly cloud = 'aws' as const
+    readonly service = 'identity' as const
+
+    constructor(private readonly iam: IAMClient = defaultIam) {}
+
+    schema(): ServiceSchema {
+        return awsIamSchema()
+    }
+
+    async list(query: ResourceQuery = {}): Promise<CloudResource[]> {
+        const users: User[] = []
+        let marker: string | undefined
+        let pages = 0
+
+        do {
+            const res = await this.iam.send(new ListUsersCommand({Marker: marker}))
+            users.push(...(res.Users ?? []))
+            marker = res.IsTruncated ? res.Marker : undefined
+            pages += 1
+        } while (marker && pages < MAX_LIST_PAGES)
+
+        return filterBySearch(users.map(toResource), query.search)
+    }
+
+    async get(id: string): Promise<CloudResource | null> {
+        try {
+            const res = await this.iam.send(new GetUserCommand({UserName: id}))
+            return res.User ? toResource(res.User) : null
+        } catch (error) {
+            if (isNotFound(error)) return null
+            throw error
+        }
+    }
+
+    async create(input: CreateResourceInput): Promise<CloudResource> {
+        const userName = stringValue(input.values.userName)
+        const path = stringValue(input.values.path)
+        if (!userName) throw new ValidationError('userName is required')
+        if (!new RegExp(IAM_USER_NAME_PATTERN).test(userName)) throw new ValidationError(IAM_USER_NAME_MESSAGE)
+        if (path && (path.length > IAM_PATH_MAX_LENGTH || !new RegExp(IAM_PATH_PATTERN).test(path))) {
+            throw new ValidationError(IAM_PATH_MESSAGE)
+        }
+
+        const res = await this.iam.send(new CreateUserCommand({
+            UserName: userName,
+            Path: path || undefined,
+        }))
+        if (!res.User) throw new RuntimeError('AWS IAM did not return the created user')
+        return toResource(res.User)
+    }
+
+    async delete(id: string): Promise<void> {
+        try {
+            await this.iam.send(new DeleteUserCommand({UserName: id}))
+        } catch (error) {
+            if (isNotFound(error)) throw new NotFoundError(`IAM user ${id} not found`, {cause: error})
+            if (isDeleteConflict(error)) {
+                throw new ConflictError(
+                    `IAM user ${id} still has attached resources. Remove group memberships, access keys, `
+                    + 'certificates, MFA devices, and policies before deleting the user.',
+                    {cause: error},
+                )
+            }
+            throw error
+        }
+    }
+}
+
+function toResource(user: User): CloudResource {
+    const userName = user.UserName ?? ''
+    return {
+        id: userName,
+        name: userName,
+        cloud: 'aws',
+        service: 'identity',
+        type: 'iam-user',
+        region: null,
+        createdAt: user.CreateDate?.toISOString() ?? null,
+        metadata: {
+            provider: 'aws',
+            identityService: 'iam',
+            userId: user.UserId,
+            arn: user.Arn,
+            path: user.Path,
+            permissionsBoundary: user.PermissionsBoundary,
+            tags: user.Tags,
+        },
+    }
+}
+
+function stringValue(value: unknown): string {
+    return typeof value === 'string' ? value.trim() : ''
+}
+
+function filterBySearch(resources: CloudResource[], search?: string): CloudResource[] {
+    const normalized = search?.trim().toLowerCase()
+    if (!normalized) return resources
+    return resources.filter((resource) => resource.name.toLowerCase().includes(normalized))
+}
+
+function isNotFound(error: unknown): boolean {
+    if (typeof error !== 'object' || error === null) return false
+    const candidate = error as {name?: string; $metadata?: {httpStatusCode?: number}}
+    return candidate.name === 'NoSuchEntityException' || candidate.$metadata?.httpStatusCode === 404
+}
+
+function isDeleteConflict(error: unknown): boolean {
+    if (typeof error !== 'object' || error === null) return false
+    return (error as {name?: string}).name === 'DeleteConflictException'
+}

packages/api/src/adapter-aws/awsErrors.ts

@@ -56,6 +56,7 @@ const CONFLICT_NAMES = new Set([
     'DBInstanceAlreadyExistsFault',
     'ConcurrentModificationException',
     'IncorrectState',
+    'DeleteConflictException',
 ])
 
 const ACCESS_DENIED_NAMES = new Set([
@@ -94,6 +95,7 @@ const NOT_FOUND_NAMES = new Set([
     'NoSuchBucket',
     'NoSuchKey',
     'NoSuchEntity',
+    'NoSuchEntityException',
     'NotFound',
     'NotFoundException',
     'ResourceNotFoundException',

packages/api/src/aws.ts

@@ -4,6 +4,7 @@ import { EKSClient } from "@aws-sdk/client-eks";
 import { EC2Client } from "@aws-sdk/client-ec2";
 import { RDSClient } from "@aws-sdk/client-rds";
 import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+import { IAMClient } from "@aws-sdk/client-iam";
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { APIGatewayClient } from "@aws-sdk/client-api-gateway";
 import { CloudFormationClient } from "@aws-sdk/client-cloudformation";
@@ -42,6 +43,7 @@ export type AwsClients = {
   ec2: EC2Client;
   rds: RDSClient;
   secretsManager: SecretsManagerClient;
+  iam: IAMClient;
   dynamodb: DynamoDBClient;
   apiGateway: APIGatewayClient;
   cloudformation: CloudFormationClient;
@@ -64,6 +66,7 @@ function buildClients(accountId: string): AwsClients {
     ec2: new EC2Client(base),
     rds: new RDSClient(base),
     secretsManager: new SecretsManagerClient(base),
+    iam: new IAMClient(base),
     dynamodb: new DynamoDBClient(base),
     apiGateway: new APIGatewayClient(base),
     cloudformation: new CloudFormationClient(base),
@@ -98,6 +101,7 @@ export const eks = awsClients.eks;
 export const ec2 = awsClients.ec2;
 export const rds = awsClients.rds;
 export const secretsManager = awsClients.secretsManager;
+export const iam = awsClients.iam;
 export const dynamodb = awsClients.dynamodb;
 export const apiGateway = awsClients.apiGateway;
 export const cloudformation = awsClients.cloudformation;