Permissions and records

Two mechanisms describe who can do what in Nodelets: a permission list on every credential, which decides what a call may do, and records, which keep what was done.

Capabilities and permissions

A capability is something a device can do: a property, an action or an event, as its definition declares. A permission says whether a caller may use one. Each permission names a Nodelet, a capability and an operation, and any of the three can be “all”. A credential holds a list of them, and anything not on the list is refused.

API keys and MCP connections both hold lists, chosen by the owner when the key is created or the connection approved. A list cannot be changed afterwards. To change what a program can do, make a new credential and remove the old one, so each credential’s reach is fixed for its whole life.

How a call is checked

Every call that reads from or acts on a device passes the same three checks, in this order:

The credential is current. A deleted key, or an ended connection, is refused.
The Nodelet belongs to the credential’s account.
A permission covers this capability and operation.

Only after all three does Nodelets look at the definition, the value or whether the device is available. Commands, reads, live values, history and records all pass the same checks, and the cloud’s objects refuse a call that arrives without them.

The answers are chosen so that a credential learns nothing beyond its list. A Nodelet the credential does not reach answers “not found”, the same as one that does not exist. A capability it is not given answers PERMISSION_DENIED whether or not the device has a capability of that name, so a hidden name and a missing one look the same. Listings and Thing Descriptions show only what is covered.

What the lists do not cover

The bridge’s own key. A bridge acts for its own devices and is not limited by a list.
The owner’s dashboard session. A signed-in owner can see every Nodelet and every record, and can send no commands.
Counting. Saved readings are numbered across all of a Nodelet’s properties. A key limited to some properties can see from gaps in the numbering how many readings the others saved, though not what they were.
Name changes. A permission matches a capability by name. A later definition that reuses a name changes what the permission reaches.

Ending a credential

Deleting a key or ending a connection closes what it has open. Sockets close, and a command still on its way is not sent. The cloud stores the whole job before it starts and finishes it whatever fails, so the owner does not have to repeat it. An MCP access token that a router never heard about still stops when it expires, within the hour.

The device record

Each Nodelet keeps a record of every write and action sent to it through the cloud: who sent it, when, with what value, and what happened. Attempts that were refused are counted too, collapsed into one entry with a count. A removed device’s record stays, and its owner can still read it.

The record is built to be honest about its own limits:

A result is a report. “Done” is the bridge’s word. A copied bridge key could falsify it. With no result, an entry reads unknown, never failed.
A command does not wait for its entry. The command goes out first and its entry follows, so the record never slows a command. A restart at that moment can lose an entry. A loss the cloud knows about shows as a gap; one it does not know about shows nothing.
Only actions through the cloud. A wall switch or a local app leaves no entry. Successful reads and live watching are not recorded.
Write-only values are not kept. For a property marked writeOnly, the record keeps the fact of the write without the value. Nested fields and action inputs cannot be marked, so their values are kept.
Size, not time. A record keeps entries until it reaches its size budget, then its oldest entries go. A program with write access can push out older writes by writing fast. Refused attempts have their own share and can push out only each other.
Not proof against tampering. Nothing in Nodelets can edit or delete an entry, for an owner or a key. That does not bind someone with direct access to the store, and entries are not chained with hashes.

A refused count is a lower bound, and its position among writes is approximate.

The account record

The account record, on the Account page, lists what happened to keys, connections and bridges: keys created and deleted, connections made and ended, bridges registered, keys stopped, recoveries, disables, deletions, and refused attempts the cloud can prove used a bridge’s key. Each entry shares a commit with the change it describes. It keeps 10,000 such entries per account, and automatic daily key changes are kept apart, 1,000 per account, behind Show automatic key changes, so they can only push out each other.