---
title: "§8 Binding"
description: "Normative rules for credential binding: one mode per pack, hubs, families, fail-closed mint, explicit mock, connect, and health."
canonical: https://harnesscontextprotocol.io/docs/specification/binding
---

# §8 Binding

> Normative rules for credential binding: one mode per pack, hubs, families, fail-closed mint, explicit mock, connect, and health.

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

## 8.1 Declaration

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

## 8.2 Modes

| 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"`) |

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

## 8.3 Hubs and families

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

## 8.4 Mint

1. For modes other than `public`, a runtime MUST obtain the credential from its
   hub at exec time for the Principal, pack, and family.
2. 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.
3. 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.
4. 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.

## 8.5 Connect

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

## 8.6 Health

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

## 8.7 Binding and Principal

1. Binding identity and Principal MUST be recorded separately in audit (§9.6).
2. A runtime MUST NOT infer one from the other.

## 8.8 Prohibitions

- Secrets in `surface.json`, `policy.json`, or `HARNESS.md`.
- Two modes on one pack.
- Silent env-token fallback.
- Env-flag mocks.
- Operator Binding reachable from an end-user Principal without elevation.

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)