One line of nats pub on cmd.> sends a command straight to a device. It skips arbitration, bands, suspension, interlocks and the audit trail, because all of those live in the core and the core is not on that path. Anything allowed to publish on that subject can do it. So in Sentinel the bus is the primary control surface, the HTTP API is the secondary one, and the permissions that say who may publish on which subjects are the real authorisation model.
Most of this part puts the weight on boundaries that already exist rather than adding new ones. Where the design adds nothing, it says so. There is no mTLS, no role hierarchy, no per-point permission and no defence behind the core, and each absence comes with the condition that would change it.
What this document owns: the threat model and the order effort goes in; the principal naming scheme shared by claims and credentials, and how each kind of principal is established; why rules hold no credentials; the core as one trusted principal with nothing behind it; the bus permissions that turn the subject layout into an authorisation surface; why subject scoping leaves point spoofing open, and the publisher check that closes it; human identity through forward auth, and the binding that makes it safe; the four capabilities; which bands the API can reach, and why suspend is separate from claim; the limits on the escape hatch; acting on behalf of a person; claim expiry against session expiry; secrets by reference, and their rotation; the one requirement that turns the control log into an audit log; the exposure assumption and what changes without it; and the deliberate absences, each with its trigger. It does not own the subject layout itself, which belongs to Driver Contract; the core epoch that lets a driver refuse a superseded core, which belongs to Core Runtime; the ingest stage that runs the publisher check, which belongs to Ingest Path & Log Schema; or bands, suspension and the escape hatch's command path, which belong to Command Plane.
What this defends against
In descending order of likelihood, which is also the order effort goes in:
- A compromised or hostile device on the local network. Consumer sensors and relays with firmware nobody audited. The likely case.
- A compromised driver host. A small computer on a segment, reachable, running drivers with credentials.
- Accident. A half-written script, a dashboard bug, a rule that should not have been at that band. Not malice, and the most frequent cause of damage.
- Remote exposure, if the UI ever becomes reachable from outside the network.
Explicitly not in scope: insider threat across a team, regulatory compliance, nation-state adversaries. This is a single-maintainer system, and a model that assumes otherwise generates role machinery that gets routed around at the moment something is broken. The cost of unusable security is that it stops being used.
Principals
There is one naming scheme for principals, shared between the claim model and the credential system, so an owner string in the claim log is the same string as the identity that produced it:
| principal | form | identity mechanism |
|---|---|---|
| driver host | host:rpi-c1 |
NATS NKey/JWT, one per host |
| core | system:core |
NATS NKey/JWT, one credential |
| read/UI/alert service | service:ui |
NATS credential for state, read-only Postgres role |
| person | user:alice |
forward auth at the proxy |
| rule | rule:frost-protect |
none — see below |
| registry default | system:default |
none — materialised by registry load |
mTLS is not used anywhere. It would be stronger and it is not worth the operational learning curve here. Machine identity uses NATS-native credentials, which are a file and a revocation list rather than a certificate authority to run.
Rules are not runtime principals and hold no credentials. A rule exists because a YAML file in the repository declared it, and its band was validated at registry load. Nothing on the network authenticates as a rule. This is worth stating plainly, because the instinct when securing a system is to issue every actor a credential, and doing that here would create a new path into the command plane that bypasses the registry.
The core is a single principal with broad rights, and its compromise is total. It holds the only credential that may publish commands, and it is the single writer described in Core Runtime. There is no defence in depth behind it and pretending otherwise would be theatre. The trust boundary sits at the core process, and everything else is about limiting what reaches it and what happens if something outside it is taken.
Bus permissions
Each credential carries NATS subject permissions, and those are the whole machine-authorisation model.
| principal | may publish | may subscribe |
|---|---|---|
host:{h} |
obs.{h}.>, avail.{h}.>, quarantine.{h}.>, cmdres.{h}.>
|
cmd.{h}.>, assign.{h}
|
system:core |
cmd.>, state.>, assign.>
|
obs.>, avail.>, quarantine.>, cmdres.>
|
service:ui |
nothing | state.> |
Two properties of the subject layout exist for this and are specified in Driver Contract.
Every driver-plane subject leads with a host segment. Subjects keyed on driver instance would mean a host running three instances needs three grants, and adding an instance to a host would require editing that host's credentials as well as its assignment. Two places to keep in step is one too many, and the one that gets forgotten is the credential. Prefixing by host makes one grant per host cover every instance it will ever run, and the permission becomes stable across assignment changes. The cost is one more subject token.
cmdres carries the driver instance. A subject of cmdres.{command_id} alone contains nothing scopeable, so every driver would need cmdres.> and any driver could forge a command outcome for any other driver's command.
Subject scoping does not stop point spoofing, and one ingest check does. A driver publishing obs.{its own host}.{its own instance}.boiler.ch1.flow-temp is inside its permissions even when that point belongs to a different instance entirely, because the core resolves points by point_id and does not otherwise check who sent them. One compromised host could then feed false readings to every interlock in the system.
The fix is a stage in the ingest pipeline, immediately after point resolution: the point's registry-assigned driver instance must match the publishing instance, or the observation is quarantined with reason wrong_instance. It is one comparison against a lookup already being performed, and without it the bus permissions are decorative for anything that matters.
Command authenticity runs the other way. A driver cannot verify that a command came from the legitimate core by subject permissions alone, because a driver cannot tell a stolen core credential from the real core. What it can check is that the command is not from a superseded instance, which is the core epoch described in Core Runtime.
Human identity
People sign in through forward auth at the proxy. The proxy terminates TLS, an identity provider authenticates the person, and the proxy injects the principal as a header that the core trusts.
The binding is the control, not the header. A header-trusting service reachable directly on the local network fails open: anyone who can reach the port asserts any identity they like. So the core's API listens on a unix socket, or on an interface only the proxy can reach, and the proxy is the only route rather than merely the usual one. If that binding is ever relaxed for convenience, the authentication model is gone and nothing will indicate it.
Absent principal is a rejection, never a default. No anonymous fallback, no service account the core assumes when the header is missing. A code path that cannot name its principal cannot write.
The principal string is used verbatim as the claim owner, so the value in the header is the value in the claim table and in every control_event it produces.
Capabilities, not roles. There are four, carried as a second header from the identity provider and mapped in the registry:
-
read— query state and history -
claim— set and withdraw claims at bandmanual -
suspend— suspend a named claim owner -
direct— use the commissioning escape hatch
A per-point permission matrix is deliberately not built. A few thousand points maintained by one person would rot within a month and then be trusted anyway.
Limits on each principal
Bands above manual are unreachable from the API. People claim at manual; so would any external machine client. schedule, safety and interlock are only ever reached by a rule whose band was declared in the registry and validated at load. Authorisation for those is therefore a git question — who can merge, who can deploy — not a runtime one, which is a better place for it: an interlock's band changes in a reviewable diff rather than in a request body.
suspend is a separate capability from claim, and this is the distinction worth enforcing. The right to turn on a light is not the right to switch frost protection off for thirty minutes. Collapsing them means a session in a phone browser can do both, which is exactly the credential most likely to be left logged in. suspend is never granted to a machine principal.
The escape hatch bypasses everything except interlock. direct permits a command that skips arbitration for commissioning and debugging, but an asserted interlock claim still wins. If the escape hatch could override a thermal cutout, the system would have no interlock at all. Enablement is modelled exactly like suspension — bounded, expiring, both edges in control_event — rather than as a second mechanism with its own semantics.
The read/UI/alert service acts on behalf of the person, not as itself. For any mutating call it forwards the end-user principal rather than substituting service:ui; otherwise every claim in the log reads as having been made by the UI and the audit trail is worthless for the question it exists to answer. service:ui is used only for its own read-only access: state.> on the bus and a read-only Postgres role.
Alerting needs no write rights at all. It reads state and sends notifications outbound. It holds notification channel secrets and nothing else.
Claim expiry and session expiry are unrelated. A manual claim with a two-hour expiry survives the browser tab closing, deliberately. Tying claims to sessions would mean a person's overrides silently vanishing when their laptop sleeps, which is worse than a claim that outlives the session, since that claim still ends at its own expiry.
Secrets
The bus never carries a secret, and neither does the on-disk assignment cache. An assignment carries a reference — credential: mqtt/fleet — resolved by the driver host against its own local store, provisioned out of band. Without this, every host holds a plaintext copy of every credential in its assignment, and so does anything that can read the assignment subject.
Short-lived credentials issued by the core would be better and are a lot of machinery for a fleet this size. The reference indirection is what makes that upgrade possible later without touching the assignment format again.
Rotation: device credentials rotate in the local store on each host, with no bus involvement. Bus credentials rotate by reissuing a host's JWT and adding the old one to the revocation list. Human access is revoked at the identity provider.
Audit
Most of this already exists. control_event records every claim, resolution, suspension and command, registry_version carries the git SHA that covers rule and band changes, and the core epoch identifies which core instance acted.
What makes it an audit log rather than an activity log is one requirement: the principal is mandatory on every mutating control event. Combined with the rejection of absent principals above, there is no code path that can change state without naming who asked.
Exposure
This document assumes the API and UI are reachable only from the local network, with remote access via VPN. That assumption is doing real work: it is why forward auth without MFA is proportionate, and why there is no rate limiting or lockout policy here.
If the UI is ever published to the internet, three things change and none are optional: MFA at the identity provider, rate limiting and lockout on the proxy, and a re-examination of whether the core's binding is genuinely unreachable by any other route. That is a decision to make deliberately rather than one to arrive at by opening a port.
What this deliberately does not do
This is recorded so that the absences read as decisions rather than oversights, and so the trigger for revisiting each is written down:
- No mTLS. Revisit if driver hosts move onto an untrusted network segment.
- No per-point authorisation. Revisit if a second person gets write access.
- No role hierarchy. Four capabilities, flat. Revisit at the same trigger.
- No secrets management service. Local stores per host. Revisit when rotation becomes frequent enough to be forgotten.
- No defence behind the core. Revisit if the core stops being a single trusted process, which is the same condition that would reopen the multi-core non-goal in Core Runtime.
Exit criteria
Security properties are the ones most likely to be believed rather than checked, because nothing fails when they are absent. Each of these is a test that asserts a refusal.
Bus permissions refuse, at the broker. A host credential publishing outside its own prefix is rejected by NATS, not by a check in the driver. Asserted against a real server with the real permission set, because a permission file that was never exercised is a permission file that is probably wrong.
service:ui cannot publish anything, and its Postgres role cannot write.
Point spoofing is caught core-side. A host publishing under its own valid prefix, for a point assigned to another instance, is quarantined with wrong_instance. This is the same test as in Ingest Path & Log Schema, and it belongs in both places because subject permissions and the publisher check are only meaningful together.
Absent principal is rejected, with no fallback identity. A request with no principal header is refused rather than attributed to a service account, and the core is unreachable except through the proxy — assert the binding, not just the header handling, since the binding is the actual control.
Capabilities are separable. A principal with claim but not suspend can set a manual claim and cannot suspend a safety owner. A principal with direct cannot override an asserted interlock claim.
No secret appears on the bus or in an assignment cache. Scan the cached assignment on a driver host and the assignment subject payload for anything credential-shaped. A cheap test that catches the regression where someone inlines a password to get a driver working.
On Monday - the Dev Diary. The latest on where the specification and the build disagree as the system takes shape, and which of the two had to change.
The next part - Observability. The specification's tenth part: what signals every mechanism must expose.
Start of the series: An Introduction. The map, the two decisions every later document is downstream of, and why a specification at this scale is being published in public while the system it describes gets built.
Top comments (0)