feat: auto-store sensitive output fields in vault before persistence

[stack72]

Closes #433
Closes #447

Summary

• When upstream APIs return sensitive data (e.g., EC2 CreateKeyPair returns KeyMaterial), all fields were previously written as plaintext to .swamp/.data/
• This change automatically detects fields marked with { sensitive: true } in Zod schema metadata and stores their values in the configured vault, replacing the persisted value with a CEL-compatible vault reference expression
• Zero impact on existing users — purely additive, no existing behavior changes

What users can now do

Mark individual output fields as sensitive in resource output specs:

resources: {
  result: {
    schema: z.object({
      keyId: z.string(),
      keyMaterial: z.string().meta({ sensitive: true }),
    }),
    lifetime: "infinite",
    garbageCollection: 10,
  },
}

Mark an entire resource spec's output as sensitive:

resources: {
  result: {
    schema: z.object({ ... }),
    sensitiveOutput: true,
    vaultName: "my-vault",  // Optional
    ...
  },
}

Persisted files will contain vault references instead of plaintext:

${{ vault.get('vault-name', 'modelType/modelId/methodName/fieldPath') }}

Plan vs implementation

Area	Plan	Implementation
Where sensitiveOutput lives	ResourceOutputSpec (didn't exist at plan time)	ResourceOutputSpec (now exists — per-spec, cleaner than per-method)
Where processing happens	Modify createResourceWriter()	Inside createResourceWriter() before JSON.stringify(data) — transparent to methods
VaultService factory	fromConfig() (sync, reads .swamp.yaml)	fromRepository() (already exists on main, async, reads .swamp/vault/)
Mutation safety	Not addressed in plan	structuredClone() snapshot before mutation prevents cross-contamination
Nested field handling	Not addressed	Handled via setNestedValue() without creating spurious literal dot-keys

The divergences were driven by the codebase evolving significantly since the plan was written (DataWriter/DataHandle architecture, ResourceOutputSpec, unified data repository).

Architecture benefits

• Declarative security: Model authors declare sensitivity in the schema via .meta(), not in imperative code. The runtime enforces it inside the DataWriter pipeline.
• Transparent to methods: Methods call context.writeResource() as normal. Sensitive field processing happens inside the writer — no changes needed in method implementations.
• Fail-hard on misconfiguration: If sensitive fields exist but no vault is configured, the operation fails with a clear error rather than silently writing plaintext.
• Vault resolution hierarchy: Field vaultName > spec vaultName > first available vault.
• CEL-compatible references: Single-quoted string arguments prevent the CEL parser from interpreting slashes in auto-generated keys as division.
• Snapshot-before-mutation: Deep clone prevents one field's vault ref from leaking into another field's stored value.

Files changed

New:

• src/domain/models/sensitive_field_extractor.ts — Zod schema walker for { sensitive: true } metadata
• src/domain/models/sensitive_field_extractor_test.ts — 16 unit tests
• integration/sensitive_field_vault_test.ts — 3 integration tests

Modified:

• src/domain/models/model.ts — sensitiveOutput/vaultName on ResourceOutputSpec, vaultService on MethodContext
• src/domain/models/data_writer.ts — processSensitiveResourceData() + injection into createResourceWriter()
• src/domain/models/data_writer_test.ts — 13 sensitive field unit tests
• src/domain/models/method_execution_service.ts — pass vaultService/methodName to createResourceWriter()
• src/cli/commands/model_method_run.ts — create VaultService, pass to context
• src/domain/workflows/execution_service.ts — same vault wiring
• design/vaults.md — updated "Sensitive Field Marking" section to reflect implementation

Test plan

• 16 unit tests for sensitive field extraction (schema walking, nested objects, metadata orderings)
• 13 unit tests for sensitive resource data processing (vault references, storage, CEL format, nested paths, snapshots, sensitiveOutput)
• 3 integration tests (end-to-end sensitive field → vault → reference flow)
• deno check passes
• deno lint passes
• deno fmt passes
• deno run test — 1909 tests, 0 failures

🤖 Generated with Claude Code

[github-actions]

Code Review: feat: auto-store sensitive output fields in vault before persistence

Summary

This PR implements automatic sensitive field detection and vault storage for resource outputs. The implementation is solid, well-tested, and follows the project's DDD principles.

No Blocking Issues ✅

The code passes all review criteria:

Code Quality & TypeScript Strict Mode:

• All new code uses proper TypeScript types with no any usage
• Named exports used consistently throughout
• AGPLv3 headers present in all new files

Domain-Driven Design Compliance:

• processSensitiveResourceData() is appropriately a domain service function - it orchestrates operations across the vault service and data transformation
• extractSensitiveFields() is a pure function that extracts metadata from Zod schemas - follows value object extraction patterns
• SensitiveFieldInfo is a proper value object (immutable, identified by value)
• Extensions to ResourceOutputSpec (sensitiveOutput, vaultName) are appropriate - spec types are value objects that declare intent
• The changes maintain separation between domain logic and infrastructure concerns

Test Coverage:

• 16 unit tests for sensitive_field_extractor.ts covering schema walking, nested objects, optional/nullable wrappers, metadata orderings
• 13 unit tests for processSensitiveResourceData() covering vault references, CEL format, nested paths, snapshots, error cases
• 3 integration tests for end-to-end flow
• Total: 29 new tests with 0 failures (1909 total tests passing)

Security:

• ✅ Uses structuredClone() to snapshot values before mutation (prevents cross-contamination)
• ✅ Fails hard when no vault is configured (no silent plaintext storage)
• ✅ Single-quoted strings in CEL expressions prevent parser issues with slashes in auto-generated keys
• ✅ Vault resolution hierarchy is clear: field metadata > spec-level > first available vault

Architecture Benefits:

• Declarative security model (mark in schema, runtime enforces)
• Transparent to method implementations (no changes needed in methods)
• Proper error handling with actionable messages

Suggestions (non-blocking)

1. Unused interface property (src/domain/models/sensitive_field_extractor.ts:39):
   The vault?: boolean property in SensitiveMetadata interface is declared but never used. The updated design/vaults.md documentation correctly omits this property. Consider removing it to align the code with the documentation:

   interface SensitiveMetadata {
     sensitive?: boolean;
     // vault?: boolean;  // Remove - not used in implementation
     vaultName?: string;
     vaultKey?: string;
   }

Files Reviewed

• src/domain/models/sensitive_field_extractor.ts (new)
• src/domain/models/sensitive_field_extractor_test.ts (new)
• src/domain/models/data_writer.ts (modified)
• src/domain/models/data_writer_test.ts (modified)
• src/domain/models/model.ts (modified)
• src/domain/models/method_execution_service.ts (modified)
• src/cli/commands/model_method_run.ts (modified)
• src/domain/workflows/execution_service.ts (modified)
• integration/sensitive_field_vault_test.ts (new)
• design/vaults.md (modified)

LGTM 👍

[github-actions]

Review Summary

This PR implements automatic vault storage for sensitive output fields - a well-designed security feature that prevents plaintext secrets from being persisted to disk.

Blocking Issues

None found.

Code Quality Assessment

TypeScript strict mode compliance: ✅

• All new code uses proper types with no any types
• The ZodDef interface in sensitive_field_extractor.ts:46-51 properly defines internal Zod structure types

Named exports: ✅

• All functions and interfaces use named exports (e.g., export function extractSensitiveFields, export interface SensitiveFieldInfo)

License headers: ✅

• All new .ts files include the AGPLv3 copyright header

Test coverage: ✅

• 16 unit tests for sensitive field extraction (sensitive_field_extractor_test.ts)
• 13 unit tests for sensitive data processing (data_writer_test.ts)
• 3 integration tests for end-to-end flow (integration/sensitive_field_vault_test.ts)
• Good edge case coverage: nested objects, null/undefined values, custom vaultName/vaultKey, sensitiveOutput flag

DDD Compliance

• SensitiveFieldInfo is a proper Value Object (immutable, equality by value)
• extractSensitiveFields, getNestedValue, setNestedValue are pure functions for schema walking
• processSensitiveResourceData is a Domain Service (stateless, coordinates VaultService and data transformation)
• No anemic domain models or leaking persistence concerns

Security Review

• Path traversal prevention: sanitizeVaultKey() properly removes @, /, \, .., and null bytes from vault keys
• Data integrity: Uses structuredClone() to snapshot data before mutation, preventing cross-contamination between fields
• Fail-hard security: Throws clear error when sensitive fields exist but no vault is configured - no silent plaintext fallback
• CEL-compatible references: Uses single-quoted strings in vault expressions to prevent parser issues

Architecture Notes

Good separation of concerns:

• Schema introspection isolated in sensitive_field_extractor.ts
• Processing logic in processSensitiveResourceData() within data_writer.ts
• Transparent to method implementations - no changes needed in existing methods

Suggestions (non-blocking)

1. Consider adding a test case for deeply nested objects combined with sensitiveOutput: true to verify both schema-marked and spec-level sensitive fields interact correctly at depth > 2.

2. The vault key format modelType/modelId/methodName/fieldPath is well-documented in the design doc, which is helpful for debugging.

LGTM! Well-structured implementation with comprehensive testing and proper security considerations.