docs: customer onboarding IaC for federated S3 backends

[alukach]

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

What

Customer onboarding docs + copy-paste IaC for wiring a private S3 bucket to Source via federation. This is the make-or-break for adoption.

Contents

1. Create an IAM OIDC identity provider for https://data.source.coop (AWS auto-fetches its discovery doc + JWKS).
2. Create a role with:
   • Trust policy — Federated = that provider; StringEquals { "data.source.coop:aud": "source-coop-data-proxy" }; a sub condition at the chosen scope, e.g. StringLike { "data.source.coop:sub": "scv1:conn:<id>:account:<acct>*" }.
   • Permission policy — s3:GetObject / s3:ListBucket scoped to arn:aws:s3:::<bucket>/<base_prefix><mirror_prefix>* (customer-side blast-radius cap).
3. Paste the role ARN + choose subject_scope in the Source data-connection UI.

Deliverables

• Narrative onboarding doc
• CloudFormation and Terraform snippets (parameterized by bucket, connection id, prefix)
• Trust-policy examples for each subject_scope

[alukach]

Blocked by: #326 (fields to document). Trust/permission-policy content already proven by the PR-145 federation spike; finalize against the shipped flow.

[alukach]

Design update — 2026-06-06: single fixed subject shape + cache_level

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

1. One fixed subject shape. The OIDC sub is now always product-grained: scv1:conn:{connection_id}:{account_id}/{product_id}, minted for every assumption. The three-shape subject_scope contract is dropped.

2. Granularity moves to a per-connection cache_level enum (product | account | system) that controls only the proxy's cache key, never the subject. It must be no coarser than the granularity at which the customer's trust policy discriminates.

---

Changes for this ticket (#330 — onboarding IaC):

• There is now one trust-policy template, not one per scope. The subject is always scv1:conn:{connection_id}:{account_id}/{product_id}.
• Trust policy:
  • StringEquals { "data.source.coop:aud": "source-coop-data-proxy" } — always pin aud.
  • StringLike { "data.source.coop:sub": "scv1:conn:<id>:<acct>/*" } for all of the customer's products on the connection, or StringEquals { … "scv1:conn:<id>:<acct>/<product>" } for a single product. The customer chooses their wildcard granularity here.
• The UI choice is now cache_level, and the doc must state the coupling: cache_level must be no coarser than your trust-policy sub wildcard. (Want per-product enforcement? Keep cache_level = product. Wrote …:acct/*? account is safe and more efficient.)
• Permission policy unchanged (s3:GetObject / s3:ListBucket scoped to arn:aws:s3:::<bucket>/<base_prefix><mirror_prefix>*).
• Revised deliverables:
  • Narrative onboarding doc
  • CloudFormation and Terraform snippets (parameterized by bucket, connection id, account, prefix)
  • One trust-policy template + guidance on matching cache_level to the sub wildcard (replaces "examples for each subject_scope")

[alukach]

Drafted in source-cooperative/docs.source.coop#18 — a Connect a Private S3 Bucket onboarding guide under Using Source.

Covers the deliverables:

• Narrative onboarding doc (how federation works; Source stores only a role ARN).
• Copy-paste CloudFormation and Terraform, parameterized by connection id, bucket, and prefix.
• Trust-policy template.

One update vs the original ask: the "trust-policy examples for each subject_scope" item collapses to a single template. Per the 2026-06-06 design pivot, the subject is a fixed product-grained shape, so there's one sub pattern (scv1:conn:<id>:*), not one per scope.

Draft because (1) the proxy-side federation isn't live yet (/.well-known/openid-configuration returns 403) and (2) the contract values — aud = source-coop-data-proxy, issuer https://data.source.coop, the sub format — should be confirmed against the deployed proxy before publishing. Will close this issue when #18 merges.