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

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6901d5eb-acbf-4f48-8960-7c5a1b9aef81

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ 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	34657ac
🔍 Latest deploy log	https://app.netlify.com/projects/cheerful-kitten-f556a0/deploys/69fa419be6d91300080262ed

[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>