vault-unseal
Prepare a scoped, time-bounded vault-unseal request for approval and adapter execution; never returns a secret or claims a handle was issued.
- License 许可
- MIT
- 所属仓库
- ZachDreamZ/runx
- 最近更新
- 2026-07-17
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- vault-unseal
- runx
- { "category": "security" }
- description
- Prepare a scoped, time-bounded vault-unseal request for approval and adapter execution; never returns a secret or claims a handle was issued.
02 资源文件 3
- 参考文档fixtures/unseal-missing-inputs.yaml759 B
- 参考文档fixtures/unseal-plan-approved.yaml1.0 KB
- 参考文档X.yaml1.4 KB
03 SKILL.md 正文
Vault Unseal
Turn a request for a secret into a reviewable, time-bounded access plan that hands an approval-ready request to a vault adapter instead of exposing the secret.
What this skill does
An agent rarely needs a secret. It needs the thing the secret unlocks: one API call, one signed request, one decrypt for a stated window. This skill plans that access. It binds the secret reference, the purpose, a TTL, the scope the secret covers, and the principal asking, then marks the request for a human approval gate. The output is an unseal plan; it does not contain a handle or an audit receipt because this agent runner cannot issue either. A configured vault adapter performs the live unseal after approval and owns its handle and audit evidence. The secret value is never read into the plan, the receipt, or the agent's context.
It governs explicit secret access with a TTL and approval; least-privilege only analyzes scopes, it never touches secrets.
When to use this skill
- An agent or workflow needs a credential, key, or token to complete one bounded task and the access must be approved and audited.
- A break-glass or just-in-time access request needs a plan a reviewer can read and a window that expires on its own.
- A downstream action skill needs an approval-ready request that a vault adapter can exchange for a handle without putting the secret in agent context.
- An operator wants the planning decision (
ready_for_approval,needs_agent,denied) separated from adapter-owned execution evidence.
When not to use this skill
- To read, print, copy, or return a secret value or handle. This skill prepares the request; the vault adapter owns live access.
- To grant standing or unbounded access. Every unseal is scoped to one secret for one TTL.
- To review or narrow scopes that a subject already holds. Use least-privilege for scope analysis against receipts.
- To rotate, store, or mint new secrets. That is a separate vault operation with its own gate.
- To bypass the approval gate, widen the scope past the stated purpose, or extend a TTL that has already lapsed.
Procedure
- Resolve the request. Confirm
secret_ref,purpose,ttl,scope, andprincipalare present. If any required input is missing, stop withneeds_agentand name what is missing. Do not guess a default TTL or scope. - Check purpose and scope against policy. Confirm the stated purpose is a
permitted reason to access this secret, and that the scope does not exceed
what the purpose needs. If the purpose or scope is not permitted, set
decision: deniedand name the policy that refused, not the secret. - Set the TTL window. Parse
ttlinto a duration; the window starts at approval, not at request. If the TTL is unparseable, absent, or unbounded, returnneeds_agent. There is no open-ended unseal. - Set the approval gate. A live unseal always requires human approval; set
gates.human_approval_required: true. A complete, permitted request isready_for_approval, never evidence that approval or execution occurred. - Bind the request. Bind the plan to exactly one
secret_reffor one TTL window under the requested scope. Setdecision: ready_for_approvalonly when the request is complete and policy-compatible. - Hand off execution. After separate approval evidence is attached, a vault adapter may consume the plan, issue an opaque handle, and return adapter-owned audit evidence. This skill never fabricates either outcome.
Edge cases and stop conditions
- Missing required input:
secret_ref,purpose,ttl, orscopeabsent returnsneeds_agent. The principal is also required to attribute the access. - Purpose not permitted: set
decision: denied; name the refusing policy, never the secret. - Scope exceeds purpose: narrow to what the purpose needs, or set
decision: deniedif it cannot be narrowed safely. - Unbounded or lapsed TTL: refuse. There is no standing unseal and no revival of an expired window.
- Approval absent or denied: the request remains
ready_for_approvalor moves todenied; this skill never issues a handle. - Caller asks for the raw value: refuse that part. If the workflow genuinely
cannot use an adapter-owned handle, return
needs_agentwith the constraint named, never the value. - Vault adapter unavailable: return an execution blocker; a plan is not an unseal.
Output schema
The artifact is the unseal_plan object, wrapped as runx.unseal.v1. The
secret value never appears in any field.
unseal_plan:
decision: ready_for_approval | needs_agent | denied
secret_ref: string # reference to the secret, never its value
purpose: string # bounded reason the secret is needed
ttl: string # bound duration; the window starts at approval
scope: # what the secret unlocks, as stated and as bound
resource: string
action: string
path: string
principal: string # who the access is attributed to
gates:
human_approval_required: boolean # always true for a live unseal
blockers: array # named reasons the plan is not ready
execution:
requires_adapter: true
requires_approval: true
Worked example
Input: principal svc/report-exporter requests vault://drive/service-account
for the purpose "sign one Drive export request", ttl: 10m, scope
{ resource: drive.files, action: export, path: /reports/* }.
Output: decision: ready_for_approval; policy permits the purpose and the scope
matches it; gates.human_approval_required: true; and
execution.requires_adapter: true. After explicit approval, the vault adapter
may issue an opaque handle and records its own audit evidence. The service
account key never enters the plan or the receipt.
Inputs
secret_ref(required): reference to the secret to unseal, never its value.purpose(required): the bounded reason the secret is needed.ttl(required): the access window duration; the window starts at approval.scope(required): structured statement of what the secret unlocks.principal(required): who the access is attributed to.policy_notes(optional): reserved purposes, break-glass conditions, or constraints that affect the decision.operator_context(optional): approval posture or extra guardrails.
04 同仓库更多 Skills
zapier-handoff
Validate a runx execution context and hand off a governed payload to a Zapier Catch Hook with scoped auth, idempotency, and receipt expectations.
x402-pay
Execute a governed x402 payment by delegating to the canonical spend flow with the x402 runtime path selected.
work-plan
Decompose a build objective into governed runx execution steps.
web-fetch
Fetch and extract one web source within an explicit allowlist, returning the content by digest with full provenance.
weather-forecast
Normalize provider weather evidence into an action-safe forecast packet with provenance, uncertainty, and stop conditions for downstream agents.
vuln-triage
Triage dependency or ecosystem vulnerability risk into remediation and advisory packets, grounding on verified CVE evidence when it is supplied.