Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Session Context

Session-bound invocation context is the current shared-service identity model. Capabilities decide what a process may invoke. The process session supplies the privacy-preserving subject context for the invocation. Request payloads, manifest strings, and legacy endpoint receiver metadata do not identify the caller and must not authorize service behavior by themselves.

Current Behavior

Every normal workload process has one immutable SessionContext installed through trusted spawn, session-manager, or broker paths. Endpoint CALL delivery includes a scoped caller-session reference plus freshness metadata by default. The server does not receive a global principal, account, profile, display name, auth source, or tenant field unless the call explicitly requests disclosure and the invoked service/facet has a matching disclosure scope.

The current endpoint ABI carries:

  • scoped_ref and scoped_ref_hi: a 128-bit opaque caller-session reference derived from a boot secret, endpoint service scope, and kernel session id;
  • epoch: a domain-separated freshness/audit value for the same service scope;
  • liveness/freshness state used to fail closed for stale ordinary sessions.

The reference is service-scoped and non-portable. A value observed by one service is not authority and is not a stable global identity in another service.

Authority Split

Capability possession answers whether a process may invoke a target. Session context answers who the invocation is attributable to, whether the session is fresh enough, which resource/accounting bucket should be used, and which subject facts may be disclosed.

The service decision is therefore layered:

  1. capability authority;
  2. invocation subject context;
  3. service-local policy and state.

For example, holding ChatRoot lets a process ask chat to join. The caller’s live session supplies the subject context. The chat service may key its per-session state by the opaque reference and may request bounded disclosure when its method contract and broker policy allow it.

Disclosure

Disclosure is opt-in and field-granular. A service receives broader subject facts only when both conditions hold:

  • the method or call shape explicitly requests the fields;
  • the invoked capability or broker-granted facet carries a service-scoped disclosure scope allowing those fields.

Without both, endpoint metadata stays opaque. Services that need display names, profile classes, or audit labels should request only those fields and treat them as service-local policy input, not as independent authority.

Transfer And Liveness

Cross-session capability transfer is allowed only when the transferred cap’s transfer scope permits it. A transferred cap carries invoke authority; the receiver’s session remains the invocation subject. service_regrant_only caps cannot cross sessions through raw copy, move, endpoint IPC, or spawn grants; a trusted service or broker regrant path must mint target-session authority.

Ordinary endpoint calls from logged-out or expired sessions fail closed. The current liveness implementation is a Live/LoggedOut state cell plus expiry; administrator revocation, recovery-only session modes, and renewal/recovery caps remain future lifecycle work. Fixed wall-clock expiry remains a bounded guardrail, not complete production interactive-session lifecycle UX.

Code Map

  • kernel/src/session_context.rs - kernel session records, liveness state, and scoped reference derivation.
  • kernel/src/cap/endpoint.rs - endpoint caller-session delivery and stale endpoint/session checks.
  • kernel/src/cap/transfer.rs and capos-lib/src/cap_table.rs - transfer-scope validation and rollback.
  • kernel/src/cap/session_manager.rs - session creation and UserSession result-cap minting.
  • kernel/src/cap/user_session.rs - UserSession capability behavior.
  • kernel/src/cap/restricted_launcher.rs and kernel/src/cap/authority_broker.rs - broker and launch surfaces that mint session-scoped bundles.
  • capos-rt/src/client.rs - runtime clients that observe session, endpoint, and logout behavior.
  • docs/architecture/ipc-endpoints.md - endpoint transport and transfer rules.
  • docs/architecture/process-model.md - spawn and process ownership model.

Validation

  • make run-session-context covers process-session invariants, default endpoint caller-session metadata, stale normal endpoint rejection, transfer scopes, and disclosure gating.
  • make run-capnp-chat-interop and the chat/adventure smokes cover ordinary service state keyed by live caller-session metadata instead of caller-chosen selectors.
  • make run-remote-session-capset-interop and focused remote-session UI smokes cover DTO gateway logout/close propagation.
  • make run-ssh-public-key-session covers UserSession.auditContext, explicit logout idempotence, and post-logout fail-closed reads.

Open Work

  • Administrator revocation, renewal/recovery, live proxy cleanup, and audit reason separation remain future lifecycle work.
  • Stable service-audit identity across endpoint replacement or service upgrade needs a future service-audit scope.
  • Delegated act-on-behalf-of subject context is a separate future design, not part of the completed session-bound invocation context milestone.
  • A dedicated result-cap move-source rollback proof is still needed before fixed expiry is treated as the whole production session lifecycle.

Design Grounding

The archival decision record is Session-Bound Invocation Context. The superseded direction is Superseded: Service Object Capabilities. Capability-system precedent is summarized in Capability-Based and Microkernel Operating Systems Survey.