> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stacyos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Phase 6 security governance

# Phase 6 Security Governance Release Notes

Date: 2026-05-08
Branch: `phase-6-security-governance`

## Summary

Phase 6 adds the first security and governance layer above the Phase 5 admin control plane. This phase keeps current API-key deployments compatible while adding typed request identity metadata, route-level scope enforcement, safer audit attribution, configurable admin fallback policy, and production governance guidance for future RBAC and OIDC/SSO work.

## What Changed

### Request Identity Foundation

* Added request-scoped authentication identities in the API middleware.
* Added explicit `api` and `admin` roles.
* Added initial scope metadata:
  * `api:*` for regular API identities.
  * `api:*` and `admin:*` for admin identities.
* Admin keys used through either supported key header are now represented as admin identities.
* Regular API keys remain regular API identities and still cannot access admin routes when `auth.admin_api_key` is configured.

### Route-Level Scope Enforcement

* Added a reusable `RequireScope` middleware.
* Wired authenticated admin routes through `RequireScope("admin:*")`.
* Kept unauthenticated development mode behavior unchanged when no API keys are configured.

### Audit Attribution

* Admin audit fallback attribution now reads the authenticated role and key header from request context when no `X-User-ID` actor is supplied.
* Fallback actors are now more specific, such as `admin:X-Admin-API-Key`.
* Existing explicit actor behavior is preserved: `X-User-ID` still wins when supplied.

### Admin Fallback Policy

* Added `auth.admin_fallback_enabled`.
* Kept the default as `true` for backwards compatibility.
* Production templates set it to `false` so admin routes require a dedicated `auth.admin_api_key`.

### Production Security Guidance

* Added [security-governance.md](../security-governance.md).
* Documented production admin posture, operator attribution, key handling, and audit retention guidance.
* Added an OIDC/SSO config and claims-mapping design that reuses the Phase 6 request identity and `RequireScope` model.
* Added a Phase 6 acceptance checklist for production deployments.

## Compatibility

* No deployment config changes are required.
* Existing `X-API-Key` and `X-Admin-API-Key` behavior is preserved.
* Admin route fallback to `auth.api_key` remains available by default when no separate `auth.admin_api_key` is configured.

## Verification

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
go test ./internal/api/middleware
go test ./internal/api
go test ./...
npm run build
```

GitHub CI passed on `phase-6-security-governance` for:

* Go tests and CLI build
* Swagger drift check
* Python SDK import check
* TypeScript SDK build
* Deployment smoke test
* Web build

## Release Status

Phase 6 implementation is complete. The branch is ready for the Phase 6 GitHub release.