PaperClipAI/doc/DYNAMIC-SECRETS.md

Dynamic Secrets Operator Guide

Dynamic secrets are experimental command-backed secrets. They let an operator store a generator definition instead of storing secret material. At runtime, Paperclip runs the generator on the host and injects the generated value into the target environment.

This guide is about safe generator authoring. Paperclip can enforce the runtime contract described here, but it does not certify that a generator is safe or that the token it mints has the right privileges. The operator owns that trust decision.

Runtime Contract

A dynamic secret uses managedMode: "dynamic_command" and provider host_command. It is available only when the enableDynamicSecrets experimental setting is enabled.

The shipped runtime behavior is:

• The generator command is stored on the secret as a single executable path or command string.
• Static positional arguments are stored on each secret binding. Agents cannot provide or alter these arguments at runtime.
• Paperclip invokes the generator with spawn(command, staticArgv, { shell: false }). There is no shell interpolation, and stdin is ignored.
• The generator inherits the Paperclip server process environment.
• stdout is the generated secret value. Paperclip trims surrounding whitespace from stdout before injection.
• stderr is not returned to the agent or board UI. It only affects the failure message by indicating that host logs may contain details.
• Exit code 0 with non-empty stdout succeeds.
• Missing command, non-zero exit, signal termination, timeout, or empty stdout fails closed with no value injected.
• The default timeout is 30 seconds. PAPERCLIP_DYNAMIC_SECRET_COMMAND_TIMEOUT_MS can lower it or set another positive value up to that 30 second ceiling.
• Successful generated values are cached by binding and static argv for the secret's configured TTL. During that TTL, Paperclip injects the cached value instead of re-running the generator.

Dry runs from the board UI use the same command contract, but return only a pass/fail result plus non-sensitive metadata such as byte length. They never return the generated value.

Safety Practices

Treat the generator as privileged host-side code.

• Keep the root credential on the host side, outside Paperclip agent workspaces and outside agent-readable configuration.
• Prefer a dedicated helper binary or script with a narrow interface over a general-purpose shell wrapper.
• Mint the narrowest token possible for the specific binding. Use static argv for operator-controlled selectors such as organization, repository, account, role, or installation id.
• Make the minted token short-lived. Avoid long-lived bearer tokens when the upstream service supports scoped temporary credentials.
• Never print the root secret, refresh token, private key, or credential source. Print only the derived runtime token to stdout.
• Keep stderr non-sensitive. Stderr may be referenced in host logs during debugging.
• Make generators idempotent and side-effect-light. A generator may be retried after a timeout or process failure, and a failed injection should not leave durable external state behind.
• Fail with a non-zero exit when the generated credential would be missing, over-broad, expired, or otherwise unsafe.
• Avoid reading mutable input from the agent workspace. Runtime arguments are already fixed by the operator on the binding.
• Run the board UI dry-run after authoring or changing a generator, then verify the target workflow with the least-privilege binding you expect agents to use.

Trust Posture

Dynamic secrets reduce storage of long-lived secret material in Paperclip, but they do not automatically create a hard isolation boundary.

Under the current local/default posture, dynamic generators are a soft boundary. The generator runs as the same operating-system user as the Paperclip server, similar to the local_encrypted provider posture. A same-UID agent or process with enough local access can potentially observe process state, host files, or runtime values. Use this posture for trusted local operation, not as containment against a hostile same-UID agent.

A hard boundary requires an approved sandbox or environment driver that isolates the generator and injected value from the host and from untrusted agent code. Do not describe a deployment as hard-isolated just because it uses dynamic secrets.

TTL Guidance

TTL controls Paperclip's successful-value cache. It should be no longer than the usable lifetime of the minted token and usually shorter.

Choose a TTL by balancing freshness and upstream rate limits:

• For tokens valid for minutes, use a TTL of seconds to a few minutes.
• For tokens valid for about one hour, a TTL around 5 to 15 minutes is a common starting point.
• Lower the TTL when revocation speed or least privilege matters more than API rate limits.
• Raise the TTL only when the generator is expensive or the upstream service has tight token-minting limits.
• Do not set the TTL equal to or beyond the upstream token expiry. Clock skew, queued runs, and retry timing can otherwise inject a nearly expired token.

Worked Example: GitHub App Installation Token

Goal: let an agent push to one repository without giving it the GitHub App private key.

Host setup:

• Store the GitHub App private key outside the repo and outside agent workspaces, for example under a root- or operator-owned secrets directory.
• Install a small generator at an absolute path such as /usr/local/bin/paperclip-mint-github-installation-token.
• Make the generator accept only operator-fixed static argv such as: ["--installation-id", "123456", "--repository", "owner/repo"].
• The generator authenticates as the GitHub App, requests an installation access token scoped to that repository and only the permissions needed for the task, prints the token to stdout, and exits 0.
• On any API, key, permission, or repository mismatch, the generator prints no token and exits non-zero.

Paperclip setup:

• Create a dynamic secret with command /usr/local/bin/paperclip-mint-github-installation-token.
• Set the binding static argv for the target agent, project, or routine to the installation id and repository it may access.
• Set TTL lower than the GitHub installation token lifetime. For a one-hour GitHub App installation token, start around 600 seconds and adjust for rate limits and run frequency.
• Run the board UI generator test before saving, then run a task that needs only that repository permission.

The agent receives only the installation token selected for that binding. It does not receive the GitHub App private key and cannot choose a different installation or repository unless the operator changes the binding argv.