Sparse ACLs: Identity Center permission-set scope bindings + Organizations hierarchy

[c1-squire-dev]

Summary

Sparse ACLs (Cloud Infrastructure Access) for AWS Identity Center, in two phases:

• Phase 1 reshapes the existing Identity Center permission-set assignment data into ConductorOne's Sparse-ACL ingest contract — a TRAIT_SCOPE_BINDING resource type carrying per-binding ScopeBindingTrait{role_id, scope_resource_id}, an "assigned" entitlement, a parent-pointer hierarchy edge, and Grant/Revoke that read the trait — so the AWS app ingests as SPARSE/HYBRID and lights up the RoleScopeBindingRelationship / JIT / by-inheritance UAR / JML pipelines.
• Phase 2 adds the AWS Organizations Root → OU → Account hierarchy as scope tiers, so c1's by-inheritance review can walk the org tree above the account-leaf bindings.

Neither phase adds new mutation paths: all native integration (ListAccountAssignments, Create/DeleteAccountAssignment with status polling, conflict/suspended-account handling, group→member expansion) already existed and is reused unchanged. Phase 2 adds read-only Organizations tree calls.

What Phase 1 implements

• permission_set role type (TRAIT_ROLE) — one resource per permission-set ARN; resource id is the bare ARN via the single shared helper permissionSetRoleID. pkg/connector/permission_set.go.
• permission_set_assignment binding type (TRAIT_SCOPE_BINDING, OptInRequired) — one resource per (account, permission set) provisioned, carrying ScopeBindingTrait{role=permission_set, scope=account}, with the binding's parent set to the account (hierarchy edge for the by-inheritance ancestor walk). pkg/connector/permission_set_assignment.go.
• "assigned" entitlement on the binding (slug exactly "assigned"), grantable to SSO users and groups.
• Grants principal → binding → "assigned", reusing the existing per-assignment grant construction (direct grant for users; GrantExpandable{sso_group:<arn>:member} for groups — sparse and grant-expansion coexist).
• Grant/Revoke read the ScopeBindingTrait (never parse the object id) to recover (account, permission set), then call a shared provisionAssignment / deprovisionAssignment core extracted from the existing account path — so AWS semantics (status verification, TargetType=AWS_ACCOUNT, status polling, idempotency annotations) are byte-identical.
• account advertises ChildResourceType{permission_set_assignment} so the SDK crawls bindings under each account.
• Registered both builders in the existing ssoEnabled && orgsEnabled block and in the default-capabilities builder; regenerated baton_capabilities.json (binding declares TRAIT_SCOPE_BINDING + CAPABILITY_PROVISION + optInRequired).

Binding object-id / round-trip decision (pre-implementation gate)

The binding object id is "<permissionSetArn>-<accountID>", built by the single helper permissionSetAssignmentObjectID, byte-identical to the platform's JIT-fabricated id (<role>-<scope>). The id is treated as an opaque external identity — it is never split back into (role, scope); role/scope are always recovered from the ScopeBindingTrait. A permission-set ARN embeds -, : and :::, but this is harmless: the type↔resource separator is :: and the resource half (the ARN + -<accountID>) is preserved verbatim by a first-:: split. Verified end-to-end and covered by unit tests.

HYBRID coexistence

The legacy account-entitlement Grant/Revoke path is retained (shared provision core), so the app is HYBRID during the cutover window and existing grants keep working. Removing the old account-entitlement path is deferred to a follow-up once HYBRID ingest is validated and in-flight grants are drained.

What Phase 2 implements (Organizations hierarchy)

Adds the org tree above the account-leaf bindings as navigation / by-inheritance review context — it does not add OU/Root-level grant targets. AWS Identity Center assigns permission sets to accounts only; there is no native OU- or Root-level assignment, so scope-bindings stay account-level (unchanged) and the new tiers exist purely so c1's by-inheritance UAR resolver can walk Account → OU → Root with the role pinned and the browse tree renders connected.

• organization (root) resource type and organizational_unit resource type — scope tiers only (SkipEntitlementsAndGrants + OptInRequired), no traits, no bindings. pkg/connector/organization.go.
• Org/OU builders walk ListRoots → ListOrganizationalUnitsForParent (recursive via ChildResourceType, paginated with pagination.Bag), parenting each OU to its crawl seed (root or parent OU).
• account.List re-parents each active account onto its Root/OU via ListParents, wiring the parent_app_resource_* edge the ancestor walk needs. Flat ListAccounts streaming pagination is preserved — re-parenting is a per-account parent lookup, not a switch to per-OU listing.
• Fail-soft, not fail-fast. Missing organizations:* read permission (e.g. existing IAM policies without the new perms) degrades gracefully to flat accounts with a single WARN rather than aborting the sync — bindings are account-leaf regardless, so the tree is genuinely optional context. Any other error propagates (no error-swallow / no false-revocation).
• New org-read permissions declared on the relevant capability sets (organizations:ListParents on account; ListRoots / ListOrganizationalUnitsForParent on the org/OU types); registered the two builders in the ssoEnabled && orgsEnabled block and the default-capabilities builder; regenerated baton_capabilities.json.

Code-review fixes applied (Phase 1)

This PR has been revised to resolve the principal-engineer review:

• R1 (blocking) — removed the V1Identifier that had been planted on the new permission_set role resource. A brand-new sparse-ACL resource type has no v1 predecessor entity, so there is no legacy id to preserve; this matches both proven exemplars (baton-confluence space_role, baton-azure-infrastructure role_assignment) and the sibling binding resource, which already omitted it.
• T3 — Grant idempotency is now explicit. provisionAssignment pre-checks ListAccountAssignments and emits GrantAlreadyExists (skipping the create) when the assignment is already present, mirroring the existing GrantAlreadyRevoked-on-404 path in deprovisionAssignment, instead of relying on implicit CreateAccountAssignment server-side idempotency.
• T1 — behavioral test coverage. Introduced a minimal ssoAdminAPI / orgsAPI client seam (the AWS SDK clients satisfy it structurally; production wiring is unchanged) and an in-memory fake, then added tests that exercise behavior, not just id shape: binding List emits the expected scope-binding resource + trait and is gated on an account parent; Grant calls CreateAccountAssignment with the right scope/role/principal; Revoke deletes the right assignment; and both idempotency annotations (GrantAlreadyExists / GrantAlreadyRevoked) fire.
• T2 — round-trip test now pins the REAL contract. Replaced the circular local ResourceIDToString / ParseV2ExternalID replica with assertions against the real baton-sdk constructors (resource.NewResourceID + entitlement.NewEntitlementID). The type::resource external-id codec lives in the c1 platform repo (the SDK uses single-colon type:resource), which is intentionally outside a connector's module graph, so the end-to-end "::" byte-match is verified by the .c1z grep step against a live sync rather than an unimportable function — see the limitations below.
• Pagination — verified, no change needed. The binding List collects all permission sets provisioned to an account by fully draining the SDK ListPermissionSetsProvisionedToAccount paginator inside getOrFetchPermissionSetIDs; there is no single-page truncation that could silently drop bindings. The binding Grants correctly passes the AWS assignment token through.

Testing done

• go build ./... — success
• go test ./... — all passing (23 sparse-ACL tests in pkg/connector, +10 new for the Phase 2 hierarchy)
• golangci-lint run ./... — 0 issues
• Phase 1 unit tests cover: object-id shape with a real ARN; byte-match to the JIT fabrication; role-id drift guard between the role resource and the trait; trait byte-match (role/scope ids + parent edge); "assigned" slug + entitlement id; real-SDK reconcile-key pinning (NewResourceID / NewEntitlementID); and behavioral List/Grant/Revoke/idempotency tests via the faked client.
• Phase 2 unit tests (via the same client-mock seam): org-root emission, OU crawl under a root and recursively under a parent OU, parent-type gating (OUs never listed top-level or under a non-root/OU parent), account re-parenting to Root vs OU, and the organizations:* access-denied fail-soft paths (org/OU builders and account re-parenting all degrade without error).
• Regenerated baton_capabilities.json verified to declare the new types with the correct traits/capabilities (purely additive).

Deferred to later phases / known limitations

• Account-leaf scope ceiling (product implication). Unlike Azure mgmt-group cascade, an OU/Root node can never hold a binding — every grant resolves to a concrete account. The OU/Root tiers appear in review/browse and enable by-inheritance roll-up, but a "grant on OU-Eng" request has no native realization and would have to fan out to per-account grants (a future enhancement).
• Org hierarchy opt-in vs re-parenting. The organization / organizational_unit types are OptInRequired. Account re-parenting is gated on the organizations:ListParents permission (fail-soft), not on opt-in state (the SDK does not expose opted-in resource types to a builder). A deployment that grants the perm but does not opt into the org/OU types could produce account parent pointers to un-synced tiers; c1's ancestor walk is gap-tolerant, but enabling the hierarchy types alongside the perm is recommended.
• Double representation during the HYBRID overlap window. With the legacy path retained, the same underlying AWS account assignment is emitted twice — once as a classic account-entitlement grant and once as the sparse binding "assigned" grant. This is intentional per the cutover strategy and harmless in c1 (distinct resource types), but operators will see each access in both models until the legacy account-entitlement path is removed in a follow-up (after HYBRID validation + grant drain).
• End-to-end .c1z byte-match verification (c1-side) outstanding. The connector-side bytes (binding object id, trait role/scope ids, "assigned" entitlement id, account/OU/Root parent edges) are fully unit-tested, but the JIT↔sync reconcile byte-match against live c1 (scope_role_jit.go <role>-<scope> shape) and the by-inheritance walk over a real org tree should be confirmed once via a .c1z round-trip on a real Identity Center org before enabling on a tenant.
• Phase 3 — classic IAM feasibility (expected out of scope; effective scope lives in policy documents, not a grantable (role, scope) binding).

This ships behind OptInRequired (opt in via --sync-resource-types), so it is dark until enabled per tenant.

[github-actions]

Connector PR Review: Sparse ACLs: Identity Center permission-set scope bindings + Organizations hierarchy

Blocking Issues: 0 | Suggestions: 0 | Threads Resolved: 0
Criteria: Criteria status: none loaded - .claude/skills/ci-review.md was not found at trusted base ae20289.
Review mode: incremental since ce8e0f6
View review run: https://github.com/ConductorOne/baton-aws/actions/runs/27979615160

Review Summary
The full PR diff was scanned for security and correctness; no secrets, weak crypto, insecure TLS, injection, or command execution were found. The new commit refactors permissionSetAssignmentResourceType.List to paginate the per-account permission-set fan-out in entitlementsBatchSize batches, reusing the same entitlementsPageState plus encode/decodePageToken mechanism already used and tested by account.Entitlements. Termination, batch boundaries, and one-binding-per-permission-set are verified by the added TestPermissionSetAssignmentList_PaginatesInBatches; no new issues found.

Security Issues
None found.

Correctness Issues
None found.

Suggestions
None.

[github-actions]

No blocking issues found.

[github-actions]

No blocking issues found.

[github-actions]

No blocking issues found.

[github-actions]

No blocking issues found.