use-agentcred-safely

Use AgentCred Safely

Keep credential values inside the local broker while using the smallest controller-approved authority needed for the task. Treat the current Node implementation as an experimental agentcred/0.1 wire-compatible preview, not as a strong same-user sandbox.

Preserve the boundary

• Never ask anyone to paste or send a credential through chat, a prompt, an issue, source code, a config value, a command argument, or model-visible state.
• Never inspect, print, log, summarize, transform, or test a credential value. Do not invoke a vault, Keychain read, environment dump, reveal API, or generic command runner to obtain it.
• Let the controller provision credential references and start the broker from a human-controlled environment. If provisioning is missing, name the required reference or service and stop at that boundary. For an explicitly authorized handoff or rotation, switch to the separate manage-agentcred-lifecycle workflow; never improvise lifecycle actions through the agent wire.
• Keep the AgentCredClient and GrantHandle in trusted host code. Do not expose either as a model tool. The public handle omits the capability string, but the authority still exists in client memory and on the local wire.
• Recognize rights as inherent. A capability is only scoped permission to act; requesting it does not grant it, and this skill grants no authority. The controller, consent surface, owner policy, and broker decide.

Follow the scoped workflow

1. When changing AgentCred code or policy, locate and read the owning @agenttool/credential-broker package's README.md and SPEC.md. If those files are unavailable, stop before implementation; this skill does not replace the protocol documentation.
2. Describe the intended effect, especially mutation, payment, private-network, or external-message consequences. Confirm that the task authorizes that effect separately from access to the broker.
3. Derive the narrowest grant: one opaque credential reference, exact HTTPS origin, minimum methods, segment-aware path prefixes, no query names or authority-sensitive headers by default, short TTL, low use count, and bounded request and response sizes. Keep allowPaymentSignature and allowPrivateNetwork false unless the controller explicitly approves that exact need. A path prefix also permits its descendant paths; if the task requires one exact path, disclose that widening and stop unless the controller approves it. Derive byte bounds from the serialized request and an upstream response contract. If either bound or a defensible TTL is unknown, request the missing non-secret input instead of guessing.
4. Connect with AgentCredClient, call requestGrant, and accept either approval or denial. Do not weaken policy or widen scope merely to make a denial pass.
5. Pass client.asTransport(grant) to a structurally compatible SDK, or use client.asFetch(grant) for the approved request. Set a stable idempotency key for state-changing operations and never automatically retry an ambiguous mutation. Treat maxUses: 1 as at most one broker dispatch attempt, never as proof of exactly one upstream effect.
6. Revoke the grant as soon as the bounded work finishes, then close the client. Revocation, close, or abort prevents later dispatch where possible; none of them undo an operation already sent upstream.
7. Report only task-required response data and safe metadata such as receipt or audit identifiers. Never report capabilities, credential material, raw vault output, or secret-bearing diagnostics.