Move to FastAPI with accounts, SQLite books, export and tax returns

Storage and export
- Keep books and transactions in SQLite (data/cashbook.db) instead of
  .ods files; existing .ods books are migrated once at startup
- Export a book as the cashbook spreadsheet (.xlsx/.ods, built from the
  template via LibreOffice) or as CSV
- GST rounded per transaction to match the spreadsheet

Tax
- GST return page with IRD GST101A boxes 5-15 per six-monthly,
  two-monthly or monthly period, due dates, and a Zero-rated GST type
- Income tax page with IR10 (financial statements summary) and IR4
  (company return) boxes, from the cashbook plus year-end amounts typed
  in and saved per book

FastAPI and accounts (following led-editor)
- Replace the stdlib server with a FastAPI app (src/cashbook_app) run by
  uvicorn; dependencies in Pipfile
- Cookie sessions with bcrypt passwords, first-run admin setup or
  BOOTSTRAP_ADMIN_*, invites (link or email), sign-in throttling,
  password change that signs out other sessions
- Users page for administrators: rename, reset password, promote or
  demote, delete, list and revoke invites; last admin is protected
- Replaces the shared CASHBOOK_PASSWORD basic auth; AUTH_* settings in
  .env (see .env.example)
- Docker image uses a venv with system site packages for python3-uno
- pytest suite for auth, user management, imports, GST and tax figures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-10-24 22:43:18 +13:00
1 parent 17b48f25e8
commit 4b3e5f0932
47 files changed
+4189 -862

No files matched your search

+50
View File
@@ -0,0 +1,50 @@
import pytest
from fastapi.testclient import TestClient
CSV_HEADER = "Type,Details,Particulars,Code,Reference,Amount,Date,ForeignCurrencyAmount,ConversionCharge\n"
SAMPLE_CSV = CSV_HEADER + (
"Bank Fee,Monthly A/C Fee,,,,-8.50,30/04/2026,,\n"
"Visa Purchase,4835-****-****-7294 Df,,Jaycar Chris,,-115.00,13/04/2026,,\n"
"Direct Credit,Client Ltd,Inv 101,,,1150.00,20/04/2026,,\n"
"Transfer,01-0822-0082180-30,Credit,Transfer,123,500.00,02/05/2026,,\n"
"Visa Purchase,4835-****-****-7294 If, 0.58,Hetzner.Com, 0.07,-5.53,06/05/2026,EUR 3.20 converted at 0.58,\n"
)
def make_client(tmp_path, monkeypatch, **env):
"""A TestClient for a fresh app using tmp_path as the data folder."""
defaults = {"AUTH_ENABLED": "true", "AUTH_REGISTER_OPEN": "true", "AUTH_INVITE_ONLY": "true"}
for k in ("BOOTSTRAP_ADMIN_USERNAME", "BOOTSTRAP_ADMIN_PASSWORD", "CASHBOOK_STATEMENTS",
"CASHBOOK_ALLOWED_HOSTS", "PUBLIC_BASE_URL", "SMTP_HOST"):
monkeypatch.delenv(k, raising=False)
monkeypatch.setenv("CASHBOOK_DATA", str(tmp_path))
monkeypatch.setenv("HOME", str(tmp_path / "home")) # so ~/Downloads/anz isn't listed
for k, v in {**defaults, **env}.items():
monkeypatch.setenv(k, v)
from cashbook_app.db import session
from cashbook_app.main import create_app
from cashbook_app.services import accounts
session.reset_engine()
accounts._failures.clear()
return TestClient(create_app())
@pytest.fixture
def client(tmp_path, monkeypatch):
with make_client(tmp_path, monkeypatch) as c:
yield c
@pytest.fixture
def admin(client):
"""client signed in as the first (admin) account."""
r = client.post("/api/auth/register", json={"username": "admin", "password": "admin-pass-1"})
assert r.status_code == 200, r.text
return client
def invite(client, **body):
r = client.post("/api/users/invites", json=body)
assert r.status_code == 200, r.text
return r.json()["invite_url"].split("invite=")[1]
+167
View File
@@ -0,0 +1,167 @@
from fastapi.testclient import TestClient
from conftest import invite, make_client
def test_status_and_first_run_setup(client):
s = client.get("/api/auth/status").json()
assert s == {"auth_enabled": True, "register_open": True, "invite_required": True, "setup_required": True}
# the first account needs no invite and becomes the administrator, signed straight in
r = client.post("/api/auth/register", json={"username": "owner", "password": "password-1"})
assert r.status_code == 200
assert r.json()["is_superuser"] is True
assert client.get("/api/auth/me").json()["user"]["username"] == "owner"
assert client.get("/api/auth/status").json()["setup_required"] is False
def test_api_and_pages_need_sign_in(client):
for path in ("/api/books", "/api/statements", "/api/summary?book=x", "/api/users", "/api/export?book=x"):
assert client.get(path).status_code == 401, path
assert client.post("/api/books", json={"name": "x", "year": 2026}).status_code == 401
assert client.get("/", follow_redirects=False).headers["location"] == "/login"
assert client.get("/users", follow_redirects=False).status_code == 307
# public bits
assert client.get("/healthz").json() == {"ok": True}
assert client.get("/login").status_code == 200
def test_registration_needs_invite_after_setup(admin, tmp_path, monkeypatch):
other = TestClient(admin.app)
r = other.post("/api/auth/register", json={"username": "stranger", "password": "password-1"})
assert r.status_code == 403
token = invite(admin, email="bob@example.com")
r = other.post("/api/auth/register", json={"username": "bob", "password": "password-1", "invite_token": token})
assert r.status_code == 200
assert r.json()["is_superuser"] is False
# invites work once
r = other.post("/api/auth/register", json={"username": "bob2", "password": "password-1", "invite_token": token})
assert r.status_code == 409
def test_admin_invite_grants_admin(admin):
token = invite(admin, grants_superuser=True)
other = TestClient(admin.app)
r = other.post("/api/auth/register", json={"username": "second", "password": "password-1", "invite_token": token})
assert r.json()["is_superuser"] is True
def test_login_logout_and_wrong_password(admin):
c = TestClient(admin.app)
assert c.post("/api/auth/login", json={"username": "admin", "password": "nope-nope"}).status_code == 401
assert c.post("/api/auth/login", json={"username": "ghost", "password": "nope-nope"}).status_code == 401
r = c.post("/api/auth/login", json={"username": "ADMIN", "password": "admin-pass-1"}) # case-insensitive
assert r.status_code == 200
assert c.get("/api/books").status_code == 200
c.post("/api/auth/logout")
assert c.get("/api/books").status_code == 401
def test_failed_sign_ins_are_throttled(admin):
c = TestClient(admin.app)
for _ in range(5):
assert c.post("/api/auth/login", json={"username": "admin", "password": "wrong-pass"}).status_code == 401
r = c.post("/api/auth/login", json={"username": "admin", "password": "admin-pass-1"})
assert r.status_code == 429
def test_change_password_signs_out_other_sessions(admin):
laptop = TestClient(admin.app)
laptop.post("/api/auth/login", json={"username": "admin", "password": "admin-pass-1"})
assert laptop.get("/api/books").status_code == 200
r = admin.post("/api/auth/password", json={"current_password": "wrong", "new_password": "new-pass-123"})
assert r.status_code == 400
r = admin.post("/api/auth/password", json={"current_password": "admin-pass-1", "new_password": "new-pass-123"})
assert r.status_code == 200
assert admin.get("/api/books").status_code == 200 # this session stays
assert laptop.get("/api/books").status_code == 401 # other devices are signed out
assert laptop.post("/api/auth/login", json={"username": "admin", "password": "new-pass-123"}).status_code == 200
def test_user_management(admin):
token = invite(admin)
bob = TestClient(admin.app)
bob_id = bob.post("/api/auth/register", json={"username": "bob", "password": "password-1",
"invite_token": token}).json()["id"]
# regular users can't manage users
assert bob.get("/api/users").status_code == 403
assert bob.post("/api/users/invites", json={}).status_code == 403
assert bob.get("/api/books").status_code == 200
users = admin.get("/api/users").json()
assert [u["username"] for u in users] == ["admin", "bob"]
assert admin.patch(f"/api/users/{bob_id}", json={"username": "robert"}).json()["username"] == "robert"
assert admin.patch(f"/api/users/{bob_id}", json={"username": "admin"}).status_code == 400
assert admin.patch(f"/api/users/{bob_id}", json={"is_superuser": True}).json()["is_superuser"] is True
# resetting a password signs them out
assert admin.patch(f"/api/users/{bob_id}", json={"password": "reset-pass-1"}).status_code == 200
assert bob.get("/api/books").status_code == 401
admin_id = users[0]["id"]
assert admin.delete(f"/api/users/{admin_id}").status_code == 400 # not yourself
assert admin.patch(f"/api/users/{admin_id}", json={"is_superuser": False}).status_code == 400
assert admin.delete(f"/api/users/{bob_id}").status_code == 200
assert admin.delete(f"/api/users/{bob_id}").status_code == 404
def test_last_admin_is_protected(admin):
token = invite(admin)
bob = TestClient(admin.app)
bob_id = bob.post("/api/auth/register", json={"username": "bob", "password": "password-1",
"invite_token": token}).json()["id"]
admin.patch(f"/api/users/{bob_id}", json={"is_superuser": True})
admin_id = next(u["id"] for u in admin.get("/api/users").json() if u["username"] == "admin")
# bob demotes admin, then can't demote or delete himself as the last admin
bob.post("/api/auth/login", json={"username": "bob", "password": "password-1"})
assert bob.patch(f"/api/users/{admin_id}", json={"is_superuser": False}).status_code == 200
assert bob.patch(f"/api/users/{bob_id}", json={"is_superuser": False}).status_code == 400
def test_invites_list_and_revoke(admin):
invite(admin, email="a@example.com")
pending = admin.get("/api/users/invites").json()
assert [i["email"] for i in pending] == ["a@example.com"]
assert admin.delete(f"/api/users/invites/{pending[0]['id']}").status_code == 200
assert admin.get("/api/users/invites").json() == []
assert admin.post("/api/users/invites", json={"email": "not-an-email"}).status_code == 422
def test_cross_site_changes_are_refused(admin):
r = admin.post("/api/books", json={"name": "x", "year": 2026}, headers={"Origin": "https://evil.example"})
assert r.status_code == 403
r = admin.post("/api/books", json={"name": "x", "year": 2026}, headers={"Origin": "http://testserver"})
assert r.status_code == 200
def test_auth_disabled_is_open(tmp_path, monkeypatch):
with make_client(tmp_path, monkeypatch, AUTH_ENABLED="false") as c:
assert c.get("/api/books").status_code == 200
assert c.get("/", follow_redirects=False).status_code == 200
assert c.get("/api/auth/me").json() == {"auth_enabled": False, "user": None}
assert c.get("/api/users").status_code == 400
def test_empty_auth_setting_keeps_auth_on(tmp_path, monkeypatch):
with make_client(tmp_path, monkeypatch, AUTH_ENABLED="") as c:
assert c.get("/api/books").status_code == 401
def test_bootstrap_admin(tmp_path, monkeypatch):
with make_client(tmp_path, monkeypatch, BOOTSTRAP_ADMIN_USERNAME="boss",
BOOTSTRAP_ADMIN_PASSWORD="boss-pass-1") as c:
assert c.get("/api/auth/status").json()["setup_required"] is False
r = c.post("/api/auth/login", json={"username": "boss", "password": "boss-pass-1"})
assert r.json()["is_superuser"] is True
def test_open_registration_without_invites(tmp_path, monkeypatch):
with make_client(tmp_path, monkeypatch, AUTH_INVITE_ONLY="false") as c:
c.post("/api/auth/register", json={"username": "first", "password": "password-1"})
other = TestClient(c.app)
r = other.post("/api/auth/register", json={"username": "second", "password": "password-1"})
assert r.status_code == 200 and r.json()["is_superuser"] is False
+126
View File
@@ -0,0 +1,126 @@
from conftest import CSV_HEADER, SAMPLE_CSV
def upload(client, name, text):
return client.post(f"/api/upload?filename={name}", content=text.encode())
def test_book_import_and_figures(admin):
assert admin.post("/api/books", json={"name": "cashbook-2026-27", "year": 2026,
"opening_balance": "100"}).status_code == 200
assert admin.post("/api/books", json={"name": "cashbook-2026-27", "year": 2026}).status_code == 400
r = upload(admin, "april.csv", SAMPLE_CSV)
assert r.status_code == 200
path = r.json()["path"]
stmts = admin.get("/api/statements?book=cashbook-2026-27").json()
assert [(s["name"], s["count"], s["imported"]) for s in stmts] == [("april.csv", 5, 0)]
preview = admin.post("/api/preview", json={"book": "cashbook-2026-27", "statements": [path]}).json()
assert [p["status"] for p in preview] == ["new"] * 5
fee = next(p for p in preview if p["reference"] == "Monthly A/C Fee")
assert (fee["gst"], fee["category"]) == ("Excl GST", "Bank fees")
result = admin.post("/api/import", json={"book": "cashbook-2026-27", "statements": [path]}).json()
assert sum(r["added"] for r in result) == 5
# importing again adds nothing
result = admin.post("/api/import", json={"book": "cashbook-2026-27", "statements": [path]}).json()
assert sum(r["added"] for r in result) == 0
s = admin.get("/api/summary?book=cashbook-2026-27").json()
apr, may = s["months"][0], s["months"][1]
assert (apr["count"], may["count"]) == (3, 2)
assert round(apr["closing"], 2) == 100 - 8.50 - 115 + 1150
assert round(s["closing"], 2) == round(100 - 8.50 - 115 + 1150 + 500 - 5.53, 2)
assert may["income_cats"]["Funds Intr."] == 500
def test_edit_rows_and_gst_return(admin):
admin.post("/api/books", json={"name": "b", "year": 2026})
path = upload(admin, "april.csv", SAMPLE_CSV).json()["path"]
admin.post("/api/import", json={"book": "b", "statements": [path]})
month = admin.get("/api/month?book=b&sheet=APR").json()
sale = next(r for r in month["rows"] if r["income"] == 1150)
jaycar = next(r for r in month["rows"] if r["expense"] == 115)
assert jaycar["gst"] == "Incl GST" and jaycar["gst_out"] == 15.0
# mark the sale as GST-inclusive and allocate it
r = admin.post("/api/row", json={"book": "b", "sheet": "APR", "row": sale["row"], "gst": "Incl GST", "category": "Sales"})
updated = next(x for x in r.json()["rows"] if x["row"] == sale["row"])
assert (updated["gst_in"], updated["category"], updated["unallocated"]) == (150.0, "Sales", 0)
assert admin.post("/api/row", json={"book": "b", "sheet": "APR", "row": sale["row"],
"category": "Purchases"}).status_code == 400
assert admin.post("/api/row", json={"book": "b", "sheet": "APR", "row": sale["row"],
"gst": "Maybe"}).status_code == 400
p = admin.get("/api/gst?book=b&frequency=six").json()["periods"][0]
assert p["due"] == "2026-10-28"
b = p["boxes"]
assert (b["5"], b["6"], b["8"], b["11"], b["12"], b["15"]) == (1150, 0, 150.0, 115, 15.0, 135.0)
# zero-rated sales count in boxes 5 and 6 but carry no GST
admin.post("/api/row", json={"book": "b", "sheet": "APR", "row": sale["row"], "gst": "Zero-rated"})
b = admin.get("/api/gst?book=b").json()["periods"][0]["boxes"]
assert (b["5"], b["6"], b["7"], b["8"], b["15"]) == (1150, 1150, 0, 0.0, -15.0)
two = admin.get("/api/gst?book=b&frequency=two").json()["periods"]
assert [(x["end"], x["due"]) for x in two][:1] == [("2026-05-31", "2026-06-28")]
assert two[-1]["due"] == "2027-05-07"
def test_other_years_are_skipped(admin):
admin.post("/api/books", json={"name": "old", "year": 2020})
path = upload(admin, "april.csv", SAMPLE_CSV).json()["path"]
preview = admin.post("/api/preview", json={"book": "old", "statements": [path]}).json()
assert {p["status"] for p in preview} == {"wrong year"}
result = admin.post("/api/import", json={"book": "old", "statements": [path]}).json()
assert sum(r["added"] for r in result) == 0
def test_csv_export(admin):
admin.post("/api/books", json={"name": "b", "year": 2026})
path = upload(admin, "april.csv", SAMPLE_CSV).json()["path"]
admin.post("/api/import", json={"book": "b", "statements": [path]})
r = admin.get("/api/export?book=b&format=csv")
assert r.status_code == 200
assert 'filename="b.csv"' in r.headers["content-disposition"]
lines = r.content.decode("utf-8-sig").splitlines()
assert lines[0].startswith("Date,Month,Reference")
assert len(lines) == 6
assert admin.get("/api/export?book=b&format=pdf").status_code == 400
assert admin.get("/api/export?book=nope&format=csv").status_code == 404
def test_statement_management(admin):
r = upload(admin, "notes.csv", "a,b\n1,2\n")
assert r.status_code == 400 and "ANZ" in r.json()["detail"]
assert upload(admin, "evil.sh", "x").status_code == 400
path = upload(admin, "april.csv", SAMPLE_CSV).json()["path"]
r = upload(admin, "again.csv", SAMPLE_CSV)
assert r.status_code == 400 and "already here" in r.json()["detail"]
view = admin.get("/api/statement", params={"path": path}).json()
assert len(view["transactions"]) == 5
assert admin.get("/api/statement/file", params={"path": path}).text.startswith("Type,Details")
assert admin.get("/api/statement/file", params={"path": "/etc/passwd"}).status_code == 400
new_path = admin.post("/api/statement/rename", json={"path": path, "name": "april-2026.csv"}).json()["path"]
assert new_path.endswith("april-2026.csv")
assert admin.post("/api/statement/rename", json={"path": new_path, "name": "x.pdf"}).status_code == 400
assert admin.post("/api/statement/delete", json={"path": new_path}).status_code == 200
assert admin.get("/api/statements").json() == []
def test_csv_and_pdf_of_same_period_dont_double_up(admin):
"""Matching is on date and amount, so differently-worded copies are recognised."""
admin.post("/api/books", json={"name": "b", "year": 2026})
first = upload(admin, "a.csv", SAMPLE_CSV).json()["path"]
shouty = CSV_HEADER + "\n".join(line.upper() for line in SAMPLE_CSV.splitlines()[1:]) + "\n"
second = upload(admin, "b.csv", shouty).json()["path"]
result = admin.post("/api/import", json={"book": "b", "statements": [first, second]}).json()
assert sum(r["added"] for r in result) == 5
+62
View File
@@ -0,0 +1,62 @@
from conftest import SAMPLE_CSV
def setup_book(admin):
admin.post("/api/books", json={"name": "b", "year": 2026, "opening_balance": "100"})
path = admin.post("/api/upload?filename=april.csv", content=SAMPLE_CSV.encode()).json()["path"]
admin.post("/api/import", json={"book": "b", "statements": [path]})
rows = admin.get("/api/month?book=b&sheet=APR").json()["rows"]
sale = next(r for r in rows if r["income"] == 1150)
jaycar = next(r for r in rows if r["expense"] == 115)
admin.post("/api/row", json={"book": "b", "sheet": "APR", "row": sale["row"], "gst": "Incl GST", "category": "Sales"})
admin.post("/api/row", json={"book": "b", "sheet": "APR", "row": jaycar["row"], "category": "Purchases"})
def values(data, form):
return {r["box"]: r["value"] for r in data[form.lower()]["rows"] if r["box"]}
def test_ir10_from_cashbook(admin):
setup_book(admin)
data = admin.get("/api/tax?book=b").json()
v = values(data, "IR10")
assert v["2"] == 1000.0 # sales excluding GST
assert v["4"] == 100.0 # purchases excluding GST
assert v["6"] == 900.0
assert v["24"] == 8.5 # bank fees
assert v["27"] == 891.5
assert v["31"] == round(100 - 8.5 - 115 + 1150 + 500 - 5.53, 2) # bank balance at year end
assert v["57"] == 0.0
assert any("isn't allocated" in n for n in data["ir10"]["notes"]) # the Hetzner payment
assert any("funds introduced" in n for n in data["ir10"]["notes"])
def test_adjustments_and_ir4(admin):
setup_book(admin)
# depreciation, closing stock and RWT; tax to pay at 28%
admin.post("/api/tax", json={"book": "b", "form": "IR10", "box": "13", "value": 91.5})
admin.post("/api/tax", json={"book": "b", "form": "IR10", "box": "5", "value": 50})
data = admin.post("/api/tax", json={"book": "b", "form": "IR4", "box": "30K", "value": 100}).json()
v10, v4 = values(data, "IR10"), values(data, "IR4")
assert (v10["6"], v10["25"], v10["29"]) == (950.0, 100.0, 850.0)
assert (v4["20B"], v4["29"], v4["30A"], v4["30B"]) == (850.0, 850.0, 850.0, 238.0)
assert v4["30L"] == 138.0
assert data["ir4"]["result"] == {"amount": 138.0, "kind": "to pay"}
# adjustments add to the cashbook figure, and clearing one removes it
data = admin.post("/api/tax", json={"book": "b", "form": "IR10", "box": "2", "value": -1000}).json()
assert values(data, "IR10")["2"] == 0.0
assert data["ir4"]["result"]["kind"] == "refund" # a loss: no tax, provisional tax comes back
data = admin.post("/api/tax", json={"book": "b", "form": "IR10", "box": "2", "value": None}).json()
assert values(data, "IR10")["2"] == 1000.0
def test_tax_inputs_are_checked(admin):
setup_book(admin)
assert admin.post("/api/tax", json={"book": "b", "form": "IR10", "box": "29", "value": 1}).status_code == 400
assert admin.post("/api/tax", json={"book": "b", "form": "IR3", "box": "1", "value": 1}).status_code == 400
assert admin.get("/api/tax?book=nope").status_code == 404
def test_tax_needs_sign_in(client):
assert client.get("/api/tax?book=b").status_code == 401