docs(osep): add OSEP-0005 for developer console with phased auth model (#348)

[divyamagrawal06]

Summary

• Adds oseps/0005-developer-console-phased-auth-model.md as the design proposal for issue feat: add developer console for sandbox operations with phased auth model #348.
  • Defines Phase 1 MVP scope:
    • new console/ React app for sandbox list/detail/create/renew/delete/endpoint flows
    • server-side role enforcement (read_only vs operator)
    • metadata-based owner/team scoping without introducing a database
  • Defines Phase 2 hardening scope:
    • OIDC + JWT validation
    • PostgreSQL-backed RBAC bindings and durable audit logs
  • Preserves backward compatibility for existing OPEN-SANDBOX-API-KEY automation and SDK
    workflows.
  • Documents rollout plan, risks/mitigations, and test strategy.

Testing

• Not run (documentation-only OSEP change)

Breaking Changes

• None

Checklist

• Linked issue or clearly described motivation (#348)
• Added/updated docs (OSEP)
• Security impact considered
• Backward compatibility considered

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds OSEP-0005 documentation proposing a Developer Console for sandbox lifecycle operations and a phased authentication/authorization model (Phase 1: trusted headers + metadata scoping; Phase 2: OIDC/JWT + PostgreSQL RBAC/audit).

Changes:

• Introduces a new OSEP document defining MVP console scope and server-side RBAC enforcement without a database.
• Documents Phase 2 hardening plan (OIDC/JWT validation, PostgreSQL RBAC bindings, durable audit).
• Adds rollout, risks/mitigations, and test plan sections to guide implementation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jwx0925]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b98977f0c8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[divyamagrawal06]

@jwx0925 resolved codex comments, please review

[jwx0925]

@jwx0925 resolved codex comments, please review

reviewing on it

[jwx0925]

Suggestion: clarify authentication failure behavior for trusted-header mode

The proposal explains how identity headers are configured for the trusted-header user auth path, but it does not explicitly describe the authentication failure behavior when those headers are missing.

In practice this can happen if:

• a user accesses the Console directly instead of through the configured auth proxy, or

• the proxy is misconfigured and fails to inject X-OpenSandbox-User, X-OpenSandbox-Team, or X-OpenSandbox-Roles.

It would be helpful to explicitly specify what the server should do in this case. For example:

When auth.mode = "api_key_and_user" and user_mode = "trusted_header", requests intended for Console access that do not contain the configured trusted headers should be treated as unauthenticated and rejected (e.g. 401 Unauthorized). The Console should then render a clear authentication-required or proxy-misconfiguration screen rather than silently falling back to anonymous access or another auth path.

Making this behavior explicit would remove ambiguity in the Phase 1 design and help operators understand the expected deployment model for trusted-header authentication.

[divyamagrawal06]

@jwx0925 Updated. I've edited the OSEP to state that when auth.mode = "api_key_and_user" and user_mode = "trusted_header", requests missing required trusted headers are treated as unauthenticated and rejected with 401 Unauthorized. Clarified remaining requested changes also.