§8 Binding

Binding is how a command obtains credentials without the pack holding any.

8.1 Declaration#

A pack MAY declare binding in the manifest (§3.3). A pack that executes against any protected resource MUST declare a mode.
A pack MUST declare at most one mode.
A pack MUST NOT contain credential material. Runtimes SHOULD reject a pack whose files contain material that matches common credential patterns.

Mode	Meaning	Connect
`public`	No credential	MUST be skipped; Principal still attributed
`user`	Delegated credential for the Principal	Required
`local`	Machine-local credential store	Required
`mothership`	Operator or fleet identity	Required; elevation grant for non-operator Principals
`mock`	Explicit test credential	MUST be requested in the envelope (`args.mode = "mock"`)

A control-plane pack MUST use mothership (§2.5).
A runtime MUST NOT execute a mothership Binding for a Principal that lacks an explicit operator or elevation grant.
A runtime MUST NOT select a mode based on the Invoker type or on environment contents.

hub names the kind of component expected to mint: keyring, local-credential, public, none. Its implementation is a runtime concern.
Packs sharing a family SHOULD share one consent per Principal. Connecting one pack in a family MAY connect the family.
When several packs in a family are linked, the runtime SHOULD union their delegated scopes.
Family MUST be expressed as a manifest field, not as a directory structure.

For modes other than public, a runtime MUST obtain the credential from its hub at exec time for the Principal, pack, and family.
If mint fails, the runtime MUST refuse the command. It MUST NOT fall back to an environment variable, a file the pack shipped, or any ambient source.
A runtime MUST ignore environment flags that request mock behaviour. Mock is explicit in the envelope only, and a runtime MAY refuse mock outside sandbox.
Minted material MUST be handed to the Adapter through a channel the wrapped tool already understands (environment, file) and MUST NOT be written to Skills, logs, or results.

Establishing or refreshing Binding is a command with operation: write.
It MUST be gated by capability pack.connect (§9.4), not by verb.exec.write.
Connect MUST NOT be required for public packs.
The reference lifecycle command is hcp connect <pack_id>; packs MAY also expose a domain connect or setup.* command that performs the same step.

Health commands (doctor, status) MAY report Binding state and MUST NOT mint long-lived credentials.
Binding degradation SHOULD be announced as the trigger binding.degraded (§7.7) with a state from linked, stale, needs_reauth, pending, error.
Recovery is a human or elevated connect. The Sense path never re-mints automatically.