YUME permission model

YUME splits authentication from authorization the way SSH does:

• authorized_keys lists the Ed25519 public keys that may connect. Holding one of these is the audience-with-the-king; you get past the door.
• auth_keys.meta (a JSON file) lists what each connected key is allowed to do once inside. Without an entry here, a key can talk to the server but cannot exec, cannot reach LAN addresses, cannot use privileged application codecs, cannot administer other clients.

The current revision uses one Ed25519 key per identity. A second physical key (the “noble’s seal” for stronger permission control) is a planned wire-protocol change for a post-1.1 release; in the meantime, the SSH-style split below gives you the same operational separation: connection rights vs. action rights live in different files, can be edited independently, and can be revoked independently.

The three-layer gate for dangerous features

Any of these features (server-side command execution, LAN/private-IP bridging, unrestricted address bridging) is gated by all three of:

1. Build switch. cmake -DYUME_FEATURE_EXEC=ON (or _LAN_BRIDGE, _FULL_CONTROL). Stock builds ship with all three OFF. The runtime CLI flag still parses but logs a warning and stays disabled.
2. Server flag. --allow-exec, --allow-local-ip, --control-full (or the equivalent JSON config field). This is the global “feature is allowed on this server” upper bound.
3. Per-key meta entry. "allow_exec": true (or "allow_local_ip", "control_full") in auth_keys.meta. Default is deny. The server flag never grants permission to a key that does not opt in.

A request is allowed only when all three layers say yes. Removing the build switch is the cleanest way to make a server physically incapable of running shell commands for clients, regardless of any operator misconfiguration later.

File layout

/etc/yume/
  authorized_keys           # one PEM-encoded public key per block; "who may connect"
  auth_keys.meta            # JSON mapping fingerprint → permissions; "what each may do"

A typical layout:

$ cat /etc/yume/authorized_keys
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA...alice...
-----END PUBLIC KEY-----
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA...bob...
-----END PUBLIC KEY-----
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA...visitor...
-----END PUBLIC KEY-----

// /etc/yume/auth_keys.meta
{
  "0d4f3a...alice-fingerprint...": {
    "alias": "alice",
    "permissions": {
      "allow_exec": true,
      "allow_local_ip": true,
      "allow_codecs": ["monero-rpc"],
      "allow_services": ["knyaz-control-v1"],
      "control_full": false,
      "allow_inbound_admin": true,
      "allow_outbound_admin": false,
      "allow_chat": true,
      "allow_file": true,
      "allow_bytes": true
    }
  },
  "9b21e8...bob-fingerprint...": {
    "alias": "bob",
    "permissions": {
      "allow_local_ip": true,
      "allow_chat": true,
      "allow_file": true
    }
  }
  // visitor key omitted (connects only, no extra permissions)
}

Generate fingerprints with yumed --auth-keys /etc/yume/authorized_keys --keys-list. Any field you omit defaults to the safe choice (deny for admin/exec/LAN; allow for the relay-side chat / file / bytes channels which never carry server-side actions).

Permission fields

alias is a free-form label used in logs.

Bridge / admin modes: the four quadrants

Two relationships are independent:

• server-controls-client (S → C): the server sends the client commands or open requests, and the client executes them.
• client-controls-server (C → S): the client opens streams through the server (SOCKS, port-forward, exec) or attaches to administer other clients.

--accept-server-control is the new, intuitive name for what was previously --server-in-charge (the old name still works as a deprecated alias). The “admin attach” channel between two relayed clients is governed independently by allow_inbound_admin / allow_outbound_admin on the per-key meta. Neither of these ever defaults to true.

Operational tips

• Editing auth_keys.meta is the recommended way to manage permissions. The server’s interactive --ui mode is brittle around per-key permissions; it’s documented but you’ll have a smoother time with a JSON editor.
• Reload after edits. The meta file is read at server startup. Changes take effect on systemctl restart yumed. Hot reload is on the post-1.1 roadmap.
• Application codecs. Codec permissions are intentionally narrower than allow_local_ip: they only enable named protocol-aware codecs listed in allow_codecs. The Monero built-in validates allowed wallet RPC paths/methods and reconstructs HTTP only to a loopback backend configured by --monero-rpc-backend.
• Native service streams. allow_services is for embedded C ABI users and is intentionally separate from allow_local_ip, control_full, allow_codecs, and exec. A service stream opens only when the server config lists the service, the connected key metadata lists the same service, and the embedding process registered it with yume_server_register_service.
• Revoke a key. Remove the public-key block from authorized_keys. The meta entry can stay; it’ll be ignored.
• Audit. Startup logs auth policy <permissions summary> for any key that has a non-empty meta entry. Run yumed --auth-keys ... --keys-list to dump all configured keys with their aliases.
• CI/scripted setup. Generate fingerprints with openssl pkey -pubin -in user.pub -outform DER | sha256sum | cut -d' ' -f1. The same fingerprint format is used by yumed --keys-list.

Security posture summary

• A server built without YUME_FEATURE_EXEC cannot run user commands even if every other layer is misconfigured.
• A server built with YUME_FEATURE_EXEC=ON but without --allow-exec cannot run user commands.
• A server with --allow-exec but no auth_keys.meta entry granting allow_exec cannot run user commands.
• The same applies to LAN bridging and unrestricted bridging.
• Admin (inbound/outbound) defaults to deny; chat/file/bytes default to allow.
• All key signatures are verified with constant-time EVP_DigestVerify. The auth_keys file is loaded once at startup; the auth_keys.meta file is parsed once at startup.