Multi-service authorization extension: token primitives, control plane, outbound tokens, gateway, and topology (#12–#15)

[JedimEmO]

Summary

Implements the service-coms/gateway extension from #12, #13, #14, and #15, in the layering agreed during the issue review. #16 (binary data-plane transport) is deliberately not included.

Eight new crates across three families, plus an end-to-end example and book documentation:

crates/authorization/

• ras-authorization-token — the shared foundation: one RasClaims model for all RAS token families (ras_web_session multi-audience, ras_internal_access / ras_gateway_access single-audience), ES256/EdDSA signing (HS256 for embedded shared-secret mode only), kid-based KeyRing rotation with emergency removal, JWKS publication, and a strict TokenValidator (asymmetric-only algorithm allowlist by default, key/header algorithm cross-check against key-type confusion, issuer/audience/token-type pinning, clock-skew-aware exp/nbf).
• ras-authorization-core (Add RAS-native authorization control plane and internal service token issuer #13, embedded scope) — RAS-native control plane: service registry with unique audiences, audience-scoped grants and roles ("permission P at audience A"), permission-manifest import with unknown-permission rejection (explicit grant_custom escape hatch), pluggable ServiceIdentityVerifier (constant-time static-secret dev verifier shipped; production workload-identity adapters plug into the same trait), fail-closed TokenIssuer with topology-policy edge enforcement, append-only audit events that never contain secrets, embedded axum authority routes (POST /auth/token, GET /auth/jwks.json), and RasTokenAuthProvider so existing generated services validate RAS tokens through ras-auth-core unchanged.
• ras-authorization-gateway (Add optional RAS auth gateway for multi-service browser frontends #14) — optional token-narrowing reverse proxy: local web-session validation via JWKS, deterministic longest-prefix segment-aligned routing (duplicates fail validation, unmatched fail closed), single-audience derived tokens containing only the target audience's session permissions (never invented, never widened, never outliving the session), inbound Authorization/Cookie/Host/hop-by-hop stripping, streaming bodies, derived-token cache keyed by session/subject/audience/authz-version, generated-profile consumption with startup upstream validation. WebSocket upgrades fail closed (501) in v1 — documented limitation.

crates/integration/ (#12)

• ras-integration-core — TokenSource abstraction with token families, bounds-checked caching TokenManager (family+integration+subject+audience+canonical-scopes+config-version cache keys, early refresh, per-key concurrent-refresh dedup), GrantStore trait with in-memory impl, SecretString redaction throughout, and capability-scoped AuthorizedHttpClients over ras-transport-core that validate outbound hosts before minting tokens and never auto-replay requests.
• ras-integration-oauth2 — refresh-token flow with grant scope subset checks and transactional rotation persistence, client-credentials flow with audience forwarding, typed ConsentRequired on missing/revoked grants, and a PKCE S256 ConsentFlow with opaque single-use expiring state bound to user/integration/redirect/scopes/verifier.
• ras-integration-ras — RasInternalTokenSource: obtains internal tokens from the authority (in-process EmbeddedAuthority or HTTP HttpAuthority), holds no keys, never mints locally; v1 is service-as-service only with other principal modes failing closed.

crates/topology/ (#15)

• ras-topology-core + ras-topology-macro — ras_topology! declares the logical service graph with typed references to manifest functions and generated permission constants. Compile-time: duplicate ids, undeclared references. Build-time: audience uniqueness, per-gateway route conflicts, public-gateway-exposes-private-service (explicit expose_private required), edge permissions checked against target manifests. Emits byte-deterministic artifacts with content-derived ids: authorization policy JSON (loaded by the authority to refuse issuance outside the declared graph), gateway profile TOML (loaded by the gateway with deployment-provided upstream bindings), and Mermaid diagrams.

Example + docs

• examples/authorization-demo — two real rest_service! services wired end-to-end: topology artifacts constrain the authority and configure the gateway; billing calls invoice with an authority-issued internal token through the generated client; the gateway narrows a web session per route; generated WITH_PERMISSIONS enforcement still applies per operation.
• Four new mdBook chapters (Service-To-Service Auth, Outbound Integrations, The Auth Gateway, Topology), READMEs and rustdoc on all crates, CHANGELOG entry.

Testing

• ~120 new tests covering the issue test plans: rotation + emergency key removal, alg:none/algorithm-confusion rejection, cache-key collision resistance across token families and principal modes, concurrent-refresh dedup, refresh-rotation persistence-failure surfacing, consent-state single-use/expiry/binding, all fail-closed issuance paths, narrowing invariants, exposure validation, deterministic artifacts, and cross-crate artifact consumption.
• Six end-to-end scenarios in the demo, including the negative paths (missing audience permissions → 403, no session → 401, session token at a backend directly → 401, per-operation permission rejection, undeclared topology edges denied).
• Full workspace: 130 test suites green, clippy clean (zero warnings), cargo fmt --check clean, cargo deny passing, mdBook builds.

Deliberate v1 scope cuts (from the issue review)

• Add internal binary data-plane transport for low-latency service traffic #16 binary transport: parked entirely.
• No tenant/context scoping axis; no admin REST API (in-memory management API only); user-delegated internal tokens fail closed (the request/cache model already distinguishes principal modes, so delegation is additive later).
• Gateway WebSocket proxying deferred (fails closed) pending a narrowing-at-upgrade-time design.
• ras-identity-session is not yet migrated onto ras-authorization-token signing — that is the planned breaking follow-up, named in the Service-To-Service Auth chapter. Existing session behavior is untouched by this PR.

New crates are all 0.1.0; no existing crate APIs changed (the only touch outside new code is workspace manifest membership/deps, docs, and the topology builder consuming generated ServicePermissions).

Closes #12. Closes #13. Closes #14. Closes #15.

🤖 Generated with Claude Code