You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit bd8a2ca
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: SECURITY.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -154,7 +154,7 @@ The token is a lock on the **write** surface, not a wall around the whole API.
154
154
-**The real boundary is loopback + the DSH host listener.** The host-side routes (`/api/dsh-mneme/*`) are mounted on the DSH port, which binds `127.0.0.1` and is fenced by the host against DNS rebinding and cross-site browser requests. That fence does **not** establish identity: any local process, and any page running in the host's own origin, is inside the perimeter.
155
155
-**Authentication is opt-in and fail-open.**`apiToken` defaults to empty; while it is empty, `isAuthorized()` returns true for every request — reads *and* writes. Setting a token gates the write routes and the sensitive reads; it does not gate plain reads.
156
156
- **Open reads (no token even when one is configured)**: `GET /`, `/info`, `/version-check`, `/list`, `/recall-stats`, `/search`, `/semantic`, `/semantic/llm-audit`, `/semantic/llm-audit/stats`, `/semantic/consolidation-stats`, `/semantic/graph/*`, `/entities`, `/memories/entities`, `/dream-status`, `/inject-status`, `/inject-preview`, `/pipeline`, `/candidates`, `/diary`, `/diary/entry`, `/diary/library`, `/diary/library/entry`, `/llm-providers`, `/config-keys`, plus the `GET`/`HEAD` branches of `/profile`, `/rules`, `/persona`, `/profile-facts`, `/mode`, `/features`, `/commands`, `/nudge`, `/diary/compose`, `/diary/export`, of the two share-receive routes `/receive` and `/receive/undo`, of `/profile-facts/apply`, of the six chorography read routes `/choro/repos`, `/choro/modules`, `/choro/page`, `/choro/search`, `/choro/claims`, `/choro/run` (M1/finale: they read repo-local wiki pages and `choro_*` index tables — not memory rows; with `chorographyEnabled` off they uniformly answer `409 disabled`, the #497 mount-anyway-gate-in-logic pattern), of the two T1 job routes `/choro/t1` and `/choro/t1/status` (same `token-write` shape as `/choro/run`: the only token-exempt branch is a `405`, and the POST itself answers `409 disabled` unless both `chorographyEnabled` and `chorographyT1FromPanel` are on), and of the three `token-write` knowledge-base routes `/kb/collections`, `/kb/ingest` and `/kb/search` (again only a `405` is genuinely open on them, because `needsToken()` exempts `GET`/`HEAD` under `token-write`; the two plain-`token` reads under `/kb/*` stay gated even on `GET`). `/choro/run` is the same shape as `/receive`: a `token-write` route whose GET branch is token-exempt, so the only genuinely open thing on that path is a `405` — the POST write itself stays gated. Treat them as readable by anything local. `/receive` and `/receive/undo` belong on this list even though they write: under the `token-write` policy, `needsToken()` exempts `GET`/`HEAD` from the token, so the only thing genuinely open on those two paths is a `405` — no read branch exists. `/profile-facts/apply` is POST-only for the same reason (its only open branch is a `405`). The `GET` branch of `/profile-facts` stays open even while `profileFactsEnabled` is off: facts survive a switch-off and the panel must be able to show them (same reasoning as `GET /profile`). This section mirrors the policy declarations rather than anyone's intent, which is why a write route shows up under "open reads"; `dsh-mneme/test/security-doc.test.js` compares both lists against the routes actually mounted, in both directions.
157
-
- **Gated routes (when a token is configured)**: every write — `/create`, `/update`, `/delete`, `/import`, `/bootstrap`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/conflicts/resolve`, `/profile/extract` (POST-only: one host-LLM call that returns a profile **draft**; other methods get 405 before any side effect), `/profile-facts/apply` (POST-only: per-fact manual corrections from the panel; writes the `profile_facts` tables, never `user_settings`), `/profile-facts/run` (POST-only, `token` policy like `/profile/extract`: one host-LLM maintenance pass with no read branch; 409 while `profileFactsEnabled` is off), `/choro/run` (POST-only: the panel "rebuild skeleton" write path, re-running T0 into the repo's `.chorography/**`; with `chorographyEnabled` off it uniformly answers 409 disabled), `/choro/t1` (POST-only: spawns a real T1 run through the choro CLI — a host-LLM pass that costs money, so it carries its own `chorographyT1FromPanel` switch on top of `chorographyEnabled`), `/choro/t1/status` (the job poll: its `logTail` carries CLI/model output, so it is not a public-repo read like the rest of `/choro/*`), `/kb/collections`, `/kb/search` (POST-only writes; the only token-exempt branch is the `405`, same shape as `/choro/run`), `/kb/ingest` (POST-only: pulls a configured local source into the knowledge base; source-level failures still answer `200` with `ok:false`, which is a result, not a permission), `/kb/docs`, `/kb/doc` (plain `token`: they hand back whatever collection content the user ingested — that is private material, unlike the repo-documentation `/choro/*` reads), `/receive`, `/receive/undo` (the two share-receive routes write into *this* machine's library, which is why they are `token-write`), `/diary/compose` (POST-only: one host-LLM call that writes `<memoryDir>/diaries/<projectKey>/YYYY-MM-DD.md`; 409 while `diaryEnabled` is off), `/diary/export` (POST-only: copies one entry into the *user's* bound project directory, which is outside every path the plugin otherwise owns — 409 on an existing target unless `overwrite` is explicit), and the non-`GET` branches of `/profile`, `/rules`, `/persona`, `/profile-facts`, `/mode`, `/features`, `/commands`, `/nudge` — plus six reads: `/export`, `/external-api`, `/conflicts`, `/health`, `/share`, `/memory/provenance`. `/share` is gated because the share pack is a whole-library read delivered over POST, and it answers 405 to GET — no open read path exists. `/memory/provenance` is gated because it returns the **verbatim raw text** of distilled conversation windows (opt-in via `distillRecords.enabled`); chained with the open list route it would otherwise let any local process enumerate ids and then pull that text back, which reaches the same result as `/export` in a different shape.
157
+
- **Gated routes (when a token is configured)**: every write — `/create`, `/update`, `/delete`, `/import`, `/bootstrap`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/conflicts/resolve`, `/profile/extract` (POST-only: one host-LLM call that returns a profile **draft**; other methods get 405 before any side effect), `/profile-facts/apply` (POST-only: per-fact manual corrections from the panel; writes the `profile_facts` tables, never `user_settings`), `/profile-facts/run` (POST-only, `token` policy like `/profile/extract`: one host-LLM maintenance pass with no read branch; 409 while `profileFactsEnabled` is off), `/choro/run` (POST-only: the panel "rebuild skeleton" write path, re-running T0 into the repo's `.chorography/**`; with `chorographyEnabled` off it uniformly answers 409 disabled), `/choro/t1` (POST-only: spawns a real T1 run through the choro CLI — a host-LLM pass that costs money, so it carries its own `chorographyT1FromPanel` switch on top of `chorographyEnabled`), `/choro/t1/status` (the job poll: its `logTail` carries CLI/model output, so it is not a public-repo read like the rest of `/choro/*`), `/kb/collections`, `/kb/search` (POST-only writes; the only token-exempt branch is the `405`, same shape as `/choro/run`), `/kb/ingest` (POST-only: pulls a configured local source into the knowledge base; source-level failures still answer `200` with `ok:false`, which is a result, not a permission), `/kb/docs`, `/kb/doc` (plain `token`: they hand back whatever collection content the user ingested — that is private material, unlike the repo-documentation `/choro/*` reads), `/receive`, `/receive/undo` (the two share-receive routes write into *this* machine's library, which is why they are `token-write`), `/diary/compose` (POST-only: one host-LLM call that writes `<memoryDir>/diaries/<projectKey>/YYYY-MM-DD.md`; 409 while `diaryEnabled` is off), `/diary/export` (POST-only: copies one entry into the *user's* bound project directory, which is outside every path the plugin otherwise owns — 409 on an existing target unless `overwrite` is explicit), and the non-`GET` branches of `/profile`, `/rules`, `/persona`, `/profile-facts`, `/mode`, `/features`, `/commands`, `/nudge` — plus seven reads: `/export`, `/external-api`, `/conflicts`, `/conflicts/ledger` (read-only triage ledger — tier/status/detection timestamps and title-level info, same sensitivity as `/conflicts`), `/health`, `/share`, `/memory/provenance`. `/share` is gated because the share pack is a whole-library read delivered over POST, and it answers 405 to GET — no open read path exists. `/memory/provenance` is gated because it returns the **verbatim raw text** of distilled conversation windows (opt-in via `distillRecords.enabled`); chained with the open list route it would otherwise let any local process enumerate ids and then pull that text back, which reaches the same result as `/export` in a different shape.
158
158
-**The standalone data plane** (`127.0.0.1:8790`) is the opposite shape: every route except `GET /health` requires its own Bearer token. Pointing `externalApiHost` at a non-loopback address therefore turns it into a plaintext, token-only HTTP surface — an explicit operator decision.
159
159
-**Consequence**: if you expose the plugin beyond loopback (reverse proxy, non-loopback bind), set `apiToken`*and* check that the plain reads above are acceptable to expose — they are not covered by it.
160
160
-**How this list stays true**: every route declares its own `policy` (`open` / `token` / `token-write`) at registration, and `createRouteRegistrar` throws when a route has none or reuses a path. A new route that forgets its classification **fails to boot** instead of silently opening. The two lists above are compared against the routes actually mounted by `dsh-mneme/test/security-doc.test.js` in both directions, so adding a route without updating this section fails CI rather than quietly drifting — the matrix is derived from code, not from anyone's memory.
@@ -552,7 +552,7 @@ Token 是**写**面上的锁,不是把整个 API 围起来的墙。
0 commit comments