SECURITY_SPEC.md
1. Security design goals
Goals:
• Memory safety in all safe NXD code
• Predictable error behavior
• Controlled capabilities (IO, network, filesystem, crypto)
• Auditable unsafe operations
• Backend‑agnostic guarantees across Nim, Elixir, and D
NXD is explicitly designed for security‑sensitive systems (your Homeland OS vision).
2. Memory safety
Safe NXD code guarantees:
• No manual free
• No use‑after‑free
• No dangling references
• No implicit shared mutable state between processes
• Ownership operations (MOVE, CLONE, BORROW) are visible in IR
Backend mapping:
• Nim → ARC/ORC/GC, ref, ptr only in unsafe regions
• Elixir → immutable data, BEAM GC
• D → GC/RAII, pointers only in unsafe regions
3. Integer and bounds safety
Integer handling:
• Default int operations are checked in safe NXD:• overflow → ERR("integer overflow") or exception
• Explicit UNSAFE_INT operations may be added later for unchecked arithmetic.
Bounds checking:
• All list/array/map indexing in safe NXD is bounds‑checked:• out‑of‑range → ERR("index out of bounds") or exception
These rules are enforced in IR and by backend shims.
4. Unsafe blocks
NXD reserves explicit unsafe regions:
UNSAFE:
RAW_MEMORY_ACCESS()
Semantics:
• Inside UNSAFE, memory and integer safety guarantees are relaxed.
• Pointer arithmetic, manual allocation, FFI, and backend‑specific low‑level operations are allowed.
• All unsafe regions are:• marked in IR
• visible to audit agents
• traceable in compiled output
Backend mapping:
• Nim/D → direct pointer/FFI operations
• Elixir → NIFs, ports, or external calls
5. Capability and permissions model
NXD treats sensitive operations as capabilities, not just functions:
Capability domains:
• Filesystem
• Network
• Crypto
• Process control
• System resources
Example:
FUNC READ_SECURE(FILE, CAP_FS_READ):
...
Semantics:
• Certain APIs require explicit capability tokens.
• Capabilities can be:• granted at startup
• restricted per module/package
• audited via IR and runtime logs
This gives you a foundation for sandboxing and least‑privilege execution.
6. Sandboxing and isolation
Process isolation:
• NXD processes are logically isolated:• no implicit shared mutable state
• communication via channels/messages only
Sandboxing:
• A future spec can define:• sandboxed processes with restricted capabilities
• module/package‑level security policies
• runtime enforcement via backend shims
The security spec makes isolation a core semantic, not an afterthought.
7. Crypto interfaces
NXD’s standard library will expose high‑level crypto APIs, not raw primitives:
• HASH(data)
• ENCRYPT(data, key)
• DECRYPT(data, key)
• SIGN(data, key)
• VERIFY(data, sig, key)
Rules:
• Safe defaults only (no weak algorithms by default).
• Algorithm selection is explicit and auditable.
• Backend implementations must use vetted libraries.
8. Error handling and security
Security‑relevant errors:
• must never be silently swallowed
• must be visible in IR and logs
• should use RESULT or explicit exceptions
Examples:
• auth failure → ERR("unauthorized")
• capability violation → ERR("capability denied") or exception
• sandbox violation → exception + runtime log
9. Auditability
NXD is designed so that security agents can reason about programs:
• IR contains:• ownership operations
• unsafe blocks
• capability usage
• concurrency primitives
• Runtime logs:• process/task lifecycle
• channel usage
• capability checks
• critical errors
This makes NXD code inspectable for security posture.
Short summary
NXD security is built on:
• safe defaults (memory, integers, bounds)
• explicit unsafe regions
• capability‑based sensitive operations
• process isolation and message passing
• auditable IR and runtime behavior
Documentation