Access control

​

The model

• Principal — the authenticated console caller: the subject (email or token sub) plus the groups it belongs to. On an auth-optional console (require_app_auth = false), callers without a valid voluntarily supplied token are anonymous and only match rules without subject constraints. With access control and trusted-token validation configured, a valid optional token can still identify a named principal for HTTP and SSE access checks.
• Resource — usually an agent: its identity, role, and labels (the same labels you already use for console grouping).
• Action — a verb from a fixed vocabulary:

• Rule — matches principals (subjects, groups), actions (exact, agent.*, or *), and resources (agents, roles, match_labels). Resource selectors AND together; values within a list OR together. Empty selectors leave a dimension unconstrained.

​

Spawn-lineage inheritance

​

Side chats

• an allow must match the agent or one of its ancestors. A rule that matches only the side chat itself (its name, its role, or a label only the side chat carries, such as its own console flags) grants nothing, so a grant on a side chat’s name never widens what its agent allows;
• a deny that matches the side chat, the agent or any of its ancestors refuses, as everywhere.

​

Configuration

enabled = true
admins = ["root@example.com"]

[groups.ops]
description = "Operations"
members = ["alice@example.com", "bob@example.com"]

[groups.contractors]
description = "Payments contractors"
members = ["contractor@example.com"]

# Ops can see every agent...
[[rules]]
id = "ops-view-all"
groups = ["ops"]
actions = ["agent.view"]

# ...but only interact with the ops lead.
[[rules]]
id = "ops-send-lead"
groups = ["ops"]
actions = ["agent.send"]
agents = ["identity:ops-lead"]

# Contractors see only the payments org, read-only.
[[rules]]
id = "contractors-payments-readonly"
groups = ["contractors"]
actions = ["agent.view"]
[rules.match_labels]
org = "payments"

# Nobody but admins ever touches the auditor, even via wildcards.
[[rules]]
id = "protect-auditor"
effect = "deny"
actions = ["agent.*"]
agents = ["identity:auditor"]

let runtime = UnifiedRuntime::builder()
    .definition_path("config/mob.toml")
    .access_control_file("config/access.toml")?
    .build()
    .await?;

import { Meta } from "@rkat/meta-sdk";

const meta = await Meta.builder()
  .mob("config/mob.toml")
  .accessControl("config/access.toml") // auto-discovered if the file exists
  .gateway("/path/to/rpc_gateway")
  .build();

meta = await (
    Meta.builder()
    .mob("config/mob.toml")
    .access_control("config/access.toml")  # auto-discovered if the file exists
    .build()
)

​

Approver identities

[approvers."person:alice"]
subjects = ["alice@example.com"]

[approvers."role:release-manager"]
groups = ["release-managers"]

​

Live administration from the console

​

Configure the owner and the connection

​

Review and save

1. Start an edit in Overview, Groups or Rules. The draft keeps the configuration, owner instance and revision from when the edit began.
2. Select Save. The owner rechecks the caller’s current administrator access and the draft’s complete edit token in the same serialized mutation. Another administrator’s successful save makes an older revision stale.
3. On a conflict or owner replacement, keep the draft and inspect the refreshed settings. Select Review and reapply, then deliberately save again. That review step binds the intended edit to the current configuration; it does not itself write. Refreshing alone never silently rebases or retries the draft.

​

Implement a checked-save client

{
  "jsonrpc": "2.0",
  "id": "access-save-1",
  "method": "meta/access/rules/upsert",
  "params": {
    "checked_v1": {
      "owner_instance": "<owner_instance from get>",
      "expected_revision": 12,
      "rule": {
        "id": "ops-view-all",
        "groups": ["ops"],
        "actions": ["agent.view"]
      }
    }
  }
}

​

Refusal feedback and audit limits

node console/browser-e2e.cjs --list --scenario=real-checked-save-recovery

​

What gets enforced

• /console/experience — agents the caller can’t view vanish from the sidebar, roster, topology, identity status; per-agent affordances (can_send_message, can_retire, can_respawn) and runtime capabilities are intersected with the caller’s grants, so the stock console UI degrades invisibly. Affordances are resolved per agent: a caller who can view and retire an agent but not message it gets a disabled composer on that agent while keeping the retire action — having no send grant anywhere does not flip the whole console to deployment read-only.
• /console/timeline, timeline streams, and meta/console/query_timeline — frames for hidden identities are filtered out.
• meta/console/send and /console/send — require agent.send on the target.
• meta/schedule/list (an agent’s console schedules) - requires agent.view on the agent; meta/schedule/create, update, pause, resume and delete require agent.send on it, since a console schedule is a deferred send. Each fire is a console send by the schedule’s sender, judged when it fires: the Console admits the sender as it admits a live request by it (sign-in, allowlist, trusted issuer, revoked sessions), and the send needs agent.send for the sender under the policy at that time, so withdrawing the grant stops the schedule’s later sends.
• meta/agent_memory/remember and meta/agent_memory/forget — require agent.memory.write and agent.memory.delete respectively on the target identity. meta/agent_memory/recall and meta/agent_memory/manifest require both agent.memory.read and agent.view on the identity.
• meta/memory/panel/* (the console Memory panel’s reads) filters every returned record by its scope: identity-scoped records need agent.memory.read + agent.view on that identity, mob-scoped records need mob.memory.read, operator-scoped records need operator.memory.read, realm-scoped records and meta/memory/panel/dreams need an unscoped agent.memory.read grant, and quarantined records (still quarantined, or tombstoned after ever being quarantined) plus meta/memory/panel/quarantine need memory.quarantine.review. The review grant only opens the quarantine surface; each queue record is still filtered by the per-scope read grants above on its scope, and each pending promotion both on its target scope and on its source record or proposal (a promotion the steward made from a proposal names that proposal, judged by its scope), whose content it would publish and which still holds that content. Once applied, the promoted content is a record of its target scope and is judged there. The other realm-level reads (overview, proposals, injections, harvests and audit_verdicts) also need the unscoped agent.memory.read grant to be called, and return only the rows the caller may read by the same rules: a store-overview scope row and a proposal by their scope, a harvest by its identity, an audit verdict by its record, and an injection-ledger row by both its record and the identity it went into (a record’s detail likewise lists only the injections into identities the caller may read). Their entry check has no resource, so a deny on one identity, role or label does not refuse the call; it removes that identity’s rows from the answer. Each row is judged under the name the console gives the identity, and so is the identity a record listing is filtered by: on a shared Console that is <namespace>/<identity>, so its rules name identities that way, and the Console records its runtimes’ roles and labels before a memory read. An identity whose attributes the console does not know (memory written for a name no member holds) is withheld while a deny scoped by a role, a label or another agent applies to agent.memory.read or agent.view, since its bare name cannot be matched against such a deny. meta/memory/panel/dreams and meta/memory/panel/dream_runs summarize steward runs that span a realm’s scopes and can describe quarantined content, so they list a realm’s runs only to a caller who may read every memory scope the realm names (the scopes of its records, proposals and gated promotions, and its harvested identities: each identity by the identity rule above, its mobs by mob.memory.read, and the operator scope by operator.memory.read) and, while the realm holds quarantined content (a quarantined record, or a tombstoned one that was ever quarantined), also holds memory.quarantine.review. For any other caller those runs are left out, and withheld_by_access in the result is true when access withholds the dream history of at least one realm, whether or not that realm has runs (false otherwise), so a client can tell withheld history from none. Memory content is more sensitive than roster visibility, so plain agent.view alone no longer reads any of it.
• meta/memory/quarantine/decide (the operator quarantine decision) requires memory.quarantine.review, agent.view and agent.memory.read on the identity, and agent.memory.write to release or agent.memory.delete to tombstone (any other verdict needs both, then fails validation). Every effect is one the same caller could already cause through remember, update or forget (a released update supersedes its prior, as update does); the decision adds the lineage, the trust ceiling, the content binding and the audit trail. An anonymous caller is held to the same grants whenever access control is on. The capabilities list advertises it only to callers holding memory.quarantine.review.
• Lifecycle and runtime RPCs — mapped to agent.retire / agent.respawn / agent.reset / agent.spawn / runtime.admin per method.
• meta/mob_announcements/* on /console/rpc - every method, the reads included, requires runtime.admin with no resource: they list announcements, subscriptions and deliveries across members and mobs with no per-agent filter. A read-only console refuses the ones that change state (announce, subscriptions/put, pause, resume, cancel and deliveries/reconcile) with the read_only error. The capabilities list names the family only while the runtime has mob announcements.
• Topology control — query visibility requires agent.view and topology.view per endpoint. Connect, disconnect, and reconnect require the matching topology.* grant on both endpoint identities for planning as well as applying. Multi-operation requests also require topology.bulk; the runtime still enforces its finite batch ceiling. Durable mutation audit and actor/principal attribution require the separate topology.audit grant on every endpoint in a returned record. Cross-authority mutation is separately gated and is available only to a same-process host coordinating both runtimes; the authority-local JSON-RPC surface fails it closed.
• /agents/{id}/events — requires agent.view on that agent. /mob/events and /meta/mob_events/stream require mob.observe to open and additionally filter each event by agent.view on its source (see below).

​

mob.observe and per-agent filtering

​

/blobs/{id} is a capability surface

​

Relationship to authentication

​

Timeline frames of members that changed or left

• A frame is visible only when both the recorded attributes and the member’s current attributes allow it. After a member is relabelled into a denied class, its earlier frames are denied too; after it is relabelled out of one, frames its recorded attributes deny stay denied.
• A member that has left, or that nothing has read from the roster since a restart, is decided by its recorded attributes only. A label or role deny keeps applying to its frames.
• A spawn ancestor is recorded only from the member that actually performed the spawn (the spawning session), not from a later member under the same identity. An ancestor that could not be confirmed counts as unknown, and the current attributes of a member under an ancestor’s identity can only add a deny.
• A frame recorded without member attributes (written by an earlier release, or when the console could not tell which member wrote it) and an unknown ancestor are refused under any deny rule the identity alone cannot decide: a rule with a role or label selector, or one naming another agent (it could be an ancestor). Allow rules and identity-only denies decide such a frame by its identity, as before.
• The console’s own frames (the _system and __console__ identities) are decided by those identities. No member can run under them.

​

Cross-mob control grants

​

How a caller is identified

​

Configuring grants

[control_grants.ops-mob]
# The calling gateway's pubkey, from its `meta/peer_pubkey`.
pubkey = "ed25519:KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKio="
verbs = ["lookup_member", "wire", "unwire"]
members = ["bob"]

[control_grants.dispatcher]
pubkey = "ed25519:..."
verbs = ["inject"]
# `members` omitted (or ["*"]) grants every member, present and future.

let mut table = ControlGrantTable::new();
table.insert(
    peer_pubkey,
    ControlGrant::new(
        "ops-mob",
        [ControlVerb::Inject],
        ControlMemberScope::members(["bob"]),
    ),
);
let advertised = runtime
    .start_control_listener_with_authorizer(
        &addr,
        Arc::new(ControlAuthorizer::with_grants(table)),
    )
    .await?;

​

Keyed inject

• a grant that names the verb explicitly, on a listener with grants (an open authorizer refuses them);
• a request issued within the serving gateway’s freshness window of its own clock (runtime_options.control_request_window_ms, five minutes by default) and not before the serving process started. A delivery the gateway admitted has a deadline, its issue time plus the window: the gateway prepares the member within it, checks it again just before the commit, and refuses a delivery it cannot commit in time; a member preparation it stopped waiting for still finishes, so the next attempt finds the member ready. The deadline uses the serving gateway’s own window, so gateways that deliver to each other should configure the same control_request_window_ms. Each stale refusal carries its typed cause in a field of the signed refusal: outside_window, issued_before_start (a request issued before the serving process started, as when it restarted while the request was on its way) or deadline_passed;
• an identity-first serving gateway that serves keyed injects. Every gateway that binds a control listener (rpc_gateway, meta_gateway, and a runtime the builder composes) seals what the plane serves once its runtime is composed, whether or not it enables mob announcements itself. Until then the verbs answer keyed_inject_unavailable: the gateway is starting. A gateway that is not identity-first, or whose configuration turns serving off (runtime_options.serve_keyed_inject: false on rpc_gateway), answers not_served with its typed cause, not_identity_first or runtime_disabled, in a field of the signed refusal. meta_gateway has no such switch: its listener serves keyed injects whenever its runtime is identity-first (its default), with the default window, DEFAULT_KEYED_INJECT_WINDOW_MS (five minutes), so the grants that name the verbs are what decide who may call them.

• A grant is checked per request, so a caller granted inject on a member may inject repeatedly. Grants bound who and what, not how often.
• The channel has no replay cache: a captured request stays valid at its audience until the grant is withdrawn. Each request carries a client-minted nonce inside the signed material, so a future replay guard has something to key on, but none is enforced today.
• wire is a trust-granting verb. A caller granted wire on a member may install a trusted peer descriptor of its choosing on that member - including one naming a third party’s key. Grant it only to peers you would let choose who your member talks to; inject and lookup_member are the narrower verbs.