# Trust Boundaries

This page gives reviewers one place to find the hostile-input boundaries,
trusted inputs, and current isolation assumptions that matter for capOS
security review.

## Current Boundaries

### Ring 0 to Ring 3

- **Trust rule:** the kernel trusts no userspace register, pointer, SQE,
  CapSet, or result-buffer field.
- **Implemented:** syscall arguments, user-buffer ranges, page permissions,
  opcodes, and capability-table lookups are validated before privileged use in
  `kernel/src/arch/x86_64/syscall.rs`, `kernel/src/mem/paging.rs`,
  `kernel/src/mem/validate.rs`, and `kernel/src/cap/ring.rs`.
- **Validation:** [`../panic-surface-inventory.md`](../panic-surface-inventory.md)
  and `REVIEW.md` at the repository root.

### Capability Table to Kernel Object

- **Trust rule:** a process acts only through a live table-local `CapId` with
  matching generation and interface.
- **Implemented:** `capos-lib/src/cap_table.rs` owns generation-tagged slots;
  kernel capability dispatch goes through `CapObject::call`.
- **Validation:** `cargo test-lib` plus QEMU ring and IPC smokes recorded in
  done task records.

### Capability Ring Shared Memory

- **Trust rule:** userspace owns SQ writes, but the kernel owns validation,
  dispatch, completion, and failure semantics.
- **Implemented:** SQ/CQ headers and entries live in
  `capos-config/src/ring.rs`; kernel dispatch bounds indexes, opcodes,
  transfer descriptors, and CQ posting, and copies CALL/RECV/RETURN buffers
  while holding the owning process `AddressSpace` lock.
- **Validation:** `cargo test-ring-loom` plus QEMU ring corruption, reserved
  opcode, fairness, IPC, and transfer smokes.

### Endpoint IPC and Transfer

- **Trust rule:** IPC cannot create or destroy authority except through
  explicit copy, move, release, or spawn transactions. Delegating an imported
  client facet must preserve service-visible identity, and shared-service
  handlers should derive caller identity from live caller-session metadata.
- **Implemented:** `kernel/src/cap/endpoint.rs`,
  `kernel/src/cap/transfer.rs`, and `capos-lib/src/cap_table.rs` implement
  queued calls, `RECV`/`RETURN`, copy/move transfer, legacy receiver metadata
  propagation, and rollback. Legacy badge metadata is a debug/test surface
  only. Normal chat, stdio bridge, and shared demo handlers use live
  caller-session metadata instead of caller-selected badge identity.
- **Validation:** [`../authority-accounting-transfer-design.md`](../authority-accounting-transfer-design.md)
  and any open transfer review-finding task records.

### Manifest and Boot Package

- **Trust rule:** boot manifest bytes and embedded binaries are untrusted until
  parsed and validated. Only BootPackage holders can request chunked manifest
  bytes; ordinary services receive no default boot-package authority.
- **Implemented:** `tools/mkmanifest` validates the embedded `initConfig`
  graph before serialization. Kernel bootstrap validates the kernel-owned
  manifest boundary before loading one init process; init BootPackage
  validation resolves service graph references before spawning children.
  `kernel/src/cap/boot_package.rs`, `capos-lib/src/elf.rs`, and load paths
  still enforce manifest-read, ELF, load-range, CapSet, and interface bounds.
- **Validation:** `cargo test-config`, `cargo test-mkmanifest`,
  `cargo test-lib`, manifest and ELF fuzz targets, and `make run`.

### Process Spawn Inputs

- **Trust rule:** parent-supplied spawn params, ELF bytes, grants, legacy
  badges, and result-cap insertion must fail closed. Endpoint kernel grants
  must not share owner caps with the parent. Delegated client facets must not
  be relabeled into another service identity.
- **Implemented:** `ProcessSpawner` validates ELF load, grants, frame
  exhaustion, parent cap-slot exhaustion, child-local endpoint creation, and
  parent-only client result facets. Delegated `ClientEndpoint` grants preserve
  source identity; explicit relabel encodings fail closed except for owner or
  trusted parent endpoint-result caps.
- **Validation:** spawn QEMU smoke evidence and review-finding task records.

### Console Authentication and Setup

- **Trust rule:** console input, account selectors, password verifiers, setup
  tokens, and passkey challenge state are hostile or sensitive until a
  login/session component validates them.
- **Implemented:** `Console` remains output-only. The first interactive
  boundary is session-scoped `TerminalSession` with bounded `readLine`,
  visible/hidden echo, structured cancellation, one move-only foreground
  holder, caller-session-checked output, and stale-input scrubbing on cancel or
  owner teardown. `CredentialStore` verifies one manifest-supplied Argon2id
  operator credential and one bounded volatile RAM-overlay password created by
  first-boot setup. `capos-shell` drives `login` and `setup`; there is no
  separate `ConsoleLogin` service.
- **Validation:** [`../proposals/boot-to-shell-proposal.md`](../proposals/boot-to-shell-proposal.md),
  boot-to-shell gates in [`../../docs/tasks/README.md`](../../docs/tasks/README.md),
  `make run-terminal`, `make run-login`, and `make run-login-setup`.
- **Open/future:** durable multi-account credential storage, multiple verifier
  records, rotate/disable state, broader anti-enumeration audit policy, and
  bounded single-use setup-token/challenge state.

### Session Authority and Audit

- **Trust rule:** authenticated sessions receive only broker-issued narrow
  caps. Audit output, service logs, terminal output, and failed-auth
  diagnostics must not disclose secrets or verifier material.
- **Implemented:** `SessionManager` mints entropy-backed `UserSession`
  metadata for operator, explicitly seeded guest, and anonymous profiles.
  Endpoint caller-session references are HMAC-SHA256 values scoped by an
  entropy-backed boot key and non-reused endpoint service-scope id.
  `AuthorityBroker` validates session/profile matches before minting bundles.
  `RestrictedLauncher` returns shell-scoped launch paths instead of
  BootPackage or broad ProcessSpawner authority.
- **Validation:** [`../proposals/user-identity-and-policy-proposal.md`](../proposals/user-identity-and-policy-proposal.md),
  [`../proposals/boot-to-shell-proposal.md`](../proposals/boot-to-shell-proposal.md),
  `make run-login`, `make run-login-setup`, and future auth/session hostile
  input tests.
- **Open/future:** audit records, stable service-audit identity across endpoint
  replacement, opaque record IDs, mutable session liveness cells,
  `UserSession.logout`, owner-shell/gateway close propagation, narrow renewal
  paths, broader policy evaluation, and web-terminal origin/RP-ID validation.

### SSH Remote Shell Ingress

- **Trust rule:** SSH network input, keys, usernames, channel requests, PTY
  state, environment requests, and disconnects are hostile until the gateway
  validates protocol state, authenticates the user, and receives a
  broker-issued shell bundle.
- **Implemented:** current proofs cover schema stubs, one development-only
  host-key fixture, manifest-seeded `AuthorizedKeyStore`, public-key session
  minting, unsupported-feature policy, restricted shell launch, and bounded
  terminal-host wiring over host-local plain TCP. The proposal keeps SSH
  transport authority in `SshGateway`; the spawned shell receives only an
  `SshTerminalFactory`-produced `TerminalSession` plus the normal scoped
  session bundle through `RestrictedShellLauncher`. Fixture host-key signing,
  authorized-key mapping, public-key session minting, SSH policy rejection, and
  restricted launcher inputs fail closed for malformed or unsupported cases.
- **Validation:** [`../proposals/ssh-shell-proposal.md`](../proposals/ssh-shell-proposal.md),
  [`../backlog/runtime-network-shell.md`](../backlog/runtime-network-shell.md),
  `make run-ssh-host-key`, `make run-ssh-authorized-key`,
  `make run-ssh-public-key-session`, `make run-ssh-public-key-auth`,
  `make run-ssh-feature-policy`, and `make run-restricted-shell-launcher`
  (the plain-TCP `run-ssh-gateway-terminal-host` terminal-host proof is
  retired with the kernel socket owner).
- **Open/future:** full SSH transport transcript and channel binding,
  password-auth verifier/backoff wiring, production host-key storage, broader
  account storage, and production remote-shell hardening.

### Identity Metadata and Account Records

- **Trust rule:** users, principals, accounts, sessions, roles, and profile
  names are policy metadata, not kernel subjects, ambient authority, or
  substitutes for held capabilities.
- **Implemented:** sessions receive capabilities only after authentication and
  broker policy evaluation; a principal or account record does not run or call
  the kernel.
- **Validation:** [`../backlog/local-users-management.md`](../backlog/local-users-management.md)
  and [`../proposals/user-identity-and-policy-proposal.md`](../proposals/user-identity-and-policy-proposal.md).
- **Open/future:** durable local account-store behavior, profile persistence,
  rollback checks, and quota enforcement.

### Host Tools and Filesystem

- **Trust rule:** manifest/config input must not escape intended source
  directories or invoke unconstrained host commands.
- **Implemented:** `tools/mkmanifest` validates references and path
  containment, rejects unpinned CUE compilers, and Makefile targets route CUE
  and Cap'n Proto through pinned tool paths.
- **Validation:** [`../trusted-build-inputs.md`](../trusted-build-inputs.md),
  `make generated-code-check`, and `make dependency-policy-check`.

### Generated Code and Schema

- **Trust rule:** schema, generated bindings, and no_std patches are trusted
  build inputs.
- **Implemented:** `schema/capos.capnp`, build scripts,
  `tools/generated/capos_capnp.rs`, and `tools/check-generated-capnp.sh` make
  generated-code drift review-visible.
- **Validation:** [`../trusted-build-inputs.md`](../trusted-build-inputs.md)
  and `make generated-code-check`.

### Device DMA and MMIO

- **Trust rule:** current userspace receives no raw DMA buffer, device physical
  address, virtqueue pointer, BAR mapping, or device interrupt handle.
- **Implemented:** the QEMU virtio-net path is allowed only through
  kernel-owned bounce buffers and kernel-owned MSI-X source records routed
  through the kernel device interrupt dispatch table, bounded device MSI vector
  pool, and kernel-owned route lifecycle checks.
- **Validation:** [`../dma-isolation-design.md`](../dma-isolation-design.md)
  and `make run-net`.
- **Open/future:** typed `DMAPool`, `DeviceMmio`, and `Interrupt`
  capabilities for userspace-driver transition.

### Panic and Emergency Paths

- **Trust rule:** hostile input should produce controlled errors, not panic,
  allocate unexpectedly, or expose stale state.
- **Implemented:** ring dispatch is mostly controlled-error; remaining panic
  surfaces are classified by reachability and tracked as hardening work.
- **Validation:** [`../panic-surface-inventory.md`](../panic-surface-inventory.md)
  and `REVIEW.md`.

## Security Invariants

- All authority is represented by capability-table hold edges; no syscall or
  host tool path should bypass the capability graph.
- Identity metadata is not authority. Principals identify audit and policy
  subjects, accounts store durable policy inputs, profiles select bundle and
  quota templates, and sessions receive caps only through explicit broker
  minting.
- The interface is the permission: method authority is expressed by the typed
  Cap'n Proto interface or by a narrower wrapper capability, not by ambient
  process identity.
- Kernel operations at hostile boundaries validate structure, bounds,
  ownership, generation, interface ID, and resource availability before
  mutating privileged state.
- Failed transfer, spawn, manifest, and DMA setup paths must leave ledgers,
  cap tables, frame ownership, and in-flight call state unchanged or explicitly
  rolled back.
- Trusted build inputs must be pinned or drift-review-visible before their
  output becomes part of the boot image or generated source baseline.
- Authentication/session code must treat credential records, setup tokens,
  passkey challenges, session IDs, and audit logs as security boundaries, not
  ordinary console text.

## Open Work

- Unify fragmented resource ledgers into the authority-accounting model so
  reviewers can audit quotas without following parallel counters.
- Harden open panic-surface entries that become more exposed as spawn,
  lifecycle, SMP, or userspace drivers expand hostile input reachability.
- Keep DMA in kernel-owned bounce-buffer mode until the `DMAPool`,
  `DeviceMmio`, and `Interrupt` transition gates have code and QEMU proof.
- Do not expand production authentication or remote-shell surfaces without
  hostile-input tests for bounded terminal input, credential failure paths,
  challenge expiry/replay, audit redaction, and narrow shell cap bundles.