spec(security): add security boundary specification and refactor model spec

[markturansky]

Summary

• Adds specs/security/security.spec.md — a security boundary specification defining WHO can do WHAT across the platform's six identity boundaries (CP SA, per-session SA, user SSO, Vertex credentials, integration credentials, build agent SA)
• Refactors specs/api/ambient-model.spec.md to separate WHAT (schemas, endpoints, provider enum, permission matrix) from HOW (runtime authorization, credential grant semantics, proxy auth)
• Moves model spec from specs/sessions/ to specs/api/ with all reference updates
• Cross-references link both documents at each boundary

Key sections in security spec:

• §1: OpenShift build agent SA (namespace-scoped)
• §2: Security boundaries (CP, Vertex, SSO, integration creds, MCP lifecycle, per-session SA isolation)
• §3: Architecture diagram + invariants
• §4: Credential authorization model (extracted from model spec)
• §5: Design decisions (extracted from model spec)

Accounts and tokens table

15-row identity matrix covering every SA, token, and credential in the platform.

Test plan

• Verify all cross-references resolve correctly
• Verify no broken links in BOOKMARKS.md or design README
• Review security boundaries for completeness

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added comprehensive Security Specification defining identity boundaries, credential isolation, and runtime authorization model.
  • Migrated Credentials management from project-scoped to global with new REST API endpoints (/api/ambient/v1/credentials).
  • Added new RBAC roles: credential:owner and credential:viewer.

• Documentation

  • Reorganized specification documentation and updated reference paths across guides and workflows.
  • Expanded specification index to include new API and Security domains.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 76052905-92ea-4515-b724-55dc79d78a46

📥 Commits

Reviewing files that changed from the base of the PR and between 3b05694 and d18d439.

📒 Files selected for processing (8)

• BOOKMARKS.md
• docs/internal/design/README.md
• skills/devflow/SKILL.md
• specs/api/ambient-model.spec.md
• specs/index.spec.md
• specs/security/security.spec.md
• workflows/integrations/mcp-server.workflow.md
• workflows/sessions/ambient-model.workflow.md

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

---

📝 Walkthrough

Walkthrough

This PR reorganizes platform specifications by relocating the ambient data model to the api/ domain, redesigning the credential model from project-scoped to global resources with RoleBinding-based access control, and introducing a comprehensive security specification covering identity boundaries and credential authorization.

Changes

Specification Structure Reorganization & Credential Model Redesign

Layer / File(s)	Summary
Index & Domain Setup specs/index.spec.md, BOOKMARKS.md	Specs index adds api/ and security/ domains. Bookmarks table adds Security entry and updates MCP Server reference path.
Core Spec Migration docs/internal/design/README.md, skills/devflow/SKILL.md, workflows/sessions/ambient-model.workflow.md, workflows/integrations/mcp-server.workflow.md	All references to specs/sessions/ambient-model.spec.md redirected to specs/api/ambient-model.spec.md. Design README, contributor onboarding, and workflow guides updated.
Credential Model Transformation specs/api/ambient-model.spec.md	Credential redefined as global resource (single PAT/token store) accessible via RoleBindings with scope=credential. ER diagram, CLI (acpctl credential bind), and REST API (/api/ambient/v1/credentials) updated. RBAC roles expanded with credential:owner and credential:viewer. Implementation coverage matrix reflects global credential status.
Security Framework specs/security/security.spec.md	New 407-line security specification defining identity boundaries (control plane, per-session runners, user SSO, global credentials, OpenShift build agent), credential authorization model (RoleBinding-scoped access, token-reader gating), per-session ServiceAccount isolation with resourceNames scoping, and runtime credential enforcement rules. Includes boundary diagram and key invariants.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/security-spec

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/security-spec

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[netlify]

✅ Deploy Preview for cheerful-kitten-f556a0 canceled.

Name	Link
🔨 Latest commit	d18d439
🔍 Latest deploy log	https://app.netlify.com/projects/cheerful-kitten-f556a0/deploys/69fcd9e7c1de4f000832b2b1

[jsell-rh]

Review: Security Boundary Specification

Overall this is a strong spec — the six identity boundaries are clearly articulated, the accounts/tokens table is comprehensive, and the per-session SA isolation gap (§2.5) is well-documented with a concrete migration path. A few items to address before merge:

Blockers

1. Broken GFM table (§5 Design Decisions). The header separator row has a double pipe (||) which will break table rendering. Quick fix.

2. Spec format doesn't match project conventions. Per specs/index.spec.md, specs require ### Requirement: blocks with RFC 2119 keywords (SHALL/MUST/SHOULD) and #### Scenario: blocks with Given/When/Then. This spec uses prose sections and narrative description throughout. This is the same gap the markdown rendering specs had before they were rewritten — see specs/frontend/sessions/messages/markdown-rendering.spec.md for the target format.

3. Implementation details leak into the spec. File paths (components/manifests/base/rbac/control-plane-sa.yaml), function names (resolveCredentialIDs(), enforceCredentialRBAC(), clear_runtime_credentials()), and line numbers appear throughout. Per the spec format: "if the implementation can change without changing externally visible behavior, it does not belong in the spec." These belong in a paired workflow file, not the spec itself.

Structural Issues

4. namespace vs project terminology is conflated. The spec uses "project namespace", "single namespace", and "project-scoped" interchangeably without establishing the relationship. In the Ambient domain model, Project is the Ambient-level isolation boundary (API resource) and namespace is the Kubernetes implementation detail. They're 1:1 today, but the spec blurs them — e.g. §2.5 says "all runner sessions within a project namespace share access" without clarifying which boundary is being described. Recommend adding a terminology note upfront: "Each Project is realized as a single Kubernetes namespace. This spec uses 'project' for the Ambient boundary and 'namespace' only when referring to the Kubernetes primitive directly." — then use the terms consistently throughout.

5. New api/ domain not registered. The ambient-model.spec.md move from specs/sessions/ to specs/api/ creates a new domain without adding it to specs/index.spec.md's domain table. BOOKMARKS.md also still labels it as domain: sessions.

6. §1 (Build Agent SA) feels out of place. It's a proposed (not existing) SA for OpenShift CI/CD with very implementation-specific details (exact API groups and verbs). Consider a separate spec or appendix — it reads differently from the rest of the document.

Minor

7. "Status: Draft" / "Authors" / "Last Updated" metadata — other specs don't use this header format. Inconsistent but non-blocking.

8. Cross-references use §4 anchors that depend on heading numbering staying stable — fragile if sections are reordered. Consider using descriptive anchor links instead.

9. Model spec refactoring removes content and replaces it with cross-references. If someone reads the model spec standalone, they lose important credential design context. The security spec should be additive, not require readers to chase links for context that was previously inline.

---

Ambient Review Bot <jsell-rh.ambient-review-bot@redhat.com>

[jsell-rh]

Credential ownership gap after global migration

The latest commit (c37f0c90) moves credentials from project-scoped to global, but the permission matrix doesn't define who can create them:

Role	Credentials
platform:admin	full
project:owner	manage bindings
project:editor	—
project:viewer	—

Only platform:admin has credential CRUD. That means a regular user can't create their own GitHub PAT credential without an admin — which defeats the self-service model. This probably needs credential:owner and credential:viewer roles (or similar) so users can manage credentials they created and bind them to projects they own.

Security spec contradictions

The security spec was not updated to reflect the global credential model. It currently contradicts the model spec in several places:

• Requirement: Project-Scoped Credential Sharing — says "Credentials SHALL belong to a Project" and "no explicit sharing or per-credential RoleBindings needed" (the model spec now requires RoleBindings as the only access mechanism)
• Requirement: Integration Credential Isolation — says "Projects MUST NOT access each other's credentials" with a scenario "Cross-Project credential access blocked" (model spec explicitly enables cross-project sharing via RoleBindings)
• Design decisions table — says "Four-scope RBAC... no dedicated credential scope needed" and "Credential is Project-scoped, like a Kubernetes Secret" (model spec adds credential as a 5th scope and says "Credential is global, not project-scoped")
• Token Reader Role Grant — says "project:owner and project:editor can create/update/delete credentials" (model spec permission matrix says they can't)
• Multi-Project credential pattern — describes duplicating credentials across projects; model spec says the opposite

Stale references in security spec

• Token Reader scenario uses GET /projects/{id}/credentials/{cred_id}/token — model spec changed to GET /credentials/{cred_id}/token
• Key invariant #3 still says "Integration credentials are Project-scoped"
• Accounts table still shows Scope: Project for all credential rows
• K8s analogy table says "Credential | Secret | Project-scoped secret" — analogy breaks for global resources since K8s Secrets are namespace-scoped

[jsell-rh]

lgtm