Team Cert Verification

Team certificate verification

Use this when your service is a BYOT relying party: agents present a DIDKey signature plus an AWID team certificate on every team-scoped request. The code ground truth is src/folio/auth.py; the test ground truth is tests/test_auth_v2_envelope.py. Port both and keep the tests green.

Envelope contract

Every team-scoped request carries four headers:

Authorization: DIDKey <did:key:z6Mk...> <base64url-no-padding-ed25519-signature>
X-AWEB-Timestamp: <RFC3339 UTC timestamp>
X-AWID-Team-Certificate: <base64-standard-json-team-certificate>
X-AWEB-Signed-Payload: <base64url-no-padding canonical-JSON of the signed payload>

X-AWEB-Signed-Payload decodes to canonical JSON with these fields:

{"aud":"https://<service-origin>","body_sha256":"<sha256 hex of request body>","method":"<UPPER>","path":"<raw path?query>","team_id":"<team>:<namespace>","timestamp":"<RFC3339 UTC timestamp>","v":2}

Rules:

• The signed-payload header is base64url with no padding (= is rejected in folio; see src/folio/auth.py:137-146).
• Parsed JSON must round-trip to the same canonical bytes: canonical_json(parsed) == decoded bytes (src/folio/auth.py:188-193).
• The Ed25519 signature verifies over those decoded presented bytes, not over a payload the server reconstructs (src/folio/auth.py:217-220).

Ten verification steps

Follow this implementation order when porting src/folio/auth.py. The cert is parsed early to obtain team_id for request binding and to compare member_did_key; it is still untrusted data until the AWID-resolved team key verifies its signature and revocation passes.

1. Parse DIDKey auth and timestamp — 401 on bad Authorization, missing/invalid timestamp, or timestamp outside skew. Why: this selects the request signing key and bounds stale requests.
2. Decode the team certificate and required fields — 401 on missing or malformed certificate, missing team_id/certificate_id/member_did_key/ alias, or certificate.member_did_key != request did:key. Why: the signed payload's team_id must bind to the presented cert's team, and the cert must name the same member key as the request signer.
3. Read and hash exact request bytes — store the body bytes and SHA-256. Later return 401 if signed body_sha256 differs. Why: bodyless and bodyful methods use the same rule; tampered bodies fail.
4. Require and decode X-AWEB-Signed-Payload — 401 on missing, malformed, padded, non-canonical, or non-object payload. Why: the presented canonical bytes are the signed object; accepting alternatives creates ambiguity.
5. Require v == 2 — 401 on absent or other versions. Why: v1/compact payloads do not bind method/path/audience.
6. Bind timestamp, body hash, method, raw path, team id, and audience — 401 on mismatch or invalid/disallowed audience. Why: this is what makes a captured signature useless against another endpoint, method, team, body, or host.
7. Verify the DIDKey signature over decoded signed-payload bytes — 401 on bad signature. Why: the agent must have signed exactly the payload bytes it presented.
8. Resolve AWID team facts — 401 for an invalid/unknown team id; 503 for unavailable or malformed AWID team-key/revocation facts with no unexpired cache entry. Why: AWID, not the cert, is authority for the team key.
9. Check revocation and verify the certificate signature — 401 if the certificate_id is revoked or the cert signature fails; 503 if the AWID-resolved team public key is invalid. Why: membership can be removed outside your app, and cert signatures must verify against AWID-resolved authority.
10. Build the principal from the verified certificate — no request-body team id. Why: all app queries must scope by the certificate's team_id.