DeploymentRef & VAULT Credential Path

ELI5

Rocky never writes a workspace’s password into its own database. The console DB holds a pointer — a string that says “ask SS-06 VAULT for the secret at this path” — and only VAULT hands the secret to authorised callers, with a log entry every time.

Technical Deep Dive

Two storage layers, one slug

Rocky never stores CAIRNET/LORE contents — only deployment metadata. Driver-issued credentials land in SS-06 VAULT keyed by workspace_slug.

DeploymentRef shape (Phase 5 §6)

{
  workspace_slug: string,
  tier: Tier,
  driver: DriverName,
  endpoint: string,           // resolvable URL or socket path
  secrets_vault_path: string, // pointer, e.g. "vault://hearth/<slug>"
  created: string,            // ISO 8601
  last_status: Status         // see rocky-008 state machine
}

secrets_vault_path is a string — the console’s VAULT layer translates it on read. For the LocalDocker driver (Phase 5 §9): secrets_vault_path = vault://hearth/<slug>.

Read path

flowchart LR
    UI[admin UI / SS-04 caller]
    SS08[SS-08 console getWorkspaceDeployment]
    DB[(console DB DeploymentRef row)]
    VAULT[SS-06 VAULT]
    HATCH[HATCH log]

    UI --> SS08
    SS08 -->|select by slug| DB
    DB -->|row| SS08
    SS08 -->|return DeploymentRef metadata| UI
    UI -.optional.-> VAULT
    VAULT -->|every read| HATCH
    note1[console NEVER logs raw credential]:::n
    SS08 -.no secret on this edge.-> UI
    classDef n fill:#ffe,stroke:#cc0

The discovery seam every other subsystem uses is getWorkspaceDeployment(slug) — it returns DeploymentRef | null containing the pointer, not the secret. Subsystems that actually need the secret call VAULT directly; SS-06 audits read access.

Class shape

classDiagram
    class DeploymentRef {
        +string workspace_slug
        +Tier tier
        +DriverName driver
        +string endpoint
        +string secrets_vault_path
        +string created
        +Status last_status
    }
    class VaultEntry {
        +string path
        +bytes secret
        +datetime last_read_at
    }
    class HatchEvent {
        +string actor
        +string subject_path
        +string ts
    }
    DeploymentRef ..> VaultEntry : "vault pointer"
    VaultEntry --> HatchEvent : every read

The non-leak invariant

Phase 5 D7: “VAULT is the only credential store. Driver-issued credentials never land in the console DB; they go to SS-06 VAULT keyed by workspace_slug. The DeploymentRef row stores secrets_vault_path (a pointer), never the secret. Tenancy invariant: SS-06 audits read access; the console never logs a raw credential.”

The “never logs a raw credential” part is enforced by code review against the parsers at SS-08 trust boundaries — the routes log the DeploymentRef, which by construction contains only the pointer.

Key Terms

• DeploymentRef → metadata row in console Postgres; pointer to credentials, not the credentials themselves
• secrets_vault_path → opaque string, conventionally vault://hearth/<slug> for the LocalDocker driver
• VAULT → SS-06 subsystem; sole credential store; audits every read
• Discovery seam → getWorkspaceDeployment(slug); resolves CAIRNET/LORE endpoints for any subsystem that needs them

Q&A

Q: Why is endpoint on the DB row but the credential is not? A: endpoint is non-secret routing metadata; revealing it does not compromise access. Credentials are gated by VAULT so every read is audited; mixing audited and non-audited fields in one row would leak audit fidelity.

Q: What format does the LocalDocker driver write to secrets_vault_path? A: vault://hearth/<slug>. The console’s VAULT layer translates the URL on read.

Q: Can a subsystem fetch the secret without going through VAULT? A: No — the DeploymentRef row carries no secret material. The pointer is unusable except via SS-06, which logs every access through HATCH.

Examples

A safety-deposit box bank: the receipt (DeploymentRef) tells you which branch and which box number, but the actual key lives at the bank (VAULT). Every time someone opens the box, the bank logs it. Lose the receipt and you can’t open the box; the receipt by itself is not the key.