Skip to content

security.md

Latest commit

 

History

History
37 lines (23 loc) · 3.15 KB

security.md

File metadata and controls

37 lines (23 loc) · 3.15 KB
Raw

Security boundaries and threat model

Data classes

Persisted metadata: user identifier/password hash, device name/platform/version, trust domain, device credential digest, pairing-code digest/expiry, presence timestamps, and audit action/outcome.

Transit-only sensitive data: Codex messages, prompts, assistant deltas, tool commands/output, approvals, attachment bytes, local paths, and session identifiers. These may exist in Hub process memory and TLS termination buffers while routed, but are never sent to the storage interface or normal logs.

Agent-local session data: browser-uploaded attachments are stored under the signed-in user's ~/.codex-remote/attachments/<thread-id> so later Codex turns can still resolve their local paths. Files are created with user-private permissions where the operating system supports POSIX modes. The Hub and public repository never store these files.

Secrets: Hub signing secret, password, TLS key, device credential, and any future optional identity-provider secrets. Supply through environment variables or mounted secret files outside the repository.

Controls

  • TLS/WSS required for every non-localhost Agent Registry.
  • Separate signing keys/databases/domains/certificates/identities for personal and company domains.
  • scrypt password hashing; HMAC-signed 15-minute access credentials.
  • Random 256-bit Agent credential; digest at rest. One-time pairing code expires in five minutes.
  • Ownership check before routing every Agent method.
  • Request payload limits, protocol schema validation, bounded timeouts, a 24 MB WSS frame ceiling, and attachment limits of four files / 8 MB each / 16 MB total.
  • Agent runs as the signed-in user so it sees only that user's Codex environment.
  • Fastify request logging is disabled and Codex stderr is discarded.
  • No telemetry, CDN, third-party script, or public upgrade check.

Important residual risks

The Hub is trusted and can inspect transit content in memory. A compromised Hub or reverse proxy can capture sessions. End-to-end browser-to-Agent encryption is future work.

The environment-seeded administrator is intentionally sufficient for personal and single-user deployments; SSO is not required. If a future company deployment needs broad multi-user administration, it can place the Hub behind an identity-aware reverse proxy or add a public OIDC provider implementation without changing the Agent protocol.

Browser storage contains the short-lived access credential and is therefore exposed to XSS. The PWA uses no third-party runtime scripts, but a production Content Security Policy should still be set at the reverse proxy.

Revocation UI, attachment retention cleanup, and device credential rotation are future work. Delete the device row/DB identity and re-pair if a credential is suspected compromised. Delete the Agent attachment directory explicitly if local uploaded files must be purged before retention tooling exists.

Logging rule

Audit only action names such as turn.start, device/user IDs, outcome, and timestamp. Never add arbitrary request bodies, WebSocket frames, authorization headers, Codex stderr, prompts, assistant text, tool arguments/output, tokens, or code diffs to logs.