feat(federation): versioned subject contract + render_subject(subject_scope)

[alukach]

Part of the Federated backend authentication epic (proxy-side).

What

Implement the versioned, structured subject contract and a render_subject function. AWS trust policies can only condition on :aud / :sub for generic OIDC IdPs, so all scoping context is packed into sub.

Contract (scv1 scheme — public, versioned)

scv1:conn:{connection_id}
scv1:conn:{connection_id}:account:{product_account}
scv1:conn:{connection_id}:product:{product_account}/{product_id}

fn render_subject(scope: &SubjectScope, conn_id: &str, account: &str, product: &str) -> String

Notes

• sub is a public contract: customer trust policies hard-code its shape. Any future scv2 must be dual-minted during a transition (claim-level analog of dual-key JWKS rotation).
• Source IDs are [a-z0-9-], so : and / are safe delimiters.

Acceptance

• render_subject covers all three scopes
• Unit tests assert exact strings per scope
• Scheme tag (scv1:) present and documented as stable

[alukach]

Blocked by: source-cooperative/source.coop#326 (the subject_scope values). Pure string-formatting — can start as soon as the scope names are fixed.

[alukach]

Design update — 2026-06-06: render_subject is now branchless (no subject_scope)

This supersedes the subject_scope design across the federated-backend-auth epic.

Decision: the OIDC sub is now a single fixed, product-grained shape — scv1:conn:{connection_id}:{account_id}/{product_id} — minted for every assumption. Granularity moved off the subject and onto a per-connection cache_level enum (product | account | system) that controls only the proxy's cache key (see #141), never the subject. Rationale: subject_scope conflated what identity we assert (a public, hard-to-change contract) with how we cache it (an internal optimization); separating them keeps the public subject minimal and eliminates the prefix-collision between the old scv1:conn:{id} system subject and customer scv1:conn:{id}* wildcards.

---

Changes for this ticket (#139 — versioned subject contract + render_subject):

• render_subject is now branchless and takes no scope argument. Proposed signature:

  fn render_subject(conn_id: &str, account: &str, product: &str) -> String
  // -> "scv1:conn:{conn_id}:{account}/{product}"

• The three-shape contract (scv1:conn:{id} / scv1:conn:{id}:account:{acct} / scv1:conn:{id}:product:{acct}/{product}) and its account: / :product: type tags are dropped in favor of the one shape above. With a single shape there's no tag ambiguity.
• scv1: stays a versioned public contract; any future shape change is still a dual-mint scv2 migration. (A non-product granularity is the only thing that would force scv2 — unlikely now that granularity lives in cache_level.)
• IDs are [a-z0-9-], so : and / remain safe delimiters — assert/sanitize that charset on conn_id/account/product before composing (reject : / * whitespace).
• Revised acceptance:
  • render_subject returns scv1:conn:{conn}:{account}/{product} for any valid inputs
  • charset of each component asserted/sanitized
  • scv1: tag present and documented as stable
  • (removed) covers all three scopes — single shape, no scopes

Note (RoleSessionName): do not derive the AssumeRoleWithWebIdentity RoleSessionName from this subject — its charset is [\w+=,.@-] (no ://) and it caps at 64 chars. Keep the full subject in the sub claim (that's what the trust policy matches + what CloudTrail shows) and pass a separate sanitized short session name.