Design 02: signing commits and tags with your own key, the way Git does it

Read with design__00__index-and-reconciliation.md: where the two disagree (shared foundations F1–F9, the in-progress rules), the index wins.

Roadmap item: 2.2 in roadmap__git-parity.md (priority 1). Status: design, not built. Written against c57aea9+ on claude/charming-babbage-5hzcxq. Size: about 4 days with tests (section 10). Gate: none. Section 5.9 proves why; two items must still be confirmed before release (5.9.4, D7).

1. Summary and the exact Git behaviour matched

Git does not decide who is allowed to write. It signs with the key the user already has, stores the signature in the commit, and leaves trust to whoever verifies. sgit does the same, as an optional second signature next to the per-clone ECDSA signature it already makes.

1.1 Signing

1.2 Verifying

What stays as it is:

• The clone key. Every commit keeps its per-clone ECDSA signature (signature, author_key_id). signatures-required keeps meaning "every commit carries a valid clone signature".
• TM-R01. It is unchanged at vault level. It is closed for any verifier who keeps an allowed-signers file, in exactly the way Git closes it (6.1).

2. Scope and non-goals

2.1 In scope

• Commits and annotated tags (vault tag create) carry an optional user signature.
• SSH (all key types OpenSSH signs with, 5.4.3) and OpenPGP via gpg.
• Settings are read from the user's Git config (global and system), and can be overridden per command.
• Verification surfaces:
• history log --show-signature
• history show --show-signature
• check verify, extended with a user-signature summary, --require-user-signature and --json
• vault tag show
• the --json output of those commands
• An in-process verifier for SSH signatures. No ssh-keygen is needed to verify; it is needed only to sign with agent or hardware keys.
• A per-clone verification cache.

2.2 Non-goals

Each one is listed with where it belongs instead.

3. CLI surface

3.1 Flags

Git's spelling everywhere it exists.

3.2 Configuration

Configuration is read from Git's config files (5.6). There is nothing to set in sgit.

3.3 How the attached key form is parsed

CLI__Main.run gets a pre-parse step, CLI__Argv__Signing.normalise(argv):

• -S<KEY> becomes --gpg-sign-key <KEY> -S
• --gpg-sign=<KEY> becomes --gpg-sign-key <KEY> --gpg-sign
• bare -S / --gpg-sign are left as flags (store_true)

--gpg-sign-key is a hidden option, so -S msg keeps meaning "sign, message msg". The step applies only to argv tokens in the commands listed in 3.1, and only when they come before --.

3.4 Output

Signing. A signed commit adds one line to the existing commit output:

Signed with ssh key SHA256:uK0E…Qx8 (user.signingKey ~/.ssh/id_ed25519.pub)

A signing failure exits 1 and writes nothing:

error: signing failed: ssh-keygen: agent refused operation
       nothing was committed. Run again without signing: sgit commit --no-gpg-sign

history log --show-signature. The line goes under each commit, worded as Git words it:

  commit obj-cas-imm-3f9a…
  Good "git" signature for alice@example.com with ED25519 key SHA256:uK0E…Qx8
  Clone signature: verified (key-rnd-imm-0011223344556677)
  Date:      …

The other outcomes:

check verify. One new summary line, printed only when at least one commit carries a user signature:

Checked 412 commit(s): 412 verified, 0 bad, 0 unsigned, 0 without a known key, 0 missing
User signatures: 37 good, 2 untrusted, 0 bad, 0 expired key, 0 revoked, 0 cannot check, 373 none

vault tag show v1.0:

  Signature: signature verified
  Signed by: alice@example.com (ssh, good)

3.5 Exit codes

3.6 JSON shapes

The same object appears in history log --json, history show --json, check verify --json (per commit with --verbose) and vault tag show --json. All values are strings:

"user_signature": {
  "status":          "good",
  "code":            "G",
  "format":          "ssh",
  "principal":       "alice@example.com",
  "key_type":        "ED25519",
  "key_fingerprint": "SHA256:uK0E…Qx8",
  "signed_at_ms":    "1761600000000",
  "reason":          ""
}

status is one of good, untrusted, bad, expired-signature, expired-key, revoked, cannot-check, none.

check verify --json adds:

{
  "total": 412,
  "counts": { "verified": 412, "bad": 0, "unsigned": 0, "no-key": 0, "missing": 0 },
  "user_counts": { "good": 37, "untrusted": 2, "bad": 0, "expired-signature": 0, "expired-key": 0,
                   "revoked": 0, "cannot-check": 0, "none": 373 },
  "user_by_status": { "untrusted": ["obj-cas-imm-…", "…"], "bad": [] },
  "first_failure": null
}

4. How the code works today

4.1 Commit schema and the signing input

4.2 Signature checks today

4.3 Tags

4.4 Where commits are made

4.5 The cross-client rule

tests/_fixtures/interop_vectors.json, key commit_signing, states the JCS rule and gives a stored commit with its signing bytes and signature. The web UI follows that rule. The rule text changes in 5.10.

4.6 Existing subprocess pattern

sgit_ai/core/serve/Container__Command_Runner.py:10-31: argv lists only, capture_output, text=True, timeouts mapped to code 124, a missing binary to 127, and # nosec B603 comments for Bandit. Signing needs bytes on stdin/stdout, so it gets its own runner (5.5) following the same pattern.

5. Design

5.1 The signed bytes

There is one definition, used by both signatures (clone and user), for commits and for tags:

SIGNATURE_MEMBERS = ('signature', 'user_signature')            # class attribute on Vault__Commit and Vault__Sync__Tag

signing_bytes(d) = UTF-8( JCS( { k: v for k, v in d.items() if k not in SIGNATURE_MEMBERS } ) )
                 = json.dumps(body, sort_keys=True, separators=(',', ':'), ensure_ascii=False).encode('utf-8')

• d is commit.json() (or tag.json()) of the current schema, which includes author_signature: null and attestations: [] exactly as today. Removing user_signature makes these bytes identical to what every existing client computes. Existing clients never see the member, because their schema drops it (4.1).
• Legacy form (author_key_id null): legacy_signing_bytes(d) must also drop user_signature before setting signature: None. Otherwise a new client would add "user_signature": null to the bytes and fail every pre-0.19 commit. This is the one easy-to-miss change.
• Both signatures cover the same bytes. The user signature therefore covers:
• tree_id and parents (the content and the history);
• timestamp_ms;
• message_enc (the ciphertext, which AES-GCM authenticates, so it fixes the plaintext);
• branch_id and author_key_id (it binds the clone key that co-signed).

It does not cover the clone signature, and the clone signature does not cover it. Either can be checked alone, and stripping one leaves the other valid. That is what Git does with gpgsig and the commit.

• For SSH, the user signature is an SSHSIG over these bytes with namespace git (D1) and hash sha512 (ssh-keygen's default). For OpenPGP, it is a binary detached signature over these bytes.

5.2 New types and schemas

All new files follow the existing Safe type layout. Validation is strict_validation = True unless noted.

How the field is written. Vault__Commit.create_commit stores data = commit.json(); if data.get('user_signature') is None: del data['user_signature'], and the same for tags. So an unsigned commit is byte-identical to today's format. Nothing grows and no new null member appears for the web UI to meet.

5.3 Classes

There is a new package, sgit_ai/crypto/signing/. It has an __init__.py (source only; tests have none, per rule 8). Everything is a Type_Safe class, with no module-level functions and no @staticmethod.

5.3.1 Signing

5.3.2 Verifying

5.3.3 Vault-level

5.4 SSH: exact formats and the in-process verifier

5.4.1 SSHSIG layout (OpenSSH PROTOCOL.sshsig)

Blob (what we store, base64 in blob):

byte[6]  MAGIC_PREAMBLE  "SSHSIG"
uint32   SIG_VERSION     0x00000001
string   publickey       (wire-encoded public key; for certificates, the certificate)
string   namespace       "git"
string   reserved        ""   (verifiers ignore its content)
string   hash_algorithm  "sha512" | "sha256"
string   signature       (an SSH signature: string algorithm, then the algorithm's blob)

Signed data (what the key actually signs):

byte[6]  MAGIC_PREAMBLE  "SSHSIG"
string   namespace
string   reserved
string   hash_algorithm
string   H(message)       SHA-512 or SHA-256 of signing_bytes (5.1)

Armor (only for display and for ssh-keygen): -----BEGIN SSH SIGNATURE-----, base64 wrapped at 70 columns, -----END SSH SIGNATURE-----.

Parser rules (every one of these has a test):

• the whole blob ≤ 6144 bytes after base64 decoding;
• every string length ≤ the remaining bytes;
• no trailing bytes;
• magic exact;
• version == 1;
• namespace == the configured namespace (git, D1);
• hash in {sha256, sha512};
• the signature algorithm must agree with the key type: ssh-ed25519 ↔ ssh-ed25519; ecdsa-sha2-nistpN ↔ the same; RSA keys only with rsa-sha2-256 / rsa-sha2-512 (ssh-rsa / SHA-1 is rejected, as ssh-keygen does); sk types ↔ the same.

5.4.2 Fingerprints and display

• The fingerprint is SHA256: + base64 (no padding) of SHA-256 over the wire public-key blob, exactly as ssh-keygen -l prints it.
• The key type name for display follows ssh-keygen: ED25519, ECDSA, RSA, ED25519-SK, ECDSA-SK.

5.4.3 Key types verifiable in-process with cryptography 49.0 (installed)

sk flags: user-presence bit 0x01 is required unless the matching allowed-signers line has no-touch-required. Verify-required (0x04) is required when the line has verify-required. These are the same rules ssh-keygen applies.

5.4.4 The allowed-signers file

Format from ssh-keygen(1), ALLOWED SIGNERS section: one entry per line, principals [options] keytype base64-key [comment]. # starts a comment and blank lines are ignored.

• Principals: comma-separated patterns. * and ? are wildcards, and a leading ! negates (match_pattern_list semantics). A principal matches if it matches at least one positive pattern and no negated one.
• Options handled in-process:
• namespaces="git,file": the configured namespace must be in the list;
• valid-after="YYYYMMDD[HHMM[SS]][Z]", valid-before="…": local time unless Z; compared with the commit's timestamp_ms (5.4.6);
• no-touch-required, verify-required.
• Option that forces delegation: cert-authority (5.4.5).
• principals_for(key, ns, t) returns, in file order, every line whose key equals the signature's public key and whose namespace and validity allow it. When there is more than one, the first principal is shown and the rest are listed in --json.

The three outcomes, as Git produces them:

How Git's exact behaviour on valid-before is reported is not fully pinned down here. ssh-keygen -Y verify fails, and Git then falls back to check-novalidate. The xver run (9.5) records what Git 2.43 prints, and the label is aligned to it before release.

5.4.5 Delegation to ssh-keygen

SSH__Sig__Verifier__Keygen is used only when one of these holds:

1. the signature's public key is a certificate;
2. the allowed-signers file has a cert-authority line;
3. the revocation file is a binary KRL (magic SSHKRL\n\0).

It reproduces Git's calls exactly:

ssh-keygen -Y find-principals -f <allowed> -s <sigfile> [-Overify-time=<YYYYMMDDHHMMSS>]
ssh-keygen -Y verify -n git -f <allowed> -I <principal> -s <sigfile> [-r <revocation>] [-Overify-time=…]   (payload on stdin)
ssh-keygen -Y check-novalidate -n git -s <sigfile>                                                         (payload on stdin)

• <sigfile> is the armored signature written to .sg_vault/local/tmp/sig-<random>.sig (0600) and removed in a finally. The payload is ciphertext-derived JSON, but it still goes on stdin, not to disk.
• Without ssh-keygen, the result is cannot-check, never good.

5.4.6 Time

Commit time is timestamp_ms, chosen by the committer (as Git's committer date is). valid-after/valid-before are checked against it, exactly as Git passes -Overify-time=<committer date>. 6.5 covers what that does and does not prove.

5.5 Running ssh-keygen and gpg

Signing__Command_Runner.run(argv, stdin, timeout, env):

• Process: subprocess.run(argv_list, input=stdin_bytes, capture_output=True, timeout=…, env=env, cwd=<a safe dir>, close_fds=True). Never shell=True. argv is built from config values as separate list items; nothing is joined into a string.
• Program: resolved with shutil.which (config value first, then the default name). A config value that is a path is used as is. Not found → code=127.
• cwd: the user's home directory, never the vault working copy. Neither program reads per-directory config, but this removes any chance that a file in the vault is picked up.
• Environment:
• inherited: SSH_AUTH_SOCK (agent), GNUPGHOME, GPG_TTY, DISPLAY/WAYLAND_DISPLAY and SSH_ASKPASS (pinentry and askpass), HOME, PATH;
• added: LC_ALL=C, so messages are stable for the error text; the gpg status lines do not depend on locale anyway.
• Timeouts:
• signing 120 s (a passphrase prompt or a hardware-key touch can take a while);
• verifying with gpg 30 s;
• git config 10 s;
• gpg.ssh.defaultKeyCommand 10 s.

A timeout is a failure with its own message.

• stdin is the payload, so passphrase prompts go to /dev/tty (ssh-keygen) or to pinentry (gpg), exactly as with Git. With no TTY and no agent, signing fails, and the command fails closed (3.5).
• Signing argv:

| Case | argv | |---|---| | SSH, key is a private-key path | [ssh_program, '-Y', 'sign', '-n', 'git', '-f', <path>], stdout = armored SSHSIG | | SSH, key is a .pub path | same; ssh-keygen finds the private half in the agent | | SSH, literal key (key::ssh-… or ssh-…) | write the literal to .sg_vault/local/tmp/signing-<random>.pub (0600) and pass -f <that> -U. -U exists from OpenSSH 8.9; on an older ssh-keygen the call fails and the error names the version | | SSH, no key but gpg.ssh.defaultKeyCommand set | run it (shlex.split, never a shell; Git runs it through a shell, a documented difference), take the first line of output starting ssh- or key::, then as the literal case | | GPG | [gpg_program, '--status-fd=2', '-bsu', <key>], stdout = binary signature. Success requires [GNUPG:] SIG_CREATED in stderr's status lines and exit 0 |

• Output checks:
• SSH: dearmor, then SSH__Sig__Blob.parse, and the signer verifies its own output in-process before returning (this catches a misconfigured program).
• GPG: the output must start with an OpenPGP signature packet tag (0x88/0x89/0xC2), with length within the 8 KB cap.

5.6 Configuration resolution

5.6.1 Order (first set wins per key)

1. Command flags: -S / --gpg-sign[=KEY] / --no-gpg-sign; for tags -s / -u KEY / --no-sign. A key given here also turns signing on (Git: -S<key>).
2. The user's Git config, global then system (5.6.2): sgit.gpgSign for the on/off switch; user.signingKey, gpg.* for how.
3. Defaults: signing off; format openpgp (Git's default) unless user.signingKey looks like an SSH key (a literal ssh- or key::, or a path ending .pub or to an OpenSSH private key). Git requires gpg.format = ssh for that; inferring it is a convenience, not a contradiction, because Git would fail on that key with openpgp. Flag D3b.

Repository-level Git config (.git/config of a repository the vault happens to sit in) is not read (D3). Vault content is never read for signing settings: no file in the working copy or the vault can change how or whether sgit signs (6.4).

5.6.2 Reading Git's config

Git__Config__Reader._read_with_git() runs these when git is on PATH:

git config --global --includes --null --list
git config --system --includes --null --list

Both run in the home directory, with Git's own environment honoured (GIT_CONFIG_GLOBAL, GIT_CONFIG_SYSTEM, GIT_CONFIG_NOSYSTEM, XDG_CONFIG_HOME). The output is NUL-separated key\nvalue records. Global overrides system, and within a file the last value wins.

When git is not installed, _read_files() falls back to a small INI reader:

• Files: $GIT_CONFIG_GLOBAL, else $XDG_CONFIG_HOME/git/config then ~/.gitconfig.
• Supported: sections, subsections, key = value, quoting, \ escapes, booleans (true/yes/on/1).
• Not supported: include/includeIf (a warning names them).

The result is cached for the process, and sgit doctor gains a "Signing" block showing each value and its source.

5.7 OpenPGP specifics

5.7.1 Verify call (Git's)

gpg --keyid-format=long --status-fd=1 --verify <sigfile> -

The payload goes on stdin. <sigfile> is the binary signature in .sg_vault/local/tmp/ (0600, removed in finally).

5.7.2 Status parsing (GPG__Status_Parser, as Git's gpg-interface.c)

Only lines starting exactly with [GNUPG:] on the status fd are read. gpg escapes newlines in user ids, so a user id cannot inject a status line. Nothing else is read.

5.7.3 gpg.minTrustLevel

undefined | never | marginal | fully | ultimate. A good signature below it becomes untrusted. Unset, Git treats marginal and above as G and lower as U; same here.

5.8 File-by-file changes

Core changes:

Commit sites:

Other new classes:

CLI:

5.9 Compatibility: why no gate is needed

5.9.1 Clients from before this change

• They read a signed commit without error. from_json ignores the unknown member (tested on the current osbot-utils; 9.5 runs released builds).
• Their clone-signature check still passes. They compute signing_bytes(commit.json()) from their schema, which has no user_signature. The new client computes the same bytes because it removes user_signature (5.1). The bytes are equal, so verification succeeds.
• They never write the member back. Commits and tags are immutable content-addressed objects, and no client re-serialises an existing one. The only rewriters (pack convert, migrate, move sentinels) make new commits; old clients would simply not carry the member, and new ones deliberately do not (7.6).
• Their signatures-required checks see no change, because that policy is about the clone signature.

5.9.2 New clients reading old commits

user_signature is absent, so the status is none. signing_bytes and legacy_signing_bytes are unchanged for these commits, because removing an absent or null member changes nothing. The legacy path needs the explicit removal in 5.1, and a test pins it.

5.9.3 Unsigned commits

They are byte-identical to today's (the member is not written when None).

5.9.4 Two things to confirm before release

1. The web UI. If the web UI computes the clone signing bytes from the raw stored JSON rather than from its own schema, it will now include user_signature and report a bad signature on user-signed commits. Its rule must become "remove signature and user_signature". The interop vector (5.10) makes that testable for them. Until they confirm, a user-signed commit may show as bad in the web UI. Unsigned commits are unaffected. (D7)
2. The oldest sgit still in use. The xver run (9.5) must show that released builds (0.19.0, 0.21.0, 0.24.0, 0.26.0) ignore the unknown member.

• Fallback if any of them rejects it: sign only in vaults whose min_client is at or above the oldest build that tolerates it, and say so by name.
• Why this is not a gate: it is a refusal to sign, not a format change.

5.10 Interop vectors to add (tests/_fixtures/interop_vectors.json)

New key commit_user_signing:

• rule: "signing bytes for BOTH signatures = JCS of the stored commit JSON with signature AND user_signature removed; user_signature = {format, blob}, blob = base64 of the binary SSHSIG (namespace git, hash sha512) or binary OpenPGP signature".
• A fixed ed25519 OpenSSH test key: private key in OpenSSH format, unencrypted, test-only, plus the public line.
• stored_commit_json: with both signature (the existing P-256 test key) and user_signature (ed25519 SSHSIG; ed25519 is deterministic, so the blob is reproducible).
• signing_bytes_utf8: the expected bytes.
• sshsig_signed_data_hex: the SSHSIG signed-data structure for those bytes.
• armored: the same signature armored, for ssh-keygen -Y verify outside sgit.
• allowed_signers_line: test@example.com namespaces="git" ssh-ed25519 AAAA….

Changed: the existing commit_signing.rule text gains "and user_signature". Its bytes are unchanged, because that commit has no user signature.

OpenPGP: no vector, because the signature is not deterministic. Covered by real-gpg tests (9.4).

6. Security and threat model

6.1 What TM-R01 becomes

TM-R01 is the attack where any read-key holder with store write access mints a clone key and authors commits that check verify calls verified. After this change:

• For a verifier with an allowed-signers file (or a GPG keyring with trust): a commit is attributable to a principal only if it carries a good user signature. The forger cannot produce one without that principal's private key. Its commits show none or untrusted, and check verify --require-user-signature fails on them. That is exactly Git's guarantee.
• At vault level, nothing changes: the vault does not require user signatures, and two verifiers with different files can disagree. That is by design (Git parity). Vault-level enforcement belongs to SGitHub.
• Threat model text: TM-R01's row gains "closed per verifier for commits carrying a user signature (design 02); vault-level enforcement: SGitHub".

6.2 Key material never enters the vault

• sgit never reads a private key, with one exception: SSH__Signer__In_Process reads an unencrypted OpenSSH key file that user.signingKey explicitly names, when ssh-keygen is absent (D4). It reads it in memory, never copies it, never logs it, and never caches it.
• Signing otherwise happens inside ssh-keygen or gpg, which talk to their agents.
• What the vault stores is the signature, whose SSHSIG form includes the public key, plus nothing else.
• Suggested follow-up (small, separate): extend the existing secret guard to refuse committing OpenSSH or OpenPGP private key files. Detect -----BEGIN OPENSSH PRIVATE KEY----- and -----BEGIN PGP PRIVATE KEY BLOCK-----, with the existing --allow-secret-file override (D11).

6.3 What vault readers and the host learn

6.4 Subprocesses (TM-R45)

• Which programs run: they come from the user's global or system Git config, as with Git. Vault content can never name a program:
• nothing is read from the working copy;
• repository-level Git config is not read (D3);
• vault content cannot plant .git/* anyway (TM-F03).
• How they run:
• argv lists, no shell;
• cwd is home;
• stdin carries the payload;
• timeouts are bounded;
• output is bounded by the cap;
• temporary files are 0600 under .sg_vault/local/tmp/ and removed in finally.
• gpg.ssh.defaultKeyCommand: Git runs it through a shell; sgit splits it with shlex instead, so shell syntax in it is not interpreted. This is a documented difference.
• Residual: someone who controls the user's Git config already controls what Git runs. Accepted, the same as Git.

6.5 Principals and time

6.6 New threat-model rows

7. Interactions

8. Performance

The cache (User__Signature__Cache, .sg_vault/local/user-signature-cache.json, 0600):

• Key: the commit or tag object id. It is a content address over the ciphertext that contains the signature, so it fixes both payload and signature.
• Value: the Schema__User_Signature__Result plus a trust_digest. For SSH, the digest is SHA-256 over the allowed-signers bytes, the revocation-file bytes, the namespace and the verifier version. For GPG, it is SHA-256 over the size and mtime of pubring.kbx/pubring.gpg and trustdb.gpg in GNUPGHOME, plus gpg.minTrustLevel.
• Invalidation: an entry is used only when its digest equals the current one. Editing the allowed-signers file or the keyring invalidates everything at once.
• Scope: check verify and history log --show-signature use the cache; signing does not.
• Size: bounded at 200,000 entries. Oldest first out; the file is rewritten atomically.

9. Test plan

All tests use real objects: real cryptography keys, real gpg where present, real git for config. No mocks. No __init__.py under tests/.

9.1 Unit: formats (tests/unit/crypto/signing/)

9.2 Unit: schema, bytes and compatibility (tests/unit/storage/, tests/unit/schemas/)

9.3 SSH without ssh-keygen in this container

• Signing: SSH__Signer__In_Process signs with real keys generated by cryptography. Ed25519 is deterministic, so it is checked byte for byte against the vector.
• Cross-check with OpenSSH: the interop vector's armored signature is produced once with real ssh-keygen on a machine that has it, and committed. The in-process verifier must accept it, and the in-process signer must reproduce it exactly (ed25519). This proves byte-compatibility without ssh-keygen at test time.
• Integration (tests/integration/test_User_Signing__SSH_Keygen.py, class Test_User_Signing__SSH_Keygen): real ssh-keygen sign and verify, -Y verify of an sgit signature outside sgit, delegation for a cert-authority line with a real CA and certificate, a KRL. Skipped when shutil.which('ssh-keygen') is empty. That is a missing-binary skip, not a mock. The CI integration job installs openssh-client so it runs there.

9.4 GPG (installed here)

tests/unit/crypto/signing/test_GPG__Signer_Verifier.py, class Test_GPG__Signer_Verifier:

• Setup: a temporary GNUPGHOME (0700), with a key made by gpg --batch --pinentry-mode loopback --passphrase '' --quick-gen-key 'Test <t@example.com>' ed25519 sign never (about 1 s, once per worker).
• Cases:
• sign, then verify → untrusted (trust undefined);
• --quick-set-ownertrust / --import-ownertrust ultimate → good;
• gpg.minTrustLevel=ultimate with marginal trust → untrusted;
• payload altered → bad;
• the key removed from the keyring → cannot-check;
• an expired key (--quick-set-expire to the past) → expired-key;
• a revoked key → revoked.
• Skipped when gpg is absent.

9.5 Cross-version (xver)

• Harness: the existing one in the scratchpad (server.py in the 3.12 venv, xver.py driving pip-installed releases). It is promoted to tests/qa/xver/ as a manual job.
• Steps:

1. A new build creates a user-signed commit and tag.
2. Released sgit-ai 0.19.0, 0.21.0, 0.24.0 and 0.26.0 each clone, pull, run check verify, history log and vault tag show, and make a commit on top.

• Expected: no error; clone signatures verified; the new build sees the old builds' commits as none.
• Also recorded: Git 2.43's output for a valid-before case, to align 5.4.4's label.

9.6 End to end on the in-memory API (tests/unit/sync/test_User_Signing__End_To_End.py)

Class Test_User_Signing__End_To_End, two clones over Vault__API__In_Memory:

• Signing and verifying:
• A signs a commit (in-process SSH via sgit.gpgSign in a temp GIT_CONFIG_GLOBAL) and pushes; B pulls, and check verify shows good with B's allowed-signers file;
• without B's file → untrusted;
• --require-user-signature exits 1 on a mixed history.
• Commit sites:
• a merge commit signed when -S is passed to pull;
• a failing signer (user.signingKey pointing at a missing file) makes commit exit 1 with the working copy, ref, store and merge state unchanged;
• write -S signs;
• history revert --as-commit -S signs.
• Tags: tag create -s → vault tag show "Signed by".
• Rewrites: pack import of a user-signed vault reports the dropped count.
• Display: history log --show-signature --json carries the object; principal control characters are stripped.

9.7 Security (tests/security/)

9.8 Acceptance checklist (implementation and deployment)

Format

• [ ] user_signature is never written when None; unsigned commits are byte-identical to before (test).
• [ ] signing_bytes and legacy_signing_bytes both drop user_signature (test pins the legacy case).

Compatibility

• [ ] Old-schema fixture: parses, drops and verifies (test).
• [ ] xver: 0.19.0 / 0.21.0 / 0.24.0 / 0.26.0 read, verify and commit on top of a user-signed history (manual run recorded in the release note).
• [ ] Web UI team confirmed their signing-bytes rule excludes user_signature, or the release note states the known display issue (D7).

Signing

• [ ] sgit.gpgSign defaults off; commit.gpgSign=true alone changes nothing (test).
• [ ] Signing failure exits 1 and leaves working copy, refs, store, merge state and index untouched (test).

Verifying

• [ ] In-process SSH verify accepts the OpenSSH-produced vector and rejects every malformed case in 9.1.
• [ ] GPG statuses map as 5.7.2 with real gpg (test).
• [ ] check verify exit codes per 3.5 (tests); --json shape per 3.6.
• [ ] Cache invalidates on any change to the allowed-signers file or keyring (test).

Security and release

• [ ] Security tests 9.7 pass; TM rows R44–R47 added and R01 edited.
• [ ] Bandit baseline unchanged except the # nosec B603 lines in Signing__Command_Runner, each with a reason.
• [ ] sgit doctor shows the signing block with sources.
• [ ] CHANGELOG entry; README "Signing with your own key" section; cli.sgit.ai docs page.
• [ ] pytest tests/unit -n auto and pytest tests/security green; integration green with openssh-client installed in CI.

10. Implementation steps (ordered commits)

Total about 4 days. Each commit leaves pytest tests/unit -n auto and pytest tests/security green.

11. Open decisions for Dinis

This page as markdown · its source, admin/content/research/git-parity-design-signing.md