Security Patterns

Security Patterns

Comprehensive security patterns for building hardened applications. Each category has individual rule files in rules/ loaded on-demand.

Quick Reference

Total: 6 rule files across 4 categories. Topics marked "upstream" or "refs" keep only the ork delta here: floors and key decisions in this file, scars and house decisions in references/ork-delta.md, and first-party sources in Upstream coverage.

Quick Start

# Argon2id password hashing
from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)
ph.verify(password_hash, password)

# JWT access token (15-min expiry)
import jwt
from datetime import datetime, timedelta, timezone
payload = {
    'sub': user_id, 'type': 'access',
    'exp': datetime.now(timezone.utc) + timedelta(minutes=15),
}
token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')

// Zod v4 schema validation
import { z } from 'zod';
const UserSchema = z.object({
  email: z.email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin']).default('user'),
});
const result = UserSchema.safeParse(req.body);

# PII masking with Langfuse
import re
from langfuse import Langfuse

def mask_pii(data, **kwargs):
    if isinstance(data, str):
        data = re.sub(r'\b[\w.-]+@[\w.-]+\.\w+\b', '[REDACTED_EMAIL]', data)
        data = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[REDACTED_SSN]', data)
    return data

langfuse = Langfuse(mask=mask_pii)

Authentication

Secure authentication with OAuth 2.1, Passkeys/WebAuthn, JWT tokens, and role-based access control.

Implementation tutorials for JWT, OAuth 2.1/PKCE/DPoP, Passkeys/WebAuthn, RBAC, and MFA are upstream-covered (see Upstream coverage). The ork delta, including the argon2-cffi-over-passlib scar, lives in references/ork-delta.md.

Key Decisions: Argon2id > bcrypt | Access tokens 15 min | PKCE required | Passkeys > TOTP > SMS

Defense-in-Depth

Multi-layer security architecture with no single point of failure.

Zero-trust and tenant-isolation implementation recipes (tenant-scoped repositories, RLS, tenant-keyed caches) are upstream-covered; the immutable RequestContext pattern survives in references/request-context-pattern.md and sanitized audit logging in references/audit-logging.md.

Key Decisions: Immutable dataclass context | Query-level tenant filtering | No IDs in LLM prompts

sandbox.network.deniedDomains (CC 2.1.113+)

Network-layer blocklist enforced before Bash/WebFetch egress — pair with the hook-layer DENY_PATTERNS for defense in depth. Settings example:

"sandbox": {
  "network": {
    "deniedDomains": ["*.evil.com", "pastebin.com", "transfer.sh"]
  }
}

Wildcards supported (*.example.com, evil.com/*/malicious/*). Plugins ship a baseline list in src/settings/ork.settings.json; project settings can extend it. Use for: prompt-injection exfil sinks, known-bad registries, paste services that bypass audit.

sandbox.credentials (CC 2.1.187+)

Blocks sandboxed Bash from reading credential files and secret env vars, defense-in-depth beside sandbox.filesystem.denyRead. Merged across scopes (any scope can add, none can remove); older CC ignores the key. mode is deny or, since CC 2.1.221, mask. Settings example:

"sandbox": {
  "credentials": {
    "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
    "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
  }
}

ork ships no sandbox.credentials baseline: CC reads only the permissions key from a plugin's settings file, so the block that used to live in src/settings/ork.settings.json was retired in #3357 as inert. Set it in your user or managed settings (deny ~/.aws/credentials, ~/.ssh, ~/.gnupg, ~/.netrc, ~/.npmrc plus the token env vars that can hijack git-push auth). Pair with CLAUDE_CODE_SUBPROCESS_ENV_SCRUB to scrub all subprocess credentials regardless of sandboxing.

Masking instead of denial. Since CC 2.1.221, a credential file entry can take mode: "mask" on Linux and WSL: the sandboxed command reads a sentinel copy (the whole file, or only the spans an extract regex captures) and the sandbox proxy substitutes the real value on egress. On macOS file masking falls back to deny, so on a Mac it buys nothing over mode: deny. The richer options arrived in CC 2.1.224: beyond mode: deny, credentials can be masked so the command still runs against a redacted value: extract plus onExtractNoMatch pulls a secret out of a structured env value, decode: "jwt" with maskClaims masks named JWT claims, and awsPairs/sigv4 re-signs AWS SigV4 requests after masking. Two constraints decide whether these are usable at all:

• They require sandbox.network.tlsTerminate, so they only apply to traffic CC terminates.
• They are honored only from user settings, managed settings, or --settings. A value shipped by a plugin or set in project .claude/settings.json is ignored, so ork cannot ship these as a baseline the way it ships the deny list. Document them for operators; do not add them to src/settings/ork.settings.json expecting them to take effect.

Never write a deny path with a trailing slash. Through CC 2.1.223, a sandbox.filesystem deny entry ending in / (for example denyRead: "~/.aws/") was silently bypassable on Linux and macOS: the rule parsed, reported clean, and protected nothing. Fixed in 2.1.224, but the shape is still worth avoiding because it reads as protection either way. ork's shipped values (~/.aws/credentials, ~/.ssh/*, ~/.gnupg/*) were never affected.

Input Validation

Validate and sanitize all untrusted input using Zod v4 and Pydantic.

Advanced schema recipes (discriminated unions, file upload validation, URL allowlists) and the full Zod v4 API are upstream-covered; the Zod v4-not-v3 trap list is in references/ork-delta.md, and typed schema examples in scripts/validation-schemas.ts.

Key Decisions: Allowlist over blocklist | Server-side always | Validate magic bytes not extensions

OWASP Top 10

Protection against the most critical web application security risks.

Injection prevention (SQL/command/SSRF) and broken-auth fixes (JWT algorithm confusion, CSRF, timing attacks) plus vulnerable-vs-secure demos are upstream-covered; see Upstream coverage.