docs: new architecture RFC

[alukach]

What I'm changing

This PR adds a new RFP and accompanying ADRs to the codebase.

How I did it

This RFC (adrs/rfc-001.md) describes a new architecture for our data proxy; some of which has been partially actualized in #109. Accompanying the RFC is various ADRs that go into greater detail about components of the architecture. The new architecture is future facing (ie it includes designs for new features) but attempts to be constrained, only thoroughly exploring a first wave of near-term features and only acknowledging later-stage features like metering and rate-limiting.

All nine documents are written in ASD-STE100 Simplified Technical English: active voice, simple present tense, one topic per sentence, approved vocabulary (technical names and technical verbs excepted), and procedures as numbered vertical lists. The goal is that the design reads unambiguously, including for reviewers who do not read English as a first language.

How to test it

Review, comment inline on PR.

[github-actions]

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

• Date: 2026-07-30T18:59:27Z
• Commit: 4adf56b

[tylere]

It would be useful to visualize both the current (non-Cloudflare) data flow vs. the new Cloudflare data flow.

[tylere]

How significant is the added latency?

[tylere]

Suggested change

	1. Parse `RoleArn` → extract `account_id` and `role_name`
	2. Load Role definition from policy store (cached, 30–60s TTL)
	3. Extract `iss` from JWT (without verification)
	4. Match `iss` against the Role's allowed IdPs — reject immediately if no match
	5. Fetch JWKS from the matched IdP (cached, 1hr TTL, 3s timeout, stale-while-revalidate on fetch failure)
	6. Verify JWT signature, `exp`, `nbf` (60s clock skew tolerance), and `aud`
	7. Evaluate claim constraints for the matched IdP binding
	8. Validate `DurationSeconds` ≤ Role's `max_session_duration`
	9. Generate credentials (see ADR-001 for token structure) and return response
	1. Parse `RoleArn` → extract `account_id` and `role_name`
	2. Load Role definition from policy store (cached, 30–60s TTL)
	3. Extract `iss` from JWT (without verification)
	4. Match `iss` against the Role's allowed IdPs — reject immediately if no match
	5. Fetch JWKS from the matched IdP (cached, 1hr TTL, 3s timeout, stale-while-revalidate on fetch failure)
	6. Verify JWT signature, `exp`, `nbf` (60s clock skew tolerance), and `aud`
	7. Evaluate claim constraints for the matched IdP binding
	8. Validate `DurationSeconds` ≤ Role's `max_session_duration`
	9. Generate credentials (see ADR-001 for token structure) and return response
	````mermaid
	flowchart TD
	Start["Receive AssumeRoleWithWebIdentity request"] --> Parse["1. Parse RoleArn<br/>→ account_id + role_name"]
	Parse --> LoadRole["2. Load Role from policy store<br/>(cached, 30–60s TTL)"]
	LoadRole --> ExtractIss["3. Extract iss from JWT<br/>(without verification)"]
	ExtractIss --> MatchIdP{"4. Does iss match<br/>Role's allowed IdPs?"}
	MatchIdP -- No --> RejectIdP["Reject:<br/>IDPRejectedClaim"]
	MatchIdP -- Yes --> FetchJWKS["5. Fetch JWKS from IdP<br/>(cached 1hr TTL, 3s timeout,<br/>stale-while-revalidate)"]
	FetchJWKS --> VerifyJWT{"6. Verify JWT<br/>signature, exp, nbf, aud"}
	VerifyJWT -- Invalid --> RejectJWT["Reject:<br/>InvalidIdentityToken"]
	VerifyJWT -- Valid --> EvalClaims{"7. Evaluate claim<br/>constraints"}
	EvalClaims -- Fail --> RejectClaims["Reject:<br/>IDPRejectedClaim"]
	EvalClaims -- Pass --> ValidateDuration{"8. DurationSeconds ≤<br/>max_session_duration?"}
	ValidateDuration -- No --> RejectDuration["Reject:<br/>ValidationError"]
	ValidateDuration -- Yes --> GenCreds["9. Generate short-lived<br/>SigV4 credentials"]
	GenCreds --> Return["Return credentials response"]

[tylere]

I'm not sure the mermaid diagram is worth the extra space, but I do find it easier to understand the decision flow.

[tylere]

Note that the STS log entries may include PII (e.g. assumed_by and client_ip), and that a future logging ADR will need to address retention/redaction policies.

[tylere]

Does the current version of object_store compile to WASM? Or is the risk that future versions of object_store may not be compatible?

[claude]

Claude finished @alukach's task in 3m 25s —— View job

---

❌ Changes requested — see findings below.

• adrs/001-s3-credentials.md:82-91 — SigV4 verification never binds the access_key_id claim inside the SessionToken JWT back to the AccessKeyId actually used in the request. The design relies on two independently-obtained secrets: SecretAccessKey = HMAC(server_secret, AccessKeyId) and the ES256-signed SessionToken. The doc claims a leaked SessionToken alone "gives no access without the related SecretAccessKey" (line 73, line 77), but that's only true if the verifier checks that the token's own access_key_id claim (line 59) matches the AccessKeyId from the Authorization header. As written, the 6-step verification flow never performs that comparison — it independently validates the SigV4 signature (steps 1-4) and the JWT (step 5), then authorizes using "the identity and permissions from the token" (step 6). Any caller that legitimately obtains its own low-privilege (AccessKeyId, SecretAccessKey) pair from /.sts could attach a different, higher-privilege SessionToken it intercepted (the doc explicitly says the token's permissions claim is readable by anyone who intercepts it) in the X-Amz-Security-Token header, sign the request with its own valid secret, and pass all six steps as documented. This same gap is repeated in adrs/005-authorization.md:52-58 ("Step 1 — Identify the caller").

  Suggested fix — add an explicit binding check to the flow:

   5. Read the `SessionToken` JWT from the `X-Amz-Security-Token` header. Then check the ES256 signature, `exp`, `nbf` (with a clock difference of 60 seconds), and `aud`.
  -6. Continue to the authorization (refer to ADR-005) with the identity and the permissions from the token.
  +6. Compare the `access_key_id` claim of the SessionToken with the `AccessKeyId` from the Authorization header. Refuse the request if they do not agree.
  +7. Continue to the authorization (refer to ADR-005) with the identity and the permissions from the token.

• adrs/004-sts.md:195,212 and adrs/008-api-keys.md:93 — no validation rule is specified for the caller-supplied RoleSessionName, even though it is echoed verbatim into the STS XML response (AssumedRoleId, e.g. line 212) and into structured JSON logs (session_name, e.g. adrs/004-sts.md:285). ADR-004 §"Validation of a New Role" (line 162) is careful to constrain the Role name to [a-z0-9][a-z0-9-]{0,62}, but no equivalent constraint is given for RoleSessionName. Real AWS STS restricts RoleSessionName to a fixed character set ([\w+=,.@-]*, ≤64 chars) precisely to keep it safe to embed in ARNs, XML responses, and CloudTrail logs. Without a similar constraint here, an implementation that naively string-interpolates RoleSessionName into the XML response is exposed to XML/markup injection from a value that is entirely attacker-controlled at request time.

  Suggested fix — add a validation rule alongside the Role name rule, e.g.: "RoleSessionName must match [\w+=,.@-]{2,64}; the proxy rejects any request whose value does not match before it is used in a response or a log entry."

Everything else — the STS/IdP trust model, the Role-ceiling ∩ account-permission authorization design, the outbound aud/sub token contract in adrs/006-outbound-storage.md, and the cache-key invariants — is internally consistent and the accepted trade-offs are clearly reasoned.