Reference snapshot · source revision 7a2e36f2b250934a095e542ae20e62dcfb0d5f70

SPEC-CONFIG-SECURITY — repo-vs-user config trust split

Status: Normative. Companion to docs/THREAT-MODEL.md §4 and docs/specs/SPEC-KEYSTORE.md §8.2. Audience: anyone adding a new config key, anyone reviewing a change that touches libkit/src/config.rs, and anyone writing a transport that consumes a config-derived endpoint, key path, or credential.

This spec defines the per-key trust posture for every config knob kit reads, and the enforcement contract that keeps a hostile cloned repo from escalating into the user's signing identity, ambient network credentials, or arbitrary process execution. It exists because the underlying constant — REPO_FORBIDDEN_KEYS — is easy to forget to extend when new keys are added; this document gives the review test "is the new key on this list?" a single canonical answer.

1. Threat

The attacker is a hostile remote repo author (THREAT-MODEL §3.1). They control every byte in the cloned tree, including <repo>/.kit/config. They do NOT control $XDG_CONFIG_HOME/kit/config.

Without enforcement, any repo-scoped knob that names a file path, selects a process to spawn, points at a network endpoint that will carry ambient credentials, or selects a private signing key would be attacker-controlled. This is the same confused-deputy shape closed in GHSA-001.

The defense is structural, not per-call: at the config READ site, every key is classified as either repo-safe (SAFE) or user-only (UNSAFE). UNSAFE keys appearing in <repo>/.kit/config are dropped, and the loader reports each drop as an event. The kit command prints the event as a warning on stderr. They are only honored when read from $XDG_CONFIG_HOME/kit/config.

The user config directory is always an absolute path. The library reads no environment variable. The program gives it an environment that holds the XDG config directory, the home directory and the -c overrides. The kit command fills them from XDG_CONFIG_HOME and HOME. The XDG config directory must be absolute when set and non-empty. If it is unset or empty, kit uses <home>/.config, and the home directory must be absolute. Otherwise the command fails with an error. kit never falls back to a relative path, so no working directory can supply user-scoped config or trust roots.

The trust boundary is anchored in libkit/src/config.rs::REPO_FORBIDDEN_KEYS. That constant is the single source of truth — libkit is the only crate that performs config-file I/O, so there is exactly one place to fence.

2. Per-key audit

The table below covers every key that apply_kv in rust/crates/libkit/src/config.rs recognizes — the flat keys (in source order), the dotted-section families (remote.<name>.*, branch.<name>.*) handled via apply_section_kv, and the _url-suffixed slot. Rows marked "not yet implemented" classify keys that a specification defines before apply_kv reads them; the patch that implements such a key adds it to REPO_FORBIDDEN_KEYS per §5, including a matcher for a remote.<name>.* pattern key.

2.1 Borderline cases

• remote_type: borderline because a hostile flip from file to s3 could change the transport's credential-handling surface given a user-trusted endpoint. The defense rests on the endpoint itself being the credential carrier — enforce_trusted_remote_endpoint fences on remote_endpoint, not on remote_type. If a future transport ever decides credential routing from remote_type independent of remote_endpoint, this key MUST be reclassified as UNSAFE and added to REPO_FORBIDDEN_KEYS.
• remote_bucket: currently inert and SAFE. The same caveat as remote_type applies — if a future S3 transport ever signs requests using remote_bucket independent of remote_endpoint, the key must be promoted to UNSAFE.
• default_branch: SAFE because kit verifies signed history regardless of which ref is nominated as default. A hostile clone pointing default_branch = main at attacker-controlled commits does not bypass signature verification.
• transport_auth: UNSAFE. Signing request authorization is a distinct capability from signing repository objects. Cryptographic domain separation does not authorize a repository to invoke the user's ambient signer.

3. Enforcement contract

The fence is implemented at the file-read site, not at the field-consumer site, so every consumer gets the same guarantee without needing to remember to check.

3.1 Read-site rule

In libkit::config::apply_text:

if scope == ConfigScope::Repo && REPO_FORBIDDEN_KEYS.contains(key) {
    report a ConfigEvent to the observer;
    skip the key (continue);
}

The key never reaches apply_kv, so the matching field on Config stays at its default (empty string / Vec::new() / the documented fallback). Higher-priority layers (user-scoped, defaults) are untouched.

3.2 Write-site rule

In libkit::config::write, only an explicit allow-list of repo-safe keys is emitted:

default_branch
durability.objects
remote_endpoint
remote_bucket
remote_type
remote.<name>.url / remote.<name>.type   (per named remote)
branch.<name>.remote / branch.<name>.merge   (per-branch upstream tracking)

Any other field on the in-memory Config is suppressed when serializing <repo>/.kit/config. The kit config <key> <value> command intercepts UNSAFE keys (REPO_FORBIDDEN_KEYS.contains(key)) and writes them to the user-scoped file instead.

3.3 Warning shape

warning: ignoring `<key>` from per-repo config at <path> \
  (security-sensitive keys are user-scoped only — see \
   <user-config-path> and docs/THREAT-MODEL.md)

The kit command prints this text from the event. The exact text is snapshot-tested (crates/kit-bin/tests/snapshots/repo_config_forbidden_keys__repo_config_forbidden_warning.snap). Any wording change requires a reviewable cargo insta snapshot diff.

3.4 Runtime credential and request-signing gates

remote_endpoint is repo-safe to read, but kit push, kit pull, and kit fetch call enforce_trusted_remote_endpoint before attaching ambient credentials. The gate fires when ALL of:

• the merged endpoint is non-empty,
• the repo layer's remote_endpoint equals the merged endpoint (that is, it came from <repo>/.kit/config, not user config),
• the user layer's trusted_remote_endpoint does NOT equal the merged endpoint,
• the relevant ambient credential env var is set (KIT_API_TOKEN for HTTP, KIT_S3_* for S3).

Independently, selecting user-scoped transport_auth = envelope for any HTTP(S) endpoint MUST require exact equality with user-scoped trusted_remote_endpoint, before loading a key or constructing a signer. This applies whether or not a bearer token is present, and to explicit clone URLs as well as configured remotes. Repository and CLI-supplied destination selection cannot confer signing trust on that destination.

When the gate fires, the command exits with a typed error directing the user to kit config trusted_remote_endpoint <endpoint>, which writes to the user-scoped config. The repo-scoped knob can therefore NEVER unilaterally trust a remote — the user's hand is always required.

The admission helper has a gate of its own. The client MUST NOT run a user-scoped admission_helper (SPEC-TRANSPORT-CONNECT §5.1) for a remote unless the remote's endpoint equals the user-scoped trusted_remote_endpoint. It applies a remote's user-scoped remote.<name>.admission_headers only under the same condition. A repository-configured or CLI-supplied remote therefore cannot trigger the helper without the user's exact trust entry. Every header the helper returns passes the allowlist and the hard-reserved set of SPEC-TRANSPORT-CONNECT §5.1 before the client attaches it, and the client never logs the helper's output.

3.5 Parse failures

Config fails closed. The loader returns an error, with the file and the line number, for each of these:

• an unknown key, including every removed or misspelled key;
• a line that has no =;
• a malformed value: a control character in any value, a pull.require_signed value that is not a boolean word, a durability.objects, transport_auth, signer, attest.signer, attest.default_algorithm or ssh.strict_host_key_checking value outside its list, a non-numeric attest.external_signer_timeout_secs, and an invalid remote or branch name;
• a file larger than 1 MiB, or text that is not UTF-8.

An empty value is allowed. It leaves the key unset.

The same rules apply to the user file and to -c overrides. One case is not an error: a forbidden key in the repo file is dropped with the §3.3 warning, and the loader does not parse its value. A typo in a security key such as pull.require_signd is therefore an error. It never turns the check off.

3.6 Absolute key paths

A relative signing_key path must stay under .kit/keys/. An absolute path must lie under the home directory of the environment. That home directory must be absolute and must not be the filesystem root. If it is unset, relative or the root, every absolute key path is refused. A path with a .. component is always refused.

4. Test coverage

The fence is multiply-tested so a regression in any one layer cannot hide:

1. Per-key in-process drop test (libkit::config::tests::repo_*_is_rejected and the meta-test every_forbidden_key_is_actually_dropped_from_repo_scope). The meta-test iterates the entire REPO_FORBIDDEN_KEYS array, plants each key with a sentinel value in a repo-scoped file, and asserts the sentinel never appears in the merged Config. Adding a key to REPO_FORBIDDEN_KEYS without extending the meta-test causes a compile-fail-style panic with an actionable error message.
2. Per-key end-to-end CLI test (crates/kit-bin/tests/repo_config_forbidden_keys.rs). For every UNSAFE key, plants .kit/config, runs kit config <key>, and asserts the value did NOT propagate to stdout and that stderr emitted the named warning.
3. Warning-shape snapshot (tests/snapshots/repo_config_forbidden_keys__repo_config_forbidden_warning.snap). Pins the exact stderr wording so cosmetic drift surfaces as a reviewable diff.
4. Trusted-remote runtime-gate tests (kit_bin::config::tests::repo_*_remote_*requires_user_trust and trusted_http_remote_is_allowed). Cover the enforce_trusted_remote_endpoint semantics for both HTTP and S3, plus the safe-path where the user has trusted the same endpoint.

5. Adding a new config key

When you add a key to Config:

1. Decide whether the key is SAFE or UNSAFE per §2. The default answer is UNSAFE — only reclassify after writing down why on this list.
2. If UNSAFE:
   • Add the key to REPO_FORBIDDEN_KEYS.
   • Add an arm to the meta-test's field-accessor match (the test panics with a descriptive error if you forget).
   • Add a per-key integration test in tests/repo_config_forbidden_keys.rs.
   • Update this spec's §2 table.
   • Update docs/THREAT-MODEL.md §4 if the key changes the user-vs-repo scope landscape.
3. If SAFE:
   • Document the reasoning in §2 (especially for borderline cases where the key names a destination or transport).
   • Add a repo-scoped acceptance test alongside any existing roundtrip_repo_safe_keys-style fixture.
4. If the key carries a credential, file path, or process-spawn primitive, also write a kit config command path that routes the value to user-scoped storage (see write_user_scoped in commands/config_cmd.rs).

6. Non-goals

• This spec does not defend against an attacker who already runs as the user's UID (THREAT-MODEL §3.3). Once code runs as the user, it can edit $XDG_CONFIG_HOME/kit/config directly and the scope split is moot.
• This spec does not protect against a user who manually opts in to a hostile remote by running kit config trusted_remote_endpoint <attacker> after cloning. Local choice is the user's responsibility (THREAT-MODEL §3.1).
• This spec does not cover trust-roots file selection — see THREAT-MODEL §5. The trust-roots path is implicitly user-scoped-only because there is no repo config knob that sets it.

7. References

• rust/crates/libkit/src/config.rs — single source of truth for REPO_FORBIDDEN_KEYS and the enforcement code path.
• rust/crates/kit-bin/src/config.rs — the process binding: it prints the events and applies the runtime credential gate.
• rust/crates/kit-bin/tests/repo_config_forbidden_keys.rs — per-key CLI regression suite.
• docs/THREAT-MODEL.md §4 — wider trust-boundary discussion.
• docs/specs/SPEC-KEYSTORE.md §8.2 — the keystore-side requirement that every keystore selector be repo-forbidden.
• The credential-exfiltration channel that the runtime gate on remote_endpoint closes.

8. Invariants

§3 is the enforcement contract; this table restates what it guarantees and where each guarantee is anchored.

Every new key defaults to UNSAFE until argued SAFE on the §2 table (§5); a SAFE key that later gains credential-routing or process-spawn behavior MUST be promoted to UNSAFE in the same patch that introduces the consumer (§2, §2.1).