Skip to content

feat:added vaults support to workflows#129

Open
vinaysingh8866 wants to merge 1 commit intodecentralized-identity:mainfrom
VeriDID:feat/workflow-vaults-update
Open

feat:added vaults support to workflows#129
vinaysingh8866 wants to merge 1 commit intodecentralized-identity:mainfrom
VeriDID:feat/workflow-vaults-update

Conversation

@vinaysingh8866
Copy link
Copy Markdown
Contributor

Summary

Adds Vaults 1.0 composition to the Workflow protocol and corresponding workflow-binding conventions to the Vaults protocol. Together, these changes let agents protect sensitive context fields (secrets, PII) via vault-backed $ref pointers instead of sending plaintext over the wire.

Changes

Workflow 1.0

  • Sensitivity classification: Templates can now declare a sensitivity map that classifies context fields as secret, pii, or plain, with storage mode vault, encrypted (reserved), or plain.
  • Vault-backed $ref pointers: Fields with storage: "vault" are stored in a Vaults 1.0 EDV and represented as $ref objects (vault_id + doc_id + digest) in workflow messages — literal values never travel over the wire.
  • vault_ref on instances: Workflow instances track their bound vault identity and lifecycle state (active, sealed, retired).
  • Transient fields ($transient): advance messages can declare ephemeral input fields that are used for a single cycle (e.g., OTP codes) and wiped immediately after.
  • Display hints for sensitivity: Templates can specify masking behavior per sensitivity level (masked, masked_toggle, visible) with format tokens.
  • Guard/action resolution: Processors resolve $ref pointers on demand, verify digests, and hold plaintext only in memory. Digest mismatch = tampering, vault unreachable = vault_unavailable error.
  • Lifecycle binding: Workflow complete triggers vault seal; cancel triggers vault tombstone.
  • New error codes: vault_unavailable, vault_ref_invalid, sensitivity_violation.
  • Updated conformance requirements: 5 new Processor requirements (13-17) and 3 new Coordinator recommendations covering vault provisioning, sensitivity enforcement, and transient field safety.
  • Vault-aware flow: New section (7) documenting the end-to-end vault-integrated workflow.
  • Multiplicity restriction: Multiplicity-key expressions must not reference secret-level fields.
  • History scrubbing: Resolved plaintext must never appear in history entries, logs, or persistent storage outside the vault.
  • Future work: Per-field ZCAP, inline JWE mode, cross-workflow vault sharing.

Vaults 1.0

  • Workflow binding convention: propose.purpose field format workflow:<template_id>#<instance_id> for correlating vaults with workflow instances.
  • Workflow-scoped vault guidance: TTL synchronization, seal on complete, tombstone on cancel, key material wiping.
  • Transient data rule: Workflow $transient fields must never be stored in vaults.
  • Guard resolution timing: Decrypted plaintext for guard evaluation must be held only in memory, never cached or persisted.
  • Field indexing privacy: Guidance on avoiding metadata leakage when indexing workflow context fields in EDV encrypted indexes.
  • Role-grouped documents: Recommendation to group sensitive fields by role-access pattern to reduce observable query patterns.
  • Composition section: New Workflow 1.0 composition notes covering sensitivity maps, vault provisioning, lifecycle binding, and capability advertisement.
  • Changelog: Added v1.0-draft+wf entry.

Design Decisions

  • $ref pointers over inline JWE: Chose vault-backed references over inline encryption because it centralizes key management, enables role-scoped access, and keeps message size constant regardless of secret size.
  • Role-grouped EDV documents: Grouping fields by role-access (rather than one doc per field) reduces the number of EDV queries visible to the vault host, minimizing metadata leakage.
  • Digest verification mandatory: Every $ref resolution verifies a content digest to detect tampering at the vault layer.
  • Graceful degradation: Agents without vault support see plaintext context fields — no vault integration is required unless the template declares a sensitivity map.

Signed-off-by: Vinay Singh <vinay@verid.id>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant