# 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
[`docs/proposals/session-bound-invocation-context-proposal.md`](../proposals/session-bound-invocation-context-proposal.md).
The superseded direction is
[`docs/proposals/service-object-capabilities-proposal.md`](../proposals/service-object-capabilities-proposal.md).
Capability-system precedent is summarized in
[`docs/research/capability-systems-survey.md`](../research/capability-systems-survey.md).