feat(sts): serve the FullAccess and ReadOnly roles

[alukach]

On main, now that #235 is merged; two commits. How to test it lists what I ran locally.

What I'm changing

/.sts serves three hardcoded Roles instead of one, for ID tokens and API keys alike, as ADR-014 (#232) specifies:

Role	Credentials may
FullAccess	do everything the account's memberships allow
ReadOnly	do the same, except write
_default	do what FullAccess does; kept because deployed clients name it

• Names. Each Role is accepted bare or as the role/<name> resource of an ARN of any partition and account (arn:aws:iam::000000000000:role/ReadOnly), because SDKs check the ARN shape before sending. A pathed resource (role/team/ReadOnly), another case (readonly) or any other name is RoleNotFound, never a fallback to a default.
• The ceiling. ReadOnly seals one scope into the session token's allowed_scopes: every product (*), read actions only (GetObject, HeadObject, ListBucket). The gateway never calls multistore's own scope check (auth::authorize), because this proxy's registry is the authorizer, so the registry enforces it. get_bucket checks the ceiling first, before any Source API lookup, and refuses with the same AccessDenied as every other refusal (ADR-011, Denial Semantics). An INFO log line is the only record of why.
• It only subtracts. A write the ceiling allows still needs the account's own write permission, fetched as before.
• No scopes, no ceiling. FullAccess and _default seal no scopes, as _default never has, so every session already issued keeps working. A _default exchange returns the same response as before, AssumedRoleId included.
• Both entry points. The STS route (StsCredentialRegistry::get_role) and the API-key exchange (exchange_api_key, which accepted only _default) share one lookup, sts::role. The key exchange's log line now names the Role.

source.coop main's GitHub integration snippet (src/lib/services/github-workflow.ts) already hands out arn:aws:iam::<service-account-id>:role/FullAccess. This PR makes that Role name resolve. The rest of that path is the next PR in this stack, which trusts a GitHub token for the account it names (#222, #223), plus GetCallerIdentity in developmentseed/multistore#126.

Decisions to flag

• The first comment on Add the ReadOnly Role alongside FullAccess #221 is superseded. It says ReadOnly cannot be enforced until multistore plumbs the assumed Role through to the registry. That isn't needed: what is sealed is the Role's ceiling, not its name, and AuthenticatedIdentity.allowed_scopes already reaches BucketRegistry::get_bucket (multistore 0.7.2, auth/identity.rs). No multistore change.
• The ceiling understands only what the two Roles need: a scope over every product (*) with no prefix. A scope naming one product or a prefix permits nothing rather than being half-interpreted. ADR-011's resource matching can arrive with account-owned Roles. The * sentinel means something only to this proxy, because multistore's exact-match authorize never runs here.
• Empty scopes mean no ceiling in the registry. This is the reverse of multistore's authorize, where empty means deny-all, as ADR-001 noted. It is safe because only this proxy mints session tokens, sealed with SESSION_TOKEN_KEY, and every _default session carries empty scopes.
• ReadOnly excludes GetObjectVersion (reading a versioned copy source). The write gate already classes it as a write, and a native test pins that the ceiling and is_write_action agree on every action. That is the divergence ADR-011 warns about.
• ARNs are now parsed as six colon-separated fields with a role/<name> resource. The old _default check matched only the arn: prefix and the :role/_default suffix, so it also accepted malformed strings such as arn:role/_default. Those are now refused, and no SDK sends them anyway: they fail the SDKs' own 20-character minimum.

How I did it

• src/sts.rs: role(role_arn, issuer, audiences, max_session) returns the named Role or None, replacing default_role and is_default_role. ALL_PRODUCTS is the * sentinel.
• src/authz.rs: ceiling_permits(scopes, action).
• src/source_api/registry.rs: the check at the top of get_bucket.
• src/lib.rs: the key exchange resolves the named Role before its lookup, as before, and mints under it.
• README.md: a Roles section. adrs/001, 004 and 011, in a separate commit: see below.

How to test it

• cargo test: all suites pass. tests/sts.rs covers bare and ARN names for all three Roles, including a service-account-shaped account segment, and refusal of unknown, lower-case, pathed, suffixed and non-role names. tests/authz.rs covers that ReadOnly's sealed ceiling allows exactly the actions is_write_action calls reads, that FullAccess and _default allow every action, and that narrower scopes permit nothing. tests/keys.rs checks that a ReadOnly key's session unseals with ReadOnly's ceiling.
• cargo fmt --check, cargo clippy --target wasm32-unknown-unknown -- -D warnings and cargo check --target wasm32-unknown-unknown, through the pre-commit hook.
• pytest tests/ --ignore=tests/test_contract.py against wrangler dev (wrangler 3.114) and tests/stub_api.py: 35 passed, 15 skipped. The skipped ones are the credentialed tests that need CI's GitHub token. The new test_read_only_refuses_a_write_before_anything_is_looked_up exchanges the stub's live key for ReadOnly and for FullAccess, then writes to a product the stub has never heard of. ReadOnly gets AccessDenied. FullAccess gets past the ceiling to the product lookup and gets NoSuchBucket, and so does a ReadOnly read. The upstream write itself fails closed in CI, so the product lookup is where the ceiling's path can be told apart. I also disabled the check, saw this test fail (ReadOnly got NoSuchBucket), and restored it.

Docs and ADRs

• ADR-011 (Role-Ceiling Authorization) still describes the model. This PR implements its step 2 and its denial semantics for the two hardcoded Roles, so its status line now says it is implemented in part.
• ADR-004 described "a single built-in Role, _default". A note under that section now points to ADR-014 and this PR, and ADR-004's "Implemented by" line lists this PR.
• ADR-001 said assumed_role_id is "currently always _default" and that the sealed allowed_scopes is empty and "not enforced on this path". Its credential table now names the three Roles and their ceilings. Its bullet now says the registry enforces the ceiling and reads empty as no ceiling.
• ADR-014 (docs(adr): ADR-014 service accounts; amend ADR-010 and ADR-013 #232) says "two Roles are hardcoded, FullAccess and ReadOnly, with _default kept as an alias (Add the ReadOnly Role alongside FullAccess #221)". This PR implements that, so it still holds. ADR-010's scope note is ADR-014's amendment and also holds.
• ADR-013 as revised (docs(adr): revise ADR-013 — API keys are opaque secrets resolved by the platform #234) says a key's "role must be one the proxy serves". That still holds, and keys can now name all three Roles.
• docs.source.coop: no page on main describes /.sts or its Roles yet. The unattended-workflow guide, Unattended workflow guide docs.source.coop#34, is where the Role names belong.

PR Checklist

• This PR has no breaking changes. _default behaves and answers as before; only malformed ARNs that no SDK can send are newly refused.
• I have updated or added new tests to cover the changes in this PR.
• This PR affects the Source Cooperative Frontend & API: source.coop main's GitHub snippet names role/FullAccess, which resolves from this PR on. No source.coop change is needed.

Related Issues

Closes #221. Builds on #235, merged. ADRs: #232 (ADR-014), #234 (ADR-013 revised). Epic: source-cooperative/source.coop#491.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R1eiTse4416N6uTgAy4Ddd

[claude]

Claude finished @alukach's task in 14s —— View job

---

✅ No blocking issues — safe to merge.

I read the src/ diff: sts::role, role_name, ceiling_permits, the get_bucket check and the key-exchange change. I did not run the tests or CI. The PR notes say CI won't run until #235 merges and this is retargeted.

• Ceiling logic: ceiling_permits runs before any Source API lookup. It returns AccessDenied, the same error as other refusals. It only subtracts from the account's own permissions. Narrower scopes permit nothing.
• Empty scopes mean no ceiling: this is safe because only the proxy mints session tokens, sealed with SESSION_TOKEN_KEY. Every existing _default session carries empty scopes.
• ARN parsing: splitn(6, ':').nth(5)?.strip_prefix("role/") rejects arn:role/_default. A pathed resource (role/team/ReadOnly) is also refused, because the name would be team/ReadOnly and match nothing. That matches the PR description.
• Key exchange: the Role is resolved before the key lookup, as before. The log line now names the Role.

Simplify (ponytail)

• src/sts.rs StsCredentialRegistry: get_role clones the issuer and audiences on every call just to build a RoleConfig. That is fine at this size. If more Roles arrive, build the RoleConfigs once in new and look them up by name.

---

💰 Estimated review cost: $0.13 · 0m14s · 4 turns

[github-actions]

🚀 Latest commit deployed to https://source-data-proxy-pr-236.source-coop.workers.dev

• Date: 2026-09-30T03:36:51Z
• Commit: 05434fa

[alukach]

Rebased onto main after #235's squash merge and force-pushed: the branch is now this PR's two commits. One conflict, in adrs/004-sts.md: main gained ADR-014's amendment note (from #232) in the same place this PR adds its roles note. Both are kept, in one NOTE block, ADR-014's first. The code is unchanged and cargo test passes.