Security Conventions

Apply when writing code that touches auth, data access, file handling, or external APIs. Stella handles privileged legal data (attorney-client privilege, litigation holds, personal data).

SOC 2 / ISO 27001 Principles

• Least privilege — minimum permissions needed. No wildcard IAM policies, no admin-by-default.
• Audit trail — state-changing operations traceable to an actor and timestamp. Never silently mutate data.
• Encryption in transit and at rest — TLS everywhere, S3 SSE, no plaintext secrets in code or logs.
• Input validation at boundaries — all external input validated and sanitised before processing.
• Workspace isolation — data from one workspace must never leak to another.
• Ethical walls — workspace (matter) boundaries enforce information barriers for the member role at the RLS layer (not just the UI): a member has zero visibility into workspaces they are not assigned to via workspace_members — no names, no members, no metadata. Known limitation: org owner/admin roles carry a deliberate firm-admin override granting access to every client matter (client_id IS NOT NULL) regardless of assignment, and there is no per-matter screening to wall a specific admin out of a specific matter. Do not describe admin access as "absolute confidentiality." Screening a matter from an admin requires a matter-level exclusion consulted by the RLS view (stella_authorized_workspaces), which is not yet built.
• Access control — every endpoint enforces auth and authorisation. No "internal-only" endpoints without guards.
• Dependency hygiene — minimal, pinned, audited.
• Logging without leaking — never log secrets, tokens, PII, or document contents.
• Change management — all changes go through PR review. No direct commits to main.
• Data retention — when data is deleted, it is actually deleted (not soft-deleted indefinitely).

Structural Guardrails

Prefer solutions that make security bugs structurally impossible (compile-time, lint-time) over ones that rely on developer discipline.

Authorized database boundary

Workspace-scoped handlers use createSafeHandler, declare permissions beside the route, derive workspaceId: SafeId<"workspace"> from the authorized context, and access tenant data through scopedDb. Never accept ownership IDs from body/query input or fall back to root db because a relation is awkward to express. Root/system handlers require a documented non-tenant purpose and tables whose RLS posture denies ordinary application access. Enforced by require-safe-route-handlers/require-safe-route-handlers and no-body-ownership-ids/no-body-ownership-ids.

When an identifier comes from a related row, authorize it in the same query or transaction that uses it. A prior UI filter, cache lookup, or separate read-then-write check is not an access-control boundary.

Server-bound audit events

Actors, workspace/organization ownership, request metadata, and before/after identifiers come from authenticated server context. Clients may supply a user action or reason where the domain requires it, but never the authoritative actor or tenant. Required audit writes participate in the same transaction as the mutation, or use a durable outbox when the sink is external. Enforced by require-audit-on-mutation/require-audit-on-mutation.

Workspace status filtering

resolveAccessibleWorkspaces returns all workspaces (including deleting). The auth macro exposes two fields:

• activeWorkspaceIds — excludes deleting workspaces (includes active and archived). Use this for search, chat, MCP, and any query that builds a workspace allowlist. This is the default; reach for it first.
• accessibleWorkspaces — includes all statuses. Only use in workspaceAccessMacro (which needs the status to return appropriate HTTP codes). Never pass these IDs as a search/query allowlist.

If you need workspace IDs for a new feature, use activeWorkspaceIds unless you have an explicit reason to include deleting workspaces and document that reason in a comment.

CSV and file exports

Use escapeCSV from @/api/lib/csv for all CSV cell values. Never hand-roll CSV escaping; the shared utility handles both delimiter quoting and spreadsheet formula neutralization (=, +, -, @, tab, CR prefixes). This prevents CSV injection attacks where user-controlled values starting with formula characters execute in Excel/LibreOffice.

Multi-entry-point validation

Validate untrusted input at each entry boundary with the owning shared schema. Generated MCP capabilities validate the live endpoint's body, params, and query schemas in apps/api/src/mcp/capability-tools.ts; do not repeat that parsing inside the handler. Native MCP tools and chat registry tools normalize input through normalizeObjectInputAtBoundary before dispatch; any other caller that bypasses the HTTP route (cron jobs, workers) must apply the same normalizer and schema before calling the operation. Keep business invariants and related-resource authorization in the owning operation: an ID's valid shape does not establish its ownership.

Filename sanitization

All user-supplied filenames must pass through sanitizeFilename (@/api/lib/sanitize-filename) before storage or use in file operations (ZIP entries, Content-Disposition headers, S3 keys). The sanitizer strips path separators, traversal sequences, and dangerous characters. Enforced by security-guards/no-raw-filename-write.

Cross-org user ID validation

When a handler accepts a userId from user input (body, query, or params) and uses it in a query that returns user data (names, emails, images), validate org membership first using validateOrgUserId from @/api/lib/validated-org-user-id. The returned ValidatedOrgUserId proves the check happened at the type level, making cross-org user ID injection structurally impossible. For read paths that resolve userIds stored in the database (not from user input), scope the user query with an innerJoin on the member table filtered by session.activeOrganizationId; enforced by security-guards/no-unscoped-user-query.

CI workflow permissions

GitHub Actions workflows must declare the minimum permissions needed. Never use permissions: write-all. For PR-triggered workflows, scope to contents: read + pull-requests: write. Pin third-party actions to commit SHAs, not mutable tags. For SBOM/provenance, use the shared stella/.github reusable workflows which handle pinning, checksums, and PR-based updates.