subvocal Silent Productivity
GitHub Start building →
SPX Benchmarks Platform Docs API GitHub →

Subvocal Middleware Platform Safety & Security Specification

This document details the threat model, credential architecture, data residency standards, compliance posture, and safety design principles for the Subvocal Middleware Platform.

1. Threat Model

Operating at the intersection of biological signals, on-screen user context, and natural language action dispatchers creates a unique surface area for security threats. This section maps out the primary threat vectors and mitigation strategies.

graph TD
    A[Raw sEMG Sensors] -->|Signal Tampering / Spoofing| B(DSP & Classifier Engine)
    C[System & User Context] -->|Prompt Injection / Poisoning| D(LLM Intent Decoder)
    B -->|Discrete Shorthand Tokens| D
    D -->|Proposed Action| E{Policy Engine / Gate}
    E -->|Approved| F[Action Executor / OS Native APIs]
    E -->|Rejected| G[Audit Trace Log]

1.1 Sensor Spoofing and Physical Signal Tampering

1.2 Prompt Injection and Context Poisoning

1.3 Information Disclosure (Data Eavesdropping)

1.4 Denial of Service (DoS) and Starvation

1.5 Model Deserialization and Path Traversal

1.6 Text-to-Speech Command Injection

2. Key Management & Credential Storage

The platform integrates with cloud-hosted LLM endpoints which require API keys. Standardizing how credentials are secured prevents leakage on developer workstations and user devices.

2.1 Environmental Segregation

2.2 Native Operating System Keystore Integration

In production, the SDK integrates with native system keystores rather than storing keys in plaintext files. * macOS: Uses the Keychain Services API to securely store and retrieve secrets. Access is locked behind user biometric authorization (Touch ID) or the master login password. * Windows: Uses the Credential Manager API (specifically DPAPI) to encrypt keys on disk bound to the active Windows user account. * Linux: Integrates with the freedesktop.org Secret Service API (via gnome-keyring or KWallet).

The platform uses the keyring library as a fallback wrapper, failing gracefully to localized environmental variables if no secure system service is available:

import os
import keyring

def get_api_key(provider_name: str) -> str:
    """Retrieves API keys securely, prioritizing the OS Keychain."""
    service_name = "subvocal_middleware"
    key_name = f"{provider_name.lower()}_api_key"

    # 1. Attempt OS Keyring retrieval
    try:
        secret = keyring.get_password(service_name, key_name)
        if secret:
            return secret
    except Exception:
        pass  # Fallback if no keyring daemon is present

    # 2. Fallback to environmental variables
    env_var = f"{provider_name.upper()}_API_KEY"
    return os.environ.get(env_var, "")

2.3 HMAC-SHA256 Signed Capability Tokens

For deployments exposing the subvocal pipeline to external clients via the MCP/HTTP network interfaces, session authorization is guarded by capability-scoped tokens. * HMAC Signature Checks: Tokens carry serialized ActionGrants claims (e.g. allowed command whitelist, minimum confidence floor, and dry-run policies). The payload is signed using HMAC-SHA256 against a server-side API secret key to prevent credential tampering. * Base64 Padding Fix: Verification restores padding with payload_b64 += "=" * (-len(payload_b64) % 4) before urlsafe_b64decode, avoiding the classic bug of appending four = when len % 4 == 0, which would otherwise break token verification. * Context Isolation: Validated token claims are bound to the execution thread/coroutine context using contextvars context propagation, preventing credential leakage across simultaneous sessions.

2.4 SQLite Persistent Store Access Controls

The persistent session store maintains session configurations and active states on disk. * Database Isolation: The SQLite database file (typically sessions.db) is stored inside the user's localized app data directory. The SDK applies strict filesystem permissions (e.g., owner read/write only, Unix mode 0600) to prevent local privilege escalation. * Configuration Scrubbing: When config YAML states are stored, highly sensitive parameters (like raw provider API keys) are scrubbed before persistence, leaving credential validation to runtime keyring retrievals.

2.5 Foundation Model Supply Chain

Foundation and adaptor weights are distributed out-of-band from SubvocalConfig (opt-in subvocal[ml]) and must be treated as untrusted supply-chain artifacts:

3. Data Residency and Sovereignty

Silent speech applications ingest deeply intimate biometric signals. Standardizing where data is processed is crucial to user trust and regulatory compliance.

3.1 Local-First Processing Architecture

The platform operates on a strict local-first processing hierarchy: * Biometric Ingestion: Raw high-frequency sEMG time-series are stored solely in volatile RAM buffers and processed locally. Waveform matrices are never saved to persistent storage or written to debug logs unless explicit "diagnostic recording mode" is active. * ML Inference: The core gesture classifier (e.g., GRU or CNN) runs entirely on the local host's CPU/NPU. * Local Telemetry: Observability traces and correction datasets are stored locally in the sdk/data workspace directory, which is ignored in Git. * Trace Opt-Out and Rotation Cap: Pipeline JSONL tracing can be disabled entirely via telemetry.trace_enabled=false or runtime.trace_enabled=false (env SUBVOCAL_TELEMETRY__TRACE_ENABLED / SUBVOCAL_RUNTIME__TRACE_ENABLED) for biometric-PII minimization. When enabled, Session._write_trace enforces a 10 MB file cap — writes beyond the cap are skipped with a warning until log rotation.

3.2 Cloud LLM Processing Safeguards

When cloud-hosted LLMs are utilized for intent reconstruction, the following policies apply: * Zero-Data-Retention Profiles: Organizations must deploy the middleware using enterprise API endpoints that guarantee zero-data retention (data is not logged or cached by the provider) and opt-out of model training inputs. * Data Minimization: The platform only sends discrete tokens (e.g. clk, gt) and essential active application metadata. Full historical conversation text is truncated to a sliding window of the last 3-5 turns.

3.3 Telemetry Cardinality and Port Registry Bounds

4. Biometric Privacy Regulations Compliance

Because electromyography measures electrical muscle potentials unique to an individual's physiology, raw sEMG data constitutes biometric information under modern privacy frameworks.

4.1 BIPA (Biometric Information Privacy Act - Illinois) Compliance Checklist

BIPA governs the collection, storage, and retention of biometric identifiers. The platform satisfies BIPA through: * Written Release & Consent: Applications utilizing the SDK must present a plain-language consent screen explaining that muscle-voltage potentials are captured solely to classify speech commands. * Biometric Retention Schedule: Biometric signals are cleared from memory immediately after classification. The platform maintains a public retention policy stating that raw bio-signals are destroyed as soon as the active user session terminates, with an absolute maximum retention period of 24 hours for diagnostics. * Prohibition on Profit: The platform contains no mechanisms to sell, lease, trade, or profit from user bio-signals.

4.2 GDPR (General Data Protection Regulation) Compliance

EMG signals fall under "special category data" (Article 9) under GDPR. The platform adheres to GDPR principles: * Right to Erasure (Article 17): Users can clear all calibration profiles, saved models, and telemetry logs. The CorrectionManager provides an explicit .clear_logs() utility. * Biometric Anonymization: All exported fine-tuning datasets and correction logs are stripped of hardware identifiers, network IP addresses, and demographic attributes. * Data Portability (Article 20): Users can export their calibration profiles and correction logs in a standard open format (JSONL) to port to other devices or platforms.

4.3 HIPAA (Health Insurance Portability and Accountability Act) Compliance

If deployed in clinical or assistive-care environments: * Protected Health Information (PHI): Shorthand text and reconstructed intent strings could contain health identifiers. The platform supports local-only LLM providers (e.g., Llama via Ollama) to eliminate the risk of PHI transmission to external servers. * Business Associate Agreements (BAAs): If cloud providers are used, the deploying organization must execute a BAA with the cloud LLM host to ensure HIPAA-compliant data handling.

5. Safety Best Practices Guide

To prevent dangerous or unintended outcomes arising from misclassified gestures or hallucinated intents, developers must adhere to the following safety rules:

5.1 Command Confirmation Patterns

Actions are categorized by risk levels: * Low-Risk (Read-Only / Local Navigation): (e.g. scrolling, searching local documents). These can execute instantly without confirmation. * Medium-Risk (Reversible System Actions): (e.g. opening an application, copying text). Executed instantly but must support a quick "undo" command (e.g. standard system undo keyboard shortcuts). * High-Risk (Irreversible / Destructive): (e.g. deleting files, sending emails, executing shell commands, transferring funds). These must never execute instantly. The executor must present an interactive prompt requesting user verification (e.g., requiring the user to execute a distinct confirmation gesture sequence like "Double Jaw Clench" or hover-and-confirm).

5.2 Safety Cooldowns and Spasm Filtering

To prevent continuous command execution during physical motor ticks or electrode disconnection: * Consecutive Action Gating: If the pipeline triggers 3 actions within 1.5 seconds, it automatically engages a safety lock, requiring a manual button press or sustained resting signal (3 seconds of silence) to unlock. * Maximum Gesture Boundaries: Gestures that persist longer than 4.0 seconds (e.g., continuous jaw clenches) are flagged as invalid muscle tension and discarded.

5.3 Failsafe Mechanisms