Security Principles

The lab's security model — what we protect, what we don't, the trust boundaries, the threat model, and the principles that guide decisions.

Purpose

This page is the canonical reference for the lab's security model. It documents:

The assets the lab protects.
The threats the lab defends against.
The trust boundaries the lab enforces.
The principles that guide security decisions.
The practices the lab follows.

The audit layer is documented in Audit Model. The decisions are in Architecture Decisions.

What We Protect

The lab protects:

User data. The user's files, projects, notes, and personal context.
Credentials. API keys, tokens, passwords, and any other secrets the lab uses.
Research artifacts. The reports, the mission state, and the audit trail.
Configuration. The framework's configuration files and the project's configuration.
The lab itself. The integrity of the framework, the agents, and the tools.

The lab does NOT protect:

The user's machine's general security (the user is responsible for the OS, the firewall, the backups).
The external providers' security (out of scope).
The physical security of the hardware (out of scope).

What We Don't Protect

Some assets are out of scope:

Generated outputs. The Media Lab Server's outputs are not encrypted or backed up by default. The user is responsible for backing them up if they care.
Downloaded media. The torrent-finder and similar tools download content to a public directory. The user is responsible for the legal and ethical implications.
In-memory state. Session state is not encrypted in memory. A process dump could expose it.
Network traffic. The lab does not encrypt traffic to local devices. A user on the same LAN could sniff the traffic.

The lab documents these limitations but does not try to address them. The threat model excludes them.

Threat Model

The lab's threat model considers:

Threat actor	Capability	Likelihood	Impact	Mitigation
Curious user on the LAN	Network sniffing	Low	Low	Local-only services; no exposed ports.
Compromised browser extension	Read page content	Medium	Medium	Web Agent does not log page content.
Compromised model provider	Read prompts	Low	High	No secrets in prompts; minimal personal data.
Compromised search provider	Read queries	Low	Low	No PII in queries.
Compromised streaming service	Read playback	Low	Low	No user data in playback requests.
Compromised sub-agent sandbox	Escape sandbox	Low	Critical	Strict sandbox; reviewed prompts.
Compromised local process	Read memory, files	Low	Critical	Filesystem permissions; process isolation.
Compromised backup	Read user data	Low	High	Encrypted backups (user's responsibility).
Malicious request from user	Bypass safeguards	Medium	High	User authorization for high-risk operations.
Prompt injection in user data	Hijack the agent	Medium	High	Sanitization; structured tool I/O.
Resource exhaustion attack	DoS the model	Low	Medium	Quota tracking; rate limits.
Replay attack on the API	Replay a request	Low	Low	No sensitive state in requests.
Configuration drift	Subtle misconfig	Medium	High	Configuration review; audit.

The lab does not have a formal threat model document. This table is the de facto model.

Trust Boundaries

The lab has the following trust boundaries:

Boundary	Trust on the inside	Trust on the outside	Enforcement
Coordinator ↔ User	The user	The Coordinator	Authenticated session, user input sanitization.
Coordinator ↔ Scout	The Coordinator	The Scout	Local HTTP; no external exposure.
Coordinator ↔ Coding sub-agent	The Coordinator	The sub-agent	Sandbox; scoped prompts.
Coordinator ↔ Web Agent	The Coordinator	The browser	Isolated browser profile.
Scout ↔ External providers	The Scout	The providers	Token pool; request journal.
Media Lab Server ↔ Public	The Server	The public	Local-only bind (`127.0.0.1`).
Sub-agent ↔ Project workspace	The sub-agent	The sandbox	`workspace-write` mode.
Memory layer ↔ Rest of system	The memory layer	Everything else	Filesystem permissions.

The boundaries are enforced by:

Process isolation. Each gateway runs in a separate process.
Network isolation. Local-only services; no exposed ports.
Sandboxing. The coding sub-agent runs in a sandbox.
Filesystem permissions. Sensitive directories are owner-only.
Configuration. The framework's configuration declares the boundaries.

A boundary violation is a bug. The audit layer records violations and the operator reviews them.

The lab's security decisions are guided by these principles.

1. Documentation is a deliverable

Every project must have documentation. The documentation includes a security section (if the project has any security implications). A project without documentation is incomplete.

This is documented as a hard rule in Architecture Decisions → ADR-009.

2. The Coding Assistant never writes code directly

The Coding Assistant delegates all code-writing to a sandboxed sub-agent. The Assistant reviews the code, integrates it, and tests it. The Assistant never writes code by hand.

This is documented as a hard rule in ADR-002.

3. The main agent and the specialized agents are isolated

The Coordinator and the specialized agents run in separate processes. They communicate through defined interfaces. They do not share memory or files except through the artifact layer.

This is documented as a hard rule in ADR-001.

4. Secrets are never logged

API keys, tokens, passwords, and other secrets are never written to logs, journals, or artifacts. The framework's logging layer redacts secrets. The audit layer verifies that secrets are not leaked.

5. The user authorizes high-risk operations

Some operations are high-risk (sending an email, modifying a production system, exposing a service). The user explicitly authorizes them. The Coordinator surfaces the authorization request and waits for the user's response.

6. The system fails closed

When a component fails, the default is to stop the operation, not to continue. A failure in the coding sub-agent stops the Coding Assistant. A failure in a research phase stops the mission. The user decides whether to retry.

7. The system is auditable

Every request, every response, every external call, every configuration change is recorded. The audit trail is the foundation of the lab's security model.

8. The system is recoverable

A failed mission can be resumed. A crashed gateway can be restarted. A corrupted artifact can be regenerated from the inputs. The lab is designed to recover from failure, not to be perfect.

9. The user is the operator

The lab has a single user. The user is the operator. The user authorizes operations, reviews audits, and makes security decisions. The lab does not have multiple users or multiple operators.

10. The documentation reflects reality

The lab's documentation is updated to match the system's actual state. A discrepancy between the documentation and the system is a bug. The audit layer flags discrepancies.

Practices

The lab follows these security practices.

Authentication

Local services have no authentication. The user assumes the local machine is trusted.
External services use API keys or tokens. The keys are stored in configuration files with owner-only permissions.
The coding sub-agent uses OAuth or local auth as configured by the framework.

Authorization

The user authorizes high-risk operations explicitly. The Coordinator surfaces the authorization request and waits for the user's response.
The coding sub-agent's sandbox is configured per project. The default is workspace-write.
The audit layer records every authorization decision.

Auditing

Every request is logged. The Coordinator logs the request and the response.
Every external call is recorded in the request journal. The journal is append-only.
Every configuration change is recorded in the audit log.
The audit log is reviewed weekly.

Backup

Critical data is backed up daily. The user is responsible for the backup destination.
The backup is encrypted (the user chooses the encryption).
The backup is verified with a checksum.

Incident Response

Incidents are detected by the heartbeat, the health checks, or the user.
Incidents are triaged by the user.
Incidents are contained by the user.
Incidents are mitigated by following the relevant runbook.
Incidents are recovered by the user.
Incidents are post-mortemed in a document under {workspace-root}/security/incidents/.

Configuration Management

Configuration is in files, not in code.
Configuration changes are reviewed by the user.
Configuration changes are logged in the audit log.
Secrets are in environment variables or secret managers, not in configuration files.

What the Lab Does Not Do

The lab does not:

Operate production systems. The lab is a personal research and development environment.
Expose services to the public internet. The lab is local-first.
Handle payment processing. The lab does not process payments.
Handle personal data at scale. The lab handles the user's personal data, but not at scale.
Provide multi-user authentication. The lab has a single user.
Provide role-based access control. The lab has a single role.
Encrypt data at rest. The user is responsible for full-disk encryption.
Encrypt data in transit to local devices. The user is responsible for the LAN security.
Provide a formal security certification. The lab is not certified.

The lab's scope is intentionally limited. The limitations are documented so the user knows what to expect.

Future Security Work