The audit trail — append-only, enforced by the database

Code

Weave an event into every state change

Five files as tabs. The audit helper now threads through every state change, and the detail page grows the trail. documents.go → signing.go → signing_view.go → web/signing.go → documents.templ.

1. internal/handlers/documents.go (modify) — two handlers gain an event, inside a transaction:

UploadDocument now wraps CreateDocument and an evtUploaded event in one transaction (rolling back the blob if either fails).
DeleteDocument wraps DeleteDraftDocument and an evtDeleted event in one transaction — and this is the payoff: because document_id is FK-free, the delete removes the document while its audit rows (including "Deleted draft") stay.
renderDocumentDetail records an evtTamper event when integrity fails on view, loads the trail with ListAuditEventsByDocument, and passes it to the page.

2. internal/handlers/signing.go (modify) — the signing flow records the interesting moments: evtSent (in the invite transaction), evtViewed (best-effort, when a pending signer opens their link), evtSigned and — for the last signer — evtCompleted (both in the sign transaction), and evtBadToken (a repeat-sign or expired-link attempt). Each uses the actor that fits: actorUser, actorSigner, or actorSystem.

3. internal/handlers/signing_view.go (modify) — add viewAuditEvents, which maps db.AuditEvent rows into web.AuditView and flags the security-relevant types (bad_token, tamper_detected) for emphasis.

4. internal/web/signing.go (modify) — add the AuditView struct.

5. internal/web/documents.templ (modify) — DocumentDetail grows an events parameter and renders @AuditLog(events); AuditLog is a new component that shows each event's time, message, and actor, with security rows highlighted.

Verify — reseed, run, and exercise the whole flow while watching the audit trail on a document's page:

Upload a document, open it — the trail shows one event: Uploaded "contract.pdf" ..., actor you.
Send it to two signers — a Sent for signature to 2 signer(s) event, actor you.
Open a signing link — a ... opened the signing link event, actor signer. Sign — a ... signed as "..." event. Sign as the second — signed, then All invited signers have signed — document completed, actor system. Two events in one transaction, same timestamp, ordered by seq.
Tamper with the file (as last lesson) and reload — an Integrity check FAILED event, highlighted.

Now the property the whole table was designed for. Delete a draft and confirm its history outlives it:

$ psql "$DATABASE_URL" -c "select event_type, actor_label, message from audit_events
                           where document_id='<the deleted draft id>' order by seq;"
    event_type      | actor_label |            message
--------------------+-------------+--------------------------------
 document.uploaded  | you@ex.com  | Uploaded "notes.txt" (12 B, ...)
 document.deleted   | you@ex.com  | Deleted draft "notes.txt"

The documents row is gone; its audit rows remain, document_id still set. A foreign key would have cascaded them away or blocked the delete. FK-free is why the trail survives — the point of the whole lesson.

documents.go MODIFY 71 lines changed

Edit this file in internal/handlers/

package handlers

import (
	"context"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strings"

	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/pgtype"

	"github.com/programuoki/signflow/internal/db"
	"github.com/programuoki/signflow/internal/web"
)

// Dashboard lists the signed-in user's documents.
func (h *Handlers) Dashboard(w http.ResponseWriter, r *http.Request) {
	user := mustUser(r)
	docs, err := h.Queries.ListDocumentsByOwner(r.Context(), user.ID)
	if err != nil {
		h.serverError(w, r, "list documents", err)
		return
	}
	render(w, r, http.StatusOK, web.Dashboard(h.nav(r), viewDocuments(docs)))
}

// UploadDocument accepts a multipart file, hashes and stores it, and records it
// as a draft owned by the current user.
func (h *Handlers) UploadDocument(w http.ResponseWriter, r *http.Request) {
	user := mustUser(r)

	// Cap the request body. +1KiB slack covers multipart field overhead so a
	// file exactly at the limit still succeeds.
	r.Body = http.MaxBytesReader(w, r.Body, h.Cfg.MaxUploadBytes+1024)

	file, header, err := r.FormFile("file")
	if err != nil {
		// Covers both "no file" and "too large" (MaxBytesReader error).
		h.Log.Warn("upload rejected", "err", err, "user", user.Email)
		http.Error(w, "upload failed: file missing or too large", http.StatusRequestEntityTooLarge)
		return
	}
	defer file.Close()

	if header.Size == 0 {
		http.Error(w, "upload failed: empty file", http.StatusBadRequest)
		return
	}

	contentType := header.Header.Get("Content-Type")
	if contentType == "" {
		contentType = "application/octet-stream"
	}

	key, size, hash, err := h.Store.Save(r.Context(), file)
	if err != nil {
		h.serverError(w, r, "store file", err)
		return
	}

	// Create the document and its audit event in one transaction. If either
	// fails, roll back and remove the just-saved blob so nothing is orphaned.
	filename := sanitizeFilename(header.Filename)
	tx, err := h.Pool.Begin(r.Context())
	if err != nil {
		_ = h.Store.Delete(r.Context(), key)
		h.serverError(w, r, "begin tx", err)
		return
	}
	defer tx.Rollback(context.Background())
	q := h.Queries.WithTx(tx)

	doc, err := q.CreateDocument(r.Context(), db.CreateDocumentParams{
		OwnerID:     user.ID,
		Filename:    filename,
		ContentType: contentType,
		Size:        size,
		FileHash:    hash,
		StorageKey:  key,
	})
	if err != nil {
		_ = h.Store.Delete(r.Context(), key)
		h.serverError(w, r, "create document", err)
		return
	}
	if err := h.audit(r.Context(), q, doc.ID, evtUploaded,
		fmt.Sprintf("Uploaded %q (%s, SHA-256 %s)", filename, humanizeBytes(size), shortHash(hash)),
		actorUser(user)); err != nil {
		_ = h.Store.Delete(r.Context(), key)
		h.serverError(w, r, "audit upload", err)
		return
	}
	if err := tx.Commit(r.Context()); err != nil {
		_ = h.Store.Delete(r.Context(), key)
		h.serverError(w, r, "commit", err)
		return
	}
	h.Log.Info("document uploaded", "id", doc.ID.String(), "owner", user.Email, "size", size, "sha256", hash)

	h.respondWithDocList(w, r, user)
}

// ViewDocument renders a single document's detail page. Owner only: ownedDocument
// enforces that in the query, returning 404 for anything the user doesn't own.
func (h *Handlers) ViewDocument(w http.ResponseWriter, r *http.Request) {
	doc, ok := h.ownedDocument(w, r)
	if !ok {
		return
	}
	h.renderDocumentDetail(w, r, doc, "")
}

// renderDocumentDetail loads the integrity status, signer roster, and audit trail
// and renders the owner detail page, optionally with an inline error (e.g. bad
// invite input).
func (h *Handlers) renderDocumentDetail(w http.ResponseWriter, r *http.Request, doc db.Document, errMsg string) {
	integ, err := h.checkIntegrity(r.Context(), doc)
	if err != nil {
		h.serverError(w, r, "hash document", err)
		return
	}
	signers, err := h.Queries.ListSignersByDocument(r.Context(), doc.ID)
	if err != nil {
		h.serverError(w, r, "list signers", err)
		return
	}

	// A failed integrity check on view is itself an audited security event.
	if !integ.Matches {
		h.auditBestEffort(r.Context(), doc.ID, evtTamper,
			"Integrity check FAILED on view — stored file no longer matches the upload hash",
			actorUser(mustUser(r)))
	}

	events, err := h.Queries.ListAuditEventsByDocument(r.Context(), doc.ID)
	if err != nil {
		h.serverError(w, r, "list audit events", err)
		return
	}

	render(w, r, http.StatusOK, web.DocumentDetail(
		h.nav(r), viewDocument(doc), viewIntegrity(integ, doc), viewSigners(signers, doc),
		viewAuditEvents(events), errMsg,
	))
}

// DownloadDocument streams the stored file back with its original name (owner only).
func (h *Handlers) DownloadDocument(w http.ResponseWriter, r *http.Request) {
	doc, ok := h.ownedDocument(w, r)
	if !ok {
		return
	}
	h.streamDocument(w, r, doc)
}

// streamDocument writes the stored file as an attachment. Shared by the owner
// download route and the tokened signer download route.
func (h *Handlers) streamDocument(w http.ResponseWriter, r *http.Request, doc db.Document) {
	rc, err := h.Store.Open(r.Context(), doc.StorageKey)
	if err != nil {
		h.serverError(w, r, "open file", err)
		return
	}
	defer rc.Close()

	safe := sanitizeFilename(doc.Filename)
	w.Header().Set("Content-Type", doc.ContentType)
	w.Header().Set("Content-Length", fmt.Sprintf("%d", doc.Size))
	// Provide both a plain ASCII filename and a UTF-8 one per RFC 6266.
	w.Header().Set("Content-Disposition",
		fmt.Sprintf("attachment; filename=%q; filename*=UTF-8''%s", safe, url.PathEscape(doc.Filename)))
	if _, err := io.Copy(w, rc); err != nil {
		h.Log.Warn("stream download", "err", err, "id", doc.ID.String())
	}
}

// DeleteDocument deletes a draft the user owns. Non-drafts are refused — the
// first real business rule: once a document is sent, its record is immutable.
func (h *Handlers) DeleteDocument(w http.ResponseWriter, r *http.Request) {
	user := mustUser(r)
	id, ok := parseUUID(chiURLParam(r, "id"))
	if !ok {
		http.NotFound(w, r)
		return
	}

	doc, err := h.Queries.GetDocumentForOwner(r.Context(), db.GetDocumentForOwnerParams{ID: id, OwnerID: user.ID})
	if errors.Is(err, pgx.ErrNoRows) {
		http.NotFound(w, r) // not owned / not found — don't leak which
		return
	}
	if err != nil {
		h.serverError(w, r, "get document", err)
		return
	}
	if doc.Status != "draft" {
		http.Error(w, "only draft documents can be deleted", http.StatusUnprocessableEntity)
		return
	}

	// Delete the row and record the audit event in one transaction. The event's
	// document_id is FK-free, so this row (and every earlier one) survives the
	// document's deletion — that's the whole point of the trail.
	tx, err := h.Pool.Begin(r.Context())
	if err != nil {
		h.serverError(w, r, "begin tx", err)
		return
	}
	defer tx.Rollback(context.Background())
	q := h.Queries.WithTx(tx)

	n, err := q.DeleteDraftDocument(r.Context(), db.DeleteDraftDocumentParams{ID: id, OwnerID: user.ID})
	if err != nil {
		h.serverError(w, r, "delete document", err)
		return
	}
	if n == 1 {
		if err := h.audit(r.Context(), q, doc.ID, evtDeleted,
			fmt.Sprintf("Deleted draft %q", doc.Filename), actorUser(user)); err != nil {
			h.serverError(w, r, "audit delete", err)
			return
		}
	}
	if err := tx.Commit(r.Context()); err != nil {
		h.serverError(w, r, "commit", err)
		return
	}
	if n == 1 {
		// Best-effort blob cleanup after commit; a leftover file is harmless.
		_ = h.Store.Delete(r.Context(), doc.StorageKey)
		h.Log.Info("document deleted", "id", doc.ID.String(), "owner", user.Email)
	}

	h.respondWithDocList(w, r, user)
}

// --- helpers ---

// ownedDocument loads the {id} document if the current user owns it, else writes
// a 404 and returns ok=false.
func (h *Handlers) ownedDocument(w http.ResponseWriter, r *http.Request) (db.Document, bool) {
	user := mustUser(r)
	id, ok := parseUUID(chiURLParam(r, "id"))
	if !ok {
		http.NotFound(w, r)
		return db.Document{}, false
	}
	doc, err := h.Queries.GetDocumentForOwner(r.Context(), db.GetDocumentForOwnerParams{ID: id, OwnerID: user.ID})
	if errors.Is(err, pgx.ErrNoRows) {
		http.NotFound(w, r)
		return db.Document{}, false
	}
	if err != nil {
		h.serverError(w, r, "get document", err)
		return db.Document{}, false
	}
	return doc, true
}

// respondWithDocList returns the refreshed list partial to HTMX callers, or
// redirects to the dashboard for a plain form post.
func (h *Handlers) respondWithDocList(w http.ResponseWriter, r *http.Request, user db.User) {
	if r.Header.Get("HX-Request") == "" {
		http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
		return
	}
	docs, err := h.Queries.ListDocumentsByOwner(r.Context(), user.ID)
	if err != nil {
		h.serverError(w, r, "list documents", err)
		return
	}
	render(w, r, http.StatusOK, web.DocumentList(viewDocuments(docs)))
}

func mustUser(r *http.Request) db.User {
	u, _ := UserFrom(r.Context()) // routes are behind RequireAuth
	return u
}

func parseUUID(s string) (pgtype.UUID, bool) {
	var u pgtype.UUID
	if err := u.Scan(s); err != nil {
		return u, false
	}
	return u, u.Valid
}

// sanitizeFilename strips path separators and control characters so a filename
// can't traverse directories or inject headers.
func sanitizeFilename(name string) string {
	name = strings.ReplaceAll(name, "\\", "/")
	if i := strings.LastIndex(name, "/"); i >= 0 {
		name = name[i+1:]
	}
	name = strings.Map(func(rn rune) rune {
		if rn < 0x20 || rn == 0x7f || rn == '"' {
			return -1
		}
		return rn
	}, name)
	name = strings.TrimSpace(name)
	if name == "" {
		return "document"
	}
	return name
}

signing.go MODIFY 35 lines changed

Edit this file in internal/handlers/

package handlers

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"io"
	"net/http"
	"strings"
	"time"

	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/pgtype"

	"github.com/programuoki/signflow/internal/auth"
	"github.com/programuoki/signflow/internal/db"
	"github.com/programuoki/signflow/internal/email"
	"github.com/programuoki/signflow/internal/web"
)

// signerLinkTTL bounds how long a signing link is valid. Signers take days, not
// minutes, so this is generous — but it's still bounded, so a leaked link isn't
// useful forever.
const signerLinkTTL = 30 * 24 * time.Hour

const maxSignedNameLen = 200

// --- Owner: invite signers ---

// InviteSigners creates signer rows for a draft, flips it draft -> sent, and
// emails each signer their tokened link. All DB writes happen in one transaction.
func (h *Handlers) InviteSigners(w http.ResponseWriter, r *http.Request) {
	user := mustUser(r)
	id, ok := parseUUID(chiURLParam(r, "id"))
	if !ok {
		http.NotFound(w, r)
		return
	}
	doc, err := h.Queries.GetDocumentForOwner(r.Context(), db.GetDocumentForOwnerParams{ID: id, OwnerID: user.ID})
	if errors.Is(err, pgx.ErrNoRows) {
		http.NotFound(w, r)
		return
	}
	if err != nil {
		h.serverError(w, r, "get document", err)
		return
	}
	if doc.Status != "draft" {
		http.Error(w, "signers can only be invited while the document is a draft", http.StatusUnprocessableEntity)
		return
	}

	emails := parseEmails(r.FormValue("emails"))
	if len(emails) == 0 {
		h.renderDocumentDetail(w, r, doc, "Enter at least one valid email address.")
		return
	}

	// One transaction: create every signer + flip the document to sent. If any
	// insert fails, nothing is committed and the document stays a draft.
	type invite struct{ email, link string }
	var invites []invite

	tx, err := h.Pool.Begin(r.Context())
	if err != nil {
		h.serverError(w, r, "begin tx", err)
		return
	}
	defer tx.Rollback(context.Background())
	q := h.Queries.WithTx(tx)

	for _, addr := range emails {
		raw, hash, err := auth.GenerateToken()
		if err != nil {
			h.serverError(w, r, "generate token", err)
			return
		}
		if _, err := q.CreateSigner(r.Context(), db.CreateSignerParams{
			DocumentID: doc.ID,
			Email:      addr,
			TokenHash:  hash,
			ExpiresAt:  pgtype.Timestamptz{Time: time.Now().Add(signerLinkTTL), Valid: true},
		}); err != nil {
			h.serverError(w, r, "create signer", err)
			return
		}
		invites = append(invites, invite{email: addr, link: h.Cfg.BaseURL + "/sign/" + raw})
	}

	if _, err := q.MarkDocumentSent(r.Context(), db.MarkDocumentSentParams{ID: doc.ID, OwnerID: user.ID}); err != nil {
		h.serverError(w, r, "mark sent", err)
		return
	}
	if err := h.audit(r.Context(), q, doc.ID, evtSent,
		fmt.Sprintf("Sent for signature to %d signer(s): %s", len(emails), strings.Join(emails, ", ")),
		actorUser(user)); err != nil {
		h.serverError(w, r, "audit sent", err)
		return
	}
	if err := tx.Commit(r.Context()); err != nil {
		h.serverError(w, r, "commit", err)
		return
	}

	// Send the links after the DB is committed (console sender prints them).
	for _, inv := range invites {
		text := fmt.Sprintf(
			"You've been invited to sign \"%s\" on SignFlow.\n\n"+
				"Open your signing link (valid 30 days):\n%s\n",
			doc.Filename, inv.link)
		if err := h.Mailer.Send(r.Context(), email.Message{
			To:      inv.email,
			Subject: fmt.Sprintf("Please sign \"%s\"", doc.Filename),
			Text:    text,
			HTML:    fmt.Sprintf(`<p>You've been invited to sign <strong>%s</strong>.</p><p><a href="%s">Open your signing link</a> (valid 30 days).</p>`, doc.Filename, inv.link),
		}); err != nil {
			h.Log.Error("send signer invite", "err", err, "to", inv.email)
		}
	}
	h.Log.Info("document sent for signature", "id", doc.ID.String(), "signers", len(invites))

	http.Redirect(w, r, "/documents/"+doc.ID.String(), http.StatusSeeOther)
}

// --- Signer: the tokened, account-less signing flow ---

// SignPage renders the signing page for a valid token.
func (h *Handlers) SignPage(w http.ResponseWriter, r *http.Request) {
	signer, doc, ok := h.resolveSigner(w, r)
	if !ok {
		return
	}
	// Record that an outstanding signer opened their link — worth knowing.
	if signer.Status == "pending" && !signerExpired(signer) {
		h.auditBestEffort(r.Context(), doc.ID, evtViewed,
			fmt.Sprintf("%s opened the signing link", signer.Email), actorSigner(signer))
	}
	h.renderSignState(w, r, signer, doc, "")
}

// SignDownload streams the document to a signer via their token (no account).
func (h *Handlers) SignDownload(w http.ResponseWriter, r *http.Request) {
	_, doc, ok := h.resolveSigner(w, r)
	if !ok {
		return
	}
	h.streamDocument(w, r, doc)
}

// Sign records the signature: typed name + now + SHA-256 of the document at this
// moment. If this is the last outstanding signer, the document flips to completed.
func (h *Handlers) Sign(w http.ResponseWriter, r *http.Request) {
	signer, doc, ok := h.resolveSigner(w, r)
	if !ok {
		return
	}
	// Idempotent: re-posting a signed token just shows the signed state — but a
	// spent token being re-used is a security-relevant event, so record it.
	if signer.Status == "signed" {
		h.auditBestEffort(r.Context(), doc.ID, evtBadToken,
			fmt.Sprintf("Rejected repeat-sign attempt on an already-signed link (%s)", signer.Email),
			actorSigner(signer))
		h.renderSignState(w, r, signer, doc, "")
		return
	}
	if signerExpired(signer) {
		h.auditBestEffort(r.Context(), doc.ID, evtBadToken,
			fmt.Sprintf("Rejected sign attempt via an expired link (%s)", signer.Email),
			actorSigner(signer))
		render(w, r, http.StatusOK, web.SignExpired(h.nav(r)))
		return
	}

	name := strings.TrimSpace(r.FormValue("signed_name"))
	if name == "" || len(name) > maxSignedNameLen {
		h.renderSignState(w, r, signer, doc, "Please type your full name (up to 200 characters).")
		return
	}

	// The document hash AT SIGNING TIME — recomputed from the stored bytes right
	// now, not trusted from the record. This is what the signature attests to.
	integ, err := h.checkIntegrity(r.Context(), doc)
	if err != nil {
		h.serverError(w, r, "hash document", err)
		return
	}

	tx, err := h.Pool.Begin(r.Context())
	if err != nil {
		h.serverError(w, r, "begin tx", err)
		return
	}
	defer tx.Rollback(context.Background())
	q := h.Queries.WithTx(tx)

	n, err := q.SignSigner(r.Context(), db.SignSignerParams{
		ID:            signer.ID,
		SignedName:    &name,
		SignedDocHash: &integ.CurrentHash,
	})
	if err != nil {
		h.serverError(w, r, "sign", err)
		return
	}
	if n == 0 {
		// Lost a race — already signed between load and now. Show signed state.
		_ = tx.Rollback(r.Context())
		h.SignPage(w, r)
		return
	}
	if err := h.audit(r.Context(), q, doc.ID, evtSigned,
		fmt.Sprintf("%s signed as %q (SHA-256 at signing %s)", signer.Email, name, shortHash(integ.CurrentHash)),
		actorSigner(signer)); err != nil {
		h.serverError(w, r, "audit signed", err)
		return
	}

	pending, err := q.CountPendingSigners(r.Context(), doc.ID)
	if err != nil {
		h.serverError(w, r, "count pending", err)
		return
	}
	if pending == 0 {
		if err := q.MarkDocumentCompleted(r.Context(), doc.ID); err != nil {
			h.serverError(w, r, "mark completed", err)
			return
		}
		if err := h.audit(r.Context(), q, doc.ID, evtCompleted,
			"All invited signers have signed — document completed", actorSystem()); err != nil {
			h.serverError(w, r, "audit completed", err)
			return
		}
	}
	if err := tx.Commit(r.Context()); err != nil {
		h.serverError(w, r, "commit", err)
		return
	}
	h.Log.Info("document signed", "doc", doc.ID.String(), "signer", signer.Email, "hash", integ.CurrentHash, "remaining", pending)

	// PRG: redirect to GET so a refresh doesn't re-post.
	http.Redirect(w, r, r.URL.Path, http.StatusSeeOther)
}

// --- helpers ---

// resolveSigner loads the signer for the {token} param and its document. Writes
// the appropriate error page and returns ok=false when the token is unknown.
func (h *Handlers) resolveSigner(w http.ResponseWriter, r *http.Request) (db.Signer, db.Document, bool) {
	token := chiURLParam(r, "token")
	signer, err := h.Queries.GetSignerByToken(r.Context(), auth.HashToken(token))
	if errors.Is(err, pgx.ErrNoRows) {
		render(w, r, http.StatusNotFound, web.SignInvalid(h.nav(r)))
		return db.Signer{}, db.Document{}, false
	}
	if err != nil {
		h.serverError(w, r, "get signer", err)
		return db.Signer{}, db.Document{}, false
	}
	doc, err := h.Queries.GetDocument(r.Context(), signer.DocumentID)
	if err != nil {
		h.serverError(w, r, "get document", err)
		return db.Signer{}, db.Document{}, false
	}
	return signer, doc, true
}

// renderSignState shows the right signing page for the signer's state: expired,
// already-signed, or the sign form (with an optional error message).
func (h *Handlers) renderSignState(w http.ResponseWriter, r *http.Request, signer db.Signer, doc db.Document, errMsg string) {
	integ, err := h.checkIntegrity(r.Context(), doc)
	if err != nil {
		h.serverError(w, r, "hash document", err)
		return
	}
	if !integ.Matches {
		h.auditBestEffort(r.Context(), doc.ID, evtTamper,
			"Integrity check FAILED on signing view — stored file no longer matches the upload hash",
			actorSigner(signer))
	}
	nav := h.nav(r)
	docView := viewDocument(doc)
	integView := viewIntegrity(integ, doc)

	if signer.Status == "signed" {
		render(w, r, http.StatusOK, web.SignDone(nav, docView, integView, viewSigner(signer)))
		return
	}
	if signerExpired(signer) {
		render(w, r, http.StatusOK, web.SignExpired(nav))
		return
	}
	token := chiURLParam(r, "token")
	render(w, r, http.StatusOK, web.SignForm(nav, docView, integView, signer.Email, token, errMsg))
}

// integrity is the result of recomputing the stored file's hash and comparing it
// to the hash recorded at upload.
type integrity struct {
	Matches     bool
	CurrentHash string
}

// checkIntegrity re-hashes the stored bytes and compares to doc.FileHash. A
// mismatch means the file changed after upload — the tamper-evidence property.
func (h *Handlers) checkIntegrity(ctx context.Context, doc db.Document) (integrity, error) {
	rc, err := h.Store.Open(ctx, doc.StorageKey)
	if err != nil {
		return integrity{}, err
	}
	defer rc.Close()
	sum := sha256.New()
	if _, err := io.Copy(sum, rc); err != nil {
		return integrity{}, err
	}
	cur := hex.EncodeToString(sum.Sum(nil))
	return integrity{Matches: cur == doc.FileHash, CurrentHash: cur}, nil
}

func signerExpired(s db.Signer) bool {
	return s.ExpiresAt.Valid && s.ExpiresAt.Time.Before(time.Now())
}

// parseEmails splits a textarea of emails (newline/comma separated), normalizes,
// validates, and de-duplicates while preserving order.
func parseEmails(raw string) []string {
	fields := strings.FieldsFunc(raw, func(r rune) bool {
		return r == '\n' || r == '\r' || r == ',' || r == ';' || r == ' ' || r == '\t'
	})
	seen := map[string]bool{}
	var out []string
	for _, f := range fields {
		addr := normalizeEmail(f)
		if addr == "" || seen[addr] || !validEmail(addr) {
			continue
		}
		seen[addr] = true
		out = append(out, addr)
	}
	return out
}

signing_view.go MODIFY 15 lines changed

Edit this file in internal/handlers/

package handlers

import (
	"github.com/programuoki/signflow/internal/db"
	"github.com/programuoki/signflow/internal/web"
)

func viewIntegrity(integ integrity, doc db.Document) web.IntegrityView {
	return web.IntegrityView{
		Matches:     integ.Matches,
		StoredHash:  doc.FileHash,
		CurrentHash: integ.CurrentHash,
	}
}

func viewSigner(s db.Signer) web.SignerView {
	v := web.SignerView{
		Email:    s.Email,
		Status:   s.Status,
		IsSigned: s.Status == "signed",
	}
	if s.SignedName != nil {
		v.SignedName = *s.SignedName
	}
	if s.SignedAt.Valid {
		v.SignedAt = s.SignedAt.Time.Format("2006-01-02 15:04 MST")
	}
	if s.SignedDocHash != nil {
		v.SignedDocHash = *s.SignedDocHash
	}
	return v
}

func viewAuditEvents(events []db.AuditEvent) []web.AuditView {
	out := make([]web.AuditView, 0, len(events))
	for _, e := range events {
		out = append(out, web.AuditView{
			Time:       e.CreatedAt.Time.Format("2006-01-02 15:04:05 MST"),
			ActorLabel: e.ActorLabel,
			ActorType:  e.ActorType,
			Message:    e.Message,
			EventType:  e.EventType,
			Security:   e.EventType == "signer.bad_token" || e.EventType == "document.tamper_detected",
		})
	}
	return out
}

func viewSigners(signers []db.Signer, doc db.Document) web.SignerRoster {
	roster := web.SignerRoster{Total: len(signers)}
	for _, s := range signers {
		sv := viewSigner(s)
		// Flag any signature made against a different hash than the file now
		// holds — extra tamper visibility on the roster.
		if sv.IsSigned {
			roster.Signed++
			sv.HashMatchesNow = sv.SignedDocHash == doc.FileHash
		}
		roster.Signers = append(roster.Signers, sv)
	}
	return roster
}

signing.go MODIFY 11 lines changed

Edit this file in internal/web/

package web

// IntegrityView is the result of re-hashing the stored file and comparing to the
// hash recorded at upload. Matches=false means the file changed after upload.
type IntegrityView struct {
	Matches     bool
	StoredHash  string // recorded at upload
	CurrentHash string // recomputed now
}

// SignerView is one row in the signer roster / a signer's own signed state.
type SignerView struct {
	Email         string
	Status        string
	IsSigned      bool
	SignedName    string
	SignedAt      string
	SignedDocHash string
	// HashMatchesNow is true when this signature's hash still equals the file's
	// current stored hash (i.e. the file wasn't changed after they signed).
	HashMatchesNow bool
}

// SignerRoster is the owner-facing summary of who has and hasn't signed.
type SignerRoster struct {
	Signers []SignerView
	Total   int
	Signed  int
}

// AuditView is one row of the append-only trail, rendered in plain language.
type AuditView struct {
	Time       string
	ActorLabel string
	ActorType  string // user | signer | system | anonymous
	Message    string
	EventType  string
	// Security marks a row that deserves visual emphasis (bad token / tamper).
	Security bool
}

documents.templ MODIFY 29 lines changed

Edit this file in internal/web/

package web

import "fmt"

// DocumentList is the swappable partial that HTMX refreshes after upload/delete.
// Its id="doc-list" is the hx-target the upload form swaps.
templ DocumentList(docs []DocumentView) {
	<section id="doc-list" class="card">
		<h2>Documents</h2>
		if len(docs) == 0 {
			<p class="muted">No documents yet. Upload one above to get started.</p>
		} else {
			<table class="table">
				<thead>
					<tr>
						<th>Name</th>
						<th>Status</th>
						<th>Size</th>
						<th>Uploaded</th>
						<th></th>
					</tr>
				</thead>
				<tbody>
					for _, d := range docs {
						@documentRow(d)
					}
				</tbody>
			</table>
		}
	</section>
}

templ documentRow(d DocumentView) {
	<tr>
		<td><a href={ templ.SafeURL("/documents/" + d.ID) }>{ d.Filename }</a></td>
		<td><span class={ "pill", "pill-" + d.Status }>{ d.Status }</span></td>
		<td>{ d.SizeHuman }</td>
		<td>{ d.CreatedAt }</td>
		<td class="row-actions">
			<a class="btn btn-ghost btn-sm" href={ templ.SafeURL("/documents/" + d.ID) }>View</a>
			if d.IsDraft {
				<button
					class="btn btn-danger btn-sm"
					hx-post={ "/documents/" + d.ID + "/delete" }
					hx-target="#doc-list"
					hx-swap="outerHTML"
					hx-confirm={ fmt.Sprintf("Delete draft %q? This can't be undone.", d.Filename) }
				>Delete</button>
			}
		</td>
	</tr>
}

// DocumentDetail shows a document's metadata, integrity status, and — once sent —
// the signer roster. While it's a draft, the owner can invite signers here.
templ DocumentDetail(nav Nav, d DocumentView, integ IntegrityView, roster SignerRoster, events []AuditView, errMsg string) {
	@Layout(d.Filename, nav) {
		<p><a href="/dashboard">← Back to documents</a></p>
		<section class="card">
			<div class="doc-head">
				<h1>{ d.Filename }</h1>
				<span class={ "pill", "pill-" + d.Status }>{ d.Status }</span>
			</div>
			@integrityBanner(integ)
			<dl class="meta">
				<dt>Type</dt>
				<dd>{ d.ContentType }</dd>
				<dt>Size</dt>
				<dd>{ d.SizeHuman }</dd>
				<dt>Uploaded</dt>
				<dd>{ d.CreatedAt }</dd>
				<dt>SHA-256</dt>
				<dd><code class="hash">{ d.FileHash }</code></dd>
			</dl>
			<div class="cta-row">
				<a class="btn btn-primary" href={ templ.SafeURL("/documents/" + d.ID + "/download") }>Download</a>
				if d.IsDraft {
					<form method="post" action={ templ.SafeURL("/documents/" + d.ID + "/delete") } class="inline-form">
						@authCSRF(nav.CSRFToken)
						<button class="btn btn-danger" type="submit">Delete draft</button>
					</form>
				}
			</div>
		</section>
		if d.IsDraft {
			<section class="card">
				<h2>Invite signers</h2>
				<p class="muted">Enter one or more email addresses. Sending will move this
					document from <em>draft</em> to <em>sent</em> and email each signer a
					private signing link.</p>
				if errMsg != "" {
					<div class="flash flash-error">{ errMsg }</div>
				}
				<form method="post" action={ templ.SafeURL("/documents/" + d.ID + "/invite") } class="form">
					@authCSRF(nav.CSRFToken)
					<div class="field">
						<label for="emails">Signer emails (one per line, or comma-separated)</label>
						<textarea id="emails" name="emails" rows="3" placeholder="alice@example.com&#10;bob@example.com" required></textarea>
					</div>
					<button class="btn btn-primary" type="submit">Send for signature</button>
				</form>
			</section>
		} else {
			<section class="card">
				<h2>Signers <span class="muted">({ fmt.Sprintf("%d of %d signed", roster.Signed, roster.Total) })</span></h2>
				<table class="table">
					<thead>
						<tr>
							<th>Email</th>
							<th>Status</th>
							<th>Signed as</th>
							<th>Signed at</th>
							<th>Hash signed</th>
						</tr>
					</thead>
					<tbody>
						for _, s := range roster.Signers {
							<tr>
								<td>{ s.Email }</td>
								<td><span class={ "pill", "pill-" + s.Status }>{ s.Status }</span></td>
								<td>
									if s.IsSigned {
										{ s.SignedName }
									} else {
										<span class="muted">—</span>
									}
								</td>
								<td>
									if s.IsSigned {
										{ s.SignedAt }
									} else {
										<span class="muted">—</span>
									}
								</td>
								<td>
									if s.IsSigned {
										<code class="hash-short">{ shortHash(s.SignedDocHash) }</code>
										if !s.HashMatchesNow {
											<span class="tag-warn" title="This signature was made against a different hash than the file now holds">⚠ differs</span>
										}
									} else {
										<span class="muted">—</span>
									}
								</td>
							</tr>
						}
					</tbody>
				</table>
			</section>
		}
		@AuditLog(events)
	}
}

// AuditLog renders the append-only trail in plain language: when, who, what.
templ AuditLog(events []AuditView) {
	<section class="card">
		<h2>Audit trail</h2>
		<p class="muted">Append-only. Every state change is recorded and can never be
			edited or deleted — enforced in the database.</p>
		if len(events) == 0 {
			<p class="muted">No events yet.</p>
		} else {
			<ol class="audit">
				for _, e := range events {
					<li class={ "audit-item", templ.KV("audit-security", e.Security) }>
						<div class="audit-when">{ e.Time }</div>
						<div class="audit-body">
							<div class="audit-msg">{ e.Message }</div>
							<div class="audit-actor">
								<span class={ "actor-tag", "actor-" + e.ActorType }>{ e.ActorType }</span>
								{ e.ActorLabel }
							</div>
						</div>
					</li>
				}
			</ol>
		}
	</section>
}

// shortHash abbreviates a hex hash for compact display.
func shortHash(h string) string {
	if len(h) <= 16 {
		return h
	}
	return h[:8] + "…" + h[len(h)-8:]
}