@synapsor/runner 0.1.12 → 0.1.14

package/THREAT_MODEL.md

@@ -0,0 +1,79 @@
+# Threat Model
+
+Synapsor Runner protects one narrow boundary: model-facing MCP database actions that go through reviewed Synapsor capabilities and guarded writeback jobs.
+
+It is not a general MCP security gateway, not a prompt-injection cure, not a replacement for host security, and not a self-hosted copy of Synapsor Cloud.
+
+## Assets
+
+- Customer Postgres/MySQL credentials.
+- Business rows targeted by model-facing workflows.
+- Trusted tenant, principal, source, object, allowed-column, and version bindings.
+- Proposal diffs, evidence bundles, query audit, approvals, writeback jobs, receipts, and replay records.
+- Runner token and local SQLite proposal store.
+
+## Trust Boundaries
+
+```text
+MCP client/model
+  -> Synapsor Runner MCP server
+  -> reviewed capability config
+  -> read-only database credential
+  -> local proposal/evidence/replay store
+  -> human approval outside the model
+  -> guarded worker with write credential
+  -> Postgres/MySQL
+```
+
+In Cloud-linked mode:
+
+```text
+MCP client/model
+  -> local Synapsor Runner MCP server
+  -> Synapsor Cloud adapter/capability API
+  -> Cloud proposal/approval/replay/job lease
+  -> local guarded worker
+  -> Postgres/MySQL
+```
+
+The model-facing MCP tool call has request/proposal authority. The trusted runner has execution authority only for already-approved, scoped writeback jobs.
+
+## Covered Threats
+
+- Model asks for arbitrary SQL: no generic SQL tool is exposed in the Synapsor path.
+- Model supplies `tenant_id`, `principal`, source id, allowed columns, row version, or approval identity: runner rejects trusted-binding overrides.
+- Prompt injection in database content asks the model to bypass policy: the runner ignores text as authority and only accepts structured capability/job state.
+- Wrong tenant or object: reads and writes include trusted primary-key and tenant predicates.
+- Disallowed field update: patch columns must be allowlisted.
+- Stale row: conflict guard mismatch returns `conflict` instead of silently writing.
+- Duplicate retry: receipt/idempotency state prevents applying the same job twice.
+- Over-broad update: only single-row `UPDATE` is supported and success requires exactly one affected row.
+- Cloud credential leakage: database URLs and write credentials stay local and are not sent to Cloud.
+- Model-callable approval: approval/commit tools are not exposed to MCP clients by default.
+
+## Not Covered
+
+- A compromised local host, MCP host, or modified runner binary.
+- A malicious or compromised non-Synapsor MCP server.
+- Credential theft outside the runner process.
+- OAuth, SSRF, token-passthrough, or confused-deputy bugs in unrelated MCP systems.
+- Sensitive data already returned to a model.
+- Prompt injection itself.
+- Business invariants not represented in the capability config, proposal, application handler, or database constraints.
+- Multi-row business transactions, DDL, DELETE, INSERT, UPSERT, or cross-database atomicity in v0.1.
+
+## Required Operator Controls
+
+- Use a read-only credential for MCP reads.
+- Use a separate write credential only in the trusted runner environment.
+- Scope runner tokens to the project/source they serve.
+- Keep capability config under code review.
+- Prefer version/timestamp conflict guards over weak row-hash fallback.
+- Review proposal diffs and evidence before approval.
+- Monitor conflict/failed receipt rates.
+
+## Release Blockers
+
+- Client-specific MCP configuration must be tested before claiming support for that client.
+- Cloud-linked mode requires a compatible Synapsor Cloud API and scoped runner token.
+- Public release should include dependency review, secret scanning, and container-backed smoke results.

package/dist/runner.mjs

@@ -8439,7 +8439,7 @@ function stringOrDefault(value, fallback) {
 // apps/runner/package.json
 var package_default = {
   name: "@synapsor/runner",
-  version: "0.1.12",
+  version: "0.1.14",
   description: "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   license: "Apache-2.0",
   type: "module",
@@ -8470,9 +8470,12 @@ var package_default = {
     "schemas/**",
     "recipes/**/*.json",
     "README.md",
+    "AGENTS.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "LICENSE",
     "NOTICE",
+    "THREAT_MODEL.md",
     "TRADEMARKS.md"
   ],
   keywords: [

package/docs/README.md

@@ -1,13 +1,13 @@
 # Synapsor Runner Docs
 
 Start with the README. Use this index when you need the task-specific next
-step. The order is intentional: run something first, wire your database second,
-then read the concepts once the safety boundary is visible.
+step. The order is intentional: audit the model-facing risk first, run the
+no-database demo, wire your database, then read deeper concepts.
 
 ## 01 Quickstart
 
-- [README](../README.md): wedge, no-DB quick demo, five-line model, and the
-  shortest own-database path.
+- [README](../README.md): audit-first proof, no-database demo, safety diagram,
+  and the shortest own-database path.
 - [Troubleshooting First Run](troubleshooting-first-run.md): common first-run
   failures, redacted diagnostics, and fixes.
 
@@ -98,6 +98,8 @@ then read the concepts once the safety boundary is visible.
   scope, database roles, receipt grants, local ledger backup, restart behavior,
   Docker/systemd shapes, TLS, and release-gate expectations.
 - [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [OSS Runner Vs Synapsor Cloud](oss-vs-cloud.md): detailed product and
+  operational boundary.
 - [Cloud Push](cloud-push.md): register a validated local contract in the
   versioned Cloud registry.
 - [Runner Bundles](runner-bundles.md): download the same immutable contract and
@@ -116,3 +118,26 @@ then read the concepts once the safety boundary is visible.
 The public docs intentionally stay task-first. Historical implementation
 reports, release checklists, and internal planning notes are not part of the
 getting-started path.
+
+## Core Terms
+
+- Capability: a reviewed model-facing business tool such as
+  `billing.inspect_invoice` or `billing.propose_late_fee_waiver`.
+- Proposal: an exact suggested change saved without mutating the source
+  database.
+- Writeback: execution of an approved proposal outside the model-facing MCP
+  surface.
+- Executor: Runner's guarded one-row updater or an app-owned handler for richer
+  approved business transactions.
+
+## Repository Map
+
+- `apps/runner`: CLI, local review UI, and packaged npm documentation.
+- `packages/spec`: canonical contract schemas and conformance fixtures.
+- `packages/dsl`: SQL-like contract authoring.
+- `packages/mcp-server`: stdio and HTTP MCP runtime.
+- `packages/proposal-store`: local evidence, proposal, receipt, and replay
+  ledger.
+- `packages/postgres`, `packages/mysql`: guarded writeback adapters.
+- `examples`: disposable demos and client integrations.
+- `docs`: task guides, security boundaries, operations, and release policy.

package/docs/getting-started-own-database.md

@@ -78,20 +78,11 @@ that is not a Postgres permission issue. It means the client reached the
 database, but your local Node/Postgres TLS stack could not verify the server's
 certificate chain.
 
-For disposable dev RDS fixtures, you can allow an insecure retry:
-
-```bash
-./scripts/use-your-db.sh --allow-insecure-ssl
-```
-
-or put `sslmode=no-verify` in the disposable test URL.
-
-For real staging or production-like testing, do not disable verification.
-Install/use the AWS RDS CA bundle and keep certificate verification enabled.
-For example, download the AWS RDS global bundle and configure your Postgres URL
-or client environment so the Node Postgres client trusts that CA. The exact
-mechanism depends on your deployment environment and should be treated like any
-other trusted database TLS setup.
+Do not disable certificate verification. Install the managed database CA bundle
+and configure the Postgres/MySQL client environment to trust it. For AWS RDS,
+use the current AWS RDS regional or global CA bundle. Treat database CA
+configuration like any other production trust-store dependency and verify it
+before using staging or production-like data.
 
 ## 2. Inspect metadata
 

package/docs/mcp-audit.md

@@ -150,3 +150,29 @@ A safer model-facing database MCP tool should look like a reviewed semantic prop
 ```
 
 Trusted values such as tenant, principal, source, allowed columns, approval identity, row-version guard, and database credentials must come from Synapsor/runner context, not from model-facing arguments.
+
+## Related Fixture Benchmark
+
+`synapsor-runner benchmark mcp-efficiency` compares a fixed generic database
+MCP shape with the semantic late-fee-waiver path used by Runner. The checked-in
+fixture currently demonstrates:
+
+```text
+Generic database MCP reference:
+  exposed tools: 4
+  scripted tool calls: 5
+  raw SQL exposed: yes
+  approval separated: no
+  stale-row conflict checked: no
+
+Synapsor Runner semantic path:
+  exposed tools: 2
+  scripted tool calls: 2
+  raw SQL exposed: no
+  approval separated: yes
+  stale-row conflict checked: yes
+```
+
+The fixture tokenizer is deterministic and repeatable for this repository. It
+is not a model billing tokenizer and does not support a universal token-savings
+claim.

package/docs/oss-vs-cloud.md

@@ -0,0 +1,50 @@
+# OSS Runner Vs Synapsor Cloud
+
+Synapsor Runner and Synapsor Cloud share the canonical `@synapsor/spec`
+contract, but they solve different operational problems.
+
+Runner is the open-source runtime that stays next to your application and
+database. It serves reviewed MCP tools, binds trusted context, stores local
+evidence and proposals, keeps approval outside MCP, applies or routes approved
+writeback, and records receipts and replay in a local SQLite ledger.
+
+Cloud is the team control plane. It stores versioned contracts, produces
+downloadable Runner bundles, and provides shared activity, evidence, approval,
+and investigation surfaces for enabled design-partner deployments.
+
+| Need | OSS Runner | Synapsor Cloud |
+| --- | --- | --- |
+| MCP runtime | Local stdio or Streamable HTTP server | Contracts export to local Runner bundles; managed runner fleet is future work |
+| Contract source | Local files reviewed in Git | Shared registry with immutable versions and digests |
+| Trusted context | Local environment/session bindings | Registered bindings plus deployment-specific Cloud session context |
+| Capabilities | Local semantic MCP tools | Registry, version history, and capability inspection |
+| Evidence and replay | Local SQLite ledger | Shared activity and evidence surfaces where enabled |
+| Approval | Local CLI or localhost UI | Team approval surfaces where enabled |
+| Writeback | Guarded one-row update or app-owned executor | Cloud-linked jobs with local execution; managed production orchestration is future work |
+| MCP risk audit | Static local audit | Organization-wide continuous audit is future work |
+| Identity | Local operator boundary | Workspace RBAC where configured; SAML and SCIM are future work |
+| Operations | Customer-operated single node | Design-partner operation; no enterprise SLA in the current beta |
+
+## What Stays Local
+
+- database read and write credentials;
+- trusted application handler credentials;
+- direct access to Postgres or MySQL;
+- the process that executes guarded writeback;
+- local development ledgers when Cloud linkage is not enabled.
+
+Cloud contract registration does not require uploading database credentials or
+business rows. A Runner bundle contains the normalized contract, placeholder
+environment-variable wiring, and MCP client templates.
+
+## Adoption Path
+
+1. Run the OSS audit and quick demo without an account.
+2. Connect Runner to a staging database and review the model-facing tools.
+3. Keep contracts in Git and exercise proposal, approval, writeback, and replay.
+4. Push the validated contract when the team needs a shared registry and review
+   surface.
+
+See [Cloud Push](cloud-push.md), [Runner Bundles](runner-bundles.md), and
+[Cloud Mode](cloud-mode.md) for commands and deployment details. See
+[Current Limitations](limitations.md) for the runtime boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,9 +31,12 @@
     "schemas/**",
     "recipes/**/*.json",
     "README.md",
+    "AGENTS.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "LICENSE",
     "NOTICE",
+    "THREAT_MODEL.md",
     "TRADEMARKS.md"
   ],
   "keywords": [