Signing and the honest caveat

Code

The signer page and the signing flow

Nine files as tabs, bottom-up. The queries and view struct first, then the signer pages, the handlers, and the owner detail page that now shows integrity. signers.sql → documents.sql → web/signing.go → signing.templ → signing_view.go → signing.go → documents.go → documents.templ → router.go.

1. internal/db/queries/signers.sql (modify) — three new queries: GetSignerByToken (the token → one row), SignSigner (the status='pending'-guarded update, :execrows), and CountPendingSigners.

2. internal/db/queries/documents.sql (modify) — two new: GetDocument (unscoped by id — only for token-authorized flows) and MarkDocumentCompleted.

3. internal/web/signing.go (modify) — add the IntegrityView struct (recorded hash vs current hash).

4. internal/web/signing.templ (new) — the signer-facing pages and two shared components: integrityBanner (the loud TAMPER DETECTED / quiet verified banner), signatureCaveat (the honesty note), SignForm, SignDone, SignExpired, SignInvalid. Every signing page embeds the banner and the caveat.

5. internal/handlers/signing_view.go (modify) — add viewIntegrity (maps the recomputed hash into IntegrityView).

6. internal/handlers/signing.go (modify) — the signer flow, alongside last lesson's InviteSigners:

resolveSigner — the token maps to one signer + its document (GetSignerByToken → GetDocument); an unknown token renders SignInvalid (404).
checkIntegrity — re-hashes the stored bytes and compares to file_hash. Called on every view and before every sign.
SignPage / SignDownload / Sign — review, download via the token, and sign. Sign recomputes the hash, records the signature in a transaction, and — if it was the last signer — marks the document completed. A double-post shows the signed state (the :execrows guard).

7. internal/handlers/documents.go (modify) — renderDocumentDetail now also computes integrity and passes it to the page; and DownloadDocument is refactored to call a shared streamDocument helper — the signer download needs the same streaming, so a second caller now exists.

8. internal/web/documents.templ (modify) — the owner detail page grows the integrityBanner, and the signer roster grows Signed as / Signed at / Hash signed columns, with a ⚠ differs flag when a past signature's hash no longer matches the file.

9. internal/handlers/router.go (modify) — three routes outside the authenticated group — the token is the whole authorization:

r.Get("/sign/{token}", h.SignPage)
r.Post("/sign/{token}", h.Sign)
r.Get("/sign/{token}/download", h.SignDownload)

Verify — reseed, run, and send a document to two signers (as in lesson 10). Copy a signing link from the console and open it (a private window is a nice way to feel the "no account" part):

The signing page shows a green Integrity verified banner, the document metadata, a Download & review button, and the honesty caveat.
Type a name, Sign — the page shows ✓ You've signed, the hash you signed, and the caveat again.
Reload the signed link: still the signed state, not a second sign (single-use). Re-POST it by hand — same result, zero rows updated.
Sign as the second signer. When the last one signs, the owner's detail page shows the document as completed and the roster as 2 of 2 signed.

level=INFO msg="document signed" doc=… signer=alice@example.com hash=4a7d1ed4… remaining=1
level=INFO msg="document signed" doc=… signer=bob@example.com   hash=4a7d1ed4… remaining=0

remaining=0 is the moment the document completed.

signers.sql MODIFY 15 lines changed

Edit this file in internal/db/queries/

-- name: CreateSigner :one
INSERT INTO signers (document_id, email, token_hash, expires_at)
VALUES ($1, $2, $3, $4)
RETURNING *;

-- name: GetSignerByToken :one
-- The token hash is the only key a signer presents. Unique, so it maps to
-- exactly one signer row — no signer can reach another's row or document.
SELECT * FROM signers WHERE token_hash = $1;

-- name: ListSignersByDocument :many
SELECT * FROM signers WHERE document_id = $1 ORDER BY created_at;

-- name: SignSigner :execrows
-- Records the signature, but only if still pending. The status='pending' guard
-- makes signing single-use: a spent token updates zero rows.
UPDATE signers
SET status = 'signed', signed_name = $2, signed_at = now(), signed_doc_hash = $3
WHERE id = $1 AND status = 'pending';

-- name: CountPendingSigners :one
SELECT count(*) FROM signers WHERE document_id = $1 AND status = 'pending';

documents.sql MODIFY 8 lines changed

Edit this file in internal/db/queries/

-- name: CreateDocument :one
INSERT INTO documents (owner_id, filename, content_type, size, file_hash, storage_key)
VALUES ($1, $2, $3, $4, $5, $6)
RETURNING *;

-- name: ListDocumentsByOwner :many
SELECT * FROM documents
WHERE owner_id = $1
ORDER BY created_at DESC;

-- name: GetDocumentForOwner :one
-- Owner-scoped read: returns nothing if the document belongs to someone else,
-- so authorization is enforced in the query, not just the handler.
SELECT * FROM documents
WHERE id = $1 AND owner_id = $2;

-- name: GetDocument :one
-- Unscoped read by id. ONLY for flows already authorized by a signer token —
-- never call this directly from a user-facing route (use GetDocumentForOwner).
SELECT * FROM documents WHERE id = $1;

-- name: MarkDocumentSent :execrows
-- draft -> sent. Owner-scoped and draft-guarded, so it is idempotent-safe and
-- can't resurrect a completed document.
UPDATE documents SET status = 'sent'
WHERE id = $1 AND owner_id = $2 AND status = 'draft';

-- name: MarkDocumentCompleted :exec
UPDATE documents SET status = 'completed' WHERE id = $1;

-- name: DeleteDraftDocument :execrows
-- Deletes only if the caller owns it AND it is still a draft. Returns the number
-- of rows affected so the handler can tell "deleted" from "not allowed".
DELETE FROM documents
WHERE id = $1 AND owner_id = $2 AND status = 'draft';

signing.go MODIFY 8 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
}

signing.templ CREATE

Create this file in internal/web/

package web

// integrityBanner shows whether the stored file still matches its upload hash.
// A mismatch is shown LOUDLY — it is the one security property this app has.
templ integrityBanner(integ IntegrityView) {
	if integ.Matches {
		<div class="integrity integrity-ok">
			✓ Integrity verified — the stored file still matches the SHA-256 recorded at upload.
		</div>
	} else {
		<div class="integrity integrity-bad">
			<strong>⚠ TAMPER DETECTED.</strong> The stored file no longer matches the
			SHA-256 recorded at upload. It has been altered since it was uploaded.
			<div class="hash-compare">
				<div><span>recorded at upload:</span> <code>{ integ.StoredHash }</code></div>
				<div><span>file right now:</span> <code>{ integ.CurrentHash }</code></div>
			</div>
		</div>
	}
}

// signatureCaveat is the honesty note shown wherever a signature is made or displayed.
templ signatureCaveat() {
	<p class="caveat">
		<strong>About this signature:</strong> it is your typed name, the time, and a
		SHA-256 fingerprint of the document at signing. That makes it
		<em>tamper-evident</em> — you can tell if the document changed afterward — and
		nothing more. It is <strong>not</strong> a qualified or eIDAS electronic
		signature and is not proof of identity.
	</p>
}

// SignForm is the signer's page: review the document, then type a name to sign.
templ SignForm(nav Nav, d DocumentView, integ IntegrityView, signerEmail, token, errMsg string) {
	@Layout("Sign "+d.Filename, nav) {
		<div class="card sign-card">
			<h1>Sign this document</h1>
			<p class="muted">Invited as <strong>{ signerEmail }</strong>. No account needed —
				this link is your authorization to sign.</p>
			@integrityBanner(integ)
			<dl class="meta">
				<dt>Document</dt>
				<dd>{ d.Filename }</dd>
				<dt>Type</dt>
				<dd>{ d.ContentType }</dd>
				<dt>Size</dt>
				<dd>{ d.SizeHuman }</dd>
				<dt>SHA-256</dt>
				<dd><code class="hash">{ d.FileHash }</code></dd>
			</dl>
			<p>
				<a class="btn btn-ghost" href={ templ.SafeURL("/sign/" + token + "/download") }>Download &amp; review</a>
			</p>
			if errMsg != "" {
				<div class="flash flash-error">{ errMsg }</div>
			}
			<form method="post" action={ templ.SafeURL("/sign/" + token) } class="form sign-form">
				@authCSRF(nav.CSRFToken)
				<div class="field">
					<label for="signed_name">Type your full name to sign</label>
					<input id="signed_name" name="signed_name" type="text" maxlength="200" required autocomplete="name" autofocus/>
				</div>
				<button class="btn btn-primary" type="submit">Sign document</button>
			</form>
			@signatureCaveat()
		</div>
	}
}

// SignDone is shown after a signer has signed (and on revisiting their link).
templ SignDone(nav Nav, d DocumentView, integ IntegrityView, signer SignerView) {
	@Layout("Signed", nav) {
		<div class="card sign-card">
			<h1>✓ You've signed</h1>
			<div class="flash flash-ok">
				Signed as <strong>{ signer.SignedName }</strong> on { signer.SignedAt }.
			</div>
			@integrityBanner(integ)
			<dl class="meta">
				<dt>Document</dt>
				<dd>{ d.Filename }</dd>
				<dt>Signed by</dt>
				<dd>{ signer.SignedName } &lt;{ signer.Email }&gt;</dd>
				<dt>Signed at</dt>
				<dd>{ signer.SignedAt }</dd>
				<dt>Document hash you signed</dt>
				<dd><code class="hash">{ signer.SignedDocHash }</code></dd>
			</dl>
			@signatureCaveat()
		</div>
	}
}

templ SignExpired(nav Nav) {
	@Layout("Link expired", nav) {
		<div class="card sign-card">
			<h1>This signing link has expired</h1>
			<p class="muted">Signing links are valid for 30 days. Ask the document owner
				to send you a fresh invitation.</p>
		</div>
	}
}

templ SignInvalid(nav Nav) {
	@Layout("Invalid link", nav) {
		<div class="card sign-card">
			<h1>This signing link is invalid</h1>
			<p class="muted">The link may be mistyped or the invitation may have been
				withdrawn. Check the link in your email.</p>
		</div>
	}
}

signing_view.go MODIFY 8 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 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 178 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 := 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
	}
	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.
	if signer.Status == "signed" {
		h.renderSignState(w, r, signer, doc, "")
		return
	}
	if signerExpired(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
	}

	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 := 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
	}
	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
}

documents.go MODIFY 15 lines changed

Edit this file in internal/handlers/

package handlers

import (
	"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"
	}

	// The store hashes while it writes — the file is never fully in memory.
	key, size, hash, err := h.Store.Save(r.Context(), file)
	if err != nil {
		h.serverError(w, r, "store file", err)
		return
	}

	doc, err := h.Queries.CreateDocument(r.Context(), db.CreateDocumentParams{
		OwnerID:     user.ID,
		Filename:    sanitizeFilename(header.Filename),
		ContentType: contentType,
		Size:        size,
		FileHash:    hash,
		StorageKey:  key,
	})
	if err != nil {
		_ = h.Store.Delete(r.Context(), key) // don't orphan the blob
		h.serverError(w, r, "create document", 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 re-hashes the stored file for its integrity status, loads
// the signer roster, 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
	}
	render(w, r, http.StatusOK, web.DocumentDetail(
		h.nav(r), viewDocument(doc), viewIntegrity(integ, doc), viewSigners(signers, doc), 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
	}

	// The query is the real guard: it filters owner_id AND status='draft', so even
	// without the check above a sent or foreign document deletes zero rows.
	n, err := h.Queries.DeleteDraftDocument(r.Context(), db.DeleteDraftDocumentParams{ID: id, OwnerID: user.ID})
	if err != nil {
		h.serverError(w, r, "delete document", err)
		return
	}
	if n == 1 {
		// Best-effort blob cleanup; 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
}

documents.templ MODIFY 39 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, 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>
		}
	}
}

// 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:]
}

router.go MODIFY 6 lines changed

Edit this file in internal/handlers/

package handlers

import (
	"io/fs"
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
	"github.com/gorilla/csrf"
)

// Router builds the Chi router with the middleware stack and all routes.
//
// csrfKey must be 32 bytes; it authenticates the CSRF token cookie.
func (h *Handlers) Router(staticFS fs.FS, csrfKey []byte) http.Handler {
	r := chi.NewRouter()

	// Base middleware, outermost first.
	r.Use(middleware.RequestID)
	r.Use(middleware.RealIP)
	r.Use(middleware.Logger)    // request logging
	r.Use(middleware.Recoverer) // turn panics into 500s instead of crashing

	// In dev we serve plaintext HTTP on localhost. gorilla/csrf otherwise assumes
	// TLS and enforces a strict Origin/Referer check that rejects http:// origins.
	// Marking dev requests plaintext relaxes that ONE check while keeping the
	// token check. Production (HTTPS at Railway's edge) is NOT marked, so it keeps
	// the full strict-origin protection.
	if !h.Cfg.IsProd() {
		r.Use(func(next http.Handler) http.Handler {
			return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
				next.ServeHTTP(w, csrf.PlaintextHTTPRequest(req))
			})
		})
	}

	// CSRF: enforced on all unsafe methods (POST/PUT/PATCH/DELETE). Safe methods
	// pass through but get the token cookie set so forms can embed it. The field
	// name matches the hidden input our templates render.
	csrfMW := csrf.Protect(
		csrfKey,
		csrf.Secure(h.Cfg.IsProd()),
		csrf.Path("/"),
		csrf.SameSite(csrf.SameSiteLaxMode),
		csrf.FieldName("gorilla.csrf.Token"),
	)
	r.Use(csrfMW)

	// Resolve the session cookie into the request context for every route.
	r.Use(h.LoadUser)

	// Static assets (CSS, vendored htmx), served from the embedded FS.
	r.Handle("/static/*", http.StripPrefix("/static/", http.FileServer(http.FS(staticFS))))

	// Public routes.
	r.Get("/", h.Home)
	r.Get("/healthz", h.Health)

	// Auth routes.
	r.Get("/register", h.RegisterForm)
	r.Post("/register", h.Register)
	r.Get("/login", h.LoginForm)
	r.Post("/login", h.Login)
	r.Post("/logout", h.Logout)
	r.Get("/forgot", h.ForgotForm)
	r.Post("/forgot", h.Forgot)
	r.Get("/reset/{token}", h.ResetForm)
	r.Post("/reset/{token}", h.Reset)

	// Signer routes — no account required. The token in the URL is the entire
	// authorization, so these live outside the authenticated group.
	r.Get("/sign/{token}", h.SignPage)
	r.Post("/sign/{token}", h.Sign)
	r.Get("/sign/{token}/download", h.SignDownload)

	// Authenticated routes.
	r.Group(func(pr chi.Router) {
		pr.Use(h.RequireAuth)
		pr.Get("/dashboard", h.Dashboard)
		pr.Post("/documents", h.UploadDocument)
		pr.Get("/documents/{id}", h.ViewDocument)
		pr.Get("/documents/{id}/download", h.DownloadDocument)
		pr.Post("/documents/{id}/delete", h.DeleteDocument)
		pr.Post("/documents/{id}/invite", h.InviteSigners)
	})

	return r
}