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. [review]
- Encryption in transit and at rest — TLS everywhere, S3 SSE,
no plaintext secrets in code or logs. [review]
- Input validation at boundaries — all external input
validated and sanitised before processing. [review]
- Workspace isolation — data from one workspace must never
leak to another.
[test: apps/api/src/tests/security/cross-tenant-handlers.test.ts]
- 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.
[test: apps/api/src/tests/security/rls-negative.test.ts]
- Access control — every endpoint enforces auth and
authorisation. No "internal-only" endpoints without guards.
[test: apps/api/src/tests/security/route-auth-invariants.test.ts]
- Dependency hygiene — minimal, pinned, audited.
[check: scripts/dependency-audit.ts]
- Change management — all changes go through PR review. No
direct commits to main.
[check: .github/workflows/audit-branch-protection.yml]
- Data retention — when data is deleted, it is actually
deleted (not soft-deleted indefinitely). [review]
Structural Guardrails
Prefer solutions that make security bugs structurally impossible
(compile-time, lint-time) over ones that rely on developer discipline.
Authorized database boundary
- 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.
[review]
Server-bound audit events
- Audit actors, workspace and organization ownership, request metadata, and
before/after identifiers come from authenticated server context; a client
may supply an action or reason, never the actor or tenant. [review]
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. [review]
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. [review]
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.
[review]
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.
[review]
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.
[review]
1---2name: conventions-security3description: "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)."4metadata:5 source: https://skillmd.com/skills/stella/conventions-security6---78# Security Conventions910Apply when writing code that touches auth, data access, file11handling, or external APIs. Stella handles privileged legal data12(attorney-client privilege, litigation holds, personal data).1314## SOC 2 / ISO 27001 Principles1516- **Least privilege** — minimum permissions needed. No wildcard17 IAM policies, no admin-by-default. [review]18- **Encryption in transit and at rest** — TLS everywhere, S3 SSE,19 no plaintext secrets in code or logs. [review]20- **Input validation at boundaries** — all external input21 validated and sanitised before processing. [review]22- **Workspace isolation** — data from one workspace must never23 leak to another.24 [test: apps/api/src/tests/security/cross-tenant-handlers.test.ts]25- **Ethical walls** — workspace (matter) boundaries enforce26 information barriers for the `member` role at the RLS layer (not27 just the UI): a member has zero visibility into workspaces they28 are not assigned to via `workspace_members` — no names, no29 members, no metadata. **Known limitation:** org `owner`/`admin`30 roles carry a deliberate firm-admin override granting access to31 every client matter (`client_id IS NOT NULL`) regardless of32 assignment, and there is no per-matter screening to wall a33 specific admin out of a specific matter. Do not describe admin34 access as "absolute confidentiality." Screening a matter from an35 admin requires a matter-level exclusion consulted by the RLS36 view (`stella_authorized_workspaces`), which is not yet built.37 [test: apps/api/src/tests/security/rls-negative.test.ts]38- **Access control** — every endpoint enforces auth and39 authorisation. No "internal-only" endpoints without guards.40 [test: apps/api/src/tests/security/route-auth-invariants.test.ts]41- **Dependency hygiene** — minimal, pinned, audited.42 [check: scripts/dependency-audit.ts]43- **Change management** — all changes go through PR review. No44 direct commits to main.45 [check: .github/workflows/audit-branch-protection.yml]46- **Data retention** — when data is deleted, it is actually47 deleted (not soft-deleted indefinitely). [review]4849## Structural Guardrails5051Prefer solutions that make security bugs **structurally impossible**52(compile-time, lint-time) over ones that rely on developer discipline.5354### Authorized database boundary5556- When an identifier comes from a related row, authorize it in the same query or57 transaction that uses it. A prior UI filter, cache lookup, or separate58 read-then-write check is not an access-control boundary.59 [review]6061### Server-bound audit events6263- Audit actors, workspace and organization ownership, request metadata, and64 before/after identifiers come from authenticated server context; a client65 may supply an action or reason, never the actor or tenant. [review]6667### Workspace status filtering6869`resolveAccessibleWorkspaces` returns **all** workspaces (including70`deleting`). The auth macro exposes two fields:7172- `activeWorkspaceIds` — excludes `deleting` workspaces (includes73 active and archived). Use this for search, chat, MCP, and any74 query that builds a workspace allowlist. This is the default;75 reach for it first. [review]76- `accessibleWorkspaces` — includes all statuses. Only use in77 `workspaceAccessMacro` (which needs the status to return78 appropriate HTTP codes). Never pass these IDs as a search/query79 allowlist. [review]8081If you need workspace IDs for a new feature, use `activeWorkspaceIds`82unless you have an explicit reason to include deleting workspaces83and document that reason in a comment.8485### CSV and file exports8687- Use `escapeCSV` from `@/api/lib/csv` for all CSV cell values. Never88 hand-roll CSV escaping; the shared utility handles both delimiter89 quoting and spreadsheet formula neutralization (=, +, -, @, tab, CR90 prefixes). This prevents CSV injection attacks where user-controlled91 values starting with formula characters execute in Excel/LibreOffice.92 [review]9394### Multi-entry-point validation9596- Validate untrusted input at each entry boundary with the owning shared schema.97 Generated MCP capabilities validate the live endpoint's body, params, and query98 schemas in `apps/api/src/mcp/capability-tools.ts`; do not repeat that parsing99 inside the handler. Native MCP tools and chat registry tools normalize input100 through `normalizeObjectInputAtBoundary` before dispatch; any other caller that101 bypasses the HTTP route (cron jobs, workers) must apply the same normalizer and102 schema before calling the operation. Keep business invariants and103 related-resource authorization in the owning operation: an ID's valid shape104 does not establish its ownership.105 [review]106107### CI workflow permissions108109- GitHub Actions workflows must declare the **minimum** permissions110 needed. Never use `permissions: write-all`. For PR-triggered111 workflows, scope to `contents: read` + `pull-requests: write`.112 Pin third-party actions to commit SHAs, not mutable tags. For113 SBOM/provenance, use the shared `stella/.github` reusable114 workflows which handle pinning, checksums, and PR-based updates.115 [review]