Skip to content

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.

  • $node is 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 $node grants 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 $node grants 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: renaming Line1 moves what $node/Line1/# covers. A path no element sits at covers nothing.
  • Only people hold $node grants. Enrollment refuses them for machines, services and nodes, whose placement is their zone. admin:$node is reserved like every zone-scoped admin.
  • Nodes released before node-relative grants refuse a definition that holds a $node grant. 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.