git.stella-ops.org/docs/contracts/authority-routing-decision.md

Authority Routing Decision

Decision ID: DECISION-AUTH-001 Status: DEFAULT-APPROVED Effective Date: 2025-12-06 48h Window Started: 2025-12-06T00:00:00Z

Decision

Authority claim routing uses RBAC-standard routing patterns aligned with existing docs/security/scopes-and-roles.md.

Rationale

1. RBAC patterns are well-established and auditable
2. Consistent with Authority module implementation
3. Supports multi-tenancy requirements
4. Compatible with external IdP integration (OIDC, SAML)

Routing Matrix

Claim	Source	Routing	Scope
tenant_id	Token/Session	Per-request	All endpoints
project_id	Token/Header	Per-request	Project-scoped
user_id	Token	Per-request	User-scoped
role	Token claims	Authorization	Role-based access
scope	Token claims	Authorization	Fine-grained access

Claim Priority

When claims conflict:

1. Explicit header overrides token claim (if authorized)
2. Token claim is authoritative for identity
3. Session context provides defaults

Implementation Pattern

// Authority claim resolution
public class ClaimResolver : IClaimResolver
{
    public AuthorityContext Resolve(HttpContext context)
    {
        var tenantId = context.Request.Headers["X-Tenant-Id"]
            ?? context.User.FindFirst("tenant_id")?.Value;

        var projectId = context.Request.Headers["X-Project-Id"]
            ?? context.User.FindFirst("project_id")?.Value;

        return new AuthorityContext(tenantId, projectId);
    }
}

Impact

• Tasks unblocked: ~5
• Sprint files affected: SPRINT_0303

Reversibility

To change routing patterns:

1. Update docs/security/scopes-and-roles.md
2. Get Authority Guild + Security Guild sign-off
3. Update AuthorityClaimsProvider implementations
4. Migration path for existing integrations

References

• Scopes and Roles
• Auth Scopes
• Tenancy Overview