Secret tools

Secret metadata and rotation. No tool here returns secret material, and none accepts it — a value typed into a conversation cannot be un-written.

Permission is what the tool server requires before it dispatches; who holds it is read from the control plane’s own grant. The two are read from different places on purpose: a tool server that grants more than the control plane does offers an operation and then has it refused halfway through a conversation.

Advertised says whether the tool appears in the default tool list. Most do not: a small window is advertised and the rest are found with search_tools, read with describe_tool and invoked with request_tool. A tool reached that way is checked against the same permission as a direct call.

Generated from Tool. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

Tool	Permission	Who holds it	Advertised
secret_consumers	vault:read	developer	no
secret_metadata	vault:read	developer	no
secret_resources	vault:read	developer	no
secret_rotation_begin	vault:manage	developer	no
secret_rotation_retire	vault:manage	developer	no
secret_rotation_status	vault:read	developer	no
secret_rotation_switch	vault:manage	developer	no

secret_consumers

List the workloads that reference one secret document. Use this before rotating or removing a credential: a document with consumers is still live, and a CronJob plus its materialised Job count as two consumers.

Argument	Type	Required	Meaning
resource	string	yes	codecheck-db
namespace	one of resources, deployments, jobs, cronjobs	no	Which namespace the document lives in. Omit for ‘resources’ (the current layout); the other three are the legacy layout still in use.

secret_metadata

Show what a Vault-backed secret document contains WITHOUT revealing it: whether it exists, its key names, and its version. No route on this platform returns a secret value to anyone, so this is the only read there is — use it to confirm a write landed or to check which keys a workload will receive.

Argument	Type	Required	Meaning
resource	string	yes	codecheck-db

secret_resources

List every secret document referenced by this tenant’s workloads, each with the deployments, jobs and cronjobs that reference it. Derived on read from the stored specs — key names and paths only, never material.

Takes no arguments.

secret_rotation_begin

Open a rotation window: the platform preserves the current credential, then mints replacement material for the named keys. BOTH credentials are valid afterwards — nothing has switched yet. The new value is minted by the platform and is never shown to anyone. If the datastore needs a matching change (CREATE ROLE, ACL SETUSER), name the tenant’s own Job in apply_job; the platform never authors that step. Follow with secret_rotation_switch, then secret_rotation_retire.

Argument	Type	Required	Meaning
resource	string	yes	codecheck-db
keys	array	yes	password
apply_job	string	no	Name of an EXISTING Job in this tenant that applies the change to the datastore. It must already exist; the platform will not create it.
length	integer	no	CHARACTER AXIS. Characters per replacement value. Omit for the platform default (32). Mutually exclusive with bytes/encoding.
charset	one of alphanumeric, alphanumeric_symbols, hex	no	CHARACTER AXIS. Alphabet to mint from. Default: alphanumeric. Mutually exclusive with bytes/encoding.
bytes	integer	no	BYTE AXIS (#277). How many random BYTES to mint before encoding. Omit for the platform default (32). Use this — not length/charset — when the consuming app DECODES the value and needs an exact byte count: Fernet, NaCl/libsodium, AES-256, WireGuard and JWT HS256 keys are all 32 bytes. Mutually exclusive with length/charset; sending both is rejected.
encoding	one of base64, base64url, hex	no	BYTE AXIS (#277). How those bytes are rendered as text. Default: base64, which is byte-for-byte what openssl rand -base64 <bytes> produces. Use base64url for material carried in URLs or headers. Mutually exclusive with length/charset.

secret_rotation_retire

Close a rotation window by destroying the PREVIOUS credential. This is irreversible: the old material is gone and only the new credential remains valid. The platform refuses it while any consumer is still on the old credential, or if a new consumer appeared during the window. Run your own datastore retire step (DROP ROLE, ACL DELUSER) if the apply Job did not.

Argument	Type	Required	Meaning
resource	string	yes	codecheck-db
confirm	boolean	yes	Must be true to proceed. Retiring destroys the previous credential.

secret_rotation_status

Show the state of a secret’s rotation window: phase (applying, switching, retiring, complete, failed), the keys being rotated, and which consumers have moved onto the new material. Returns key names and paths, never a value.

Argument	Type	Required	Meaning
resource	string	yes	codecheck-db

secret_rotation_switch

Move every consumer of a rotating secret onto the new material by bumping its secretsVersion, which recreates its containers. Both credentials remain valid until retire, so this is recoverable: if some consumers fail, fix them and call it again.

Argument	Type	Required	Meaning
resource	string	yes	codecheck-db