@ismaelsoilet/synapsejs 1.8.0 → 1.9.0

package/README.md

@@ -21,7 +21,7 @@ Features are listed with the command that fails when they break. Nothing is docu
 without one — see the repository's `AGENTS.md` for the full contract.
 
 **Stable:** vertical slices (N = 1) · `Result<T, E>` flows · TypeBox JIT contracts · declarative
-`sliceSchema` migrations with DAG topological ordering · bidirectional `-- up:` / `-- down:` rollbacks (`synapse rollback`) · embedded SQLite (WAL, tuned busy_timeout & cache pragmas delivering 4,000+ req/s, CTE-safe) ·
+`sliceSchema` migrations with DAG topological ordering · bidirectional `-- up:` / `-- down:` rollbacks (`synapse rollback`) · embedded SQLite (WAL, tuned busy_timeout & cache pragmas, CTE-safe; measured by `bun run bench:concurrency`) ·
 full-duplex WebSockets (`defineSocket` + `useWebSocket`) · hierarchical sub-slice composition & outlets (`<SubSlice>`, `<SliceOutlet>`) · in-memory SSR micro-cache & ISR (`defineCache`) ·
 vendor bundle code-splitting via Import Maps (`compiler.vendorChunks`) · standardized shared domain modules (`synapse new-shared`) ·
 isomorphic Query Builder with parameterized relational joins and sub-object nesting (`nestJoinedRow`) · centralized Schema Catalog (`.codebase/db-schema.d.ts`) ·
@@ -47,8 +47,10 @@ implemented with and without the slice convention, including what the numbers do
 `fc` and `MockDatabaseClient` are deliberate parts of the contract, not accidents: slices declare their
 invariants with `fc`, and the oracles use the mock. Both are asserted by
 `packages/synapse/test/machine-types.test.ts` ("public contract"), together with every other export this
-README lists. The same block is the list of what 1.0 will freeze. In 0.x a minor bump may still break;
-every break is in [CHANGELOG.md](../CHANGELOG.md).
+README lists. The same block is the list of frozen surfaces. A minor bump may still break in 1.x;
+every break is listed in [CHANGELOG.md](../../CHANGELOG.md), each with the flag that restores the
+previous behaviour where one exists — start with
+[`docs/migration-1.9.md`](../../docs/migration-1.9.md) if you are coming from 1.8.
 
 ## Quick start
 
@@ -131,9 +133,98 @@ bun run mcp     # JSON-RPC 2.0 over stdio
 Tools: `synapse_get_repo_map`, `synapse_get_db_schema`, `synapse_check`, `synapse_split`,
 `synapse_run_pbt`, `synapse_scaffold_slice`, `synapse_migrate`, `synapse_rollback`, `synapse_contract`,
 `synapse_check_db_drift`, `synapse_diff_impact`, `synapse_test_gate`, `synapse_abort_check`,
-`synapse_verify_step`, `synapse_reasoning_effort`, `synapse_triage_error`, `synapse_route_task`, `synapse_evaluate_nudge`.
+`synapse_verify_completion`, `synapse_reasoning_effort`, `synapse_triage_error`, `synapse_route_task`, `synapse_evaluate_nudge`.
 Slice-dependent tools fail with `NO_SLICES_DIR` (listing the paths they examined) instead of reporting an empty success.
 
+## Write-surface containment
+
+Every surface that turns caller input into a filesystem path segment goes through the single
+validator in `core/path-guard.ts`: `synapse new-slice` (`domain` and `name`), `synapse new-shared`
+(`name`), the CRUD scaffold, `synapse new`'s project directory and the upload parser. It rejects
+separators, parent traversal, absolute prefixes, empty segments and over-length input, and the
+resolved target must stay inside the directory the operation owns before anything is written.
+`--fields` names are validated as plain identifiers before they reach the generated DDL, so a crafted
+name cannot end up in a migration.
+
+The failures are machine-readable and non-zero:
+
+| code | meaning |
+|---|---|
+| `INVALID_PATH_SEGMENT` | a domain, slice name, shared-module name or project directory is not a single safe path segment |
+| `INVALID_FIELD_NAME` | a `--fields` name or enum value is not a plain identifier |
+| `SLICE_EXISTS` | the target file already exists |
+| `WRITE_FAILED` | the filesystem refused the write |
+| `NO_SLICES_DIR` | no `src/slices` was found; `candidates[]` lists every path examined |
+| `AMBIGUOUS_SLICES_DIR` | several workspace members own slices; set `SYNAPSE_ROOT` or run inside the target app |
+
+Uploads apply the same name rule and additionally refuse a file whose declared extension is outside
+`SYNAPSE_UPLOAD_ALLOWED_TYPES` (default: png, jpg, jpeg, gif, webp, pdf, txt, csv, json, md) or whose
+bytes do not match that extension, answering `415 UNSUPPORTED_FILE_TYPE`. The framework does not serve
+the upload directory — serving it is the application's responsibility.
+
+## Sessions and cookies
+
+With `SYNAPSE_SESSION_SECRET` set, a bearer token must be a signed session and its claims win: role
+headers are ignored and the tenant comes exclusively from the verified claims. Revocation is consulted
+on every request — in-process first, then against the persisted blacklist. Without a secret, identity
+headers are honoured **only** under the explicit development opt-in `SYNAPSE_DEV_HEADERS=true` (or a
+`development`/`test` runtime mode); an unset, staging or production environment resolves every request
+to an anonymous session, and `synapse start` refuses to run in production without a secret unless the
+operator passes `--acknowledge-insecure`.
+
+`ctx.setCookie` is secure by default: a cookie written with no options carries `HttpOnly`, `Secure`
+and `SameSite=Lax`, and only an explicit `false` opts out. A cookie written by **browser** script
+(`storeSession`) cannot: `document.cookie` cannot set `HttpOnly`, by construction, so a
+script-written session cookie is readable by any script in the origin. A session that must be
+unreachable by script is the one the server emits through `ctx.setCookie`.
+
+## Realtime: declared topics and a fail-closed upgrade
+
+A topic is declared, never inferred — a name is not a permission. Declare it in the slice that owns it:
+
+```typescript
+import { defineTopic } from 'synapsejs';
+
+export const sliceRealtime = defineTopic({ name: 'tickets', owner: 'tickets/view-tickets', readRoles: ['support'] });
+```
+
+`GET /_synapse/sse/tickets` then refuses an unauthenticated subscriber (`401 UNAUTHENTICATED`), an
+undeclared topic (`404 TOPIC_NOT_FOUND`) and a session without a declared role
+(`403 TOPIC_FORBIDDEN`). Topics resolve inside the subscriber's tenant, so two tenants using the same
+name never see each other's events, and `ctx.broadcast(topic, data)` notifies zero subscribers unless
+the calling slice is the declared owner. The registry and concurrent subscriptions are bounded
+(`config.realtime`), and a disconnect releases the topic entry.
+
+The WebSocket upgrade (`GET /_synapse/ws/<domain>/<name>`) is fail-closed on origin: with no
+`SYNAPSE_ALLOWED_ORIGINS` configured every upgrade is refused, an absent or opaque `null` origin is
+always refused, and only a loopback origin is carved out for local development. Both transports share
+one rate limiter and a per-client cap on concurrent connections. Every refusal is JSON
+(`{ ok: false, error, message }`) with one of `UNAUTHENTICATED`, `TOPIC_NOT_FOUND`,
+`TOPIC_FORBIDDEN`, `RATE_LIMIT_EXCEEDED`, `REALTIME_LIMIT_EXCEEDED`, `ORIGIN_NOT_ALLOWED` — the same
+set `synapse contract` enumerates with its statuses.
+
+## Per-process state, rate limiting and the image allowlist
+
+The token bucket rate limiter, the server-render micro-cache and the realtime event hub keep their
+state **in the serving process only**; there is no shared backend. A restart discards counters, cached
+responses and buffered events, and N instances behind a load balancer permit up to N times the
+per-instance allowance with a per-instance cache hit rate. The allowance registry is bounded
+(`config.rateLimit.maxBuckets`, 10,000 by default) and a saturated registry **refuses** the excess
+with `429` instead of evicting a live counter, so a rotating-identity flood cannot reset an abuser's
+allowance. Forwarding headers are trusted only when `SYNAPSE_TRUST_PROXY=true` (or
+`config.trustProxy`) is set; otherwise the peer address is the client identity, and every accepting
+surface — RPC, uploads, webhooks, SSE, WebSocket upgrades, the image endpoint, health, metrics,
+repo-map and server-rendered pages — draws from that one limiter.
+
+`/_synapse/images/optimize` requires a session, is rate limited, caps the upstream response
+(`config.imageOptimizer.maxResponseBytes`, 10 MiB by default) and the fetch duration
+(`config.imageOptimizer.timeoutMs`, 10 s by default), connects to the exact address that passed
+`validateExternalUrl` (so the hostname is not resolved a second time) and refuses redirects. When
+`SYNAPSE_ALLOWED_IMAGE_DOMAINS` (or `config.imageOptimizer.allowedDomains`) lists hosts, only those
+hosts are accepted; when nothing is configured **any publicly routable host is permitted** —
+loopback, link-local, private and cloud-metadata addresses are always refused, but there is no
+implicit allowlist beyond that.
+
 Client configuration for an agent host:
 
 ```json