feat(api)!: Plan 20 PR 5 — a guard on every RPC method (RFC #1351)

connect/src/core.ts

@@ -13,7 +13,7 @@ const LOCKED_WALLET = "Cannot extractByTags from a ciphered wallet. You must unl
 /** How the executor's close reason (code 1013) and 503 begin when its wallet is locked. */
 const EXECUTOR_LOCKED = "Executor is locked";
 
-/** Whether `error` says the node's wallet is locked: a state of the node, so the token stays. */
+/** Whether `error` says the executor's wallet is locked: a state of the executor, so the token stays. */
 const saysLocked = (error: any): boolean => {
   const text = errorText(error);
   return text === LOCKED_WALLET || (typeof text === 'string' && text.startsWith(EXECUTOR_LOCKED));

core/src/agent/AgentClient.ts

@@ -297,7 +297,7 @@ export class AgentClient {
   /**
    * Revokes every token of a user issued up to now, this client's own included, and closes
    * their sockets. A user leaves out `email` (or names themselves); the operator names the
-   * user. Tokens from a later login work.
+   * user. Needs AGENT_UPDATE, which a login holds. Tokens from a later login work.
    */
   async revokeAllSessions(email?: string): Promise<boolean> {
     return this.#apiClient.call('user.revokeAllSessions', email === undefined ? {} : { email });

core/src/apiClient.test.ts

@@ -441,7 +441,7 @@ describe('ApiClient when the executor refuses the token', () => {
         expect(authFailed).not.toHaveBeenCalled()
     })
 
-    // A locked wallet is a state of the node: the token may be good. 1013 is not an auth failure.
+    // A locked wallet is a state of the executor: the token may be good. 1013 is not an auth failure.
     it('treats close code 1013 (executor locked) as an ordinary close that carries its reason', async () => {
         const LOCKED = 'Executor is locked: ask the operator to unlock it, then reconnect'
         open()

rust-executor/AGENTS.md

@@ -42,7 +42,7 @@ Some tests in `perspectives/*_e2e.rs` and `flow_context/real_llm_e2e.rs` call re
 | `languages/` + `js_core/` | Language runtime: one Deno isolate per Language on its own thread; install, templates, expressions | `src/languages/AGENTS.md`, `src/js_core/AGENTS.md` |
 | `holochain_service/` | Embedded Holochain conductor behind an actor channel; signal fan-in | `src/holochain_service/AGENTS.md` |
 | `agent/` | Agent keys/DID, signing, multi-user (managed agents by DID; a user's email is only the login name), `capabilities/` (auth tokens, capability defs) | — |
-| `db.rs` | All SQLite access (`rusqlite`), single `impl Ad4mDb`, accessed via `Ad4mDb::with_global_instance(closure)`. Perspective **links** are not here (they are in `perspectives/sparql_store.rs`); `db` holds handles, diffs, agent data, AI models/tasks, users, billing, notifications. | — |
+| `db.rs`, `db/` | All SQLite access (`rusqlite`): `impl Ad4mDb` in `db.rs` plus child modules in `db/`, accessed via `Ad4mDb::with_global_instance(closure)`. Perspective **links** are not here (they are in `perspectives/sparql_store.rs`); `db` holds handles, diffs, agent data, AI models/tasks, users, billing, notifications. | `src/db/AGENTS.md` |
 | `db_backend.rs` | `SharedDb` HTTP backend for stateless/hosted mode; only used when `config.db_backend == "shared"` | — |
 | `pubsub.rs` | Global broadcast bus: one channel of typed events (`events.rs`: `Topic`, `Audience`, `Event`) for every event (live query updates too, as `Event::for_connection`); feeds `api/events_ws.rs` | `src/api/AGENTS.md` |
 | `types/` | `core.rs` = domain types (Link, Expression, Perspective…), `domain.rs` = wire/input types; some duplicates, see spec item 5 | — |
@@ -101,11 +101,19 @@ Some tests in `perspectives/*_e2e.rs` and `flow_context/real_llm_e2e.rs` call re
 - **Billing** is per agent: `billing::bill_compute(agent_did, ..)`, `compute_log.agent_did`,
   `payment_requests.agent_did`. Credits stay on the user's `users` row, reached by
   DID (`get_agent_credits`, `deduct_credits_and_log`).
-- **Capabilities**: every WS handler checks `ctx.require(&X_CAPABILITY)` itself
-  (`agent/capabilities/defs.rs`); `Session::may` answers the same question as a `bool`. MCP tools
-  check via `Ad4mMcpHandler::get_*_perspective`.
+- **Capabilities**: every WS method declares a guard where it registers (`api/guards.rs`); the
+  dispatcher checks its capability (`agent/capabilities/defs.rs`) and ownership rule before the
+  handler runs. A handler calls `ctx.require(&X_CAPABILITY)` only for a check its guard does not
+  make; `Session::may` answers the same question as a `bool`. MCP tools check via
+  `Ad4mMcpHandler::get_*_perspective`.
+- **Per-agent objects**: a session reaches only its agent's; the operator reaches all.
+  Perspectives are owned by DID (`owners`; none = the main agent), AI tasks by DID
+  (`tasks.agent_did`; `NULL` = the main agent), grants and capability requests by their agent's
+  DID. A WS method that names one declares `Guard::Owns` (`api/AGENTS.md`); missing and not
+  yours are both 404. The capability check alone does not
+  separate users: user tokens hold wildcard perspective, neighbourhood and AI capabilities.
 - **Capability requests** (#1399, executor side): `agent.requestCapability(authInfo, agent?)`
-  names a target agent (a managed user's email; absent = the main agent) and records a
+  names a target agent (a managed agent's DID, or its user's email, resolved to the DID at once; absent = the main agent) and records a
   `PendingRequest` in memory only (`agent/capabilities/pending.rs`: never on disk, anonymous
   callers create them; 1024 at most, unapproved evicted first). The approval request event goes to
   the target agent's DID with `AGENT_PERMIT`. `agent.permitCapability` (the operator, or a

rust-executor/src/agent/capabilities/defs.rs

@@ -512,7 +512,8 @@ pub fn get_user_default_capabilities() -> Vec<Capability> {
         AGENT_SIGN_CAPABILITY.clone(),
         AGENT_SUBSCRIBE_CAPABILITY.clone(),
         // Approving apps' requests for this user's own agent (#1399, D12):
-        // `capabilities::may_approve` limits it to requests that name this agent.
+        // `agent.permitCapability`'s guard (`Owns { Request }`) limits it to requests that
+        // name this agent.
         AGENT_PERMIT_CAPABILITY.clone(),
         // Note: Excluding LOCK, UNLOCK as these are admin operations
 

rust-executor/src/agent/capabilities/mod.rs

@@ -12,7 +12,6 @@ pub use token::*;
 pub use types::*;
 
 use crate::agent::grants::now;
-use crate::agent::session::Session;
 use crate::agent::AgentContext;
 use crate::events::Event;
 use crate::pubsub::get_global_pubsub;
@@ -295,8 +294,13 @@ pub fn capabilities_from_token(
 /// so anonymous callers cannot list them.
 pub fn anonymous_capabilities() -> Vec<Capability> {
     use crate::db::Ad4mDb;
-    let multi_user_enabled =
-        Ad4mDb::with_global_instance(|db| db.get_multi_user_enabled().unwrap_or(false));
+    anonymous_capabilities_when(Ad4mDb::with_global_instance(|db| {
+        db.get_multi_user_enabled().unwrap_or(false)
+    }))
+}
+
+/// [`anonymous_capabilities`] with multi-user mode on or off.
+pub fn anonymous_capabilities_when(multi_user_enabled: bool) -> Vec<Capability> {
     if multi_user_enabled {
         vec![
             AGENT_AUTH_CAPABILITY.clone(),
@@ -486,32 +490,20 @@ pub fn request_target(request_id: &str) -> Option<RequestTarget> {
     PendingRequests::global().target(request_id, now())
 }
 
-/// Whether `session` may approve a capability request for `target` (D12): the operator, or a
-/// session that acts as `target` (the same DID) and holds AGENT_PERMIT (a user on their own
-/// agent; on the main agent, an app the operator gave AGENT_PERMIT). Nobody approves for
-/// another agent; only the operator approves a request for [`RequestTarget::NoAgent`], and
-/// its code redeems nothing. An anonymous caller approves nothing, whatever it holds: it acts
-/// as the main agent only in name.
-pub fn may_approve(session: &Session, target: &RequestTarget) -> bool {
-    session.is_operator()
-        || session.is_authenticated()
-            && target.agent().is_some_and(|agent| {
-                session.acts_as() == *agent && session.may(&AGENT_PERMIT_CAPABILITY)
-            })
-}
-
 /// Approves a pending request with `auth_info_extended.auth` as the operator, which holds
 /// every capability: [`permit_capability_within`] with no limit beyond the request's agent.
 /// For the operator and dev-mode auto-permit; a session approves with its own capabilities.
 pub fn permit_capability(auth_info_extended: AuthInfoExtended) -> Result<String, String> {
-    permit_capability_within(auth_info_extended, &[ALL_CAPABILITY.clone()])
+    permit_capability_within(auth_info_extended, std::slice::from_ref(&*ALL_CAPABILITY))
 }
 
 /// Approves a pending request with `auth_info_extended.auth`, which may grant less than the
 /// app asked for, and returns the code the app redeems: for the approver only. The request's
-/// agent stays the one it named. The caller has checked [`may_approve`]. An approver grants
-/// no more than it holds itself (`approver`, its session's capabilities): an app with
-/// AGENT_PERMIT approves only within its own grant, so it cannot mint a wider one.
+/// agent stays the one it named. The caller has checked that the approver owns that agent
+/// (`agent.permitCapability`'s guard, `api::guards::Owner::Request`; MCP's
+/// `caller_can_permit`). An approver grants no more than it holds itself (`approver`, its
+/// session's capabilities): an app with AGENT_PERMIT approves only within its own grant, so
+/// it cannot mint a wider one.
 pub fn permit_capability_within(
     auth_info_extended: AuthInfoExtended,
     approver: &[Capability],
@@ -1333,44 +1325,6 @@ mod app_token_tests {
         assert_eq!(caps_text(&caps), caps_text(&reader));
     }
 
-    // D12: the operator approves anything; a session approves only for the agent it acts as,
-    // and only while it holds AGENT_PERMIT.
-    #[test]
-    fn only_the_operator_or_the_agent_with_permit_may_approve() {
-        use crate::agent::session::{Principal, Session};
-        let main = AgentContext::main_agent();
-        let alice = AgentContext::managed("did:key:z6MkAlice".into());
-        let bob = AgentContext::managed("did:key:z6MkBob".into());
-        let permit = vec![
-            AGENT_PERMIT_CAPABILITY.clone(),
-            AGENT_READ_CAPABILITY.clone(),
-        ];
-        let no_permit = vec![AGENT_READ_CAPABILITY.clone()];
-        let session = |agent: &AgentContext, caps: &Vec<Capability>| {
-            Session::for_test(Principal::Agent(agent.clone())).with_caps(caps.clone())
-        };
-        let targets: [RequestTarget; 4] = [
-            main.clone().into(),
-            alice.clone().into(),
-            bob.clone().into(),
-            RequestTarget::NoAgent,
-        ];
-
-        let operator = Session::for_test(Principal::Operator);
-        assert!(targets.iter().all(|t| may_approve(&operator, t)));
-
-        let anonymous = Session::for_test(Principal::Anonymous).with_caps(permit.clone());
-        assert!(targets.iter().all(|t| !may_approve(&anonymous, t)));
-
-        for (agent, own) in [(&main, &targets[0]), (&alice, &targets[1])] {
-            assert!(may_approve(&session(agent, &permit), own), "{agent:?}");
-            assert!(!may_approve(&session(agent, &no_permit), own), "{agent:?}");
-            for other in targets.iter().filter(|t| *t != own) {
-                assert!(!may_approve(&session(agent, &permit), other), "{agent:?}");
-            }
-        }
-    }
-
     #[tokio::test]
     async fn redeeming_caps_a_wider_approval_at_the_managed_agents_capabilities() {
         setup();

rust-executor/src/ai_service/AGENTS.md

@@ -16,8 +16,9 @@ Split plan: spec item 9 (`mod.rs`), item 7 (`harness/` → `agentic/`).
 | rest | tests |
 
 Persistence of models/tasks is in `db.rs` (`models`, `tasks`, `model_status`,
-`default_models` tables). Billing goes through `crate::billing` with the caller's
-`AgentContext`/email.
+`default_models` tables). Tasks have an owner (`tasks.user_email`, `NULL` for operator
+tasks; see `src/db/AGENTS.md`): `add_task` takes it, and the WS guards enforce it.
+Billing goes through `crate::billing` with the caller's `AgentContext`/email.
 
 ## `harness/`