Skip to content

harvest-invoicer: invoice archive, unique links, deletion and email sending - #190

Merged
aldoborrero merged 3 commits into
mainfrom
feat/harvest-invoicer-archive
Nov 3, 2026
Merged

aldoborrero merged 3 commits into
mainfrom
feat/harvest-invoicer-archive

Conversation

@aldoborrero

Copy link
Copy Markdown
Member

harvest-invoicer serve now keeps every PDF it generates, links each one, can delete them and can email them to the client. It also replaces the template error you get when issuer or client data is missing.

What changes

  • Archive. "Generate PDF" stores the PDF under --invoices-dir / HARVEST_INVOICER_INVOICES_DIR (default invoices/ next to the database), recorded in a new invoices table (schema v4, added by the usual migration).
    • File names look like <number>_<client>_<8 hex>.pdf.
    • Generating identical content again reuses the existing entry.
    • Files are created 0600, the directory 0700, and nothing is ever overwritten.
  • Links. GET /invoices/<id>.pdf shows a PDF inline; add ?download=1 to download it. Ids are 128-bit random. After generating, a panel shows the file name with Open, Download and Send buttons, replacing the small "open" link.
  • Invoices page. /invoices lists date, number, client, total and sent status, with Open, Download, Send and Delete actions. Delete asks for confirmation, with an extra warning if the invoice was already sent.
  • Email. Send prefills the recipient from the bill-to client's email, and the subject and body from per-language templates (en/es). It attaches the PDF through the existing SMTP settings and records sent_at/sent_to.
    • Only accepted recipients are recorded. A partial refusal shows a warning naming the refused addresses; if every client address is refused, the send fails even when the self-copy got through.
    • Resending asks for confirmation.
    • Without SMTP, the button is disabled and says why.
  • Configuration errors. A missing issuer name or bill-to client now shows a localized pointer to Settings instead of 'dict object' has no attribute 'name'.

Behaviour changes

  • serve no longer writes invoice-<number>.pdf to the current directory. It archives, and also writes a copy when --output is given. The README has an "Upgrading" note.
  • The Host allow-list now applies to every request, not only POSTs. Without it, a DNS-rebinding page could read /invoices in local mode. A proxy must forward the public host.
  • GET /healthz is exempt from the Host check and from the login guard, so Kubernetes probes, which use the pod IP as Host, keep working.
  • --demo and generate are unchanged.

Security

An independent review found nothing critical. Its findings are fixed here:

  • partial SMTP refusals were recorded as delivered;
  • the Host check did not cover reads;
  • Unicode line breaks in the subject gave a 500;
  • recipients with control characters were accepted;
  • a delete racing a send gave a 500;
  • PDFs are now opened with O_NOFOLLOW, so a symlink is never followed;
  • an existing invoices directory is tightened to 0700;
  • a QUIT failure after delivery counted as a failed send;
  • timestamps now carry their timezone.

Login (OIDC) and CSRF cover every new route. Recipients and subjects with line breaks are rejected, and nothing new is logged.

Testing

  • 557 passed, 1 skipped (previously 415).
  • Email tests run against a real aiosmtpd server on loopback (new test extra dependency; uv.lock updated).
  • nix fmt and nix flake check pass.

…ending

serve now archives every generated PDF under --invoices-dir (default: invoices/ next to the database) with its own link, lists them on an Invoices page, deletes them, and emails them to the client through the existing SMTP settings, recording who it was sent to. Missing issuer or client data shows a pointer to Settings instead of a template error. The Host allow-list now applies to reads too, and /healthz is the probe endpoint.
A wildcard bind no longer disables the Host guard when --allowed-host or OIDC is set, and configured hosts are normalised like request hosts; a malformed Host gets 403. The From header is a structured mailbox with an explicit envelope sender, so issuer names with commas work. Every send is kept in a history (schema v5) and a resend, from the editor or the Invoices page, needs confirmation server-side. The subject is checked before anything is archived; deleting removes the file before the row; new PDFs are fsynced and verified against their sha256 before reuse, sending or serving; /pdf serves this session's last generated invoice; an existing invoices directory is warned about, never chmod'ed. Adds tests for the O_EXCL retry and write/DB failure cleanup.
… the header

A configured sender with a display name works again: it is parsed once and the bare address is the envelope sender. A resend is detected by content across every earlier sent entry, so a damaged or deleted file can no longer be replaced and resent unconfirmed; the Invoices list shows missing or altered files without links. The v5 migration runs in one transaction and tolerates a NULL sent_to. Host handling: a malformed Host or one with userinfo gets 403 even with a wildcard bind, --allowed-host rejects wildcards, IDN names are IDNA-encoded, and loopback origins must match the server port. A failed delete row gives a toast instead of a 500, the send dialog snapshots settings under the lock, and an unconfirmed resend returns the dialog with the confirmation. The editor header no longer repeats the invoice number.
@aldoborrero
aldoborrero added this pull request to the merge queue Nov 3, 2026
Merged via the queue into main with commit c298b88 Nov 3, 2026
3 checks passed
@aldoborrero
aldoborrero deleted the feat/harvest-invoicer-archive branch November 3, 2026 12:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant