gitbound 1.0.0

A safety-first local GitHub identity manager
Documentation
# Security policy

## Reporting a vulnerability

Report suspected vulnerabilities through GitHub's private advisory form:
**[Report a vulnerability](https://github.com/BitKiln/GitBound/security/advisories/new)**. Please do not open
a public issue for an unfixed security problem.

Include the GitBound version (`gitbound --version`), your operating system,
and the smallest set of steps that reproduces the behaviour. You should get an
acknowledgement within seven days.

## Supported versions

Fixes land on the latest minor release. Older releases are not patched.

| Version | Supported |
| ------- | --------- |
| 1.x     | Yes       |
| < 1.0   | No        |

## Threat model

GitBound is a local tool. It runs as the user who invokes it and holds no
privileges that user does not already have. It is therefore not a boundary
against an attacker who can already run code as that user.

What it does defend:

- **Identity confusion.** A repository must be bound to an explicit profile, and
  a check must fail rather than pass when the effective Git author, GitHub CLI
  account, SSH identity, remote host, or owner policy disagrees with it. A check
  that reports OK when the push would go out under the wrong identity is a
  security bug, and is the class of defect this project cares most about.
- **Fail-closed verification.** Network-dependent checks report `unverified`
  rather than `ok` when they cannot be completed, and the pre-push hook treats
  `unverified` as a failure.
- **Confinement of writes.** Binding writes only to the repository that was
  explicitly selected. Environment variables that would redirect Git elsewhere
  (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_CONFIG_COUNT`, and related) are removed from
  the subprocess environment.
- **Non-destructive edits.** GitBound refuses to replace a hook or a directory
  fragment it did not write, and `unbind` restores the exact repository-local
  values that existed before the first bind.

What it explicitly does not do:

- It never asks for, reads, stores, or transmits GitHub tokens, passwords, or
  private key material. Credentials are delegated to GitHub CLI, Git credential
  helpers, and OpenSSH.
- It does not protect against a compromised `git`, `gh`, or `ssh` on `PATH`.
- It does not defend the user's own configuration against the user: values set
  deliberately in the environment or in Git config are honoured as intent.

## Release verification

Release binaries are published by `.github/workflows/release.yml` and are
currently unsigned, so Windows SmartScreen and macOS Gatekeeper will warn on
first run. Every published asset — desktop bundles and the standalone CLI, on
all three platforms — is accompanied by a `.sha256` file and by a build
provenance attestation generated by `actions/attest-build-provenance`. Verify
the download before running it:

```console
sha256sum --check GitBound_1.0.0_windows_x86_64.exe.sha256
```

```console
(Get-FileHash .\GitBound_1.0.0_windows_x86_64.exe -Algorithm SHA256).Hash
```

Provenance can be checked with the GitHub CLI:

```console
gh attestation verify GitBound_1.0.0_windows_x86_64.exe --repo BitKiln/GitBound
```

Do not run a binary obtained from anywhere other than this repository's Releases
page.