#190 swamp vault: vendor-specific annotations (e.g. 1Password notesPlain, tags, custom fields)

Problem

The swamp vault CLI exposes only key/value semantics: put, get, list-keys. Inside an extension model, this means there's no way to attach contextual metadata to a stored secret — for example, the rotation history line Rotated <ISO timestamp> that the bash predecessor of an SSH-key rotation extension writes via op item edit … notesPlain=….

When the underlying vault provider is 1Password, items have a rich field model: notesPlain, tags, custom [concealed]/[text] fields. The same goes for AWS Secrets Manager (Description, Tags) and probably other providers we'd want to support. None of that is reachable through swamp vault.

Use case (real)

Working on a swamp extension model for SSH-key rotation on Harvester nodes (PLT-487 in hivemq/hivemq-terraform-harvester). The bash script that this model replaces appends a rotation timestamp to the 1Password item's notesPlain field on every rotate, giving operators a vault-side audit trail. To stay vault-agnostic and use only swamp vault put + swamp vault list-keys, we had to drop that audit trail entirely — operators now rely on stdout logs.

Proposed solution

A vault-provider-aware annotation API. Two API shapes worth considering:

A. Generic annotate subcommand

swamp vault annotate <vault> <key> <annotation-name> <value>

<annotation-name> is provider-defined. For @swamp/1password: notesPlain, tags, or any custom field name. For @swamp/aws-sm: Description or Tags. The built-in vault could no-op or store annotations in a sidecar.

B. --metadata key=value flag on swamp vault put

echo \"\$SECRET\" | swamp vault put my-vault MY_KEY --metadata notesPlain=\"Rotated 2026-04-30T12:00:00Z\"

Same provider-defined keys, but co-located with the put.

Either way: in-model TS access via the swamp model context (e.g. a vault helper that lets a method write annotations alongside the secret).

Alternatives considered

• Drop the audit trail entirely (current workaround) — what we did for now. Loses vault-side visibility.
• Shell out to op item edit directly from inside the model — bypasses swamp's vault abstraction, couples model to 1P, breaks if anyone migrates the vault to a different backend.
• Sibling vault key per metadata field (e.g. MY_KEY_ROTATION_LOG) — works for read-modify-write of multi-line text, but pollutes the keyspace and swamp vault list-keys output, and there's no way to atomically update both the value and the metadata.

Context

• swamp `20260429.224106.0-sha.e4033bbc`
• @swamp/1password 2026.04.22.2
• Discovered while writing bootstrap and rotate methods for @hivemq/host-kernel-ssh (hivemq/hivemq-terraform-harvester#212).