Skip to main content

Module security

byteflow::docs

Module security 

Source
Expand description

Security model: authenticated sender, FlowCap, invariants S1–S7.

§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:

Value::Pid(42)

does not prove that the current flow is authorized to communicate with flow 42.

Likewise:

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:

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:

current_flow.id

and never:

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:

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:

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 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:

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:

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:

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.