feat(iam): add an AWS IAM adapter with a schema-declared kind facet

[TheSaifZaman]

Adds an iam service under Security covering users, roles and customer-managed
policies — and the small SPI change it needs.

Why the SPI change ships with a consumer

IAM holds three kinds of resource in one category, and kind=roles is not something
a free-text search box can express. So this adds ResourceQuery.filters, populated
by the list route.

I deliberately did not send the facet plumbing as its own PR. sortable and
copyable were removed from TableColumnSchema in review for being unused, so
schema surface with no consumer gets rejected here — rightly. This lands the facet
and its first real user together.

filters is populated only for the facet names a service's own schema declares,
so an undeclared or stale query param is ignored rather than reaching an adapter that
never asked for it — the same way the catalog gates unknown service slugs. search
stays a separate field, so every existing adapter is untouched.

Decisions that follow from the API's shape

• Resource ids are kind/identifier — user/alice, role/deployer, and
  policy/{arn} for policies, because GetPolicy and DeletePolicy take an ARN
  rather than a name. A bare name would be ambiguous across the three kinds and
  would not tell get or delete which API to call. The ids survive the generic
  route because HttpClient.ts:257 encodes path params — verified with an encoded
  ARN, not assumed.
• Policies are listed with Scope: 'Local'. Real IAM otherwise returns close to
  a thousand AWS-managed policies and buries the account's own. The emulator returns
  few enough that only a test can hold this line.
• A role's trust policy is decoded from the percent-encoded form IAM returns,
  which is unreadable raw in the inspector.
• create validates per kind: a role needs a trust policy, a policy needs a
  document, and both must parse as JSON. The message names the field and the kind,
  because a flat form cannot mark a field conditionally required and the form shows
  both for every kind.
• Every List call pages on IsTruncated/Marker.

Verification

lint, type-check, test and build pass from the repo root; both lockfiles
install --frozen-lockfile clean.

25 adapter tests plus 4 route tests for the facet plumbing. Hermetic — the IAM,
route, capability-guard and catalog suites (149 tests) pass with globalThis.fetch
replaced by a throw. I also confirmed the route tests genuinely fail without the
plumbing rather than passing by construction.

End to end through the route: nav entry, create for all three kinds, list with and
without the facet, an undeclared param being ignored, an unknown facet value
returning 400, inspect by encoded id including a policy ARN, the decoded trust
policy, delete for each kind, and 404 for a missing entity.

Merge note

Branched off main. Adds 'iam-user' | 'iam-role' | 'iam-policy' to
CloudResource.type, which #156–#161 also widen with their own members, so the last
to merge resolves a one-line conflict. The ResourceQuery and route changes are
additive and touched by no other open PR.

Follow-ups this unblocks: GCP IAM service accounts, and attach/detach of policies
once there is a generic resource actions route.

[greptile-apps]

Greptile Summary

Adds an AWS IAM adapter (users, roles, customer-managed policies) plus schema-declared kind facet plumbing on list routes.

• Registers @aws-sdk/client-iam and wires IAMClient into AWS clients.
• Introduces AwsIamAdapter with list/get/create/delete, kind-prefixed ids, Local-scoped policy listing, and policy-document load on inspect.
• Extends ResourceQuery.filters, catalog/schema, and route tests so only schema-declared facets reach adapters.

Confidence Score: 5/5

The PR appears safe to merge; the prior policy-inspect gap is addressed and no blocking failure remains.

Policy get loads the default version with GetPolicyVersion, decodes the document for inspect, degrades with policyDocumentUnavailable on version failure, and list still avoids N+1 version calls. No remaining blocking failure on the changed path.

Important Files Changed

Filename	Overview
packages/api/src/adapter-aws/AwsIamAdapter.ts	IAM adapter with kind-prefixed ids; policy inspect loads default version via GetPolicyVersion and surfaces decoded document (or unavailable flag).
packages/api/src/adapter-aws/AwsIamAdapter.test.ts	Covers kind facet, pagination, create validation, and policy-document inspect including encoded/literal docs and version-lookup failure.
packages/api/src/routes/clouds.ts	Populates ResourceQuery.filters only for schema-declared facet names.
packages/api/src/cloud-spi/types.ts	Adds filters on ResourceQuery and iam resource types.

_{Reviews (5): Last reviewed commit: "docs(iam): state that the kind facet is ..." | Re-trigger Greptile}

[hectorvent]

Thank you for a genuinely careful adapter. The details show real attention to the IAM contract: paging every List call on IsTruncated and Marker, listing policies with Scope Local so the account's own policies are not buried (with a test holding that line), decoding the percent-encoded trust policy, fetching the policy document only on inspect to avoid an N+1, and keying policies by ARN because GetPolicy and DeletePolicy take one. The hermetic test suite and the schema-gated facet plumbing in the route are both well thought through, and both lockfiles are regenerated, which is the most common CI trap here.

One coordination note before the substance: PR #145 has been adding AWS IAM to the Cloud Explorer since July 18 and is actively iterating through review, and the two PRs touch the same files (adapter, schema, catalog row, and the shared type unions). That is nobody's fault, but the direction (one identity category starting with users, or this three-kind service with a facet) is mine to decide, and I am working through it now. It would be worth holding off on rework here until that lands, so neither of you burns time rebasing twice.

On the merits, two questions:

1. The kind facet currently has no way to be used from the UI. DynamicResourceView only sends search (cloudProxyClient passes just that one param), and schema.filters is not rendered as controls anywhere in the frontend, so today the facet is reachable only by calling the API directly. Given your own (good) argument that schema surface needs a consumer landing with it, could you add the small piece that renders non-search filters from the schema (a select next to the search box in DynamicResourceView would do), or say explicitly in the PR that the facet is API-only for now and the UI control is a follow-up? Either is fine, it just should be a stated choice rather than a gap.

2. Nit, not a blocker: the README table row looks hand-added. AGENTS.md asks for the table to be regenerated with bun run scripts/service-matrix.ts so it cannot drift; could you confirm the row matches the script's output?

Everything else (catalog registration, typed errors, capability guard, tests colocated, no fake data, real empty states) follows the current pattern exactly. Nice work.

[TheSaifZaman]

Rebased onto fd3bd2f after #147, #152 and #155 merged. Conflict was the CloudResource.type union in both packages against the 'secret' member #147 added; all three IAM members plus 'secret' kept. README regenerated from service-matrix.ts.

Gate green after the rebase: lint, type-check, 459 tests, build.

[TheSaifZaman]

@hectorvent Thank you, and understood on the #145 coordination — I have deliberately not reworked the adapter or the taxonomy while that decision is open, so this push is limited to the two things you asked for that are independent of it.

1. The kind facet is API-only, and it is now a stated choice rather than a gap. You are right that my own "schema surface needs a consumer" argument cuts against me here, so I have taken the second of your two options and written the reasoning into iamSchema.ts above the filter declaration: DynamicResourceView sends only search, nothing renders schema.filters as controls, so the facet is reachable only by calling the API directly.

I chose that over building the control because rendering non-search filters is shared frontend work — every category with a facet needs it, and it would collide with whatever #145 lands. It belongs in its own PR rather than half-built here. If the maintainer decision goes toward this PR's shape and you would rather the select ship with it, I am happy to add it then.

2. Confirmed the README row is generated. Re-ran bun run scripts/service-matrix.ts on the rebased branch and diffed: | Security | IAM | Yes (list, create, delete, inspect) | No | No | matches the script output exactly. It was hand-added originally, so thank you for catching it — the rebase regenerated the whole table anyway, since #147 changed the Security rows.

On the FieldType limitation: #167's review turned up the same wall from the other side — an ASL definition needs a textarea, this needs a filter control, and FieldType knows only text and select. That looks like one small SPI PR that unblocks both.

Gate green: lint, type-check, 459 tests, build.