Internal e-signature: accountable-enough hardening — Implementation Plan

package adapters

import (
    "bytes"
    "fmt"
    "io"
    "strings"

    "filippo.io/age"
    "filippo.io/age/armor"
)

// keyCipher encrypts/decrypts PEM-encoded private-key blobs at rest with an age
// X25519 identity (the deployment's at-rest master key, shared with blob storage).
// A nil *keyCipher means "no key configured" → plaintext passthrough (dev), so all
// call sites are nil-safe.
//
// Stored form is age ASCII armor (text), so it fits the existing `text` key_pem
// columns unchanged. Encoding is detected by PEM header on read:
//   "-----BEGIN AGE ENCRYPTED FILE-----" → ciphertext (decrypt)
//   "-----BEGIN RSA PRIVATE KEY-----"    → legacy plaintext (accept as-is)
type keyCipher struct {
    identity  *age.X25519Identity
    recipient *age.X25519Recipient
}

const (
    ageArmorHeader = "-----BEGIN AGE ENCRYPTED FILE-----"
    rsaPEMHeader   = "-----BEGIN RSA PRIVATE KEY-----"
)

// newKeyCipher parses the age X25519 identity secret. An empty secret returns
// (nil, nil): plaintext mode. A malformed secret is a hard error (fail at boot,
// don't silently run unencrypted).
func newKeyCipher(secret string) (*keyCipher, error) {
    secret = strings.TrimSpace(secret)
    if secret == "" {
        return nil, nil
    }
    id, err := age.ParseX25519Identity(secret)
    if err != nil {
        return nil, fmt.Errorf("esign key cipher: parse master key: %w", err)
    }
    return &keyCipher{identity: id, recipient: id.Recipient()}, nil
}

// encrypt returns the age-armored ciphertext of plain. A nil cipher returns plain
// unchanged (plaintext mode).
func (c *keyCipher) encrypt(plain []byte) ([]byte, error) {
    if c == nil {
        return plain, nil
    }
    var buf bytes.Buffer
    aw := armor.NewWriter(&buf)
    w, err := age.Encrypt(aw, c.recipient)
    if err != nil {
        return nil, fmt.Errorf("esign key cipher: encrypt init: %w", err)
    }
    if _, err := w.Write(plain); err != nil {
        return nil, fmt.Errorf("esign key cipher: encrypt write: %w", err)
    }
    if err := w.Close(); err != nil {
        return nil, fmt.Errorf("esign key cipher: encrypt close: %w", err)
    }
    if err := aw.Close(); err != nil {
        return nil, fmt.Errorf("esign key cipher: armor close: %w", err)
    }
    return buf.Bytes(), nil
}

// decrypt returns the plaintext PEM for a stored blob. Legacy plaintext (RSA PEM
// header) is returned unchanged. An age blob with no cipher configured, or a
// decrypt failure, is an error (fail closed — never treat ciphertext as a key).
func (c *keyCipher) decrypt(stored []byte) ([]byte, error) {
    s := strings.TrimSpace(string(stored))
    switch {
    case strings.HasPrefix(s, rsaPEMHeader):
        return stored, nil // legacy plaintext
    case strings.HasPrefix(s, ageArmorHeader):
        if c == nil {
            return nil, fmt.Errorf("esign key cipher: key blob is encrypted but no master key is configured")
        }
        ar := armor.NewReader(bytes.NewReader(stored))
        r, err := age.Decrypt(ar, c.identity)
        if err != nil {
            return nil, fmt.Errorf("esign key cipher: decrypt: %w", err)
        }
        out, err := io.ReadAll(r)
        if err != nil {
            return nil, fmt.Errorf("esign key cipher: decrypt read: %w", err)
        }
        return out, nil
    default:
        return nil, fmt.Errorf("esign key cipher: unrecognized key blob encoding")
    }
}

// isLegacyPlaintext reports whether a stored blob is unencrypted (used by the boot
// re-encryption sweep to skip already-encrypted rows).
func isLegacyPlaintext(stored []byte) bool {
    return strings.HasPrefix(strings.TrimSpace(string(stored)), rsaPEMHeader)
}

git add go/internal/esign/adapters/keycipher.go
git commit -m "feat(esign): age key-cipher for signing keys at rest (nil=plaintext)"

// Store implements app.Repository over Postgres. When keys is non-nil, signing-key
// PEM blobs are encrypted at rest (age armor); a nil keys means plaintext (dev).
type Store struct {
    db   *db.DB
    keys *keyCipher
}

// NewStore constructs the esign repository. keys may be nil (plaintext key storage).
func NewStore(d *db.DB, keys *keyCipher) *Store { return &Store{db: d, keys: keys} }

func (s *Store) InsertCA(ctx context.Context, ca domain.CACert) error {
    encKey, err := s.keys.encrypt(ca.KeyPEM)
    if err != nil {
        return err
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO ca_certs (id, cert_pem, key_pem, created_at) VALUES ($1, $2, $3, $4)`,
        ca.ID, string(ca.CertPEM), string(encKey), ca.CreatedAt); err != nil {
        return fmt.Errorf("esign insert ca: %w", err)
    }
    return nil
}

    ca.CertPEM = []byte(certPEM)
    decKey, err := s.keys.decrypt([]byte(keyPEM))
    if err != nil {
        return domain.CACert{}, err
    }
    ca.KeyPEM = decKey
    return ca, nil

func (s *Store) InsertSigningCert(ctx context.Context, c domain.SigningCert) error {
    encKey, err := s.keys.encrypt(c.KeyPEM)
    if err != nil {
        return err
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO signing_certs (id, user_id, cert_pem, key_pem, serial, not_after, created_at)
         VALUES ($1, $2, $3, $4, $5, $6, $7)`,
        c.ID, c.UserID, string(c.CertPEM), string(encKey), c.Serial, c.NotAfter, c.CreatedAt); err != nil {
        return fmt.Errorf("esign insert signing cert: %w", err)
    }
    return nil
}

    c.CertPEM = []byte(certPEM)
    decKey, err := s.keys.decrypt([]byte(keyPEM))
    if err != nil {
        return domain.SigningCert{}, err
    }
    c.KeyPEM = decKey
    return c, nil

// ReEncryptLegacyKeys rewrites any plaintext ca_certs/signing_certs key_pem blobs as
// age ciphertext. Idempotent: already-encrypted rows are skipped. A no-op when no
// cipher is configured. A row that fails to re-encrypt is logged by the caller via the
// returned error slice being non-empty is NOT used here — instead we return the count
// converted and the FIRST error, but never abort the whole sweep. Runs at boot.
func (s *Store) ReEncryptLegacyKeys(ctx context.Context) (converted int, err error) {
    if s.keys == nil {
        return 0, nil
    }
    // ca_certs
    caRows, qerr := s.db.Exec(ctx).Query(ctx, `SELECT id, key_pem FROM ca_certs`)
    if qerr != nil {
        return converted, fmt.Errorf("esign reencrypt: list ca: %w", qerr)
    }
    type row struct{ id, keyPEM string }
    var cas []row
    for caRows.Next() {
        var r row
        if serr := caRows.Scan(&r.id, &r.keyPEM); serr != nil {
            caRows.Close()
            return converted, serr
        }
        cas = append(cas, r)
    }
    caRows.Close()
    for _, r := range cas {
        if !isLegacyPlaintext([]byte(r.keyPEM)) {
            continue
        }
        enc, eerr := s.keys.encrypt([]byte(r.keyPEM))
        if eerr != nil {
            if err == nil {
                err = eerr
            }
            continue
        }
        if _, uerr := s.db.Exec(ctx).Exec(ctx, `UPDATE ca_certs SET key_pem = $2 WHERE id = $1`, r.id, string(enc)); uerr != nil {
            if err == nil {
                err = uerr
            }
            continue
        }
        converted++
    }
    // signing_certs
    scRows, qerr := s.db.Exec(ctx).Query(ctx, `SELECT id, key_pem FROM signing_certs`)
    if qerr != nil {
        return converted, fmt.Errorf("esign reencrypt: list signing: %w", qerr)
    }
    var scs []row
    for scRows.Next() {
        var r row
        if serr := scRows.Scan(&r.id, &r.keyPEM); serr != nil {
            scRows.Close()
            return converted, serr
        }
        scs = append(scs, r)
    }
    scRows.Close()
    for _, r := range scs {
        if !isLegacyPlaintext([]byte(r.keyPEM)) {
            continue
        }
        enc, eerr := s.keys.encrypt([]byte(r.keyPEM))
        if eerr != nil {
            if err == nil {
                err = eerr
            }
            continue
        }
        if _, uerr := s.db.Exec(ctx).Exec(ctx, `UPDATE signing_certs SET key_pem = $2 WHERE id = $1`, r.id, string(enc)); uerr != nil {
            if err == nil {
                err = uerr
            }
            continue
        }
        converted++
    }
    return converted, err
}

git add go/internal/esign/adapters/pg.go
git commit -m "feat(esign): encrypt CA + signing key_pem at rest via Store cipher + boot sweep"

    esignKeyCipher, err := esignadapters.NewKeyCipher(cfg.Encryption.Key)
    if err != nil {
        return nil, fmt.Errorf("esign key cipher: %w", err)
    }
    if esignKeyCipher == nil {
        logger.Warn("esign signing keys are stored UNENCRYPTED — set BLOB_ENCRYPTION_KEY_FILE to encrypt CA + signing keys at rest")
    }
    esignStore := esignadapters.NewStore(database, esignKeyCipher)
    esignSvc := esignapp.NewService(esignStore, esignadapters.NewX509CA(), esignadapters.NewPdfSigner(cfg.ESignTSAURL), sealer, database)

    if n, rerr := esignStore.ReEncryptLegacyKeys(ctx); rerr != nil {
        logger.Error("esign: re-encrypting legacy signing keys failed for some rows (they will fail closed on use)", "converted", n, "err", rerr)
    } else if n > 0 {
        logger.Info("esign: encrypted legacy signing keys at rest", "converted", n)
    }

git add go/cmd/obscura-server/wire.go go/internal/esign/adapters/keycipher.go
git commit -m "feat(esign): wire key cipher + boot re-encryption sweep + unset-key WARN"

    // ESignTSAURL, when set, is the RFC3161 TSA the internal PAdES signer calls to embed a
    // signature timestamp (PAdES B-T). Empty = no timestamp (B-B). In the compose stack this
    // points at our own in-process responder (http://127.0.0.1:8080/api/v1/tsa).
    ESignTSAURL string `env:"ESIGN_TSA_URL"`

git add go/internal/platform/config/config.go go/go.mod go/go.sum
git commit -m "feat(config): ESIGN_TSA_URL + promote digitorus/timestamp to direct dep"

// oidExtKeyUsage is the X.509 Extended Key Usage extension (2.5.29.37); oidTimeStamping
// is id-kp-timeStamping (1.3.6.1.5.5.7.3.8). RFC3161 §2.3 requires a TSA certificate to
// carry timeStamping as its ONLY EKU, marked CRITICAL — which crypto/x509's ExtKeyUsage
// field cannot express (it emits a non-critical EKU), so we add the extension by hand.
var (
    oidExtKeyUsage  = asn1.ObjectIdentifier{2, 5, 29, 37}
    oidTimeStamping = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 3, 8}
)

// IssueTSACert issues a timestamping certificate from the in-house CA: a
// DigitalSignature key-usage leaf whose ONLY, CRITICAL EKU is id-kp-timeStamping.
func (c *X509CA) IssueTSACert(caCertPEM, caKeyPEM []byte, commonName string) (certPEM, keyPEM []byte, serial string, notAfter time.Time, err error) {
    caCert, err := decodeCertPEM(caCertPEM)
    if err != nil {
        return nil, nil, "", time.Time{}, err
    }
    caKey, err := decodeKeyPEM(caKeyPEM)
    if err != nil {
        return nil, nil, "", time.Time{}, err
    }
    tsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
    if err != nil {
        return nil, nil, "", time.Time{}, fmt.Errorf("esign generate tsa key: %w", err)
    }
    serialNum, err := randomSerial()
    if err != nil {
        return nil, nil, "", time.Time{}, err
    }
    ekuValue, err := asn1.Marshal([]asn1.ObjectIdentifier{oidTimeStamping})
    if err != nil {
        return nil, nil, "", time.Time{}, fmt.Errorf("esign marshal tsa eku: %w", err)
    }
    now := time.Now()
    notAfter = now.Add(c.signingValidity)
    tsaTmpl := &x509.Certificate{
        SerialNumber: serialNum,
        Subject: pkix.Name{
            CommonName:   commonName,
            Organization: []string{"Obscura"},
        },
        NotBefore:             now.Add(-time.Hour),
        NotAfter:              notAfter,
        KeyUsage:              x509.KeyUsageDigitalSignature,
        BasicConstraintsValid: true,
        // EKU set via a CRITICAL ExtraExtension (not the ExtKeyUsage field) so the
        // timeStamping usage is the only EKU and is marked critical, per RFC3161.
        ExtraExtensions: []pkix.Extension{{Id: oidExtKeyUsage, Critical: true, Value: ekuValue}},
    }
    der, err := x509.CreateCertificate(rand.Reader, tsaTmpl, caCert, &tsaKey.PublicKey, caKey)
    if err != nil {
        return nil, nil, "", time.Time{}, fmt.Errorf("esign create tsa cert: %w", err)
    }
    return encodeCertPEM(der), encodeKeyPEM(tsaKey), domain.FormatSerial(serialNum.Bytes()), notAfter, nil
}

    IssueTSACert(caCertPEM, caKeyPEM []byte, commonName string) (certPEM, keyPEM []byte, serial string, notAfter time.Time, err error)

// Timestamper answers an RFC3161 timestamp request (DER TimeStampReq → DER
// TimeStampResp), signing the token with the given TSA cert+key. It is the crypto
// boundary for the self-hosted TSA — the app layer never touches digitorus/timestamp.
type Timestamper interface {
    Respond(tsaCertPEM, tsaKeyPEM, reqDER []byte, now time.Time) (respDER []byte, err error)
}

func NewService(repo Repository, ca CertAuthority, signer Signer, sealer ExternalSealer, timestamper Timestamper, uow kernel.UnitOfWork) *Service {
    return &Service{repo: repo, ca: ca, signer: signer, sealer: sealer, timestamper: timestamper, uow: uow, clock: kernel.SystemClock()}
}

// tsaPrincipalID is the reserved system identity holding the in-house TSA certificate.
const tsaPrincipalID = "system:tsa"

// EnsureTSACert returns the in-house TSA signing cert, issuing one from the CA when
// absent/expired. Mirrors EnsureSigningCert but issues a timeStamping-EKU cert.
func (s *Service) EnsureTSACert(ctx context.Context) (domain.SigningCert, error) {
    ca, err := s.EnsureCA(ctx)
    if err != nil {
        return domain.SigningCert{}, err
    }
    var out domain.SigningCert
    err = s.uow.Do(ctx, func(ctx context.Context) error {
        if cert, gerr := s.repo.GetSigningCert(ctx, tsaPrincipalID); gerr == nil {
            if !cert.IsExpired(s.clock.Now()) {
                out = cert
                return nil
            }
        } else if !isNotFound(gerr) {
            return gerr
        }
        certPEM, keyPEM, serial, notAfter, ierr := s.ca.IssueTSACert(ca.CertPEM, ca.KeyPEM, "Obscura TSA")
        if ierr != nil {
            return ierr
        }
        cert := domain.SigningCert{
            ID:        kernel.NewID(),
            UserID:    tsaPrincipalID,
            CertPEM:   certPEM,
            KeyPEM:    keyPEM,
            Serial:    serial,
            NotAfter:  notAfter,
            CreatedAt: s.clock.Now(),
        }
        if ierr := s.repo.InsertSigningCert(ctx, cert); ierr != nil {
            return ierr
        }
        out = cert
        return nil
    })
    if err != nil {
        return domain.SigningCert{}, err
    }
    return out, nil
}

// Timestamp answers an RFC3161 request with a signed timestamp token from the in-house
// TSA cert. reqDER is the DER TimeStampReq body; the return is the DER TimeStampResp.
func (s *Service) Timestamp(ctx context.Context, reqDER []byte) ([]byte, error) {
    if s.timestamper == nil {
        return nil, &kernel.Error{Kind: kernel.ErrValidation, Code: "esign.tsa.unavailable", Message: "timestamp authority not configured"}
    }
    tsa, err := s.EnsureTSACert(ctx)
    if err != nil {
        return nil, err
    }
    return s.timestamper.Respond(tsa.CertPEM, tsa.KeyPEM, reqDER, s.clock.Now())
}

package adapters

import (
    "bytes"
    "crypto"
    "crypto/rand"
    "fmt"
    "math/big"
    "time"

    "github.com/digitorus/timestamp"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/esign/app"
)

// TSAResponder implements app.Timestamper using digitorus/timestamp. It parses an
// RFC3161 request, builds a granted timestamp for the current time with a fresh random
// serial, and signs it with the in-house TSA cert+key.
type TSAResponder struct{}

// NewTSAResponder constructs the RFC3161 responder adapter.
func NewTSAResponder() *TSAResponder { return &TSAResponder{} }

// Respond parses reqDER (a TimeStampReq), and returns a DER-encoded TimeStampResp
// signed by the TSA cert. A malformed request yields a valid RFC3161 rejection reply
// (not a Go error) so the HTTP layer always returns a well-formed timestamp-reply.
func (t *TSAResponder) Respond(tsaCertPEM, tsaKeyPEM, reqDER []byte, now time.Time) ([]byte, error) {
    req, err := timestamp.ParseRequest(reqDER)
    if err != nil {
        return timestamp.CreateErrorResponse(timestamp.Rejection, timestamp.BadDataFormat)
    }
    tsaCert, err := decodeCertPEM(tsaCertPEM)
    if err != nil {
        return nil, err
    }
    tsaKey, err := decodeKeyPEM(tsaKeyPEM)
    if err != nil {
        return nil, err
    }
    serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
    if err != nil {
        return nil, fmt.Errorf("esign tsa serial: %w", err)
    }
    ts := timestamp.Timestamp{
        HashAlgorithm:     req.HashAlgorithm,
        HashedMessage:     req.HashedMessage,
        Time:              now.UTC(),
        Accuracy:          time.Second,
        SerialNumber:      serial,
        Certificates:      []*x509Cert{}, // populated by AddTSACertificate
        AddTSACertificate: true,
        Nonce:             req.Nonce, // echo the client nonce when present (nil otherwise)
    }
    respDER, err := ts.CreateResponseWithOpts(tsaCert, tsaKey, crypto.SHA256)
    if err != nil {
        return nil, fmt.Errorf("esign tsa create response: %w", err)
    }
    return respDER, nil
}

var _ app.Timestamper = (*TSAResponder)(nil)
var _ = bytes.MinRead // keep bytes imported if unused elsewhere; remove if gofmt/vet flags it

git add go/internal/esign/adapters/x509ca.go go/internal/esign/adapters/tsa.go go/internal/esign/app/service.go
git commit -m "feat(esign): in-house TSA cert (critical timeStamping EKU) + Timestamper port + Service.Timestamp"

// maxTSARequestBytes bounds an RFC3161 request body (real requests are <1 KiB).
const maxTSARequestBytes = 10 << 10

// TimestampRFC3161 is the self-hosted RFC3161 Time-Stamp Authority. It reads a DER
// TimeStampReq (application/timestamp-query) and returns a DER TimeStampResp
// (application/timestamp-reply). Unauthenticated (RFC3161 clients don't authenticate);
// gated on the esign module + rate-limited. The internal PAdES signer self-calls it.
func (s *Server) TimestampRFC3161(w http.ResponseWriter, r *http.Request) {
    body, err := io.ReadAll(io.LimitReader(r.Body, maxTSARequestBytes+1))
    if err != nil || len(body) == 0 || len(body) > maxTSARequestBytes {
        writeProblem(w, &kernel.Error{Kind: kernel.ErrValidation, Code: "esign.tsa.bad_request", Message: "invalid timestamp request"})
        return
    }
    resp, err := s.esign.Timestamp(r.Context(), body)
    if err != nil {
        writeProblem(w, err)
        return
    }
    w.Header().Set("Content-Type", "application/timestamp-reply")
    w.WriteHeader(http.StatusOK)
    _, _ = w.Write(resp)
}

        // Public: self-hosted RFC3161 Time-Stamp Authority (no session; RFC3161 clients don't
        // authenticate). Gated on the esign module + its own IP rate limit. The internal PAdES
        // signer self-calls this to embed a B-T signature timestamp.
        tsaRL := s.rateLimit(tsaLimiter, ipKeyFn, apiRateTSAMax)
        r.With(tsaRL, s.requireModule("esign")).Post("/tsa", s.TimestampRFC3161)

git add go/internal/httpapi/ratelimit.go go/internal/httpapi/handlers_esign.go go/internal/httpapi/server.go
git commit -m "feat(esign): POST /api/v1/tsa RFC3161 responder (module-gated, rate-limited)"

// PdfSigner implements app.Signer using digitorus/pdfsign. When tsaURL is non-empty,
// Sign requests an RFC3161 timestamp from it (PAdES B-T); empty = no timestamp (B-B).
type PdfSigner struct {
    tsaURL string
}

// NewPdfSigner constructs the PAdES signer adapter. tsaURL "" disables timestamping.
func NewPdfSigner(tsaURL string) *PdfSigner { return &PdfSigner{tsaURL: tsaURL} }

        if p.tsaURL != "" {
            sd.TSA = sign.TSA{URL: p.tsaURL}
        }

    esignSvc := esignapp.NewService(esignStore, esignadapters.NewX509CA(), esignadapters.NewPdfSigner(cfg.ESignTSAURL), sealer, esignadapters.NewTSAResponder(), database)

      ESIGN_TSA_URL: "${ESIGN_TSA_URL:-http://127.0.0.1:8080/api/v1/tsa}"

git add go/internal/esign/adapters/pdfsign.go go/cmd/obscura-server/wire.go deploy/docker-compose.yml
git commit -m "feat(esign): internal signer requests B-T timestamp from self-hosted TSA (compose self-call)"

package domain

import "time"

// VerifyResult is the honest outcome of re-checking a signed PDF: one SignatureCheck
// per embedded signature. An empty Signatures slice means "no signature found".
type VerifyResult struct {
    Signatures []SignatureCheck
}

// SignatureCheck reports independent, non-collapsed signals for one signature:
//   - IntegrityOK: the CMS signature is cryptographically intact over its ByteRange.
//   - IssuerTrusted: the signer cert chains to one of OUR in-house CA certs (not
//     "any embedded cert" — the library's own TrustedIssuer trusts self-embedded roots).
//   - TimestampPresent/TimestampTime/TimeSource: an RFC3161 signature timestamp, if any
//     ("tsa" = from an embedded RFC3161 token; "claimed" = the signer's unverified /M date).
type SignatureCheck struct {
    SignerName       string
    SubjectCN        string
    IntegrityOK      bool
    IssuerTrusted    bool
    TimestampPresent bool
    TimestampTime    *time.Time
    TimeSource       string // "tsa" | "claimed"
    ClaimedTime      *time.Time
    CertNotAfter     time.Time
}

git add go/internal/esign/domain/verify.go
git commit -m "feat(esign): VerifyResult + SignatureCheck (honest, distinct verify signals)"

    // ListCACertPEMs returns every in-house CA certificate (PEM), for building the
    // verifier's trust pool. Usually one row.
    ListCACertPEMs(ctx context.Context) ([][]byte, error)

// ListCACertPEMs returns all in-house CA certificate PEMs (the verifier trust pool).
func (s *Store) ListCACertPEMs(ctx context.Context) ([][]byte, error) {
    rows, err := s.db.Exec(ctx).Query(ctx, `SELECT cert_pem FROM ca_certs ORDER BY created_at ASC`)
    if err != nil {
        return nil, fmt.Errorf("esign list ca certs: %w", err)
    }
    defer rows.Close()
    var out [][]byte
    for rows.Next() {
        var pemStr string
        if err := rows.Scan(&pemStr); err != nil {
            return nil, fmt.Errorf("esign scan ca cert: %w", err)
        }
        out = append(out, []byte(pemStr))
    }
    return out, rows.Err()
}

    // Verify re-checks a signed PDF and reports honest, distinct signals per signature.
    // caCertPEMs are the trusted in-house CA roots (issuer-trust is computed against
    // these, NOT the certs embedded in the PDF). A malformed/unsigned PDF yields an empty
    // VerifyResult (not an error).
    Verify(signed []byte, caCertPEMs [][]byte) (domain.VerifyResult, error)

// Verify re-checks the signed PDF and returns honest per-signature signals. Integrity
// comes from the library's cryptographic check; issuer-trust is computed HERE against
// the caller-supplied in-house CA pool (the library's own TrustedIssuer trusts certs
// embedded in the PDF, which for a self-issued chain is meaningless). Timestamp signals
// come from the library's parsed RFC3161 token. A verification negative is not an error.
func (p *PdfSigner) Verify(signed []byte, caCertPEMs [][]byte) (domain.VerifyResult, error) {
    roots := x509.NewCertPool()
    for _, pemBytes := range caCertPEMs {
        if c, derr := decodeCertPEM(pemBytes); derr == nil {
            roots.AddCert(c)
        }
    }
    resp, err := verify.Verify(bytes.NewReader(signed), int64(len(signed)))
    if err != nil || resp == nil {
        // Unparseable / unsigned PDF → no signatures (not an error to the caller).
        return domain.VerifyResult{}, nil
    }
    var out domain.VerifyResult
    for i := range resp.Signers {
        sg := resp.Signers[i]
        chk := domain.SignatureCheck{
            SignerName:  sg.Name,
            IntegrityOK: sg.ValidSignature,
        }
        // Locate the leaf (signer) cert + collect the rest as intermediates.
        var leaf *x509.Certificate
        inter := x509.NewCertPool()
        for j := range sg.Certificates {
            c := sg.Certificates[j].Certificate
            if c == nil {
                continue
            }
            if leaf == nil {
                leaf = c
            } else {
                inter.AddCert(c)
            }
        }
        if leaf != nil {
            chk.SubjectCN = leaf.Subject.CommonName
            chk.CertNotAfter = leaf.NotAfter
            if _, verr := leaf.Verify(x509.VerifyOptions{
                Roots:         roots,
                Intermediates: inter,
                KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageAny},
            }); verr == nil {
                chk.IssuerTrusted = true
            }
        }
        // Timestamp: prefer an embedded RFC3161 token; else the signer's claimed /M time.
        if sg.TimeStamp != nil && !sg.TimeStamp.Time.IsZero() {
            t := sg.TimeStamp.Time
            chk.TimestampPresent = true
            chk.TimestampTime = &t
            chk.TimeSource = "tsa"
        } else {
            chk.TimeSource = "claimed"
            if sg.SignatureTime != nil {
                chk.ClaimedTime = sg.SignatureTime
            }
        }
        out.Signatures = append(out.Signatures, chk)
    }
    return out, nil
}

// Verify re-checks a signed PDF against the in-house CA trust pool and returns honest,
// per-signature signals. A verification negative is an empty result, not an error.
func (s *Service) Verify(signed []byte) (domain.VerifyResult, error) {
    caCertPEMs, err := s.repo.ListCACertPEMs(ctx)
    if err != nil {
        return domain.VerifyResult{}, err
    }
    return s.signer.Verify(signed, caCertPEMs)
}

    name, valid, err := svc.Verify(signed)
    if err != nil {
        t.Fatalf("Verify: %v", err)
    }
    if !valid {
        t.Fatalf("signature did not validate (signer=%q)", name)
    }

    res, err := svc.Verify(context.Background(), signed)
    if err != nil {
        t.Fatalf("Verify: %v", err)
    }
    if len(res.Signatures) == 0 || !res.Signatures[0].IntegrityOK {
        t.Fatalf("signature did not validate")
    }

git add go/internal/esign/app/service.go go/internal/esign/adapters/pdfsign.go go/internal/esign/adapters/pg.go go/internal/esign/adapters/pg_test.go
git commit -m "feat(esign): honest verifier — issuer-trust vs in-house CA pool, distinct signals"

// verifySignatureDTO is one signature's honest verification signals (JSON).
type verifySignatureDTO struct {
    SignerName       string  `json:"signer_name"`
    SubjectCN        string  `json:"subject_cn"`
    IntegrityOK      bool    `json:"integrity_ok"`
    IssuerTrusted    bool    `json:"issuer_trusted"`
    TimestampPresent bool    `json:"timestamp_present"`
    TimestampTime    *string `json:"timestamp_time,omitempty"`
    TimeSource       string  `json:"time_source"`
    ClaimedTime      *string `json:"claimed_time,omitempty"`
    CertNotAfter     string  `json:"cert_not_after"`
}

// VerifyDocumentVersion re-checks the stored bytes of a document version's PDF and
// returns honest per-signature signals. Requires the esign module + read content access.
func (s *Server) VerifyDocumentVersion(w http.ResponseWriter, r *http.Request) {
    docID := chi.URLParam(r, "docID")
    version, err := strconv.Atoi(chi.URLParam(r, "version"))
    if err != nil {
        writeProblem(w, &kernel.Error{Kind: kernel.ErrValidation, Code: "esign.bad_version", Message: "version must be an integer"})
        return
    }
    rc, err := s.dms.OpenVersionContent(r.Context(), docID, version)
    if err != nil {
        writeProblem(w, err)
        return
    }
    pdf, err := io.ReadAll(rc)
    rc.Close()
    if err != nil {
        writeProblem(w, err)
        return
    }
    res, err := s.esign.Verify(r.Context(), pdf)
    if err != nil {
        writeProblem(w, err)
        return
    }
    out := struct {
        Signatures []verifySignatureDTO `json:"signatures"`
    }{Signatures: make([]verifySignatureDTO, 0, len(res.Signatures))}
    for _, c := range res.Signatures {
        dto := verifySignatureDTO{
            SignerName: c.SignerName, SubjectCN: c.SubjectCN,
            IntegrityOK: c.IntegrityOK, IssuerTrusted: c.IssuerTrusted,
            TimestampPresent: c.TimestampPresent, TimeSource: c.TimeSource,
            CertNotAfter: c.CertNotAfter.UTC().Format(time.RFC3339),
        }
        if c.TimestampTime != nil {
            ts := c.TimestampTime.UTC().Format(time.RFC3339)
            dto.TimestampTime = &ts
        }
        if c.ClaimedTime != nil {
            ct := c.ClaimedTime.UTC().Format(time.RFC3339)
            dto.ClaimedTime = &ct
        }
        out.Signatures = append(out.Signatures, dto)
    }
    writeJSON(w, http.StatusOK, out)
}

                r.With(s.requireModule("esign"), s.requireAccess(dmsdomain.AccessRead)).Get("/versions/{version}/verify", s.VerifyDocumentVersion)

git add go/internal/httpapi/handlers_esign.go go/internal/httpapi/server.go
git commit -m "feat(esign): GET /documents/{id}/versions/{v}/verify re-checks stored PDF"

  /api/v1/documents/{docID}/versions/{version}/verify:
    get:
      operationId: verifyDocumentVersion
      summary: Verify a document version's e-signatures
      description: >-
        Re-checks the stored PDF bytes of a document version and reports honest,
        distinct per-signature signals (cryptographic integrity, whether the signer
        chains to the in-house CA, and any RFC3161 timestamp). Requires the esign
        module and read content access. An unsigned/malformed PDF returns an empty list.
      tags: [esign]
      parameters:
        - $ref: '#/components/parameters/DocID'
        - name: version
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Per-signature verification signals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionVerifyResult'
        '401':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'

    VersionVerifyResult:
      type: object
      required: [signatures]
      properties:
        signatures:
          type: array
          items:
            type: object
            required: [signer_name, subject_cn, integrity_ok, issuer_trusted, timestamp_present, time_source, cert_not_after]
            properties:
              signer_name: { type: string }
              subject_cn: { type: string }
              integrity_ok: { type: boolean }
              issuer_trusted: { type: boolean }
              timestamp_present: { type: boolean }
              timestamp_time: { type: string, format: date-time }
              time_source: { type: string, enum: [tsa, claimed] }
              claimed_time: { type: string, format: date-time }
              cert_not_after: { type: string, format: date-time }

git add api/openapi.yaml web/src/api/schema.ts
git commit -m "feat(api): openapi + client for verifyDocumentVersion"

// CAInfo is the public description of the in-house CA (no private key).
type CAInfo struct {
    PEM               string
    DER               []byte
    SHA256Fingerprint string // colon-separated uppercase hex of the DER
    Subject           string
    NotBefore         time.Time
    NotAfter          time.Time
}

// CAPublicInfo returns the in-house CA's public certificate + metadata for
// distribution (trust-anchor publication). It ensures a CA exists first.
func (s *Service) CAPublicInfo(ctx context.Context) (CAInfo, error) {
    ca, err := s.EnsureCA(ctx)
    if err != nil {
        return CAInfo{}, err
    }
    block, _ := pem.Decode(ca.CertPEM)
    if block == nil {
        return CAInfo{}, &kernel.Error{Kind: kernel.ErrInternal, Code: "esign.ca.decode", Message: "ca cert not decodable"}
    }
    cert, err := x509.ParseCertificate(block.Bytes)
    if err != nil {
        return CAInfo{}, fmt.Errorf("esign parse ca cert: %w", err)
    }
    sum := sha256.Sum256(block.Bytes)
    hexParts := make([]string, len(sum))
    for i, b := range sum {
        hexParts[i] = fmt.Sprintf("%02X", b)
    }
    return CAInfo{
        PEM:               string(ca.CertPEM),
        DER:               block.Bytes,
        SHA256Fingerprint: strings.Join(hexParts, ":"),
        Subject:           cert.Subject.String(),
        NotBefore:         cert.NotBefore,
        NotAfter:          cert.NotAfter,
    }, nil
}

// GetOrgCA publishes the in-house CA certificate (trust anchor). Default is JSON with
// the PEM + SHA-256 fingerprint + subject/validity; ?format=pem or ?format=der streams a
// downloadable cert for MDM/GPO import. Requires the esign module + document.read.
func (s *Server) GetOrgCA(w http.ResponseWriter, r *http.Request) {
    info, err := s.esign.CAPublicInfo(r.Context())
    if err != nil {
        writeProblem(w, err)
        return
    }
    switch r.URL.Query().Get("format") {
    case "pem":
        w.Header().Set("Content-Type", "application/x-pem-file")
        w.Header().Set("Content-Disposition", `attachment; filename="obscura-ca.pem"`)
        _, _ = w.Write([]byte(info.PEM))
    case "der":
        w.Header().Set("Content-Type", "application/pkix-cert")
        w.Header().Set("Content-Disposition", `attachment; filename="obscura-ca.cer"`)
        _, _ = w.Write(info.DER)
    default:
        writeJSON(w, http.StatusOK, map[string]any{
            "pem":                info.PEM,
            "sha256_fingerprint": info.SHA256Fingerprint,
            "subject":            info.Subject,
            "not_before":         info.NotBefore.UTC().Format(time.RFC3339),
            "not_after":          info.NotAfter.UTC().Format(time.RFC3339),
        })
    }
}

            r.With(s.requireModule("esign"), s.requirePerm("document.read")).Get("/esign/ca", s.GetOrgCA)

git add go/internal/esign/app/service.go go/internal/httpapi/handlers_esign.go go/internal/httpapi/server.go
git commit -m "feat(esign): GET /api/v1/esign/ca publishes the in-house trust anchor (JSON/PEM/DER)"

  /api/v1/esign/ca:
    get:
      operationId: getOrgCA
      summary: Get the in-house CA (trust anchor)
      description: >-
        Returns the organization's in-house signing CA certificate plus its SHA-256
        fingerprint and validity, for distribution to trust stores (MDM/GPO). Append
        ?format=pem or ?format=der for a downloadable certificate. Requires the esign
        module and document.read.
      tags: [esign]
      responses:
        '200':
          description: The in-house CA public info.
          content:
            application/json:
              schema:
                type: object
                required: [pem, sha256_fingerprint, subject, not_before, not_after]
                properties:
                  pem: { type: string }
                  sha256_fingerprint: { type: string }
                  subject: { type: string }
                  not_before: { type: string, format: date-time }
                  not_after: { type: string, format: date-time }
        '401':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'

git add api/openapi.yaml web/src/api/schema.ts
git commit -m "feat(api): openapi + client for getOrgCA"

// Honest per-signature verification (re-checks the stored PDF).
export interface VerifySignature {
  signerName: string
  subjectCn: string
  integrityOk: boolean
  issuerTrusted: boolean
  timestampPresent: boolean
  timestampTime?: string
  timeSource: 'tsa' | 'claimed'
  claimedTime?: string
  certNotAfter: string
}

export function useVerifyDocumentVersion(docId: string, version: number) {
  return useMutation({
    mutationFn: async (): Promise<VerifySignature[]> => {
      const res = await api.GET('/api/v1/documents/{docID}/versions/{version}/verify', {
        params: { path: { docID: docId, version } },
      })
      return (ok(res).signatures ?? []).map((s) => ({
        signerName: s.signer_name,
        subjectCn: s.subject_cn,
        integrityOk: s.integrity_ok,
        issuerTrusted: s.issuer_trusted,
        timestampPresent: s.timestamp_present,
        timestampTime: s.timestamp_time,
        timeSource: s.time_source as 'tsa' | 'claimed',
        claimedTime: s.claimed_time,
        certNotAfter: s.cert_not_after,
      }))
    },
  })
}