Skip to main content
← Back to list
01Issue
FeatureShippedSwamp Club
Assigneesstack72

Relationships

#1429 Docs: document vault selection for sensitive fields (defaultVault, per-resource vaultName)

Opened by stack72 · 7/27/2026· Shipped 7/27/2026

Context

PR #1984 (swamp-club#1420) added two mechanisms for controlling which vault receives sensitive field values:

  1. Per-resource `vaultName` override in definition YAML — routes a specific resource's sensitive fields to a named vault
  2. Repo-level `defaultVault` in `.swamp.yaml` — sets the fallback vault for all sensitive field storage and serve/device-auth operations

Both are optional and fully backwards compatible — when neither is configured, behaviour is identical to before (first available vault).

What needs documenting

Reference docs (`content/manual/reference/vaults.md`)

Update the vault reference to cover:

  • Vault resolution order (the full chain):

    1. Field-level `vaultName` from `.meta({ sensitive: true, vaultName: "..." })` — set by extension authors in TypeScript
    2. Spec-level `vaultName` from `ResourceOutputSpec` — set by extension authors or overridden via definition YAML `resources..vaultName`
    3. Repo-level `defaultVault` from `.swamp.yaml`
    4. First available vault (backwards-compat fallback)

  • `defaultVault` in `.swamp.yaml`: syntax, what it affects (model execution, serve OAuth, device auth token storage), when it's ignored (field/spec-level overrides take precedence)

  • Definition-level `vaultName` override: syntax example showing the `resources` block in a model definition YAML, how it maps to the extension's `ResourceOutputSpec` names

  • Sensitive method arguments: clarify that sensitive method arguments are the user's responsibility to vault (the runtime enforces they must be `${{ vault.get(...) }}` expressions, but does not automatically route argument values into a vault)

How-to guide (`content/manual/how-to/vaults/`)

Consider a new guide: "Route sensitive fields to specific vaults" covering:

  • When you'd want multiple vaults (different trust levels, different environments)
  • Setting `defaultVault` in `.swamp.yaml`
  • Overriding per-resource in a model definition
  • Verifying which vault received a secret (`swamp vault list-keys`)

Technical details

The implementation lives in:

  • `src/domain/models/data_writer.ts` — vault resolution chain
  • `src/domain/vaults/vault_service.ts` — `getDefaultVaultName()`
  • `src/infrastructure/persistence/repo_marker_repository.ts` — `defaultVault` on RepoMarkerData
  • `src/domain/definitions/definition.ts` — `vaultName` on ResourceOverrideSchema
  • `design/vaults.md` — internal design doc (already updated)
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 3 MOREPR_MERGED+ 1 MORENOTIFICATION_SKIPPED

Shipped

7/27/2026, 4:12:09 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/27/2026, 3:23:57 PM

Sign in to post a ripple.