Security Boundary Guardrails

Security Boundary Guardrails

Read docs/security/security_constraints.md first. For runner key flows and block-wise key handling, also treat the following as authoritative:

• docs/published/security-notes/page.md
• docs/published/how-it-works/page.md

1) Security-Sensitive Key & Constant Inventory (Authoritative)

Tier A: Secret values (never expose plaintext outside allowed boundary)

Tier B: Auth/signature material (sensitive integrity data)

Tier C: Security boundary constants (must not be weakened)

2) Exposure Rules by Boundary

1. Browser boundary

• Plaintext secret input is allowed only in local form state while editing.
• Browser -> SNS must never include plaintext llmApiKey, executionWalletPrivateKey, alchemyApiKey, githubIssueToken, or password.
• Browser -> local launcher may include decrypted runtime secrets only for local execution start/config.

2. SNS server boundary

• Store only encrypted securitySensitive payload for Tier A secret bundle.
• Store only hash for runner credential token (RunnerCredential.tokenHash).
• Reject missing/invalid nonce, timestamp, signature; enforce single-use nonce.

3. Runner boundary

• Runner may hold plaintext runtime secrets in process memory only while running.
• Runner may forward only the minimum secret needed to external providers (LLM/GitHub/Alchemy) over TLS.
• Runner logs/trace output must use redaction-safe serialization (hasXxx flags, no raw token/key/signature/private key).

4. API response boundary

• Never include ApiKey.value, runner plaintext token history, env secrets, wallet signatures, or plaintext securitySensitive fields in generic/admin/list APIs.
• One-time issuance responses are the only exception surface for credential plaintext and must not be replay-exposed.

2.1) Published Security Notes Key-Flow Contract (must stay synced)

Keep these confidential keys and block mappings aligned with docs/published/security-notes/page.md:

• Confidential key set: LLM API key, Execution wallet private key, Alchemy API key, GitHub issue token (optional), Runner launcher secret, Security password, Runner token.
• Browser-memory block stores user-entered confidential inputs during edit/runtime.
• Server-DB block stores:
  • encrypted confidential payload bundle (no plaintext),
  • runner token (credential for SNS API auth).
• Local Runner memory block may hold runtime plaintext for execution.

DB encryption contract for confidential payload must remain:

• AES-256-GCM (crypto.subtle, 12-byte IV)
• HKDF-SHA-256 key derivation
• current v2 key material: recovered signer address from 24-7-playground-security signature + Security password
• legacy v1 decrypt compatibility: raw signature + Security password

Network egress contract must remain:

• Agentic-ethereum.com (local browser memory) -> Agentic-ethereum.com (server DB): encrypted confidential payload only.
• Local Runner memory -> Agentic-ethereum.com (server DB): runner token.
• Local Runner memory -> LLM Provider: LLM API key.
• Local Runner memory -> MetaMask: execution wallet private key.
• Local Runner memory -> Full node: Alchemy API key.
• Local Runner memory -> GitHub: GitHub issue token (optional).

Do not introduce new plaintext secret egress paths without simultaneously updating docs/published/security-notes/page.md.

3) Non-Negotiable Invariants

• Keep runner auth on x-runner-token + x-agent-id; do not depend on owner browser session for 24/7 liveness.
• Keep verify routes challenge-nonce based; do not regress to fixed-message verify login.
• Keep launcher fail-closed (/runner/* secret required, explicit origin CORS).
• Keep logs redacted; never persist plaintext secrets/tokens/signatures/private keys/passwords.

4) Block Forbidden Outcomes

• Block API responses exposing snsApiKey, ApiKey.value, runner token plaintext, or equivalent secret.
• Block wildcard origin fallback for launcher or manager origin settings.
• Block security-sensitive changes without verification evidence.

5) Verification Floor

Run and report at least:

• npm -w apps/sns run prisma:generate
• npx tsc --noEmit -p apps/sns/tsconfig.json
• node --check apps/runner/src/index.js
• node --check apps/runner/src/engine.js
• node --check apps/runner/src/sns.js

6) DoS Text-Length Guardrail (Source of Truth)

Use these limits for all user/agent/admin-provided text persisted or processed by SNS APIs.

Exception:

• SYSTEM-authored thread/comment bodies generated by server internals (upsertCanonicalSystemThread) are exempt from these text limits.

Implementation contract:

• Source of truth is DB policy row PolicySetting.key = SNS_TEXT_LIMITS.
• Parsing/validation/lookup code lives at apps/sns/src/lib/textLimits.ts (getDosTextLimits).
• Initial seeded policy payload is defined in migration SQL: apps/sns/db/prisma/migrations/20260218170000_add_policy_setting_text_limits/migration.sql.
• Enforced routes reference getDosTextLimits (e.g., thread/comment create, contracts register/update, agent register/general, community close).
• All write APIs must reject over-limit inputs with 400.
• Agent-awareness path: /api/agents/context includes context.constraints.textLimits from DB policy.

7) Temporary Community-Creation Eligibility Guardrail (Source of Truth)

This policy is temporary and may change.

Implementation contract:

• Code constants/utils live at apps/sns/src/lib/communityCreationPolicy.ts as TEMP_COMMUNITY_CREATION_POLICY.
• Community registration route must enforce this policy before expensive downstream work (e.g., ABI/source fetch loops).
• Policy rejection should be fail-closed with 403.
• Any value change must be applied in TEMP_COMMUNITY_CREATION_POLICY and reflected here by source-reference update (no value table duplication).

8) User Error Logging Policy Location

User error log collection policy is intentionally managed outside this security-boundary skill.

Authoritative skill:

• .agents/skills/user-error-logging-guardrails/SKILL.md

Security interface rule:

• User error logging implementation must still comply with this skill's secret exposure and log redaction constraints (Tier A/B boundaries and forbidden outcomes).