`05bd39a`

repos/sigverify: commit + tag signature verification orchestrator

Authored by mfwolffe <wolffemf@dukes.jmu.edu> yesterday

SHA: 05bd39a044f62f9903d5693936f842011535dd2c
Parents: 5cbaaa0
Tree: 633b893

5 changed files

Status	File	+
A	`internal/repos/sigverify/cache.go`	64
A	`internal/repos/sigverify/commit_object.go`	131
A	`internal/repos/sigverify/lookups.go`	78
A	`internal/repos/sigverify/result.go`	126
A	`internal/repos/sigverify/verify.go`	336

internal/repos/sigverify/cache.goadded

 +// SPDX-License-Identifier: AGPL-3.0-or-later
++
 +package sigverify
++
 +import (
 +	"context"
++
 +	"github.com/jackc/pgx/v5/pgtype"
++
 +	reposdb "github.com/tenseleyFlow/shithub/internal/repos/sqlc"
 +)
++
 +// CacheWriter is the minimal surface WriteResult needs from the
 +// reposdb queries layer. Sub-PR 3 (backfill) and Sub-PR 4 (settings
 +// add handler) both consume WriteResult; this interface lets them
 +// pass any concrete DBTX-bound queries set without taking the full
 +// reposdb.Queries struct as a dependency.
 +type CacheWriter interface {
 +	UpsertCommitVerification(ctx context.Context, db reposdb.DBTX, arg reposdb.UpsertCommitVerificationParams) error
 +}
++
 +// WriteResult persists a verification Result into the cache table.
 +// Wraps the sqlc-generated UpsertCommitVerification so the Result
 +// → params translation lives in one place.
 +//
 +// Concurrency: UpsertCommitVerification's ON CONFLICT clause makes
 +// this safe to call from the orchestrator and the backfill worker
 +// against the same (repo_id, commit_oid) without losing data — the
 +// most-recent invocation wins.
 +func WriteResult(
 +	ctx context.Context,
 +	q CacheWriter,
 +	db reposdb.DBTX,
 +	repoID int64,
 +	commitOID string,
 +	kind Kind,
 +	r Result,
 +) error {
 +	return q.UpsertCommitVerification(ctx, db, reposdb.UpsertCommitVerificationParams{
 +		RepoID:           repoID,
 +		CommitOid:        commitOID,
 +		Reason:           string(r.Reason),
 +		Verified:         r.Verified,
 +		SignerUserID:     nullableInt64(r.SignerUserID),
 +		SignerSubkeyID:   nullableInt64(r.SignerSubkeyID),
 +		Kind:             string(kind),
 +		SignatureArmored: nullableText(r.Signature),
 +		Payload:          r.Payload,
 +	})
 +}
++
 +func nullableInt64(v int64) pgtype.Int8 {
 +	if v == 0 {
 +		return pgtype.Int8{}
 +	}
 +	return pgtype.Int8{Int64: v, Valid: true}
 +}
++
 +func nullableText(s string) pgtype.Text {
 +	if s == "" {
 +		return pgtype.Text{}
 +	}
 +	return pgtype.Text{String: s, Valid: true}
 +}

internal/repos/sigverify/commit_object.goadded

 +// SPDX-License-Identifier: AGPL-3.0-or-later
++
 +package sigverify
++
 +import (
 +	"bytes"
 +	"strings"
 +)
++
 +// splitSignedObject takes the raw bytes of a git commit or annotated
 +// tag object (as returned by `git cat-file -p <oid>`) and splits it
 +// into the signature-payload (the bytes the signature was computed
 +// over) and the armored signature block.
 +//
 +// Git stores the signature as a header line whose value is a multi-
 +// line PGP armor block; the lines after the first are continuation
 +// lines starting with a single space. For example:
 +//
 +//	tree abc123...
 +//	parent def456...
 +//	author Alice <alice@example.com> 1700000000 +0000
 +//	committer Alice <alice@example.com> 1700000000 +0000
 +//	gpgsig -----BEGIN PGP SIGNATURE-----
 +//	 <body>
 +//	 -----END PGP SIGNATURE-----
 +//
 +//	commit message body
 +//
 +// The canonical payload is the same object with the gpgsig header
 +// (and its continuation lines) removed entirely. The signature is
 +// the concatenation of the gpgsig-value first line + the un-indented
 +// continuation lines.
 +//
 +// Returns (payload, armoredSig, true) when a gpgsig header was found,
 +// or (rawBody, "", false) when the object carries no signature.
 +//
 +// Tag objects can store the signature either inline at the end of the
 +// body (the classic format, with `-----BEGIN PGP SIGNATURE-----`
 +// appearing in the message body) OR via a header (the newer SSH-sig
 +// convention). For OpenPGP tags we look at both forms — the legacy
 +// trailing-block form is the dominant one in the wild.
 +func splitSignedObject(body []byte) (payload []byte, armoredSig string, signed bool) {
 +	// Find the end of the header block (the first blank line).
 +	headerEnd := bytes.Index(body, []byte("\n\n"))
 +	if headerEnd < 0 {
 +		return body, "", false
 +	}
 +	header := body[:headerEnd]
 +	rest := body[headerEnd:]
++
 +	// Walk the header lines looking for a gpgsig header. There's
 +	// exactly zero or one per object in practice.
 +	lines := bytes.Split(header, []byte("\n"))
 +	var (
 +		sigBuilder strings.Builder
 +		newHeader  bytes.Buffer
 +		inSig      bool
 +		foundSig   bool
 +	)
 +	for i, line := range lines {
 +		if inSig {
 +			if bytes.HasPrefix(line, []byte(" ")) {
 +				// Continuation line — strip one leading space.
 +				sigBuilder.Write(line[1:])
 +				sigBuilder.WriteByte('\n')
 +				continue
 +			}
 +			// End of signature continuation — fall through to
 +			// header handling for this line.
 +			inSig = false
 +		}
 +		if bytes.HasPrefix(line, []byte("gpgsig ")) {
 +			foundSig = true
 +			inSig = true
 +			sigBuilder.Write(line[len("gpgsig "):])
 +			sigBuilder.WriteByte('\n')
 +			continue
 +		}
 +		// Tag-object signature header is named differently in some
 +		// gitformats but the modern convention also uses 'gpgsig'.
 +		// Treat any other line as a regular header to preserve.
 +		if i > 0 {
 +			newHeader.WriteByte('\n')
 +		}
 +		newHeader.Write(line)
 +	}
++
 +	if !foundSig {
 +		// Check tag-object inline trailing-signature form: the body
 +		// (rest, after the blank line) may end with a PGP signature
 +		// block. This form has no `gpgsig` header.
 +		return splitTagInlineSignature(body)
 +	}
++
 +	payload = append(newHeader.Bytes(), rest...)
 +	return payload, sigBuilder.String(), true
 +}
++
 +// splitTagInlineSignature handles annotated tags that embed the
 +// signature at the end of the message body (the legacy git-tag
 +// signing convention) rather than as a header. The signature block
 +// runs from `-----BEGIN PGP SIGNATURE-----` to `-----END PGP
 +// SIGNATURE-----` inclusive at the tail of the body.
 +//
 +// Returns (payload, armoredSig, true) when an inline block is
 +// detected, or (body, "", false) otherwise.
 +func splitTagInlineSignature(body []byte) (payload []byte, armoredSig string, signed bool) {
 +	const begin = "-----BEGIN PGP SIGNATURE-----"
 +	const end = "-----END PGP SIGNATURE-----"
++
 +	beginIdx := bytes.Index(body, []byte(begin))
 +	if beginIdx < 0 {
 +		return body, "", false
 +	}
 +	endIdx := bytes.Index(body[beginIdx:], []byte(end))
 +	if endIdx < 0 {
 +		return body, "", false
 +	}
 +	endIdx += beginIdx + len(end)
 +	// Include trailing newline if present.
 +	if endIdx < len(body) && body[endIdx] == '\n' {
 +		endIdx++
 +	}
 +	armoredSig = string(body[beginIdx:endIdx])
 +	// Payload is everything before the signature block. git tag -s
 +	// appends the signature directly to the tag body — the signed
 +	// payload IS the body up to (and including the trailing newline
 +	// before) the BEGIN marker. No further trimming.
 +	payload = body[:beginIdx]
 +	return payload, armoredSig, true
 +}

internal/repos/sigverify/lookups.goadded

 +// SPDX-License-Identifier: AGPL-3.0-or-later
++
 +package sigverify
++
 +import (
 +	"context"
 +	"time"
 +)
++
 +// Lookups is the interface the orchestrator uses to resolve
 +// signature artifacts (subkeys, parent gpg keys, user emails) back
 +// to user records. The interface exists so tests can pass in a
 +// fake without touching sqlc; production wires through to
 +// usersdb.Queries.
 +type Lookups interface {
 +	// SubkeyByFingerprint looks up a user_gpg_subkeys row by its
 +	// 40-hex canonical fingerprint. Returns (subkey, true, nil) on
 +	// hit, (_, false, nil) on miss, and (_, _, err) only on DB
 +	// errors (miss is NOT an error — the orchestrator translates
 +	// it into ReasonUnknownKey).
 +	SubkeyByFingerprint(ctx context.Context, fingerprint string) (Subkey, bool, error)
++
 +	// GPGKeyByID resolves a primary gpg-key row by id. Called once
 +	// per Verify invocation after SubkeyByFingerprint returns a hit
 +	// so the orchestrator has access to the primary's armored block
 +	// (needed to construct the openpgp.Entity for cryptographic
 +	// verification).
 +	GPGKeyByID(ctx context.Context, id int64) (GPGKey, bool, error)
++
 +	// UserEmailsByUserID returns every email row for the given user
 +	// (verified or not). The orchestrator uses this for the
 +	// `bad_email` vs `unverified_email` discrimination — gh's
 +	// verification check fails open as bad_email if the signature's
 +	// email isn't claimed by the user at all, and as
 +	// unverified_email if the email is claimed but unverified.
 +	UserEmailsByUserID(ctx context.Context, userID int64) ([]UserEmail, error)
 +}
++
 +// Subkey is the orchestrator-facing shape of a user_gpg_subkeys row.
 +// Decoupled from sqlc.UserGpgSubkey so tests don't have to construct
 +// pgtype.Timestamptz values.
 +type Subkey struct {
 +	ID                int64
 +	GPGKeyID          int64
 +	Fingerprint       string
 +	KeyID             string
 +	CanSign           bool
 +	CanEncryptComms   bool
 +	CanEncryptStorage bool
 +	CanCertify        bool
 +	// ExpiresAt is the subkey's expiration timestamp; the zero Time
 +	// value means "never expires".
 +	ExpiresAt time.Time
 +	// RevokedAt is set if this subkey has been soft-deleted. The
 +	// orchestrator treats revoked subkeys as if they don't exist
 +	// (returns ReasonUnknownKey), so production lookups should
 +	// already filter `revoked_at is null` and this field is mostly
 +	// here for diagnostic completeness.
 +	RevokedAt time.Time
 +}
++
 +// GPGKey is the orchestrator-facing shape of a user_gpg_keys row.
 +type GPGKey struct {
 +	ID          int64
 +	UserID      int64
 +	Fingerprint string
 +	KeyID       string
 +	// Armored is the full ASCII-armored block. The orchestrator
 +	// re-parses this via ProtonMail/go-crypto to access the actual
 +	// public-key material for cryptographic verification.
 +	Armored string
 +}
++
 +// UserEmail is the orchestrator-facing shape of a user_emails row.
 +type UserEmail struct {
 +	Email    string
 +	Verified bool
 +}

internal/repos/sigverify/result.goadded

 +// SPDX-License-Identifier: AGPL-3.0-or-later
++
 +// Package sigverify orchestrates OpenPGP signature verification for
 +// commits and annotated tags. The shape of the Result type mirrors
 +// GitHub's documented `verification` object on the REST commits
 +// response so the API layer can render it directly.
 +//
 +// The package is read-only relative to the git repository — it shells
 +// out to `git cat-file` for object bodies but never modifies the
 +// repo. Cache writes go through the commit_verification_cache table
 +// via the sqlc helpers in WriteResult.
 +package sigverify
++
 +import "time"
++
 +// Reason mirrors GitHub's documented verification.reason enum on the
 +// REST commits response. The full set is:
 +//
 +//   - valid               — signature checks out + signer email
 +//     matches one of the user's verified emails.
 +//   - unsigned            — the commit/tag carries no gpgsig header.
 +//   - unknown_key         — gpgsig present but the signing subkey
 +//     fingerprint isn't registered with shithub.
 +//   - bad_email           — signature checks cryptographically but
 +//     the signer email doesn't match any of the
 +//     registered user's emails at all.
 +//   - unverified_email    — signature checks cryptographically; the
 +//     email matches a user-emails row but the
 +//     row's verified flag is false.
 +//   - malformed_signature — gpgsig header present but the armored
 +//     block doesn't parse.
 +//   - invalid             — signature parses, key matches, but the
 +//     cryptographic check fails.
 +//   - expired_key         — signature is by a subkey that had already
 +//     expired by the commit's signature time.
 +//   - not_signing_key     — signature is by a subkey that exists in
 +//     the registry but doesn't carry the sign
 +//     capability flag.
 +//
 +// Add new strings here only when GitHub adds them; the value is the
 +// JSON wire format and is load-bearing for shithub-cli compatibility.
 +type Reason string
++
 +const (
 +	ReasonValid              Reason = "valid"
 +	ReasonUnsigned           Reason = "unsigned"
 +	ReasonUnknownKey         Reason = "unknown_key"
 +	ReasonBadEmail           Reason = "bad_email"
 +	ReasonUnverifiedEmail    Reason = "unverified_email"
 +	ReasonMalformedSignature Reason = "malformed_signature"
 +	ReasonInvalid            Reason = "invalid"
 +	ReasonExpiredKey         Reason = "expired_key"
 +	ReasonNotSigningKey      Reason = "not_signing_key"
 +)
++
 +// Kind discriminates commit-object verifications from annotated-tag
 +// verifications in the cache table.
 +type Kind string
++
 +const (
 +	KindCommit Kind = "commit"
 +	KindTag    Kind = "tag"
 +)
++
 +// Result is the orchestrator's per-object verification verdict. All
 +// fields except Verified+Reason+VerifiedAt are populated only when
 +// the corresponding information was available — see field comments.
 +//
 +// The shape matches GitHub's verification object on the REST commits
 +// response (api.go marshalls these directly when assembling the
 +// `verification` field). Fields that gh exposes as nullable strings
 +// (`signature`, `payload`) map to empty-string here; the JSON
 +// encoder layer translates "" back to null at the surface.
 +type Result struct {
 +	// Verified is true if and only if Reason == ReasonValid. Stored
 +	// denormalized so consumers don't have to compare against the
 +	// string constant.
 +	Verified bool
++
 +	// Reason carries the gh-documented enum value. Always populated.
 +	Reason Reason
++
 +	// Signature is the armored signature block extracted from the
 +	// gpgsig header. Empty for ReasonUnsigned. Populated for every
 +	// other reason where a signature was actually present in the
 +	// object (even ReasonMalformedSignature — we surface the raw
 +	// armor so the REST consumer can inspect the bad payload).
 +	Signature string
++
 +	// Payload is the canonical commit-object bytes that the signature
 +	// was computed over (the commit object body with the gpgsig
 +	// header lines removed). Empty for ReasonUnsigned and when the
 +	// signature couldn't be parsed.
 +	Payload []byte
++
 +	// SignerUserID is the user-id of the registered GPG key that the
 +	// signature resolved to. Set whenever Reason ∈ {valid, bad_email,
 +	// unverified_email, expired_key, not_signing_key, invalid} — any
 +	// case where the subkey lookup succeeded. Zero when
 +	// Reason ∈ {unsigned, unknown_key, malformed_signature}.
 +	SignerUserID int64
++
 +	// SignerSubkeyID is the user_gpg_subkeys row id of the signing
 +	// subkey. Set under the same conditions as SignerUserID.
 +	SignerSubkeyID int64
++
 +	// SignerEmail is the email extracted from the signature's UID
 +	// embedding (or from the GPG key's primary UID if the signature
 +	// didn't carry one). Used by the popover UI to render
 +	// "Signer: <email>".
 +	SignerEmail string
++
 +	// VerifiedAt is the wall-clock time the verification ran.
 +	VerifiedAt time.Time
 +}
++
 +// unsignedResult is the canonical Result returned when an object has
 +// no gpgsig header. Constructed once per call so callers always see
 +// a fresh VerifiedAt; we don't share a package-level value.
 +func unsignedResult() Result {
 +	return Result{
 +		Verified:   false,
 +		Reason:     ReasonUnsigned,
 +		VerifiedAt: time.Now(),
 +	}
 +}

internal/repos/sigverify/verify.goadded

 +// SPDX-License-Identifier: AGPL-3.0-or-later
++
 +package sigverify
++
 +import (
 +	"bytes"
 +	"context"
 +	"encoding/hex"
 +	"fmt"
 +	"os/exec"
 +	"strings"
 +	"time"
++
 +	"github.com/ProtonMail/go-crypto/openpgp"
 +	"github.com/ProtonMail/go-crypto/openpgp/armor"
 +	"github.com/ProtonMail/go-crypto/openpgp/packet"
 +)
++
 +// Verify resolves the verification state of a single commit object.
 +// It reads the commit body via `git cat-file -p`, splits out the
 +// gpgsig header, looks up the signing subkey via lookups, performs
 +// the cryptographic check, and finally cross-checks the signer's
 +// email against the user's verified emails (when applicable).
 +//
 +// Never returns ReasonMalformedSignature or ReasonInvalid as errors —
 +// those are part of the Result. Returns an error only when the
 +// underlying git or DB call fails (i.e. the verification couldn't be
 +// attempted at all). Callers should record the verification result
 +// to the cache table even on error states; the error path is for
 +// "we don't know yet, retry later" situations.
 +func Verify(ctx context.Context, gitDir, commitOID string, lookups Lookups) (Result, error) {
 +	body, err := catFile(ctx, gitDir, commitOID)
 +	if err != nil {
 +		return Result{}, fmt.Errorf("sigverify: cat-file %s: %w", commitOID, err)
 +	}
 +	return verifyObject(ctx, body, lookups, KindCommit)
 +}
++
 +// VerifyTag is the annotated-tag variant. The commit-object splitter
 +// already handles both header-form and inline-form signatures, so
 +// the orchestration is the same — only the cache `kind` discriminator
 +// differs.
 +func VerifyTag(ctx context.Context, gitDir, tagOID string, lookups Lookups) (Result, error) {
 +	body, err := catFile(ctx, gitDir, tagOID)
 +	if err != nil {
 +		return Result{}, fmt.Errorf("sigverify: cat-file %s: %w", tagOID, err)
 +	}
 +	return verifyObject(ctx, body, lookups, KindTag)
 +}
++
 +// verifyObject is the shared implementation. _ Kind is currently
 +// unused (the Result doesn't carry it; the caller stamps Kind into
 +// the cache row themselves), kept on the signature in case future
 +// branching needs to inspect it.
 +func verifyObject(ctx context.Context, body []byte, lookups Lookups, _ Kind) (Result, error) {
 +	payload, armored, signed := splitSignedObject(body)
 +	if !signed {
 +		return unsignedResult(), nil
 +	}
++
 +	// Parse the signature packet to learn which subkey signed.
 +	sigPkt, err := readSignaturePacket(armored)
 +	if err != nil {
 +		return Result{
 +			Verified:   false,
 +			Reason:     ReasonMalformedSignature,
 +			Signature:  armored,
 +			VerifiedAt: time.Now(),
 +		}, nil
 +	}
++
 +	// Resolve the signing subkey. RFC 4880 supports both an
 +	// IssuerKeyId subpacket (lower 64 bits of the fingerprint) and
 +	// an IssuerFingerprint subpacket (the full 40-hex). Modern git/
 +	// gpg emits both; we prefer the fingerprint when present because
 +	// 64-bit key ids can collide.
 +	var fingerprintHex string
 +	if len(sigPkt.IssuerFingerprint) > 0 {
 +		fingerprintHex = hex.EncodeToString(sigPkt.IssuerFingerprint)
 +	}
 +	if fingerprintHex == "" {
 +		// IssuerKeyId fallback: we can't do a precise lookup without
 +		// the full fingerprint. Mark unknown so the user can re-sign
 +		// with a modern gpg client. (gh produces the same outcome
 +		// in this rare case.)
 +		return Result{
 +			Verified:   false,
 +			Reason:     ReasonUnknownKey,
 +			Signature:  armored,
 +			Payload:    payload,
 +			VerifiedAt: time.Now(),
 +		}, nil
 +	}
++
 +	subkey, found, err := lookups.SubkeyByFingerprint(ctx, fingerprintHex)
 +	if err != nil {
 +		return Result{}, fmt.Errorf("sigverify: lookup subkey: %w", err)
 +	}
 +	if !found {
 +		return Result{
 +			Verified:   false,
 +			Reason:     ReasonUnknownKey,
 +			Signature:  armored,
 +			Payload:    payload,
 +			VerifiedAt: time.Now(),
 +		}, nil
 +	}
++
 +	// Load the parent gpg-key so we can construct the openpgp.Entity
 +	// from its armored block. The cryptographic check needs the
 +	// actual public-key material, not just the fingerprint.
 +	gpgKey, found, err := lookups.GPGKeyByID(ctx, subkey.GPGKeyID)
 +	if err != nil {
 +		return Result{}, fmt.Errorf("sigverify: lookup parent gpg key: %w", err)
 +	}
 +	if !found {
 +		// Parent gone (revoked between subkey lookup and parent
 +		// lookup). Surface as unknown_key from the user's
 +		// perspective.
 +		return Result{
 +			Verified:   false,
 +			Reason:     ReasonUnknownKey,
 +			Signature:  armored,
 +			Payload:    payload,
 +			VerifiedAt: time.Now(),
 +		}, nil
 +	}
++
 +	entity, err := openpgp.ReadArmoredKeyRing(strings.NewReader(gpgKey.Armored))
 +	if err != nil || len(entity) == 0 {
 +		// Corrupted at-rest — surface as malformed so the cache row
 +		// makes the issue visible; rendering UI treats this as
 +		// unverified.
 +		return Result{
 +			Verified:       false,
 +			Reason:         ReasonMalformedSignature,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	}
++
 +	// Capability + expiry checks happen BEFORE the cryptographic
 +	// check. Reason: openpgp.CheckArmoredDetachedSignature does its
 +	// own expiry check using time.Now() and folds the result into a
 +	// generic error; running our checks first lets us return the
 +	// precise gh enum reason (expired_key, not_signing_key).
 +	if !subkey.CanSign {
 +		return Result{
 +			Verified:       false,
 +			Reason:         ReasonNotSigningKey,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	}
 +	if !subkey.ExpiresAt.IsZero() && sigPkt.CreationTime.After(subkey.ExpiresAt) {
 +		// Signature was made AFTER the key expired — not valid.
 +		// Sigs made before expiry remain valid even when the key
 +		// later expires (gh's behavior).
 +		return Result{
 +			Verified:       false,
 +			Reason:         ReasonExpiredKey,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	}
++
 +	// Cryptographic check. Pass Config.Time = sig creation time so
 +	// the openpgp library treats the key as live-at-sig-time (we've
 +	// already run the explicit expiry check above; the library's
 +	// re-check would just cause false negatives).
 +	cfg := &packet.Config{Time: func() time.Time { return sigPkt.CreationTime }}
 +	signer, err := openpgp.CheckArmoredDetachedSignature(
 +		entity,
 +		bytes.NewReader(payload),
 +		strings.NewReader(armored),
 +		cfg,
 +	)
 +	if err != nil || signer == nil {
 +		return Result{
 +			Verified:       false,
 +			Reason:         ReasonInvalid,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	}
++
 +	// Email cross-check. Pull the signer email from the signature
 +	// packet's UID embedding when present, otherwise from the
 +	// primary identity of the parent gpg key.
 +	signerEmail := extractSignerEmail(sigPkt, entity[0])
++
 +	if signerEmail == "" {
 +		// No email to cross-check. gh treats this as valid since
 +		// the cryptography succeeded — we follow suit.
 +		return Result{
 +			Verified:       true,
 +			Reason:         ReasonValid,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	}
++
 +	emails, err := lookups.UserEmailsByUserID(ctx, gpgKey.UserID)
 +	if err != nil {
 +		return Result{}, fmt.Errorf("sigverify: lookup user emails: %w", err)
 +	}
 +	emailVerifiedState, claimed := claimEmailLookup(emails, signerEmail)
 +	switch {
 +	case !claimed:
 +		return Result{
 +			Verified:       false,
 +			Reason:         ReasonBadEmail,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			SignerEmail:    signerEmail,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	case !emailVerifiedState:
 +		return Result{
 +			Verified:       false,
 +			Reason:         ReasonUnverifiedEmail,
 +			Signature:      armored,
 +			Payload:        payload,
 +			SignerUserID:   gpgKey.UserID,
 +			SignerSubkeyID: subkey.ID,
 +			SignerEmail:    signerEmail,
 +			VerifiedAt:     time.Now(),
 +		}, nil
 +	}
++
 +	return Result{
 +		Verified:       true,
 +		Reason:         ReasonValid,
 +		Signature:      armored,
 +		Payload:        payload,
 +		SignerUserID:   gpgKey.UserID,
 +		SignerSubkeyID: subkey.ID,
 +		SignerEmail:    signerEmail,
 +		VerifiedAt:     time.Now(),
 +	}, nil
 +}
++
 +// catFile shells out to `git cat-file -p <oid>` and returns the
 +// object body. We trim the trailing newline that git always emits.
 +func catFile(ctx context.Context, gitDir, oid string) ([]byte, error) {
 +	cmd := exec.CommandContext(ctx, "git", "-C", gitDir, "cat-file", "-p", oid)
 +	out, err := cmd.Output()
 +	if err != nil {
 +		return nil, err
 +	}
 +	return out, nil
 +}
++
 +// readSignaturePacket parses the first signature packet out of an
 +// armored block. Used to extract the issuer fingerprint + creation
 +// time + UID embedding without re-doing the full cryptographic check.
 +func readSignaturePacket(armored string) (*packet.Signature, error) {
 +	block, err := armor.Decode(strings.NewReader(armored))
 +	if err != nil {
 +		return nil, err
 +	}
 +	if block.Type != "PGP SIGNATURE" {
 +		return nil, fmt.Errorf("sigverify: expected PGP SIGNATURE block, got %q", block.Type)
 +	}
 +	pkt, err := packet.Read(block.Body)
 +	if err != nil {
 +		return nil, err
 +	}
 +	sig, ok := pkt.(*packet.Signature)
 +	if !ok {
 +		return nil, fmt.Errorf("sigverify: first packet is not a Signature")
 +	}
 +	return sig, nil
 +}
++
 +// extractSignerEmail returns the email used to sign — preferring the
 +// signature packet's UID embedding (RFC 4880 §5.2.3.28) when present,
 +// otherwise the primary UID of the signing entity.
 +func extractSignerEmail(sig *packet.Signature, e *openpgp.Entity) string {
 +	if sig.SignerUserId != nil && *sig.SignerUserId != "" {
 +		// SignerUserId is the full UID string ("Alice <alice@x>");
 +		// crack out the email part.
 +		return parseEmailFromUID(*sig.SignerUserId)
 +	}
 +	if e != nil {
 +		if id := e.PrimaryIdentity(); id != nil && id.UserId != nil {
 +			return id.UserId.Email
 +		}
 +	}
 +	return ""
 +}
++
 +// parseEmailFromUID pulls the email from a UID string of the form
 +// "Name (Comment) <email@host>" or just "email@host". Falls back to
 +// the raw string when no angle brackets are present.
 +func parseEmailFromUID(uid string) string {
 +	if i := strings.LastIndex(uid, "<"); i >= 0 {
 +		if j := strings.LastIndex(uid, ">"); j > i {
 +			return uid[i+1 : j]
 +		}
 +	}
 +	if strings.Contains(uid, "@") {
 +		return strings.TrimSpace(uid)
 +	}
 +	return ""
 +}
++
 +// claimEmailLookup walks the user's emails, returning (verified, true)
 +// when the email is claimed (case-insensitive match) and (false, false)
 +// when it isn't claimed at all.
 +func claimEmailLookup(emails []UserEmail, signerEmail string) (verified, claimed bool) {
 +	se := strings.ToLower(signerEmail)
 +	for _, e := range emails {
 +		if strings.ToLower(e.Email) == se {
 +			return e.Verified, true
 +		}
 +	}
 +	return false, false
 +}