Security model¶
Colca has no certificate authority and no password file. Nodes and machines are identified by ed25519 keys, people by OIDC tokens, and local services by the fact that they can reach a door that is never published.
Doors¶
A node opens only the listeners its configuration names. Each one has a single way of deciding who is talking.
| Door | Default port | Who uses it | Credential |
|---|---|---|---|
| local HTTP | 80 | services inside the deployment network | none; the door is not published |
| local MQTT | 1883 | the same | none |
| API | 443 | machines, external services, administrators, people | client certificate, Authorization: Bearer, or the admin token |
| machine MQTT | 8883 | machines and external services | client certificate carrying an enrolled key |
| human MQTT | 8884 | people and applications | OIDC token as the MQTT password |
| human WebSocket | 8885 | browsers | OIDC token |
| replication | 9443 | child nodes | client certificate carrying an enrolled node key |
A presented credential that fails is refused. There is no fallback to a weaker door.
The local doors are meant for services that run next to the node, for example in the same Docker network. Publish them, and anyone who reaches them can write. Keep them unpublished.
Keys instead of a CA¶
Every node and every machine owns an ed25519 key pair, created with
colca-keygen. The TLS certificate is a self-signed wrapper around that key
and carries no authority of its own.
- A parent accepts a child when the key in the child's client certificate belongs to a node enrolled at the parent.
- A child accepts its parent when the parent presents the key in
parent.pubkey. Anything else aborts the handshake. - A machine is accepted when its key is enrolled at the node it connects to.
TLS 1.3 is the minimum on every encrypted door. Revoking an entry closes the live session at once.
Identities¶
| Kind | How it gets in | What it may do by default |
|---|---|---|
| node | enrolled at its parent with its public key, bound to an element the parent holds | replicate its subtree |
| external | enrolled with its public key, bound to the element it belongs to | read its element's subtree; writing needs explicit grants |
| local | creates its own entry on first use of a local door, by name | read and write its element's subtree, or the whole node when unplaced |
| human | OIDC token; grants come from the groups the token names | nothing without grants; never writes data, only commands |
Commands need a cmd grant, with two rights implied by placement for an
unplaced local service, both on its own node only:
| Command | Who, without a grant |
|---|---|
_CmdConfigure |
any unplaced local service |
_CmdOperate to {notification-id}/notify (an app's notification for the node's notifications service) |
the unplaced local service named api, or hub-api on a node that aggregates others (uns.AppNotificationSenders) |
The second lets the platform api hand over an app's notification once it has
checked the app's own capability role; the node's notifications service
accepts and delivers it. Every other _CmdOperate -- an alarm's acknowledge,
silence, unsilence, a channel's test message -- stays a person's act,
authorized against their operate grant at its place.
Another local service, a placed one, an external service or a person gets
nothing from it. The local door authenticates by reaching it, so the name is
the same trust every unplaced local service already holds for configure.
An identity is bound to a system element, not to a path. Renaming or moving the element moves everything bound to it.
Enrollment goes through POST /enroll with the admin token, or through a
_CmdAdmin command sent down the tree to a node that is not directly
reachable. A local service whose registry entry holds cmd:#:admin can send
_CmdAdmin to its own node over the local door; admin:# it can never hold.
Who writes a signal's values¶
A write scope says where an identity may publish. It does not make the
identity a source for every signal there. A signal bound to a data tag
(_Signal.data_tag) takes its _Metric only from its producer: the
identity whose _DataTags catalogue holds that tag, at the topic that identity
publishes its catalogue on (_DataTags/<node>/<mount>/<name>). That covers
connectors, dataops outputs and signals created by autobind alike.
| Publisher | A _Metric for a bound signal |
|---|---|
| the producer | accepted |
| any other identity, local or external, whatever its grants | refused: MQTT 5 PUBACK 0x87 (not authorized), HTTP 403, colca_rejected_publishes_total{reason="not_producer"}, an _AuditEvent denial and a log line |
| any identity, when no catalogue on the node holds the tag or two claim it | refused until exactly one catalogue holds it |
the admin token (/publish with X-Colca-Token) |
accepted, stored with written_by: admin, and logged |
| replication from a child | accepted: the child admitted it |
A signal bound to nothing, or a _Metric on a path with no signal, keeps the
write-scope rule alone.
When a configure command moves a signal (a rename, a reparent, or a
_CmdEdit placement), the node moves the signal's current _Metric with it:
the same payload and timestamp at the new path, a tombstone at the old one.
When it moves an element, the catalogue of a service placed there moves to the
element's new path, so the service stays its signals' producer. Nothing new is
written for the producer; a value already published at the new path is kept.
The local door authenticates by reaching it, not by a secret, so this rule stops a misconfigured or misbehaving service. It does not stop a process that connects under the producer's name.
Grants¶
Grants use one grammar for machines and people:
| Grant | Meaning |
|---|---|
read:<element>/# |
live bus, current state and history below the element |
write:<element>/# |
publish data and entities below the element |
cmd:<element>/#:<classes> |
send commands of the listed classes below the element |
admin:# |
use the administrative routes; does not widen reads or commands |
Command classes are acknowledge, annotate, param, operate, maintain,
configure and admin. configure is separate on purpose: someone who may rename a signal
must not thereby be able to send maintenance commands to a PLC. acknowledge
is separate for the opposite reason: quitting an alarm moves nothing, so
everyone who watches a line may hold it, and holding it must not let them start
or stop the line. It covers _CmdAcknowledge and nothing else; silencing an
alarm keeps notifications from other people and stays operate. annotate is
separate for the same reason: an annotation is an event about the plant, so a
shift lead may correct or remove a colleague's entry without being able to
configure the model or move equipment. No class implies another: someone who
may both operate and acknowledge holds both.
One command needs no class: subscribing to an alarm (_CmdOperate
{alarm-path}/subscribe and /unsubscribe) is authorized by read on the
alarm's place, since asking to be told about an alarm is seeing it. A cmd
grant does not replace that read. See alarms.md.
The opposite holds for the answer to a command: a sender reads the _Ack of
its own command without a read grant on the target, and nothing else there.
See reading the answer to your own command.
_CmdEdit is a person's tool for the node's data model, and the door admits
anyone holding configure on it. Three narrower classes are also admitted, each
covering only the part of _CmdEdit that matches the hazard: annotate covers
every annotation write -- creating one, and changing or removing anyone's,
including its start and its signals; operate covers creating an annotation,
or changing or removing one's own as long as its type, start and signals stay
what the node derives its id from; param covers setting the value
and metadata of an existing constant, through an update or a single-key
metadata edit (see concepts.md) — an
operator input such as a station's sandoff or grit — never creating or deleting
a constant, never its other attributes, and never a signal's binding. All three are
scoped by the grant's element exactly as configure is:
cmd:<element>/#:param reaches only the constants under that element. The write itself is still made by the node —
_CmdEdit never lets a person publish state directly — but it carries the
operator's own verified identity as actor_id/actor_label/actor_kind, so
/kv can show who set it (see http-api.md).
An external reference is stored at the reserved path
_colca/external-references/<id>, outside every element, so _CmdEdit
authorizes it at the entity it belongs to: cmd:<element>/#:configure covers
adding, changing and removing the references of the entities under that
element, and deleting such an entity together with its references. A changed
or removed reference also counts at the entity it belongs to now, so it cannot
be moved away from an entity outside the grant.
A node holds one record per reference: the entity, the relationship, the
external system, the table and the row are its identity, and the record's id
only addresses it. A write that would add a second record for an identity the
node already holds is refused with 409 duplicate_external_reference, naming
the record that stands, whichever command or door wrote it. A node that held
two such records before this rule keeps both until an edit removes one.
# in place of an element means the whole node. A grant on an element the node
has never heard of covers nothing, and a node that has never reached its parent
cannot resolve elements above itself, so scoped grants fail closed there.
Grants relative to the node a person signs in at¶
A grant names an element by id, so a group that should give every edge's
operators their own machine would need one element id per machine. A person's
grant can instead name $node, the node they signed in at:
| Zone | Covers, at the node the person signed in at |
|---|---|
$node/# |
everything that node holds, as # does there |
$node/<path>/# |
the subtree at that local path, for example $node/Line1/Press/# |
One definition, written once at the root, then works for the whole fleet:
read:$node/# lets an operator signed in at edge 1 read edge 1 and one signed
in at edge 2 read edge 2. $node resolves when the grant is used, at the node
evaluating it; the _Group definition descends unchanged.
$nodeis the node whose door verified the person's token, or whose own local service attested their groups. A command that came down from the parent was admitted at another node, so its sender's$nodegrants cover nothing at the node executing it. Use element grants for people who command edges from the hub.- At the root,
$node/#is the whole tree. Give a group with$nodegrants only to people who sign in at the edges; when edges share one identity provider with each other, a member who can sign in at an edge holds that edge. <path>is a path of names in the node's own frame. Unlike an element id it follows a rename: renamingLine1moves what$node/Line1/#covers. A path no element sits at covers nothing.- Only people hold
$nodegrants. Enrollment refuses them for machines, services and nodes, whose placement is their zone.admin:$nodeis reserved like every zone-scopedadmin. - Nodes released before node-relative grants refuse a definition that holds a
$nodegrant. Upgrade the edges before defining such a group.
People¶
People authenticate with tokens from OIDC issuers the node lists. The node validates them offline:
auth:
issuers:
- url: https://login.example.com/realms/plant
audience: colca
jwks_url: https://login.example.com/realms/plant/protocol/openid-connect/certs
mqtt_human: { tcp_addr: ":8884", ws_addr: ":8885" }
A token's iss must be one of issuers, and its aud must be audience.
The issuer also decides which keys the signature is checked against: its own
jwks_url, or the shared auth.jwks_url when it has none. A token that names
an issuer but was signed with another issuer's keys is rejected.
Several issuers are normal when one identity provider is reached under more
than one host name. Keycloak, for example, writes the host the browser used
into iss, so a site with two networks gets two issuers with the same keys:
auth:
issuers:
- url: https://red.plant.example/realms/plant
- url: https://green.plant.example/realms/plant
audience: colca
jwks_url: http://keycloak:8080/realms/plant/protocol/openid-connect/certs
Issuers from different identity providers each name their own keys:
auth:
issuers:
- url: https://login.example.com/realms/plant
jwks_url: https://login.example.com/realms/plant/protocol/openid-connect/certs
- url: https://idp.partner.example
jwks_url: https://idp.partner.example/.well-known/jwks.json
audience: colca
Signing keys are fetched in the background from each distinct JWKS URL, stored, and refreshed when a token names an unknown key. The issuer is never called while a request waits, and a node that restarts without network keeps validating until the tokens expire. A session ends when its token expires, unless the client renews it first.
An MQTT 5 client renews on the open connection: it sends the authentication
method colca-token in its CONNECT (the token stays the password), and the node
names the method in the CONNACK. Before the token runs out, the client sends an
AUTH packet with reason 0x19, the same method, and the new token as
authentication data. The node checks it as at CONNECT, requires the same sub,
and moves the session's grants and expiry to it; the subscriptions stay. A
refused token ends the connection with 0x87 (not authorized), a different
method with 0x8C. A client without the method reconnects with a new token
instead.
A logout at the identity provider reaches the node by OIDC back-channel logout.
The node serves POST /auth/backchannel-logout on its API door and its local
door; the identity provider posts a signed logout_token there. The node checks
the signature against the issuer's keys, iss, aud (the audience above),
iat, exp if present, the back-channel logout event in events, that there
is no nonce, and that the jti was not used before, and answers 400 to a token
that fails. A valid one is answered 200: every connection of that session (the
token's sid) is closed with 0x98 (administrative action), and tokens of the
session are refused from then on, on every door. A logout token with a sub and
no sid ends everything issued to that person before it. In Keycloak, set the
client's back-channel logout URL to the node's local door, for example
http://colca/auth/backchannel-logout. Without back-channel logout, the token
lifetime is the revocation delay.
A token names groups, not grants. The node resolves the groups against
_Group definitions that its ancestors pushed down. Membership lives in the
identity provider, grants live in the tree, and an edge cut off from its parent
still knows what its people may do. colca-grantsync keeps a Keycloak realm and
the tree's groups in step, if you use Keycloak.
colca-grantsync runs a cycle when the tree tells it something changed: it
holds a /watch scoped to _SystemElement and _Group, so a new or retired
element and a group definition written elsewhere are handled within a second.
Keycloak has no push, so a tool that edits permissions, groups or role
membership there posts POST /sync to the service's HTTP_ADDR (default
:9090) to apply the edit at once. SYNC_INTERVAL_MS (default 5 minutes) is
only a safety interval for Keycloak edits nobody announced; a failed cycle is
retried sooner, backing off from 5 s up to that interval. POST /sync only
schedules an idempotent cycle and bursts are merged into one cycle a second,
so keep the address on a network only trusted tools reach.
A grant change applies to open sessions as soon as the _Group definition
reaches the node, not at the next token renewal. REST reads resolve the groups on
every request. A live MQTT or WebSocket session resolves its token's groups again
before its next delivery: a narrowed group stops an existing subscription at its
next message (counted in colca_acl_denials_total{action="sub"} and audited as
subscribe_denied), and a widened one starts delivering without a reconnect.
Group membership itself lives in the token, so adding or removing a person from a
group at the identity provider applies when the token is renewed or ends. A
personal access token carries its own grants rather than groups; its sessions
keep the grants they authenticated with, so re-issue the token to change them.
A command a person sends with a personal access token names the token (its id
and hash-only digest, never the secret) instead of groups. The node the command
comes down to authorizes the person again against its own replicated
definition of that token: the same token, still defined there, not expired, and
owned by the acting person. A token revoked or changed there makes the person
nobody, and the command is refused. A token made for mcp is also accepted
where a door asks for api; a token made for api alone is not accepted for
mcp.
Administration¶
The administrative routes (/enroll, /debug/state) require either the node's
admin token (X-Colca-Token) or a token with admin:#. An empty api.token
authenticates nobody; it does not switch the check off.
Secrets¶
With secrets_dir set, a local service can store sealed envelopes on its node
(/secrets). The node only ever holds ciphertext; the service owns the private
key and decrypts in its own process. The secret store is a separate database,
never replicated and not part of data_dir. See the secrets Go package.
Reporting a vulnerability¶
See SECURITY.md.