@@ -9,6 +9,8 @@ recursive-include fiscguy *.sql
 recursive-include fiscguy/migrations *.py
 recursive-include fiscguy/management *.py
 recursive-include fiscguy/tests *.py
+recursive-include fiscguy/templates *.html
+recursive-include fiscguy/static *
 
 global-exclude __pycache__
 global-exclude *.pyc
 
@@ -9,8 +9,6 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-<a href="https://otene.co.zw/projects/pypi" target="_blank" rel="noopener"><img src="https://otene.co.zw/badge/pypi" alt="Fiscguy on Otene" width="206" height="54" /></a>
-
 **The Modern Python Library for ZIMRA Fiscal Device Integration**
 
 FiscGuy gives Django applications a simple, Pythonic interface for every fiscal operation required by the Zimbabwe Revenue Authority — receipt submission, fiscal day management, certificate handling, and more. Built on Django REST Framework, it drops into any Django project in minutes.
@@ -173,10 +171,17 @@ For frontend integrations, call `POST /fiscguy/close-day/` once, then poll
 `GET /fiscguy/get-status/` until the fiscal day moves from `close_pending` to `closed` or
 `close_failed`.
 
+### Web UI
+
+Optional pages for registration, certificate upload, fiscal day control and receipts, protected by
+login, permissions, password re-confirmation, CSRF, throttling and an audit log. Off by default;
+see [docs/web-ui.md](docs/web-ui.md). The JSON endpoints are staff-only unless you set
+`FISCGUY_PERMISSION_CLASSES`.
+
 ### HS Code Mapping
 
 FiscGuy supports `hs_code` on receipt lines and passes it through to FDMS as
-`receiptLineHSCode`.
+`receiptLineHSCode`. It is optional; a blank code is sent as-is.
 
 Firms should map their product and service catalogues to the correct FDMS-compatible HS codes
 before going live. In practice, this means:
 
@@ -3,6 +3,68 @@
 All notable changes to Fiscguy are documented in this file.  
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-10-22
+
+### Added
+- Optional web UI (`fiscguy.web.urls`): device list, registration with an activation key,
+  registration with an uploaded certificate and key, fiscal day open/close with status polling,
+  certificate renewal, configuration sync and receipt browsing. Off unless `FISCGUY_UI_ENABLED`.
+  See `docs/web-ui.md`.
+- Permissions `manage_device`, `close_day` and `view_receipts`.
+- `AuditLog` model (read-only in admin) recording registrations, certificate changes and day open/close.
+- Services `DeviceRegistrationService`, `ManualDeviceRegistrationService` and `cert_bundle`
+  (certificate and key parsing, validation, expiry and key-match checks).
+- `FISCGUY_PERMISSION_CLASSES`, `FISCGUY_ACCESS_CHECK`, `FISCGUY_DEVICE_QUERYSET`,
+  `FISCGUY_CLOSE_POLL`, `FISCGUY_LOG_FDMS_PAYLOADS` and `FISCGUY_REAUTH_MAX_AGE` settings.
+- System checks `fiscguy.W001` (no dedicated encryption key) and `fiscguy.W002` (UI without secure cookies).
+- Optional `?device_id=` selection on the JSON endpoints.
+- Migrations `0015` and `0016`.
+
+### Changed
+- **Breaking:** JSON endpoints now require staff by default instead of being open. Set
+  `FISCGUY_PERMISSION_CLASSES` to your own classes to change this.
+- Device activation keys are encrypted at rest (existing values are encrypted by migration `0016`)
+  and hidden from the Django admin.
+- FDMS request and response bodies are no longer logged by default; error responses are logged
+  truncated. Enable `FISCGUY_LOG_FDMS_PAYLOADS` to log bodies at DEBUG.
+- `FISCGUY_CLOSE_POLL = "client"` skips the background close-day thread. The default is unchanged.
+- Open day, close day and certificate renewal through the API are audited.
+
+## [0.1.9] - 2026-10-22
+
+### Added
+- `ZIMRA_PROXY` environment variable to route FDMS traffic through a proxy.
+- `Taxes.is_standard`, set at config sync by matching the tax name (ZIMRA taxIDs are per
+  taxpayer), falling back to the highest non-withholding rate.
+- `Receipt.fiscal_day_no`, stamped at submission and exposed in the receipt serializer.
+- `qr_code_data` (base64 PNG data URI) on receipt responses.
+- Nested `tax_type` (code, name, percent) on receipt lines in receipt responses.
+- `has_validation_errors` in the submit result when FDMS returns red validation errors; the
+  receipt is kept and the errors are logged.
+- `GET /fiscguy/receipts/{id}/` is now routed.
+- Tests for by-tax close-day payloads, standard-tax detection, proxy opt-in and device-scoped signing.
+- Migration `0014`.
+
+### Changed
+- Receipt numbers and `invoiceNo` are now `<device_id>-<global_no>` instead of `R-<global_no>`.
+  `receipt_number` is unique per device rather than globally.
+- `ZIMRACrypto` signs with the certificate of the given `device`, and raises `CryptoError`
+  without a device or `private_key_path` instead of using any stored certificate.
+- Credit and debit note references resolve against the same device only.
+- Opening a fiscal day is refused while the open day is `close_pending` or `close_failed`.
+- A new device with no `lastFiscalDayNo` or `lastReceiptGlobalNo` from FDMS is treated as 0.
+- `hs_code` is no longer required on fiscal invoice lines.
+- `DevicePing` returns `online: true`, or `online: false` with 503 when FDMS is unreachable.
+  Pings time out after 8 seconds.
+- FDMS requests and responses are logged in full, including the response body on errors.
+- `DeviceSerializer.activation_key` is write-only.
+- `init_device` looks up the certificate by the device being registered.
+
+### Fixed
+- `ReceiptDetailView` queried a non-existent `receipt_lines` relation.
+- Creating a buyer with only a name and TIN raised `KeyError`.
+- The buyer router was registered as `buyer/`, producing a broken URL pattern.
+
 ## [0.1.8] - 2026-05-03
 
 ### Added
 
@@ -142,6 +142,11 @@ To switch environments, re-run `init_device`.
 
 ---
 
+## Routing FDMS traffic through a proxy
+
+Set `ZIMRA_PROXY` (for example `http://host:8889`) to send FDMS calls through a proxy. It is
+read only for ZIMRA traffic and is not the same as `HTTPS_PROXY`. Leave it unset to connect directly.
+
 ## Development Dependencies
 
 ```bash
 
@@ -56,7 +56,7 @@ receipt = submit_receipt({
     "total_amount": "-115.00",          # Must be <= 0
     "payment_terms": "Cash",
     "credit_note_reason": "Customer returned goods — defective",
-    "credit_note_reference": "R-00000142",  # Original receipt number
+    "credit_note_reference": "41872-00000142",  # Original receipt number
     "lines": [
         {
             "product": "Product Name",
@@ -105,7 +105,7 @@ receipt = submit_receipt({
     "total_amount": "23.00",
     "payment_terms": "Card",
     "debit_note_reason": "Additional delivery charge",
-    "debit_note_reference": "R-00000142",
+    "debit_note_reference": "41872-00000142",
     "lines": [
         {
             "product": "Delivery fee",
@@ -181,7 +181,8 @@ recommended flow is:
 
 ### HS Code Guidance
 
-- `hs_code` should be included in receipt-line payloads for normal invoice flows
+- `hs_code` should be included in receipt-line payloads for normal invoice flows; it is optional
+  and a blank code is sent through rather than rejecting the sale
 - Firms should map their product and service catalogues to the correct FDMS-compatible HS codes
 - Credit notes can inherit `hs_code` from the referenced original receipt line
 - Debit notes can inherit `hs_code` from the referenced original receipt line or, for
 
@@ -0,0 +1,72 @@
+# Web UI and security
+
+Fiscguy ships optional pages for device registration, certificate upload, fiscal day control,
+status polling and receipts. They are off by default.
+
+## Enable
+
+```python
+# settings.py
+INSTALLED_APPS += ["django.contrib.sessions", "django.contrib.messages", "fiscguy"]
+FISCGUY_UI_ENABLED = True
+FISCGUY_ENCRYPTION_KEY = "<Fernet key>"   # python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+
+# urls.py
+path("fiscal/", include("fiscguy.web.urls")),
+```
+
+The pages use the host's `LOGIN_URL`. Templates live under `fiscguy/` and can be overridden by
+placing files with the same names in your own `templates/fiscguy/` directory.
+
+## Settings
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `FISCGUY_UI_ENABLED` | `False` | Turns the pages on. When off they return 404. |
+| `FISCGUY_PERMISSION_CLASSES` | `["rest_framework.permissions.IsAdminUser"]` | DRF permissions for every JSON endpoint. |
+| `FISCGUY_ACCESS_CHECK` | none | `callable(request, action) -> bool` that replaces the page permission check. |
+| `FISCGUY_DEVICE_QUERYSET` | none | `callable(request) -> QuerySet[Device]` limiting which devices a request can see or act on. Use it to scope devices per customer, branch or user. |
+| `FISCGUY_CLOSE_POLL` | `"background"` | `"client"` stops the server thread; the page (or your frontend) polls `get-status` instead. |
+| `FISCGUY_LOG_FDMS_PAYLOADS` | `False` | Logs FDMS request and response bodies at DEBUG. They contain buyer TINs and receipt data. |
+| `FISCGUY_REAUTH_MAX_AGE` | `300` | Seconds a password confirmation stays valid. |
+| `FISCGUY_ENCRYPTION_KEY` | derived from `SECRET_KEY` | Fernet key for certificate keys and activation keys. |
+
+## Permissions
+
+| Permission | Allows |
+|---|---|
+| `fiscguy.view_receipts` | Dashboard, device pages, receipts, status and ping |
+| `fiscguy.close_day` | Open and close fiscal days |
+| `fiscguy.manage_device` | Register devices, upload certificates, renew, sync configuration, audit log |
+
+Superusers have all three. The JSON API is staff-only by default because it can submit receipts
+and close days; the old behaviour of open endpoints is gone. Set `FISCGUY_PERMISSION_CLASSES` to
+use your own classes.
+
+## What protects the pages
+
+- Feature flag, login and a specific permission on every view. Nothing is public.
+- Device lookups go through `FISCGUY_DEVICE_QUERYSET`, so a guessed device or receipt ID returns 404.
+- Every state change is POST-only with CSRF protection.
+- Registering, uploading certificates and renewing certificates need the user's password again
+  (valid for `FISCGUY_REAUTH_MAX_AGE` seconds). Switching a device between test and production
+  deletes its history and needs the device ID typed to confirm.
+- Per-user throttling on registration, actions, status, ping and password confirmation.
+- Responses carry `Cache-Control: no-store`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`
+  and a CSP that allows only same-origin scripts and styles. The templates have no inline script or style.
+- Keys and activation keys are write-only: never rendered back (even on a failed form), never logged,
+  encrypted at rest. Uploads are capped at 64 KB, read in memory, validated and never written to disk.
+- Passphrase-protected keys, expired certificates and key/certificate mismatches are rejected.
+- Every register, upload, renew, open day and close day is written to `AuditLog` (user, time, device, IP).
+  The log is read-only in the Django admin.
+
+`manage.py check` warns when `FISCGUY_ENCRYPTION_KEY` is unset (`fiscguy.W001`) and when the UI is
+enabled without secure cookies (`fiscguy.W002`).
+
+## Close day without a background thread
+
+With `FISCGUY_CLOSE_POLL = "client"`, `POST close-day/` returns as soon as FDMS accepts the request.
+Poll `GET get-status/` (API) or `devices/<id>/status/` (UI) until the day is `closed` or `close_failed`.
+The device page does this automatically.
@@ -1,6 +1,7 @@
 from django.contrib import admin
 
 from fiscguy.models import (
+    AuditLog,
     Certs,
     Configuration,
     Device,
@@ -26,7 +27,26 @@ def csr_preview(obj):
 
 admin.site.register(Configuration)
 admin.site.register(Taxes)
-admin.site.register(Device)
+@admin.register(Device)
+class DeviceAdmin(admin.ModelAdmin):
+    list_display = ("device_id", "org_name", "production", "created_at")
+    exclude = ("activation_key",)
 admin.site.register(FiscalDay)
 admin.site.register(Receipt)
 admin.site.register(FiscalCounter)
+
+
+@admin.register(AuditLog)
+class AuditLogAdmin(admin.ModelAdmin):
+    list_display = ("created_at", "actor_name", "action", "device_ref", "ip_address")
+    list_filter = ("action",)
+    readonly_fields = [f.name for f in AuditLog._meta.fields]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
@@ -1,6 +1,9 @@
 from django.apps import AppConfig
 
 
-#
 class FiscguyConfig(AppConfig):
     name = "fiscguy"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        from fiscguy import checks  # noqa: F401
@@ -0,0 +1,25 @@
+from loguru import logger
+
+from fiscguy.models import AuditLog
+
+
+def client_ip(request) -> str | None:
+    return request.META.get("REMOTE_ADDR") or None
+
+
+def record(request, action: str, device=None, detail: str = "") -> None:
+    """Write an audit row. Never raises and never receives key material."""
+    try:
+        user = getattr(request, "user", None)
+        authed = bool(user and user.is_authenticated)
+        AuditLog.objects.create(
+            actor=user if authed else None,
+            actor_name=(user.get_username() if authed else "")[:150],
+            action=action[:64],
+            device=device,
+            device_ref=(device.device_id if device else "")[:100],
+            detail=detail[:255],
+            ip_address=client_ip(request),
+        )
+    except Exception:
+        logger.exception(f"Failed to write audit log for {action}")
@@ -0,0 +1,30 @@
+from django.conf import settings
+from django.core.checks import Warning, register
+
+from fiscguy import conf
+
+
+@register()
+def fiscguy_security_checks(app_configs, **kwargs):
+    messages = []
+    if not getattr(settings, "FISCGUY_ENCRYPTION_KEY", None):
+        messages.append(
+            Warning(
+                "FISCGUY_ENCRYPTION_KEY is not set; certificate keys and activation keys are "
+                "encrypted with a key derived from SECRET_KEY.",
+                hint="Set a dedicated Fernet key in FISCGUY_ENCRYPTION_KEY and keep it out of the database backups.",
+                id="fiscguy.W001",
+            )
+        )
+    if conf.ui_enabled() and not settings.DEBUG:
+        if not getattr(settings, "SESSION_COOKIE_SECURE", False) or not getattr(
+            settings, "CSRF_COOKIE_SECURE", False
+        ):
+            messages.append(
+                Warning(
+                    "FISCGUY_UI_ENABLED is on but SESSION_COOKIE_SECURE or CSRF_COOKIE_SECURE is off.",
+                    hint="Serve the UI over HTTPS and set both to True.",
+                    id="fiscguy.W002",
+                )
+            )
+    return messages