Skip to content
Registry

secrets

v0.1.4

Local protected secret store. Provider keys and other credentials are encrypted under a master key kept outside the project (secret://NAME) or kept as variables in the project's .env (env://NAME), referenced from versioned configuration and resolved only by the workers each secret allowlists; metadata reads never return a value, and the secrets::changed trigger reports rotations and .env edits.

license: Apache-2.0credentialssecretssecurityvault

Install

bash
iii trigger compose::add worker=secrets@next

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions10

secrets::access

Function

Replace the list of worker names allowed to resolve a secret; [] revokes everyone. With store "env", shares the environment variable NAME (env://NAME), whether or not it is set yet.

Request
  • consumersstring[]required

    The complete new allowlist of worker names; `[]` revokes everyone.

  • namestringrequired
  • storeall of

    `vault` (default; the secret must exist) or `env` (shares the variable, whether or not it is set yet).

    all of (1)
    Variant 1
    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
Response
  • consumersstring[]required

    Worker names allowed to resolve the value. Empty: nobody.

  • created_atstringrequired
  • descriptionstring
  • fingerprintstring

    First 16 hex characters of HMAC-SHA256(master key, value). Changes on rotation. Vault only: an environment value can change outside this worker.

  • hintstringrequired

    Masked value, e.g. `sk-ant…9f2c`; `••••` under 12 characters. Empty for an environment variable that is not set.

  • last_resolved_atstring
  • last_resolved_bystring

    Worker name of the last successful resolver.

  • locationstring

    Env store: where the variable's value is read from now (the `.env` path, or this worker's environment); absent when it is not set.

  • namestringrequired
  • refstringrequired

    `secret://NAME` or `env://NAME`, the string to put in versioned configuration.

  • storeone ofrequired

    Where a secret's value lives.

    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
  • updated_atstringrequired

secrets::delete

Function

Delete a secret and revoke every consumer's access to it. With store "env", stops sharing the variable; its value stays in .env.

Request
  • namestringrequired
  • storeall of

    `vault` (default) or `env`.

    all of (1)
    Variant 1
    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
Response
  • deletedbooleanrequired

secrets::detect

Function

Look for existing values of the given env var names in this worker's environment, the project's .env and the user's login shell. Reports masked hints and whether each equals the stored value; never a value.

Request
  • namesstring[]required

    Env var names to look for (also the secret names they would be stored under).

Response
  • resultsobject[]required
    • namestringrequired
    • sourcesobject[]required
      • hintstringrequired

        Masked value found there.

      • kindstringrequiredenum process_env, dotenv, login_shell
      • locationstringrequired

        The secrets worker's environment, the `.env` path, or the login shell path.

      • matches_storedbooleanrequired

        The value equals the stored one (same fingerprint).

    • storedbooleanrequired
    • stored_hintstring

secrets::get

Function

One secret's metadata (masked hint, fingerprint, consumers, timestamps; for store "env", where the variable is read from), or null. Never the value.

Request
  • namestringrequired
  • storeall of

    `vault` (default) or `env`.

    all of (1)
    Variant 1
    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
Response
any of (2)
Variant 1
  • consumersstring[]required

    Worker names allowed to resolve the value. Empty: nobody.

  • created_atstringrequired
  • descriptionstring
  • fingerprintstring

    First 16 hex characters of HMAC-SHA256(master key, value). Changes on rotation. Vault only: an environment value can change outside this worker.

  • hintstringrequired

    Masked value, e.g. `sk-ant…9f2c`; `••••` under 12 characters. Empty for an environment variable that is not set.

  • last_resolved_atstring
  • last_resolved_bystring

    Worker name of the last successful resolver.

  • locationstring

    Env store: where the variable's value is read from now (the `.env` path, or this worker's environment); absent when it is not set.

  • namestringrequired
  • refstringrequired

    `secret://NAME` or `env://NAME`, the string to put in versioned configuration.

  • storeone ofrequired

    Where a secret's value lives.

    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
  • updated_atstringrequired
Variant 2
valuenull

secrets::import

Function

Store a value found by secrets::detect: the worker re-reads it from the named source itself, so it never passes through the caller. With store "env", a value found in .env or this worker's environment is shared as it is, and one from the login shell is copied into .env.

Request
  • consumersstring[]

    Omit to keep the current list (`[]` for a new secret).

  • descriptionstring

    Omit to keep the current description; an empty string clears it.

  • namestringrequired
  • sourceall ofrequired

    Where the worker re-reads the value; it never travels through the caller.

    all of (1)
    Variant 1
    valuestringenum process_env, dotenv, login_shell
  • storeall of

    `vault` (default) or `env`: copied into the project's `.env` (a `dotenv` source is only shared, it is already there).

    all of (1)
    Variant 1
    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
Response
  • consumersstring[]required

    Worker names allowed to resolve the value. Empty: nobody.

  • created_atstringrequired
  • descriptionstring
  • fingerprintstring

    First 16 hex characters of HMAC-SHA256(master key, value). Changes on rotation. Vault only: an environment value can change outside this worker.

  • hintstringrequired

    Masked value, e.g. `sk-ant…9f2c`; `••••` under 12 characters. Empty for an environment variable that is not set.

  • last_resolved_atstring
  • last_resolved_bystring

    Worker name of the last successful resolver.

  • locationstring

    Env store: where the variable's value is read from now (the `.env` path, or this worker's environment); absent when it is not set.

  • namestringrequired
  • refstringrequired

    `secret://NAME` or `env://NAME`, the string to put in versioned configuration.

  • storeone ofrequired

    Where a secret's value lives.

    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
  • updated_atstringrequired

secrets::list

Function

Every secret's metadata: vault secrets, then shared environment variables (masked hint, consumers, timestamps). Never a value.

Request
Empty object
Response
  • secretsobject[]required
    • consumersstring[]required

      Worker names allowed to resolve the value. Empty: nobody.

    • created_atstringrequired
    • descriptionstring
    • fingerprintstring

      First 16 hex characters of HMAC-SHA256(master key, value). Changes on rotation. Vault only: an environment value can change outside this worker.

    • hintstringrequired

      Masked value, e.g. `sk-ant…9f2c`; `••••` under 12 characters. Empty for an environment variable that is not set.

    • last_resolved_atstring
    • last_resolved_bystring

      Worker name of the last successful resolver.

    • locationstring

      Env store: where the variable's value is read from now (the `.env` path, or this worker's environment); absent when it is not set.

    • namestringrequired
    • refstringrequired

      `secret://NAME` or `env://NAME`, the string to put in versioned configuration.

    • storeone ofrequired

      Where a secret's value lives.

      one of (2)
      Variant 1
      valuestringenum vault
      Variant 2
      valuestringenum env
    • updated_atstringrequired

secrets::on-config-change

Function

Internal: re-read the secrets configuration after an operator change.

Request
  • idstring

    Configuration id that changed.

Response
  • okbooleanrequired

secrets::resolve

Function

Return the value behind secret://NAME (the vault) or env://NAME (the project's .env, else this worker's environment) to a worker listed in its consumers; anyone else gets SECRET_FORBIDDEN. The caller is identified by the engine, not by the request.

Request
  • refstringrequired

    `secret://NAME`, `env://NAME`, or a bare `NAME` (the vault).

Response
  • namestringrequired
  • valuestringrequired

secrets::set

Function

Store a credential under NAME (create, or rotate an existing one) and return its metadata. store "vault" (default) encrypts it, referenced as secret://NAME; store "env" writes NAME=value to the project's .env, referenced as env://NAME. The value is never returned by this or any metadata function. Omitted consumers keep the current allowlist ([] for a new secret).

Request
  • consumersstring[]

    Worker names allowed to resolve. Omit to keep the current list (`[]` for a new secret).

  • descriptionstring

    Omit to keep the current description; an empty string clears it.

  • namestringrequired

    `^[A-Za-z_][A-Za-z0-9_.-]{0,127}$`; provider keys reuse their env var name.

  • storeall of

    `vault` (default) or `env`.

    all of (1)
    Variant 1
    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
  • valuestringrequired

    The credential. Encrypted in the vault, or written as `NAME=value` to the project's `.env`; never returned except by `secrets::resolve`.

Response
  • consumersstring[]required

    Worker names allowed to resolve the value. Empty: nobody.

  • created_atstringrequired
  • descriptionstring
  • fingerprintstring

    First 16 hex characters of HMAC-SHA256(master key, value). Changes on rotation. Vault only: an environment value can change outside this worker.

  • hintstringrequired

    Masked value, e.g. `sk-ant…9f2c`; `••••` under 12 characters. Empty for an environment variable that is not set.

  • last_resolved_atstring
  • last_resolved_bystring

    Worker name of the last successful resolver.

  • locationstring

    Env store: where the variable's value is read from now (the `.env` path, or this worker's environment); absent when it is not set.

  • namestringrequired
  • refstringrequired

    `secret://NAME` or `env://NAME`, the string to put in versioned configuration.

  • storeone ofrequired

    Where a secret's value lives.

    one of (2)
    Variant 1
    valuestringenum vault
    Variant 2
    valuestringenum env
  • updated_atstringrequired

secrets::status

Function

Where the vault lives, where the master key comes from (III_SECRETS_KEY or a key file outside the project), how many secrets are stored, and the .env the env store uses.

Request
Empty object
Response
  • countinteger· uintrequiredmin 0
  • env_countinteger· uintrequiredmin 0

    Environment variables shared with at least one worker.

  • env_filestring

    The `.env` the env store reads and writes, when the worker has one.

  • key_pathstring

    The key file, when `key_source` is `file`.

  • key_sourceall ofrequired

    `env` when III_SECRETS_KEY supplies the master key, else `file`.

    all of (1)
    Variant 1
    valuestringenum env, file
  • vault_pathstringrequired
  • versioninteger· uint32requiredmin 0

    Vault file format version.

Triggers1

secrets::changed

Trigger

Fires after a secret is created, rotated, deleted or its consumers change. Carries name, ref, action, fingerprint and updated_at, never the value. Config: { names? } to narrow to some secrets.

Invocation
  • metadataunknown

    Metadata attached to every invocation this binding receives.

  • namesstring[]

    Secret names to fire for: a bare `NAME` for both stores, or `secret://NAME` / `env://NAME` for one. Omit or leave empty for every secret.

Return
  • actionstringrequiredenum created, rotated, deleted, access_changed
  • fingerprintstring

    The current fingerprint; absent after a deletion and for the env store.

  • namestringrequired
  • refstringrequired

    `secret://NAME` or `env://NAME`.

  • updated_atstringrequired

Search the registry

Find workers, kits and executables, or jump to a page.