Security model

How Korall Engineering™ protects your identity, data, and node control through progressive cryptographic security.

Design philosophy: Security is invisible to beginners but deep for experts. A first-time user goes from install to controlling a node with zero security decisions. An advanced user gets encrypted multi-user multi-node configurations with auditable identity.

Identity hierarchy

Korall Engineering™ uses a three-level identity model:

Device (physical hardware — phone, SBC, etc.)
  └── Node (running app — agent, remote, or hub)
        └── Sentient Identity (SID — the human operator)
              ├── Node Identity "Gustav" (NID — a personality)
              └── Node Identity "Johnny" (another personality)

Sentient Identity (SID)

A sentient identity represents a human operator. It owns one or more node identities and is secured by an encrypted hive volume.

Every node automatically creates a shadow sentient (SSID) on first boot — no setup needed. The shadow sentient has no password; physical access to the device grants full authority. Its identicon appears as a ghost shape in the navigation bar.

At any time, a shadow sentient can be upgraded to a full sentient (FSID) by setting a password. This encrypts all data with Argon2id key derivation and the first password-setter becomes the device owner.

Node Identity (NID)

A node identity is a personality that a node assumes — a keypair plus configuration, trust relationships, and audit history. NIDs are completely isolated: switching from "Gustav" to "Johnny" on the same device means different config, different trusted peers, different everything. Peers see the old NID go offline and the new one appear.

Encrypted storage

All persistent data lives inside encrypted hive volumes (Shufflecake filesystem with Argon2id key derivation). Even shadow sentients get real encryption — the hardcoded passphrase provides structural consistency, not false security.

Each NID's data lives in its own folder inside the SID's hive:

hive volume/
└── .hive/
    ├── sentient/vault.json       # SID profile + signing key
    ├── active_node_identity.json  # Last-active NID
    └── nodes/
        ├── gustav-a7f3b2c1/       # NID "Gustav"
        │   ├── identity/           # Keypair
        │   ├── config/             # App settings
        │   ├── addressbook.json    # Trusted peers
        │   └── opal-history.db     # Audit trail
        └── johnny-e4d8f901/        # NID "Johnny"
            └── ...

Trust model

Trust is binary and follows the NID, not the device or SID:

• Trust — full operational control of the peer NID
• No trust — no interaction beyond discovery

This is a deliberate simplification. Permission matrices create false security for users who don't understand them. Binary trust makes the decision always clear: "Do I trust this node? Yes or no."

The local-only flag provides one essential split: some operations (identity management, trust changes) require physical presence and cannot be invoked remotely, even by fully trusted peers.

OPAL access tiers

The OPAL task system uses precondition flags to control what operations are available at each authentication level:

Cryptographic identity

Every node identity uses Ed25519 keys by default (RSA also supported for backward compatibility):

• SID root key — derived from a 12-word BIP39 recovery phrase via PBKDF2-HMAC-SHA512 + Ed25519 seed generation
• NID key — generated independently for each node identity
• Session keys — derived per-session via ECDH for forward secrecy

All keys are stored inside the encrypted hive. Key material is held in locked memory (mlock) and zeroed on destruction.

Discovery and pairing

Pairing establishes NID-to-NID trust:

1. Discovery — LAN broadcast, QR code, or Bluetooth
2. Verification — public key exchange + identicon confirmation
3. Trust decision — user taps "Trust" (physical access required)
4. Stored — trust recorded in the NID's address book

Optional SID metadata (shadow/full status, creation date) is included in pairing messages. Peers display warnings for shadow identities and newly created nodes.

Session security

Secure sessions use a 3-way handshake (SYN/SYN-ACK/ACK) with:

• Hybrid encryption — asymmetric for handshake, symmetric for data
• XChaCha20-Poly1305 AEAD — authenticated encryption for all data
• Forward secrecy — per-session keys via ECDH
• Replay protection — 64-bit sliding window + monotonic nonces
• Cross-algorithm support — RSA nodes can pair with Ed25519 nodes

Operator authority

The human operator has ultimate authority:

• Approves all trust relationships
• Can revoke trust at any time
• Sets the device security policy (open or restricted registration)
• No automated system (including LLMs) can grant itself elevated trust

LLM interactions go through the OPAL permission system with explicit sentient approval for sensitive operations.