Document .audit() — README section, JSDoc, and a skill

[coderdan]

.audit() is supported, tested public API with almost no documentation. It appears nowhere in packages/stack/README.md, and its only JSDoc is four lines on the abstract base class — a place a consumer is unlikely to ever look.

What it actually does

.audit({ metadata }) stores auditMetadata on the operation (base-operation.ts:20), which is passed to the FFI as unverifiedContext — a current field on EncryptOptions, EncryptBulkOptions, DecryptOptions, and DecryptBulkOptions in protect-ffi 0.30. It attaches arbitrary metadata to the ZeroKMS audit log.

It is not legacy: dedicated coverage in audit.test.ts, decrypt-audit-forwarding.test.ts, and matrix-audit.test-d.ts, and mapped-decrypt.ts:46-50 deliberately makes .audit() and .withLockContext() compose in either order.

The whole of the current documentation

/**
 * Attach audit metadata to this operation. Can be chained.
 * @param config Configuration for ZeroKMS audit logging
 * @param config.metadata Arbitrary JSON object for appending metadata to the audit log
 */
audit(config: AuditConfig): this

That is base-operation.ts:15-19. Nothing on the public client methods in encryption/index.ts — no @example, no cross-reference. A consumer reading encrypt's JSDoc has no way to discover the feature exists.

What the JSDoc does not say, and should:

• The metadata becomes unverifiedContext at the FFI boundary.
• "Unverified" is load-bearing. The metadata is recorded, not cryptographically bound — unlike a lock context, which is verified and changes key derivation. The two are adjacent chainables doing very different things, and the current docs distinguish them nowhere.
• What lands in the audit log, and how it is retrieved.
• Whether there are size or shape limits on the metadata object.
• That plaintext must never be put in it (the repo's own rule that plaintext is never logged applies here most sharply — this is a field that is transmitted and stored).

Work

1. JSDoc — expand base-operation.ts, and reference .audit() from the public client methods with a worked example.
2. README — an "Audit logging" section in packages/stack/README.md: what it is, what it is for (compliance/forensics), a worked example, and the unverified-vs-lock-context distinction.
3. A skill — so agents wiring up an integration know the capability exists and know not to put sensitive values in it. Sits naturally alongside the lock context skill (Add a lock context skill #795) and the auth skill (Add a stash-auth skill covering credentials, auth strategies, and lock context #794); worth deciding whether audit is its own skill or a section of one of those.

Note

Entry parity: .audit() is native-only — the wasm-inline entry does not carry it (wasm-inline.ts:665). Whatever gets documented should say so, and it is worth deciding whether that gap should close too, the same question #793 raises for lock context.