VISK.^APP

Overview

The Visk Ops admin panel is the control plane for the sovereign relay. It exposes five process groups (SIGRUN, EIR, SKULD, GONDUL, HRIST) that map directly to server modules and policies. The relay enforces zero-knowledge behavior by never decrypting payloads and by storing only encrypted operational state.

The admin panel runs on the relay admin port (configured in config/relay.ini under [admin]). Use the panel to issue launch keys, tune boundaries and shielding, manage lifecycle/telemetry settings, administer consensus keys, and coordinate emergency actions.

Compliance & Audit Logging

Visk Ops is designed to satisfy strict regulatory compliance frameworks (such as NIS2 and CMMC) without compromising its Zero-Knowledge architecture. We achieve this by strictly separating Operational Audit Trails from Payload Telemetry.

The relay logs infrastructure management and access control events to satisfy compliance auditors, but remains physically incapable of logging user communication graphs, IP addresses, or message content.

1. What is Persisted (Operational Audit Log)

When Enterprise Compliance Mode is enabled in config/relay.ini, the following events are written to an encrypted, tamper-evident local log file (signed by the relay's ML-DSA identity):

• Admin Authentication: Successful and failed login attempts to the Visk Ops panel.
• SIGRUN Policy Changes: Modifications to cryptography layers (e.g., toggling ML-NGES, changing Argon2 parameters), boundary defense updates (CIDR/ASN changes), and shield tuning.
• SKULD Consensus Events: Records of prepared votes, submitted ML-DSA signatures, and executed multi-sig commands.
• Access Control Issuance: Timestamps of when Launch Keys were generated and when they were burned (redeemed) by a client hash.
• Federation (Kara) Events: Generation of enrollment tokens and the addition/removal of trusted relay bridges.

2. What is STRICTLY FORBIDDEN (Zero-Knowledge)

To maintain absolute information sovereignty, the relay explicitly drops the following data from memory and it never reaches the disk:

• Client IP Addresses: Connections are processed and routed without persisting origin IPs.
• Social Graphs: The relay does not track who is messaging whom. Dead-drop mailboxes are isolated.
• Message Metadata: Payload sizes, precise transmission timestamps, and client routing paths are not recorded.
• Plaintext Content: All payloads remain wrapped in the WDES pipeline (ML-KEM, Argon2, ML-NGES, ML-DSA, AES-GCM). The relay holds no decryption keys.

3. SIEM Integration

For high-assurance environments requiring central log aggregation, the operational audit log can be configured to output to standard enterprise SIEM forwarders (e.g., Splunk, ELK) in JSON format. Because the logs contain zero user metadata, forwarding these logs does not risk data privacy breaches or violate data residency policies.

Access & Authentication

Login Screen

• Password: The admin password is set in config/relay.ini as admin.password or admin.password_hash. The UI only allows login when a hash is present.
• Unlock Console: Submits the password to /api/admin/login. A session cookie (vchat_admin) is issued on success.

Host Restrictions

The admin server enforces host allowlists via admin.server_hosts. Requests from hosts not in this list are rejected. Localhost is always allowed.

Console Layout

• Top Status Bar: Displays overall system status and process integrity derived from the canary test. “OPERATIONAL” means the canary is passing; “DEGRADED” indicates a failed canary.
• Left Navigation: The process groups with functional names and system process IDs. Selecting a process shows the corresponding panel.
• Main Panel: Configuration and action controls for the selected process.
• Event Log: Real‑time ops events emitted by the relay, with timestamps and process tags.

General Setup

1. Set admin password in config/relay.ini and start the relay with python Visk_Relay.py.
2. Open the admin console (admin port) and log in.
3. Configure Access Control (enable, set TTL, generate launch keys).
4. Configure shield settings to match expected traffic patterns.
5. Set lifecycle TTL for offline mailbox retention.
6. Enter consensus keys and required approval threshold.

SIGRUN: Access Control

Enforces token-based admission and allowlist policies. Launch keys are signed by the relay’s ML‑DSA identity and can be used once to whitelist a client’s ML‑KEM public key.

Controls

• Enable Access Control (auth-enabled): If enabled, clients must present a launch key unless their key is already whitelisted.
• Require Aetherion Encryption (auth-encryption): If enabled, app clients must supply ML‑KEM + ML‑DSA public keys. Web proxy clients are exempt.
• Launch Key TTL (sec) (auth-ttl): Expiration time for launch keys.
• Save Access Policy (auth-save): Writes the Access Control policy to encrypted ops state.
• Allow‑list size (auth-allowlist-count): Count of whitelisted ML‑KEM key hashes.
• Launch Key Label (launch-label): Optional identifier for the key recipient.
• Generate Launch Key (launch-generate): Requests a new launch key and displays it.
• Launch Key Output (launch-token): Read‑only token to deliver to the client.

How it works

1. Admin generates a launch key (signed by the relay ML‑DSA identity).
2. Client supplies the launch key in the Visk app (Settings → Access Key).
3. Relay validates and burns the key, then whitelists the client’s ML‑KEM public key hash.

SIGRUN: Cryptography Policy

Controls the payload encryption layers. Adjusting these settings forces connected clients to renegotiate parameters on their next handshake.

Controls

• Enable Aetherion (crypto-nges-enabled): If disabled, the relay and clients strip the outer lattice layer and use standard AES-256-GCM only. Default: True.
• NGES Profile (crypto-nges-profile): Sets the lattice parameter set for the outer layer. Options: ION (128), NEUTRON (192), QUASAR (256 - Default), SAF (512).
• DRBG Engine (crypto-drbg): Sets the stream generator for the relay. Options: AES-CTR (Default), SHAKE-256.
• KEM Level (crypto-kem): Sets the Kyber level for key exchange. Options: ML-KEM-1024 (Default), ML-KEM-768, ML-KEM-512.
• DSA Level (crypto-dsa): Sets the Dilithium level for signatures. Options: ML-DSA-87 (Default), ML-DSA-65, ML-DSA-44.
• Argon2 Time Cost (crypto-argon-time): Iterations for Argon2 key derivation. Default: 1.
• Argon2 Memory (crypto-argon-mem): Memory cost in MiB for Argon2. Default: 16.
• Argon2 Parallelism (crypto-argon-parallel): Lanes/threads for Argon2. Default: 1.
• Save Crypto Policy (crypto-save): Writes settings to encrypted ops state.

SIGRUN: Boundary Defense

Enforces ingress boundaries at the network edge. Updates require consensus.

Controls

• Allow CIDR (wall-allow): One CIDR per line. If set, only these networks are allowed.
• Deny CIDR (wall-deny): One CIDR per line. Deny rules override allow rules.
• Allow ASN (wall-allow-asn): ASN identifiers allowed (requires ASN map file).
• Deny ASN (wall-deny-asn): ASN identifiers denied.
• Prepare Consensus Vote (wall-prepare): Generates a vote payload for signing.
• Vote Payload (wall-vote-message): Read‑only string to be signed.
• Admin Public Key (wall-vote-key): Base64 ML‑DSA public key of the signer.
• Signature (wall-vote-sig): Base64 signature of the vote payload.
• Submit Signature (wall-submit): Submits a signature toward consensus.

SIGRUN: Active Shielding

Proof‑of‑work challenges to throttle high‑volume senders and ban malformed lattice payloads.

Controls

• Enable Shielding (shield-enabled): Toggle shield enforcement.
• Window (sec) (shield-window): Rate‑limit window for connections and messages.
• Max Connections (shield-max-conn): Max connection attempts per window before PoW challenge.
• Max Messages (shield-max-msg): Max messages per window before PoW challenge.
• Puzzle Difficulty (shield-difficulty): Leading‑zero bit count for SHA‑256 puzzle.
• Ban Duration (sec) (shield-ban): Time to ban an IP after a failed challenge.
• Save Shield Policy (shield-save): Writes shielding policy to encrypted ops state.

EIR: Data Entropy

Automated retention and cryptographic erasure for stored mailbox messages.

Controls

• Message TTL (sec) (decay-ttl): Time‑to‑live for mailbox messages.
• Secure Overwrite Passes (decay-passes): Number of overwrite passes before removal.
• Save Lifecycle Policy (decay-save): Writes lifecycle policy to encrypted ops state.

EIR: Traffic Obfuscation

Injects encrypted “chaff” packets to normalize traffic volume.

Controls

• Enable Chaff Injection (mist-enabled): Toggle chaff broadcast.
• Interval (sec) (mist-interval): Chaff broadcast interval.
• Payload Size (bytes) (mist-size): Size of random payload encrypted with ML‑NGES.
• Save Obfuscation Policy (mist-save): Writes obfuscation policy to encrypted ops state.

EIR: Blind Telemetry

System health reporting without payload or contact metadata.

Readouts

• CPU: Host CPU utilization.
• Memory: Host memory utilization.
• Messages/sec: Rate derived from relay message counters.
• Canary: Result of the cryptographic self‑test (ML‑KEM + ML‑DSA + ML‑NGES).

SKULD: Consensus Command

Multi‑signature authorization for critical actions (boundary changes, alerts, dissolution).

Controls

• Required Approvals (skuld-threshold): Number of signatures required to execute a vote.
• Admin Public Keys (skuld-keys): One ML‑DSA public key per line, base64 encoded.
• Save Consensus Policy (skuld-save): Writes consensus policy to encrypted ops state.

Voting Flow

1. Prepare a vote in the relevant panel (Boundary Defense, Crisis Broadcast, Total Dissolution).
2. Sign the vote payload string using an approved ML‑DSA private key.
3. Submit the signature in the panel. When threshold is reached, the action executes.

SKULD: Federated Trust

Manages relay federation via Kara enrollment tokens and the signed relay registry.

Controls

• Relay Identity (ML-DSA) (identity-dsa): This relay's ML-DSA public key.
• Relay Identity (ML-KEM) (identity-kem): This relay's ML-KEM public key.
• Kara Public Key (kara-public-key): The pinned Kara authority key.
• Shard Hint (kara-shard-hint): Optional 2-character shard ID.
• Token TTL (kara-token-ttl): Enrollment token validity window in seconds.
• Generate Enrollment Token (kara-token-generate): Creates a signed Kara token.
• Enrollment Token (kara-token-output): Paste into relay.ini for initial Kara enrollment.
• Federated Relays: Shows enrolled relay endpoints, shard IDs, and policy sync status.

Connecting Two Relays

The console supports explicit exchange of ML‑DSA public keys for peer relays. This establishes a trusted record of the peer identity, but it does not automatically route traffic or open tunnels.

1. On Relay A, copy the ML‑DSA public key from the Federated Trust panel.
2. On Relay B, add Relay A as a peer with a name and the copied key.
3. Repeat in the opposite direction to establish a mutual record.

Consensus CLI

The relay repository includes a helper to generate and sign ML‑DSA keys:

python tools/visk_ops_cli.py gen-key
python tools/visk_ops_cli.py sign --private-key <base64> --message "<vote message>"

The vote message is shown in the console when you prepare a vote. Paste the resulting signature and the corresponding public key into the console fields to submit approval.

GONDUL: Crisis Broadcast

Delivers a signed system‑wide alert to all connected clients.

Controls

• Alert Message (alert-message): The text delivered to all clients.
• Prepare Consensus Vote (alert-prepare): Generates a vote payload for signing.
• Vote Payload (alert-vote-message): Read‑only payload string to sign.
• Admin Public Key (alert-vote-key): Base64 ML‑DSA public key of signer.
• Signature (alert-vote-sig): Base64 signature of the payload.
• Submit Signature (alert-submit): Submits a signature toward consensus.

GONDUL: Total Dissolution

Irreversibly wipes relay state and keys, then terminates the process.

Controls

• Prepare Dissolution Vote (end-prepare): Generates a vote payload for signing.
• Vote Payload (end-vote-message): Read‑only payload string to sign.
• Admin Public Key (end-vote-key): Base64 ML‑DSA public key of signer.
• Signature (end-vote-sig): Base64 signature of the payload.
• Submit Signature (end-submit): Submits a signature toward consensus.

HRIST: Startup Shakedown

Controls whether the relay runs the full Hrist test suite during startup. Changes require consensus.

Controls

• Enable Startup Testing (hrist-enabled): Global on/off for startup tests.
• Prepare Consensus Vote (hrist-startup-prepare): Generates a vote payload.
• Vote Payload (hrist-startup-vote-message): Read-only payload string to sign.
• Admin Public Key (hrist-startup-vote-key): Base64 MLDSA public key of signer.
• Signature (hrist-startup-vote-sig): Base64 signature of the payload.
• Submit Signature (hrist-startup-submit): Submits a signature toward consensus.

HRIST: Testing Groups

Fine-grained toggles for each Hrist testing group. Changes require consensus.

Controls

• Crypto Policy (hrist-group-crypto): VPQ5, KEM, DSA, NGES tests.
• Persistence (hrist-group-persistence): Store and state roundtrip tests.
• Sigrun (hrist-group-sigrun): Access control and shielding tests.
• Eir (hrist-group-eir): Lifecycle/obfuscation tests.
• Skuld (hrist-group-skuld): Consensus engine tests.
• Gondul (hrist-group-gondul): Crisis response tests.
• Core (hrist-group-core): Permissions and baseline checks.

Event Log

The right sidebar in the actual admin panel displays recent operational events tagged with process IDs. These events include launch key issuance, shield actions, federation updates, and emergency actions. Events are stored in memory only and not persisted.

Client Behavior

• Launch Key: The Visk app stores a launch key in Settings → Access Key and sends it on the hello payload.
• Shield Challenges: Clients solve SHA‑256 PoW puzzles and reply with shield.solve.
• System Alerts: Clients display system.alert and system.shutdown messages in a banner.
• Zero‑Knowledge: Messages use ML‑KEM + ML‑DSA with AES-256-GCM and optional ML‑NGES; the relay never decrypts payloads.

Admin API Reference

• GET /api/ops/summary: Status, integrity, and telemetry.
• GET /api/ops/processes: Process groups, statuses, and details.
• GET /api/ops/events: Recent ops events.
• GET /api/ops/identity: Relay ML‑DSA and ML‑KEM public keys.
• POST /api/ops/launch: Generate a launch key.
• POST /api/ops/policy: Update access, shield, lifecycle, or consensus settings.
• POST /api/ops/bridge/add: Add a federated peer.
• POST /api/ops/bridge/remove: Remove a federated peer.
• POST /api/ops/vote/prepare: Generate a vote payload.
• POST /api/ops/vote/submit: Submit a signature; executes on quorum.

Troubleshooting

• Access denied: Ensure launch keys are valid, not expired, and encryption requirements match the client type.
• Shield failures: Increase window or reduce difficulty if clients cannot solve puzzles in time.
• Consensus fails: Verify that the public key is listed in SKULD and that the signature is over the exact vote message.
• ASN policies do nothing: Configure an ASN map path via ops policy if ASN matching is required.