# Sibyl Permission System Audit (API/CLI/Web/Core)

Date: 2026-01-04

Scope: `apps/api`, `apps/cli`, `apps/web`, `packages/python/sibyl-core`

This is a code-audit report of Sibyl’s authentication/authorization/multi-tenancy system, with an
emphasis on security properties, correctness gaps, and operational/performance risks.

Update (2026-03-29): Sibyl's internal agent runtime, approval flow, and sandbox control plane were
removed after this audit was written. The findings below have been trimmed so the document reflects
the remaining live surfaces.

Update (2026-05-13): v0.8 B0 reconciled this audit against the Surreal auth/runtime implementation.
The old Postgres/FalkorDB wording below is retained as historical context, but the active control
plane is now Surreal-backed. Treat this update and the trust-surface inventory as the current
release-planning source of truth.

Update (2026-05-15): this audit remains an active input for
[`SIBYL_1_0_ROADMAP.md`](SIBYL_1_0_ROADMAP.md). v0.8 and v0.9 closed the main memory-trust release
gates, but 1.0 still needs boring CLI session behavior, persisted memory-space control-plane
records, agent delegation, stricter API-key and MCP policy coverage, job policy receipts, and
complete inspect/audit parity.

## TL;DR (Highest-Risk Items)

1. **Project RBAC is now Surreal-backed, but project records remain the critical control-plane
   boundary.** Graph project create/update/delete writes project records through the Surreal auth
   runtime, and `verify_entity_project_access()` denies non-viewer fallbacks for missing or
   unregistered projects. The remaining risk is read-side drift where a route does not ask for
   accessible project IDs or direct project authorization.
2. **Direct entity list/get and raw-capture endpoints are the highest-priority read-side audit
   targets.** Search, explore, context packs, raw memory, and MCP retrieval pass project filters,
   but `GET /api/entities`, `GET /api/entities/{id}`, and `/api/entities/captures` need explicit
   project access status before project-private data can be considered release-safe.
3. **MCP is no longer an org-only bypass for the main memory loop, but generic graph mutation is not
   yet fully policy-shaped.** MCP `search`, `explore`, `context`, `remember`, and `reflect` carry
   user/org/project context; MCP `add` and `manage` still rely on generic graph/task authorization
   rather than raw-memory policy decisions.
4. **Memory policy exists and is shared for raw memory and reflection, but audit/inspect is still
   incomplete.** Raw remember/recall log policy decisions; context packs and native retrieval carry
   policy metadata internally; humans still need a first-class inspect surface for why memory was
   shown, hidden, written, or denied.
5. **Postgres RLS is no longer part of active request isolation.** The old RLS finding is now
   documentation debt, not an active Surreal release blocker. Any remaining RLS references should be
   labeled historical or removed from default-runtime docs.

First security pass for v0.8: harden direct entity/read surfaces in B2, route MCP/CLI/jobs through
one policy context in B3, add audit and inspect in B4, then run the B6 memory trust release gate.

## 2026-05-13 Surreal Auth Reconciliation

### Active authorization model

- **Auth store:** Surreal auth namespace/database via `apps/api/src/sibyl/persistence/surreal`.
- **Org context:** JWT and API-key auth resolve `AuthContext` with user, organization, org role,
  scopes, and API-key project restrictions.
- **Graph tenancy:** Surreal namespace-per-org for graph data. The active group ID is the current
  organization ID, not FalkorDB database-per-org.
- **Project control plane:** Surreal `projects`, `project_members`, `team_projects`, and
  `api_key_project_scopes` records are the project authorization source of truth.
- **Project IDs:** external APIs and graph entities use graph project IDs such as `project_<hash>`;
  the Surreal auth runtime stores them in `projects.graph_project_id`.
- **Project fallback:** if no project control-plane records exist for an org,
  `list_accessible_project_graph_ids()` falls back to graph project entities. This is migration
  compatibility and should be retired or feature-gated during B2.
- **Project record repair:** owner/admins can preview or apply
  `POST /api/admin/backfill/project-records` to create missing Surreal auth `projects` records from
  existing graph project entities before stricter project gates are enforced.
- **Memory policy:** `sibyl_core.auth.memory_policy` currently enables private, verified project,
  and verified delegated scope reads/writes/reflection. Share is deny-only across scopes until
  promotion/share preview work lands. Team, organization, shared, and public scopes return stable
  denies.

### Trust Surface Inventory

| Surface                                          | Identity/context carried                                                    | Current policy status                                                                                                                                           | Follow-up                                                                                           |
| ------------------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| REST `/api/memory/raw`                           | user ID, org, optional agent, `project_id`, `memory_scope`, `scope_key`     | Uses shared write policy and logs `memory_policy_decision`. Project scope checks membership through `scope_key`; diary project metadata is separately verified. | B3 should canonicalize `project_id` and project `scope_key` so metadata and policy cannot drift.    |
| REST `/api/memory/raw/recall`                    | user ID, org, optional agent, `project_id`, `memory_scope`, `scope_key`     | Uses shared read policy and logs `memory_policy_decision`; project scope requires verified `scope_key`.                                                         | B3 should align `project_id` filters with project scope and keep deny reasons stable.               |
| REST `/api/memory/reflection/promote`            | user ID, org, target project, target scope, related IDs                     | Verifies target project access and delegates reflect/write policy to native promotion.                                                                          | B4 should expose promotion policy decisions and source IDs through inspect/audit.                   |
| REST `/api/context/pack`                         | user ID, org, optional agent, optional project, accessible projects         | Verifies explicit project reads or passes accessible project set into core retrieval. Raw-memory recall uses shared read policy internally.                     | B4 should surface hidden/allowed policy reasons in context-pack metadata.                           |
| REST `/api/context/reflect`                      | user ID, org, optional project, accessible projects, project/private scope  | Verifies explicit project reads and passes reflect/write policy context into core reflection when persisting.                                                   | B3 should make route-level audit wording match raw memory decisions.                                |
| REST `/api/search` and `/api/search/explore`     | user ID, org, explicit project or accessible project set                    | Explicit projects are verified; unscoped searches pass accessible project IDs into core search/explore.                                                         | B2 should add direct leak tests for project-private entities and related traversals.                |
| REST `/api/search/temporal`                      | org only                                                                    | Temporal edge queries are org-scoped compatibility/history reads and do not currently apply project policy context.                                             | B2 should either add project filtering or label the route historical/admin-only.                    |
| REST `/api/entities` list/get                    | org only on list/get route; write routes carry user/project checks          | Write routes verify project access. Direct list/get currently need explicit read-side project authorization status.                                             | B2 owns direct entity list/get filtering and negative tests.                                        |
| REST `/api/entities/captures`                    | org only; update requires org write role                                    | Raw capture sidecar is org-scoped and reviewable, but not memory-policy scoped.                                                                                 | B4 should either classify it as legacy capture review or add project/source policy metadata.        |
| REST `/api/rag` and `/api/session`               | user ID, org, accessible project set                                        | RAG and session-bundle routes resolve accessible projects before retrieval, but are outside raw-memory policy decisions.                                        | B4 should include them in inspect/audit output or explicitly classify them as derived context.      |
| MCP `search`, `explore`, `context`               | user ID, org, scopes, API-key project restrictions, optional project/agent  | No longer org-only; accessible project IDs are resolved and passed to core tools.                                                                               | B3 should add explicit deny-case coverage for restricted API keys and missing users.                |
| MCP `remember`                                   | user ID, org, project, memory scope, raw source IDs, related IDs            | Policy-backed: writes raw memory first, logs `mcp_memory_policy_decision`, then creates graph memory with raw source metadata.                                  | B4 should make raw/graph pairing inspectable.                                                       |
| MCP `reflect`                                    | user ID, org, project, accessible projects, memory scope                    | Passes policy context into core reflection and native writes.                                                                                                   | B3/B4 should align audit and inspect output with REST reflection.                                   |
| MCP `add`                                        | user ID and org metadata; optional project                                  | Generic graph mutation path, not raw-memory policy-backed.                                                                                                      | B3 should either route agent memory writes through `remember` or add project/policy gates to `add`. |
| MCP `manage`                                     | user ID and org injected into action data                                   | Depends on each management action; not a unified memory policy surface.                                                                                         | B3 should classify each manage action and reject memory-sensitive actions without policy context.   |
| CLI `remember`, `recall`, `context`, `reflect`   | bearer token/API key, linked project, optional agent/scope flags            | Thin REST client; server policy is authoritative. `remember` now captures raw memory before graph entity creation.                                              | B3 should keep CLI output showing server policy reasons and avoid local policy forks.               |
| Prompt hook `user-prompt-submit.py`              | inherits CLI auth/config and linked project through `sibyl context` command | No direct auth logic; it asks the CLI for a context pack.                                                                                                       | B3 should document hook behavior as inherited REST policy and add failure-mode tests.               |
| Async jobs `apps/api/src/sibyl/jobs/entities.py` | group/org ID plus queued entity/task data                                   | Jobs persist graph entities and task learning artifacts after the API has authorized the enqueueing route; job payloads do not carry a full policy decision.    | B3 should carry actor/project/policy receipt fields into job payloads and learning artifacts.       |

### Test Coverage Status

- Present: core memory policy allow/deny tests for private, project, delegated, and disabled scopes.
- Present: REST raw memory tests cover project membership allow/deny, missing scope key, diary
  constraints, and promotion project verification.
- Present: REST context tests cover accessible project scoping and inaccessible project denial.
- Present: REST entity list/get fixtures cover project-private, unassigned, inaccessible, and
  project-entity-as-scope read behavior. Core search, explore, and context-pack related hydration
  fixtures use the same project-entity-as-own-ID policy helper.
- Present: MCP tests cover accessible-project resolution, restricted credentials, remember policy,
  and reflect project context.
- Missing before release: raw-capture visibility classification, temporal search access tests, MCP
  generic `add/manage` policy tests, and job-payload policy receipt tests.

---

## 1) System Overview (As Implemented)

### Identity & tokens

- **Web**: cookie-based JWT access token (`sibyl_access_token`) + refresh token cookie
  (`sibyl_refresh_token`); refresh is “rotating” (`POST /api/auth/refresh`).
  - `apps/api/src/sibyl/api/routes/auth.py`
  - `apps/web/src/lib/api.ts` (refresh-on-401 behavior)
  - `apps/web/src/proxy.ts` (page gating by cookie presence)
- **CLI**: stores access token + refresh token in `~/.sibyl/auth.json` (0600) and uses Bearer auth.
  - `apps/cli/src/sibyl_cli/auth_store.py`
  - `apps/cli/src/sibyl_cli/client.py`
- **API keys**: `sk_*` keys stored hashed (PBKDF2) in Postgres; can be used as Bearer tokens.
  - `apps/api/src/sibyl/auth/api_keys.py`
  - `apps/api/src/sibyl/auth/dependencies.py#L68` (API key fallback)

### Tenancy & authorization layers

- **Graph tenancy**: group isolation via FalkorDB graph “database-per-org” (`group_id == org.id`).
  - `packages/python/sibyl-core/src/sibyl_core/graph/entities.py#L44-L64`
- **Org RBAC**: `OrganizationRole` (`owner/admin/member/viewer`) enforced by FastAPI dependencies.
  - `apps/api/src/sibyl/auth/dependencies.py#L131-L158`
- **Project RBAC (Postgres)**: `projects`, `project_members`, `team_projects` tables exist, and the
  project role resolution + filtering functions exist.
  - `apps/api/src/sibyl/auth/authorization.py`
  - `apps/api/alembic/versions/0005_project_permissions.py`
- **Project filtering of graph results**: `POST /api/search` and `/api/search/explore` compute
  accessible projects (from Postgres) and pass them down for filtering.
  - `apps/api/src/sibyl/api/routes/search.py#L62-L103`
  - `packages/python/sibyl-core/src/sibyl_core/tools/search.py#L390-L396`
  - `packages/python/sibyl-core/src/sibyl_core/tools/explore.py#L220-L226`

### MCP surface

- MCP is hosted at `/mcp` alongside REST at `/api/*`.
  - `apps/api/src/sibyl/main.py`
  - `apps/api/src/sibyl/server.py`
- MCP auth uses the FastMCP OAuth provider and accepts JWTs and API keys.
  - `apps/api/src/sibyl/auth/mcp_oauth.py`
  - `apps/api/src/sibyl/auth/mcp_auth.py`

---

## 2) Findings (Security/Correctness)

Severity rubric (rough): **Critical** (tenant/project isolation bypass or takeover), **High**
(unintended cross-user control, broad data exposure), **Medium** (abuse/DoS or policy drift),
**Low** (hardening/ergonomics).

### A. Critical: Project RBAC is likely non-functional in practice

**What**: Project RBAC enforcement relies on the Postgres `projects` table being populated with
`graph_project_id` rows. If _no_ projects exist in Postgres for an org,
`list_accessible_project_graph_ids()` returns `None`, and callers treat that as “skip filtering /
migration mode”.

- `apps/api/src/sibyl/auth/authorization.py#L225-L235` (returns `None` to skip filtering)
- `apps/api/src/sibyl/api/routes/search.py#L62-L85` (passes `accessible_projects` down)
- `apps/api/src/sibyl/auth/authorization.py#L481-L488` (if project not registered: allow org
  members)

**Why it matters**: Until Postgres projects are registered, project-level auth is effectively
disabled: filtering can be skipped for reads and `verify_entity_project_access()` will “allow org
members” even for project-scoped writes when the project cannot be resolved in Postgres.

**Evidence of missing wiring**:

- Graph project create/update/delete paths now synchronize Surreal auth `projects` records, but
  existing graph projects can still predate that synchronization.
- `POST /api/admin/backfill/project-records` repairs missing auth project records from graph project
  entities with a dry-run default. Apply mode creates organization-visible project records owned by
  the acting owner/admin and emits an audit event with the created graph project IDs.
- The old graph-to-Postgres sync CLI was removed after Surreal auth became canonical; project RBAC
  now stays anchored in the Surreal auth/runtime paths instead of resurrecting the mirror.

**Impact**:

- Users can likely access or mutate project-scoped entities without project membership being
  enforceable (because the project-to-Postgres mapping is missing or incomplete).

**Recommendation**:

- Keep graph project registration automatic for new create/update/archive operations.
- Use the project-record backfill before enforcing stricter gates against migrated dogfood data.
- Remove or time-bound “migration mode” fallbacks for **read** paths, or gate them behind an
  explicit feature flag once existing projects are repaired.

---

### B. Critical: Project membership graph-ID and org-membership invariant

**B2.2 update, 2026-05-13**: project-member routes now accept graph project IDs through the Surreal
organization runtime, and project membership no longer grants access unless the actor is still an
organization member. Adding or updating project members also requires the target user to belong to
the organization. Member listings filter stale `project_members` rows for users who are no longer
org members, while removal remains available so old grants can be cleaned up.

**Historical issue**: `/api/projects/{project_id}/members` and the web app needed to agree on graph
project IDs such as `project_<hash>`, while the runtime had to resolve those IDs to Surreal auth
`projects.uuid` before reading or writing `project_members`.

**Why it matters**:

- A user removed from an org must not retain access through stale `project_members` rows.
- Membership management must use graph project IDs at route boundaries and Surreal auth project
  UUIDs internally.

**Recommendation**:

- Keep route-boundary IDs as graph project IDs and resolve internally through the Surreal auth
  runtime.
- Add cleanup or cascade follow-up for stale `project_members` rows when org membership is removed.
- Keep tests covering actor org membership, target org membership, stale-row filtering, and
  stale-row removal.

---

### C. High: `verify_entity_project_access()` bypasses `required_role` in important cases

**What**:

- If an entity has **no project_id**, `verify_entity_project_access()` returns `ProjectRole.VIEWER`
  for any org member, regardless of the `required_role` passed in.
  - `apps/api/src/sibyl/auth/authorization.py#L473-L479`
- If the entity’s project is **not registered in Postgres**, it also returns `VIEWER` for any org
  member, regardless of `required_role`.
  - `apps/api/src/sibyl/auth/authorization.py#L481-L488`

**Why it matters**:

- For write endpoints that call `verify_entity_project_access(..., required_role=MAINTAINER)` (e.g.
  entity deletion), a missing/unregistered project causes the check to succeed, permitting the write
  if org-level RBAC permits it.
  - `apps/api/src/sibyl/api/routes/entities.py#L731-L735` (delete requires MAINTAINER, but
    bypassable)

**Recommendation**:

- Treat “no project_id” and “project unregistered” as a separate authorization domain:
  - Either map them to **org-level** permissions (e.g. only org admins can delete unassigned
    entities), or
  - Enforce `required_role` consistently (if required_role > viewer, deny).
- Log + metric these fallbacks; they’re security-relevant.

---

### D. High: MCP bypasses project RBAC and lacks user context

**What**: MCP tools are scoped by org only (`_require_org_id()` reads `org` claim). They do not
compute accessible projects for a user and therefore cannot filter per-project. This is a direct
side channel around project RBAC once project permissions matter.

- `apps/api/src/sibyl/server.py#L20-L71` (org-only context extraction)
- `apps/api/src/sibyl/server.py` tools call core tools with `organization_id=org_id` only.

Also: scopes default to `mcp` when absent, meaning access tokens issued for the web/REST effectively
grant MCP access unless a more explicit “audience/scope” strategy is adopted.

- `apps/api/src/sibyl/auth/mcp_auth.py#L24-L32` (default scopes -> `["mcp"]`)
- `apps/api/src/sibyl/auth/mcp_oauth.py#L76-L84` (default scopes -> `[OAUTH_SCOPE]`)
- `apps/api/src/sibyl/auth/jwt.py#L33-L63` (access tokens do not set scope by default)

**Recommendation**:

- If project RBAC is real, MCP must be able to derive **user_id + org_role** from the token and
  filter results by accessible projects (like REST does).
- Consider explicit audiences (`aud`) or explicit scopes for MCP vs web sessions.

---

### E. Medium/High: Postgres RLS is “allow-all on NULL context” and is not wired into request sessions

**What**:

- RLS policies explicitly allow access when `current_setting('app.org_id', true) IS NULL` (and same
  for `app.user_id`), which makes “no context” a bypass.
  - `apps/api/alembic/versions/0006_row_level_security.py#L64-L79`
  - The old PostgreSQL-only RLS integration test was removed when the active SQLModel/Alembic
    runtime island was retired.
- The historical app did not set `app.org_id` / `app.user_id` on its regular DB sessions. Active
  Surreal runtime paths no longer expose those PostgreSQL sessions.
- A helper exists to set session variables (`get_rls_session()`), but it is not used anywhere, and
  it claims “policies should deny by default” which is not consistent with the policy design.
  - `apps/api/src/sibyl/auth/rls.py#L144-L146`

**Impact**:

- RLS currently provides little to no tenant isolation hardening; isolation depends on application
  filters.
- Any missing org filter in SQL can become a cross-tenant read/write.

**Recommendation**:

- Decide what you want:
  - If RLS is **hardening**, remove the NULL-bypass in policies (or gate it on a privileged DB
    role).
  - If NULL-bypass is required for migrations, use a dedicated migration role or explicit bypass GUC
    only settable by superuser.
- Retired after the v0.6.0 Surreal auth cutover: relational RLS session dependencies no longer
  participate in request handling.

---

### F. Medium: Setup endpoints stay unauthenticated after setup

**What**: `/api/setup/*` endpoints have no auth and remain callable after users/orgs exist.

- `apps/api/src/sibyl/api/routes/setup.py#L1-L21` and endpoints below

Notably, `/setup/validate-keys` uses stored provider keys to call external APIs; this can be abused
for rate/usage pressure even if it doesn’t leak secrets.

**B2.3 update, 2026-05-13**: setup mode now stays open only until an owner/admin organization is
initialized, rather than keying solely off the presence of users. `/setup/validate-keys` requires
owner/admin authorization after bootstrap, and initialized unauthenticated setup calls return a
structured `setup_already_initialized` detail so the web setup flow can redirect instead of showing
a generic server failure. `/setup/status` remains public so login and setup routing can detect
first-run state, but `validate_keys=true` only triggers external key validation before setup is
complete.

**Recommendation**:

- Keep `/setup/status` public and side-effect free.
- Keep key validation and config mutation owner/admin-only after setup initialization.
- Add rate limiting to `validate-keys` if external API validation remains callable from the web UI.

---

### G. Medium: Web server-side caching may risk cross-user cache pollution

**What**: `apps/web/src/lib/api-server.ts` performs `fetch()` with cookies attached and uses Next
fetch caching strategies (`force-cache`, `revalidate`). Depending on Next.js caching semantics, this
can risk caching authenticated responses across users/orgs.

- `apps/web/src/lib/api-server.ts#L39-L66`

**Recommendation**:

- Confirm Next’s caching behavior when request headers include cookies.
- Consider `cache: 'no-store'` for any request that includes auth cookies, and cache only truly
  public endpoints.

---

### H. Low/Medium: API keys: coarse scopes; project scoping not enforced

**What**:

- REST scope gating is coarse (`api:read`/`api:write`) and only applied to API keys.
  - `apps/api/src/sibyl/auth/dependencies.py#L22-L49`
- Project scoping exists in schema (`api_key_project_scopes`) but is not enforced in request auth.
  - `apps/api/alembic/versions/0005_project_permissions.py#L161-L188`

**Recommendation**:

- Enforce `api_key_project_scopes` at auth time and incorporate it into project filtering.

---

## 3) “Good News” (What Looks Solid)

- API key hashing + verification is reasonable (PBKDF2 + constant-time compare).
  - `apps/api/src/sibyl/auth/api_keys.py`
- Refresh token rotation is implemented and rate limited.
  - `apps/api/src/sibyl/api/routes/auth.py#L1085-L1187`
- CLI token storage enforces restrictive file/dir permissions and atomic writes.
  - `apps/cli/src/sibyl_cli/auth_store.py`
- Core graph operations require explicit org context (`group_id`) to create managers.
  - `packages/python/sibyl-core/src/sibyl_core/graph/entities.py#L44-L64`

---

## 4) Suggested Remediation Plan (Prioritized)

### Phase 0: Safety fixes (fast, high impact)

1. Fix project membership routing:
   - Accept graph project IDs, not Postgres UUIDs, and resolve Postgres project row internally.
2. Automatically create/update Postgres `projects` rows when graph projects are created.
3. Add org RBAC guard (`require_org_role`) to `project_members` endpoints.
4. Remove/write-gate `verify_entity_project_access()` bypasses for write paths.
5. Gate setup endpoints after initial bootstrap.

### Phase 1: Hardening / defense-in-depth

1. Decide RLS posture:
   - enforce in app sessions + remove NULL-bypass for app DB role
2. Ensure org-scoped tables are always queried with `organization_id` filters (even with RLS).
3. Decide MCP scope/audience strategy and add user-derived project filtering.

### Phase 2: Tests + tooling

1. Add tests proving:
   - “removed org member cannot manage project members”
   - project access checks fail closed when Postgres project rows are missing
   - MCP requests do not bypass project filtering once project RBAC is enforced
2. Add an admin endpoint/job that shows whether Postgres projects are synced to graph projects.

---

## 5) Notes on Audit Process

- Sibyl server wasn’t reachable in this environment, so I couldn’t use `sibyl search` to pull prior
  knowledge graph patterns; this report is a static code audit.
