Skip to content

Git

Verify commits and discover identity layouts.

CommitResult dataclass 

CommitResult(commit_sha: str, is_valid: bool, signer: str | None = None, error: str | None = None, error_code: str | None = None)

Result of verifying a single commit's SSH signature.

commit_sha instance-attribute 

commit_sha: str

Git commit SHA that was verified.

is_valid instance-attribute 

is_valid: bool

Whether the commit's signature is valid.

signer class-attribute instance-attribute 

signer: str | None = None

Hex-encoded public key of the signer, if identified.

error class-attribute instance-attribute 

error: str | None = None

Human-readable error message on failure.

error_code class-attribute instance-attribute 

error_code: str | None = None

Machine-readable error code (see ErrorCode).

VerifyResult dataclass 

VerifyResult(commits: list[CommitResult], passed: bool, mode: str, summary: str)

Wrapper around commit verification results.

commits instance-attribute 

commits: list[CommitResult]

Per-commit verification results.

passed instance-attribute 

passed: bool

Overall pass/fail for the batch.

mode instance-attribute 

mode: str

Verification mode: "enforce" or "warn".

summary instance-attribute 

summary: str

Human-readable summary (e.g. "3/3 commits verified").

LayoutInfo dataclass 

LayoutInfo(bundle: str | None = None, refs: list[str] | None = None, source: str = '')

Resolved location of Auths identity data in a repository.

bundle class-attribute instance-attribute 

bundle: str | None = None

Path to identity-bundle JSON file, if found.

refs class-attribute instance-attribute 

refs: list[str] | None = None

Git ref names under refs/auths/, if found.

source class-attribute instance-attribute 

source: str = ''

How the layout was discovered: "file" or "git-refs".

LayoutError 

LayoutError(code: str, message: str)

Bases: Exception

Raised when Auths identity data cannot be found in the repo.

ErrorCode

Stable error codes for commit verification failures.

generate_allowed_signers 

generate_allowed_signers(repo_path: str = '~/.auths') -> str

Generate an allowed_signers file content from live Auths storage.

Reads device attestations from the Git-backed identity store and formats them for gpg.ssh.allowedSignersFile. Revoked attestations and devices with undecodable keys are silently skipped.

Parameters:

  • repo_path (str, default: '~/.auths' ) –

    Path to the Auths identity repository.

Returns:

  • str –

    Formatted allowed_signers file content, or an empty string if no

  • str –

    attestations are found. Write this to a file or pass to

  • str –

    verify_commit_range.

Examples:

content = generate_allowed_signers()
Path(".auths/allowed_signers").write_text(content)

discover_layout 

discover_layout(repo_root: str = '.') -> LayoutInfo

Try to find Auths identity data in the repo.

Checks .auths/identity-bundle.json then refs/auths/*. Raises :class:LayoutError if missing.

verify_commit_range 

verify_commit_range(commit_range: str, identity_bundle: str | None = None, allowed_signers: str = '.auths/allowed_signers', mode: str = 'enforce') -> VerifyResult

Verify SSH signatures for every commit in commit_range.

Parameters:

  • commit_range (str) –

    A git revision range (e.g. origin/main..HEAD).

  • identity_bundle (str | None, default: None ) –

    Path to an Auths identity-bundle JSON file.

  • allowed_signers (str, default: '.auths/allowed_signers' ) –

    Path to an ssh-keygen allowed_signers file.

  • mode (str, default: 'enforce' ) –

    "enforce" or "warn".

Returns:

  • VerifyResult –

    VerifyResult with per-commit results and a pass/fail decision.

verify_commits 

verify_commits(shas: list[str], identity_bundle: str | None = None, allowed_signers: str = '.auths/allowed_signers', mode: str = 'enforce') -> VerifyResult

Verify SSH signatures for an explicit list of commit SHAs.

Parameters:

  • shas (list[str]) –

    List of commit SHA strings.

  • identity_bundle (str | None, default: None ) –

    Path to an Auths identity-bundle JSON file.

  • allowed_signers (str, default: '.auths/allowed_signers' ) –

    Path to an ssh-keygen allowed_signers file.

  • mode (str, default: 'enforce' ) –

    "enforce" or "warn".

Returns:

  • VerifyResult –

    VerifyResult with per-commit results and a pass/fail decision.