# Byteflow Security Model
## Status
This document defines the security contract of the Byteflow runtime.
The security model is intentionally capability-oriented. Byteflow does not
consider a numeric FlowId, Message field, opcode, or register value to be an
authority by itself.
The runtime is the security boundary.
---
## 1. Threat Model
Byteflow executes bytecode that may be supplied by an untrusted module.
The following distinction is fundamental:
### Trusted components
The following components are trusted:
- host Rust code;
- the Byteflow runtime;
- the scheduler;
- the mailbox implementation;
- the flow directory;
- native functions explicitly registered by the host;
- the host supervisor responsible for configuring the runtime;
- verified bytecode admission performed by the host.
Trusted components are responsible for enforcing all authority boundaries.
Bytecode must never be trusted to enforce its own security policy.
### Untrusted components
The following are considered untrusted:
- `.bf` bytecode;
- bytecode instructions;
- register contents;
- values constructed by bytecode;
- Message fields supplied by bytecode;
- Pid values supplied by bytecode;
- native arguments supplied by bytecode;
- control flow generated by bytecode.
A malformed or malicious bytecode module must therefore be assumed capable of
deliberately constructing invalid values whenever the VM permits such values.
---
## 2. Security Boundary
The VM is a computation engine, not the authority manager.
The VM may validate structural invariants required by an instruction, but it
must not grant authority merely because a bytecode value claims to possess it.
The scheduler and runtime own:
- flow identity;
- message delivery;
- mailbox ownership;
- sender authentication;
- capability resolution;
- native authority;
- resource quotas.
This distinction is critical.
A register containing:
```text
Value::Pid(42)
```
does not prove that the current flow is authorized to communicate with flow 42.
Likewise:
```text
Message {
sender: 42,
...
}
```
does not prove that flow 42 actually created the message.
---
## 3. Atomic Hop Security
Byteflow's Atomic Hop model establishes that Send and Ask operate on
`Value::Message`.
This provides an important structural invariant:
```text
Send/Ask -> Message -> mailbox
```
However, structural typing is not authentication.
A Message constructed by bytecode may contain arbitrary application data,
including a forged sender field.
Therefore the runtime MUST authenticate the sender at the scheduler boundary.
The authoritative sender is:
```text
current_flow.id
```
and never:
```text
Message.sender
```
provided by bytecode.
---
## 4. Authenticated Sender
### Rule
Before a Message is delivered by Send or Ask, the runtime MUST overwrite the
sender field with the identity of the flow performing the operation.
Conceptually:
```text
message.sender = current_flow.id;
```
The value originally contained in `Message.sender` MUST NOT influence the
authenticated origin of the hop.
This means the following bytecode behavior is intentionally ineffective:
```text
make_msg(
sender = victim_flow,
request_id = 1,
tag = REQUEST,
payload = 41
)
```
followed by `Send(...)`. The receiver MUST observe `sender = actual_sender_flow`
and never `sender = victim_flow`.
Host-side [`Runtime::send`](../src/scheduler/runtime.rs) remains a **trusted**
injection path: the host may choose `sender` (including `0` for non-flow
origins). Only bytecode-driven `Send` / `Ask` are re-stamped.
---
## 5. Why Sender Authentication Happens in the Worker
Sender stamping MUST happen after the VM has identified the current flow and
before the message enters another flow's mailbox.
The VM does not own mailbox state and must not become responsible for
scheduler authority.
The intended execution boundary is:
```text
bytecode
|
v
VM validates Message
|
v
VmResult::Send / VmResult::Ask
|
v
scheduler / worker
|
+--> authenticate sender
|
+--> resolve destination
|
+--> deliver mailbox message
|
v
target flow
```
The scheduler therefore becomes the single authority responsible for the
identity associated with an outgoing hop.
---
## 6. Ask Security
Ask uses request correlation.
The reply MUST NOT be accepted solely because the request_id matches.
The authenticated reply rule is:
```text
reply.request_id == request.request_id
&&
reply.sender == target
```
where `target` is the flow to which the request was delivered.
This prevents an unrelated flow from satisfying an outstanding Ask by
guessing or reusing a request_id.
The request itself is also sender-stamped before delivery.
Therefore:
- forged request sender → overwritten by runtime
- forged reply sender → rejected by Ask correlation
are separate security properties. Both are required.
After FlowCap (0.5.x), Ask must compare `reply.sender` to the **resolved
FlowId** behind the target Cap — never to a CapId.
---
## 7. FlowCap — Current Version (0.5.x)
Bytecode `Send` / `Ask` require [`Value::Cap`]. A CapId is opaque and resolves
through the runtime `CapTable` to `{ FlowId, CapRights }` (`SEND`, `ASK`).
[`Value::Pid`] remains for **identity** inside authenticated messages
(`Message.sender` / `msg_sender`). It is **not** an ambient address.
Outgoing hops also mint `Message.reply_cap` with **SEND**-only rights so a
receiver can answer without knowing or forging a Pid address.
`SelfPid` and bytecode `Spawn` write a Cap (`SEND|ASK`) into the destination
register — not a raw Pid.
Host `Runtime::send(FlowId, …)` remains a trusted host path (no Cap required).
---
## 8. Message Construction
The current `make_msg` native may accept a sender field for compatibility with
the existing Value/Message ABI.
That field MUST be considered untrusted metadata.
The sender field supplied by `make_msg` is never authoritative.
For outgoing Send and Ask operations:
```text
runtime_sender = current_flow.id
```
always wins.
Future versions may remove the sender argument from `make_msg` entirely.
That is an API cleanup, not a prerequisite for sender authentication.
---
## 9. Native Authority
Native functions are trusted host extensions.
A native function executes with authority granted by the host's native table.
Bytecode must not be able to manufacture native authority merely by providing
a numeric native index.
The current native-index ABI is preserved in 0.4.x.
Native capabilities and per-flow native allowlists are planned for a later
security phase.
Until then:
- NativeTable configuration = trusted
- native index supplied by bytecode = untrusted input
---
## 10. Mailbox Security
Mailbox operations are scheduler-owned operations.
The mailbox MUST preserve the existing anti-lost-wakeup invariant:
`park + push/wake` must be synchronized under the same mailbox synchronization
boundary.
Selective receive MUST preserve FIFO-skip semantics.
A message that does not satisfy the active waiter filter must remain in the
mailbox.
Security changes MUST NOT weaken these synchronization guarantees.
---
## 11. Fail-Closed Policy
Security failures must fail closed.
Production code MUST NOT use `unwrap()` / `expect()` for runtime security
decisions.
Poisoned synchronization primitives MUST NOT be recovered through
`PoisonError::into_inner()`.
A poisoned security-relevant lock is treated as a runtime failure.
The runtime must prefer refusing an operation over continuing with potentially
corrupted authority state.
---
## 12. Panic Isolation
Untrusted bytecode must not be able to directly terminate the host process
through ordinary VM execution.
Runtime boundaries should convert invalid bytecode operations into explicit
VM traps or scheduler errors.
Host-native code remains trusted.
A malicious or incorrectly implemented native may still violate host-level
assumptions. Native isolation is therefore outside the VM's trust guarantees.
---
## 13. Denial of Service
Byteflow 0.4.x does not yet provide complete resource isolation.
The following remain known limitations:
- unlimited or insufficiently bounded mailbox growth;
- unrestricted flow creation where permitted by the host;
- potentially unbounded outstanding Ask operations;
- native functions that consume arbitrary host resources.
Resource quotas are planned for the quota phase.
Capability security prevents unauthorized access but does not automatically
prevent an authorized flow from exhausting resources.
---
## 14. Timing Side Channels
Byteflow does not currently claim resistance against timing side channels.
Observable differences may exist through scheduling, mailbox contention,
message latency, native execution, flow starvation, and resource exhaustion.
Applications requiring side-channel resistance must implement additional
isolation at the host/platform level.
---
## 15. FFI Boundary
FFI and native code are trusted boundaries.
Values crossing the FFI boundary must be validated before being converted into
runtime-owned structures.
A host must not construct invalid internal runtime state through unsafe or
unchecked FFI integration.
The Byteflow runtime does not treat an FFI-provided value as trusted merely
because it originated outside bytecode.
---
## 16. Future Capability Model
The target security architecture is object-capability based.
The intended model is `Value::Cap(CapId)` where CapId is opaque and is not a
FlowId.
A capability resolves through the runtime directory to `{ FlowId, Rights }`
(e.g. `SEND`, `ASK`, `LINK`, `ADMIN`).
The bytecode-visible capability MUST NOT expose the underlying FlowId.
Capability creation, delegation and attenuation belong to the trusted runtime.
---
## 17. Security Invariants
The following invariants are normative.
### S1 — Sender authenticity
A receiver observes the sender assigned by the runtime, never the sender
claimed by bytecode.
### S2 — Ask reply authenticity
An Ask completes only when the reply matches both `request_id` and
`sender == requested target`.
### S3 — VM authority separation
The VM does not directly manipulate mailboxes, scheduler state, timers or
threads.
### S4 — Fail closed
Invalid security state results in an error/trap rather than recovery using
possibly corrupted state.
### S5 — FIFO selective receive
Selective waiting does not discard unrelated messages.
### S6 — Cap is the address; Pid is identity
Bytecode addressing for `Send` / `Ask` uses `Value::Cap`. `Value::Pid` is
authenticated identity only and does not grant delivery authority.
### S7 — Native index is not inherently a capability
Native authorization is currently host-configured and is not yet represented
as a first-class bytecode capability.
---
## 18. Security Roadmap
### Phase 1 (done)
Authenticated sender stamping on bytecode `Send` / `Ask`.
### Phase 2 (done — 0.5.x)
Flow capabilities: `Value::Cap` for Send/Ask; `reply_cap` grant; Pid = identity.
### Phase 3
Native capabilities and resource quotas.
### Phase 4
Optional host-side bytecode attestation.
---
## 19. Non-Goals
The following are explicitly outside the current security model:
- cryptographic authentication between flows;
- encrypted mailbox contents;
- OS sandboxing / seccomp / process isolation;
- constant-time scheduling;
- protection against malicious trusted natives;
- complete DoS resistance;
- cryptographic module attestation.
These may be implemented at higher layers where appropriate.