QDat.io Support Portal

1. Breaking change — `Sensor` → `Tag`

The entity Sensor was renamed to Tag across the entire stack. The end-user UI, MQTT topic stream, and log strings already spoke in "tags"; this brings code, API, and DB schema into agreement.

• •Database tables: sensor, sensorreading, sensorevent, sensortemplate, sensoralert → tag, tagreading, tagevent, tagtemplate, tagalert. Foreign-key columns sensor_id → tag_id. Field Sensor.tag_type (RFID chip family) renamed to Tag.chip_type to free the slot for the entity-type enum (Sensor.sensor_type → Tag.tag_type). PostgreSQL enum types renamed in lockstep. Migration: o5k6l7m8n9o0_rename_sensor_to_tag.
• •REST API: /sensors, /sensor-templates → /tags, /tag-templates. Pydantic schemas Sensor* → Tag* (response payload keys change).
• •Frontend: route paths /sensors, /sensor-detail, /sensor-form, /sensor-templates → /tags, /tag-detail, /tag-form, /tag-templates. i18n namespace sensors → tags (translated values were already "Tag"/"Tags" in en/fr/es; only key names changed).
• •CLI: qdat-cli sensor … → qdat-cli tag ….

External clients consuming the old paths must update. The auto-generated frontend SDK regenerates on npm run generate-client and produces the new identifiers automatically.

2. Digital Product Passport

• •Public DPP pages at https://<dpp_host>/<EPCID-or-UID> (no auth). Every QDatDroid-provisioned tag URL now renders an operator-authored page with HERO / IDENTITY / SPECS / LOCATION / PROVENANCE / DOCUMENTS / MATERIALS / CONTACT / QR / CUSTOM_HTML / CUSTOM_JSON_LD sections. The section list and per-section visibility are template-driven; visible fields are gated by a closed allowlist (DppExposableTagField) so adding a column to Tag never auto-leaks it.
• •`PassportTemplate` entity — branding (logo, primary/accent colour, font), ordered section list, visible-field allowlist, auto-bind matchers (chip_manufacturer, cin_brand, nfc_ic_manufacturer, tag_type). Exactly one default per organisation (partial unique index). Bound to tags via Tag.dpp_template_id, with dpp_binding_locked honoured by the ingester auto-bind hook.
• •Admin UI at /admin-dpp with three sub-pages: templates (list, name, default badge, section count, branding swatch, auto-bind matchers), bindings (every tag with its bound template, lock state, clickable public URL), and settings (edit Organisation.dpp_host, view DPP_PUBLIC_ENABLED status and rate-limit).
• •`Tag.url` field on the tag edit form, so operators can set the public DPP URL directly instead of waiting for the next SCAN.
• •Ingester auto-bind hook — on every newly-discovered tag the MQTT ingester runs PassportTemplateRepository.find_auto_bind_match() (same priority axes as the operational TagTemplate matcher) and binds the tag's dpp_template_id unless dpp_binding_locked is set.

3. Demo mode

• •All admin cards visible in demo mode — backend endpoints stay gated by forbid_in_demo_mode, so a visitor clicking through gets a 403 toast rather than a destructive action.
• •Enable/disable confirmation dialogs itemise everything that will be added (Demo org, readers, tags, DPP template, synthesizer) and everything removed (non-protected-org data, API tokens, reader MQTT credentials), plus the operational consequences of disabling.
• •Expanded seed mix — one of every tag kind (TEMPERATURE, TEMPERATURE_DATALOGGER, GENERIC, NFC type V, NFC type A), two readers (UHF FX9600 + a bogus-Android-device-ID NFC phone), all with mqtt_credentials_active=False so they look like decommissioned hardware. Each tag gets a 4 000-row TagReading backfill at ~20 °C with Montréal coords + jitter (~2.8 days of history).
• •Demo seed claims the cluster's public DPP host for the Demo org on enable (saving the prior owner in system_setting, restored on disable); every seeded tag's Tag.url is populated as https://<host>/<EPCID> so demo public DPP pages just work.
• •Login restructured under demo and the demo banner mounts in __root.tsx so it shows on the login screen too.

4. Security — login IP banning

After N failed logins from one IP in a rolling M-second window, an IpBan row is inserted with banned_until = now() + ban_seconds. The /login/access-token endpoint refuses banned IPs with HTTP 429 + Retry-After before any password verification runs. Tunables (enabled, attempts_threshold, window_seconds, ban_seconds) live in system_setting and are editable at a new admin page /admin-ip-bans, which also lists active bans with a per-row Unban action.

5. Fixes (backend)

• •Reader.lat / lon typed float | None on ReaderBase (and therefore ReaderRead), matching the nullable DB column — without this every reader-list endpoint threw ResponseValidationError for any reader that hadn't been geolocated.
• •AuthEventTypeEnum gained the four DEMO_* values (DEMO_MODE_ENABLED, DEMO_MODE_DISABLED, DEMO_PURGE_RUN, DEMO_VISITOR_SESSION_CREATED) that migration n0o1p2q3r4s5 had already added to Postgres; without them every demo lifecycle action threw AttributeError inside record_auth_event.
• •DemoService._create_visitor_user no longer calls int(Flag) (rejected by Python 3.10's Flag); uses .value so visitor users get their ResourceTypePermission rows.
• •Visitor emails use @demo.qdat.io instead of @demo.local (Pydantic's EmailStr rejects RFC 6762 reserved TLDs).
• •Demo seed sets Reader.role (NOT NULL constraint).
• •BACKEND_CORS_ORIGINS now allows the apex host too.

6. Migrations & infrastructure

• •New backend settings: DPP_PUBLIC_ENABLED (kill-switch — public resolver returns 404 when false), DPP_RATE_LIMIT, DPP_CACHE_MAX_AGE_SECONDS.
• •IpBan* admin endpoints under /admin/ip-bans (superuser-only, include_in_schema=False).
• •cert-manager.yaml Certificate gains APEX_HOST_PLACEHOLDER so the bare instance host is in the cert SANs.

1. DPP rules engine

• •`PassportTemplate.rules` — a JSON column storing operator-authored rewrite rules evaluated on every public DPP resolve. Each rule carries an optional geo block (within X metres of lat/lon, anchored on tag.last_lat/last_lon) and an optional time block (X minutes/hours/days since tag.last_seen_at). When both are set the rule fires only if every condition holds — spatiotemporal AND. On ties, a rule carrying a geofence beats a time-only rule. The public response now carries redirect_url + redirect_reason (geo / time / spatiotemporal); the SPA hands the visitor off via window.location.replace. Migration v8w9x0y1z2a3.
• •`PassportTemplate.auto_bind_tag_template_id` — new FK so a DPP template can bind directly to a TagTemplate row rather than duplicating the matching axes. It is the highest-priority axis in PassportTemplateRepository.find_auto_bind_match, threaded through both auto-bind call sites (REST upsert + MQTT ingest).
• •Ingester evaluates rules at SCAN time — _process_inventory_result_inner reuses _evaluate_template_rules after the SCAN writes the freshly-scanned GPS + last_seen_at to the tag. When a rule fires, the TAG_REGISTERED ack on devices/<topic_id>/command carries the rule-corrected redirect_url + redirect_reason, so clients can override the NFC-encoded URL the visitor would otherwise land on.
• •Map-driven geofence picker — the /admin-dpp/templates new-rule UI gains Photon civic-address autocomplete, a Leaflet OSM map with draggable marker and tunable radius circle, and synced lat / lon / radius inputs.

2. Admin UI polish (backend-relevant)

• •`/admin-dpp/templates` editor replaces the read-only stub: create/edit templates (PUT /passport-templates/{id}), bulk-select + delete, and a rules editor with the same bulk-select pattern.
• •Tile gating during demo mode — eight destructive tiles are greyed in /admin, and the matching backend mutations gain a forbid_in_demo_mode dependency so a CLI poke gets a matching 403 instead of mutating sandbox state.
• •Demo enable/disable/purge envelope — admin demo mutations now always respond with the canonical settings shape ({enabled, …, error?: {code, message}}) on every path, catching in-flight DB rollbacks that used to drop CORS headers and leave the dashboard with an unactionable "blocked by CORS" error.
• •`/admin-dpp/settings` removed — its only interactive control (the dpp_host editor) already lives on the org-edit form.
• •Demo seed completes the Cooltag hierarchy — seeds Tag Templates Cooltag-Opus / Cooltag-NFC-V, Passport Templates auto-bound to them carrying two seeded rules (geofence at Montréal City Hall + 5-min elapsed), and rebinds the seeded OPUS Datalogger / NFC-V demo tags through that hierarchy so tapping either tag exercises the rules engine end-to-end.

3. Fixes (backend)

• •Demo purge now also drops Manufacturer / Representative / DppRecord (DppRecord first because it FKs into both); re-enable previously crashed with a UniqueViolation on ix_manufacturer_org_name.
• •`Manufacturer.id` / `Representative.id` / `DppRecord.id` gained default_factory=uuid4 — they were default=None, so the seeder sent NULL into NOT-NULL PK columns and the scheduled auto-purge silently retried the crash every minute.
• •`TagEvent.lon`/`lat` / `TagReading.lon`/`lat` made nullable — phone-tethered readers and TapDPP devices have no GPS; better to record NULL than fail the whole SCAN batch (which used to roll back the tag-metadata updates and the TAG_REGISTERED ack alongside). Migration u7v8w9x0y1z2.
• •`IntegrityError` on a SCAN batch now logs `e.orig` so the next collision names the firing constraint.

4. Migrations

1. Overview

A QDAT cluster previously had no concept of a *device licence*. The License Manager adds one. It is single-instance and device-keyed, not scoped to an organisation: a licence binds to a device_id — the stable per-install identifier the QDatDroid client sends — rather than to a user or department.

The feature has two surfaces, both mounted under the /api/v1/licenses prefix:

1. A public, device-facing API (no authentication, rate-limited) that the Android client calls directly: request a trial, validate, revoke, sync telemetry, and request a managed licence. 2. An admin API (superuser only, hidden from the public OpenAPI schema) that backs the /licenses console: mint, list, update/revoke, delete, and approve or reject managed requests.

A device's full life-cycle is therefore: **request → (auto-grant trial *or* admin approval) → validate on launch → sync usage → renew / revoke.**

2. Data model

Three new tables were added (backend/app/models/license.py).

license

One licence row, bound to a device_id.

license_lead

A sales lead captured when a trial is requested (email, name, product, optional claim_token minted by the qdat.io download page to join a web lead).

license_request

A managed licence request raised by a device. The device POSTs its device_id; the row sits pending until a superuser approves it (minting a License bound to the same device_id) or rejects it. The device re-POSTs the same endpoint to poll and, once approved, download the licence. Carries device telemetry captured at request time (app_version, reader_model, tier, requested_max_tags) to help the admin decide, plus an admin note surfaced back to the device and the license_id it resolved into.

3. Public device-facing API

All five endpoints are unauthenticated and rate-limited to 30 requests/minute per client. Field names match exactly what the QDatDroid client serialises/deserialises.

Every response embeds a license object (key, product, status, customer, max_tags, expires_at, days_remaining, the trial/activated/subscription flags). The trial response additionally carries the flat mqtt and device blocks described next.

4. MQTT credentials delivered on the trial API

This is the headline integration change. POST /request-trial now does more than mint a licence — when the cluster is in demo mode, it also provisions a broker identity for the device and returns it inline, so QDatDroid is fully connected after a single call.

On a successful trial the response carries two flat top-level blocks alongside license (the same shape as the combined provisioning QR):

• •`mqtt` — host, port, wss_port, tls, username, password.
• •`device` — topic_id and the three resolved topics: devices/<topic_id>/{command,response,data}.

Mechanics and safety:

• •Provisioning reuses the existing TapDPP self-provision path (DemoService.provision_tapdpp_reader): a Demo-org reader plus a Mosquitto dynamic-security user. It is idempotent per `device_id`, and the password rotates on every call.
• •It is best-effort: if demo mode is off (or provisioning fails), the trial still returns a licence-only response and no broker credentials are minted. The demo-mode gate short-circuits *before* any reader or dynsec client is created, so a cluster with demo mode off never hands out Mosquitto credentials over the internet.

5. Combined provisioning wizard & QR

• •Combined provisioning wizard — a pending license request on /licenses launches an optional 3-step flow inside /reader-form: respond to the request (shows the Android Device ID + timestamp, sets the licence terms and approves), create the RFID reader using the Device ID as a quasi-MAC (device_model = QDATDROID, no MAC-format validation) with MQTT credentials, then display one large combined QR. The plain reader form is unchanged when no requestId is present.
• •Combined `qdat-provisioning` QR (v1.0) — a single self-describing envelope carrying license + mqtt + device (the devices/<topic_id>/{command,response,data} topics) so the client provisions licence and broker connection in one scan. Documented in docs/standards/QR_ENVELOPE_CONVENTION.md.

6. Admin API and console

The admin surface (superuser only, include_in_schema=False) backs the /licenses console.

The console gained per-row and bulk delete of revoked licences, Created and Days-left columns, a customer Email column, and a horizontally scrollable table.

7. Audit trail

License life-cycle events are now written to the auth audit trail (visible at /admin-audit). Three values were added to the autheventtypeenum Postgres enum:

• •`LICENSE_CREATED` — on hand-mint, on request approval, and on auto-granted trials (logged once, on the first mint).
• •`LICENSE_REVOKED`
• •`LICENSE_DELETED`

Each event records the acting admin (null for anonymous trials), the client IP, and metadata (key, device_id, max_tags, source).

8. Reader model change

To let the same machinery provision the Android device as a "reader", two backing changes were made to the reader model:

• •`reader.mac_address`: `MACADDR` → `VARCHAR(128)` — so the column can hold a non-MAC device identity (the Android Device ID). The application-level uniqueness check already lower-cases and casts to text, so it works for arbitrary strings.
• •New `QDATDROID` value on `readermodelenum` — identifies an Android client acting as a reader, alongside the existing FX7500 / FX9600 / AR.

9. Migrations

1. Bug fix — `request-license` re-queue

A device whose previous request had already resolved (approved *or* revoked) could re-POST /request-license and receive a lodged 200 while no new pending row was actually persisted — so a revoked device's renewal never reappeared in the console. The endpoint now lodges a fresh pending request for any non-pending latest state, making renewals reliable.

2. New-vs-renewal context

Each pending request in the console now shows a Type badge (*New* when the device has no prior licence, *Renewal* otherwise), the device's most-recent prior licence (key + status — typically the revoked one prompting the re-request), and the request timestamp. This is backed by three derived (not stored) fields on the admin request view — is_new, previous_license_key, previous_license_status — computed by looking up the device's prior licence. No schema migration was required.

3. Migration

Both production clusters are at head r8s9t0u1v2w3. alembic upgrade head runs the whole chain.

1. Bug fix — `request-license` dropped while on a trial

request_license() opened with an auto-issue short-circuit: if the device already held an active license, it handed that license straight back with 200 and returned *before* lodging a LicenseRequest. Because _is_active() counts an unexpired trial as active, a device on a trial that asked for a full (managed) license got its trial echoed back and no pending request was ever persisted — so the request never appeared in the /licenses console.

The short-circuit now excludes trials (… and not active.is_trial): a trial holder asking for a full license falls through and always lodges a pending request. A device with a real (non-trial) active license still re-downloads it without creating a duplicate request. A license request is therefore never silently dropped.

2. Approval replaces the trial

When a managed request is approved, the device's prior trial license(s) are moved to expired as the full license is minted, so the approved license is the single authoritative license for that device_id (the bind key — get_by_device_id returns one row). A new LicenseRepository.list_by_device_id() backs this.

3. Files touched

• •app/services/license.py — request_license() trial exclusion; approve_request() trial expiry.
• •app/repositories/license.py — new list_by_device_id().
• •app/tests/services/test_license_service.py — regression coverage (request always logged; idempotent refresh; trial expired on approval).

1. The problem

The wizard's step 2 creates the RFID reader with the Android Device ID as a quasi-MAC. If a reader already owned that device id — e.g. the device had a prior trial-provisioned reader — POST /api/v1/readers/ returned 409 MAC address already in use by reader '<name>' …, and provisioning dead-ended.

2. The fix — re-bind instead of fail

POST /api/v1/readers/ gains a `rebind` query flag. When rebind=true and a reader already owns the supplied MAC / device id, the endpoint updates that existing reader in place — moves it to the target organization and refreshes its fields (device_model = QDATDROID, name, role) — and returns it, rather than raising 409 or creating a duplicate. The reader is never deleted; the same MQTT identity (reader.id) is preserved, and the wizard regenerates its MQTT credentials for the combined QR. Non-superusers may only re-bind a reader they can already see (else 403).

In the console the wizard surfaces a confirmation on the conflict: re-bind the existing reader (moving it to the selected org, setting QDATDROID, and regenerating its MQTT credentials) or cancel.

3. Files touched

• •app/api/routes/reader.py — rebind flag on create_reader; in-place re-bind path.
• •app/services/reader.py — public get_by_mac_address().
• •app/tests/api/routes/test_reader_mac_uniqueness.py — rebind=true reuses the existing reader (no duplicate; org moved).
• •frontend/src/routes/_layout/reader-form.tsx — wizard confirmation + rebind=true retry.