Vehicle Registry

A platform that hands out identities has to remember that it did. The Vehicle Registry is the component that answers three questions an operator will ask on the first day:

• Which vehicle identities does this platform know about?
• Who issued each one, and when?
• Which of them is this user allowed to see?

It is a small service — base-services/vin-registry — and it does exactly one thing: it records issuance events, and it turns a successful issuance into fleet membership.

---

What gets recorded

Every certificate issuance produces one event. The registry keeps an append-only list of them, so a VIN that is re-registered later simply gains another entry rather than overwriting the first.

Field	Meaning
vin	the vehicle the event is about
source	which service issued it — factory-helper or registration
action	factory-certificate-issued or operational-certificate-issued
result	success or failure
detail	optional free text
created_at	when the event was recorded

source, action and result are closed sets rather than free text: these are the values an operator groups and filters by, and a typo in a calling service would otherwise create a second, silent category.

Events, not a vehicle list

The registry stores what happened, not a current-state table of vehicles. The per-vehicle view you see in FleetView — first seen, last seen, number of events, last action and its result — is derived from the event list when you ask for it. Opening a vehicle in that view shows the underlying events themselves.

---

Who reports to it

Two services report, and both are certificate issuers:

Service	Reports
Registration Server	an operational certificate was issued to a VIN
Factory Helper	a factory certificate was issued to a VIN

Reporting is best effort, by design. The call is detached from the request that triggered it and carries a two-second timeout; if the registry is slow, broken or not deployed at all, the issuing service logs it and continues. A vehicle never fails to get its certificate because the registry is unavailable.

The consequence is worth stating plainly: a report made while the registry was down is lost. There is no retry and no later reconciliation against the certificate authorities — recovering such gaps is not part of this release.

Optional by construction

Both issuers take the registry’s address from their configuration. If it is empty, they do not report at all, and the rest of the platform behaves exactly as before. The registry is a companion, never a dependency.

---

How a vehicle reaches a fleet

This is the part that makes the registry more than a log.

1. A certificate is issued The registration server or the Factory Helper signs a certificate for a VIN and reports the event.

2. A successful issuance enrols the vehicle In the same database transaction as the event, the registry adds the VIN to the fleet nexus-fleet. A failed attempt is recorded but enrols nothing — it is worth knowing about, but it should not put a vehicle in front of anyone’s eyes.

3. A user sees the vehicles of their own fleets FleetView reads the user’s group memberships from their Keycloak token and shows the vehicles enrolled in those groups.

Re-registering a vehicle does not create a second membership; enrolment is idempotent.

What this means in practice

A user sees a vehicle when both are true: the issuance succeeded, and the user is a member of the matching Keycloak group. A user who is in no group sees nothing, and that is the intended default.

Two roles matter:

Keycloak object	Effect
Group nexus-fleet	membership shows the vehicles the platform has enrolled
Realm role nexus-admin	sees every recorded identity, including ones that belong to no fleet

nexus-admin exists because of the failure case: an issuance that did not succeed is never enrolled anywhere, so a purely group-scoped view would hide exactly the entries an operator needs to look at.

Who you put in nexus-fleet

Every issued VIN joins this group, so anyone in it sees every vehicle on the platform. For a workshop or a shared environment where each participant should only see their own vehicle, create a separate group per participant and enrol the VIN there as well — a vehicle can belong to several groups.

Fleet membership governs more than the registry page: the telemetry views are filtered through the same mechanism, so a vehicle that is not in one of your groups is not visible there either.

---

Reaching the service

The registry is an internal component. It runs in the base-services namespace and is reachable only from inside the cluster; the two issuing services report to it there, and FleetView reads from it. Everything a user sees goes through FleetView, which requires a signed-in session and applies the group filtering described above.

Its interface is deliberately small:

Endpoint	Purpose
POST /v1/events	record an issuance, and enrol the VIN on success
GET /v1/vins	the per-vehicle summary FleetView renders
GET /v1/vins/{vin}/events	one vehicle’s history, newest first
GET /health	liveness and readiness

---

Not in this release

• One fleet. Every issued VIN joins nexus-fleet. Several fleets managed by the platform itself would be a schema and interface change, not a setting.
• No reconciliation. The registry does not compare itself against the certificate authorities, so reports lost during an outage stay lost.
• No revocation. The registry records issuance; it does not withdraw an identity.