The spec is OpenAPI.
The promises are tests.
Describe your system in a manifest, wire the hooks, prove it with the 52-check conformance suite. The source is published on GitHub.
Up and running in five minutes
# Node 22.19+ · pnpm 10 git clone https://github.com/ITC-cloud-soft/biz-ai.git cd biz-ai pnpm install pnpm test # every workspace package pnpm validate # OpenAPI lint + bundled manifests # the sample business system (PostgreSQL) pnpm --filter @dsh-bridge/example-equipment-inspection start → http://127.0.0.1:19730
import { createBridgeApp, createPool, createPostgresStore } from '@dsh-bridge/server-kit' const store = createPostgresStore({ pool: await createPool(DB_URL) }) await store.migrate() // bridge_* tables const bridge = await createBridgeApp({ manifest: { file: './bridge.manifest.yaml' }, store, serviceToken, bffSecret, hooks: { employees, authenticate, isSessionLive, recipientsFor, approvals, proposalKinds, reports, piiScan }, }) createServer(bridge.handler).listen(8080)
Your system writes only hooks
| hook | Returns / must keep |
|---|---|
employees | { id, role, active }. Deactivated staff lose every token at once |
authenticate | Existing session → { user: { id, role }, sessionId }. Never a second login |
recipientsFor | null / { stale } / { users, paramsFor, link, dedupeKey }. Decide the scope; check each person with the web's authorization |
approvals | get · approvers · card · mayDecide · decide. Same rules for web and chat |
proposalKinds | { roles, validate, apply }. apply runs only when a person accepts, in the same transaction |
reports | compute(viewer) → sections of counts only |
piiScan | Returns only categories when a directory name matches (never the text) |
Endpoints
Every response carries bridge-protocol: 1. Errors are { ok: false, error: <lower_snake_case> }. Within v1 we only add.
| Area | Operations | Principal |
|---|---|---|
| Basics | GET /health · GET /manifest | — · service |
| Identity | GET /identity · POST /identities/link · /me/link-codes · /me/identities | service · employee |
| Delegation | POST /delegations · /assistant/tickets · /assistant/delegations | service · BFF |
| Events · notifications | GET /events?after= · /notifications/for-event/{id} · /notifications/deliveries | service |
| Approvals | /approvals/{id}/deliveries · /approvals/{id}/im-decision · /approvals/im-decisions | service |
| Proposals | POST /proposals · /proposals/{id}/accept · /reject | delegation · employee |
| Reports | GET /reports/latest · POST /reports/run | employee · delegation |
| Optional | /help/* · /pii-scan · /ai-profile · /document-reads · /connectors/* | — |
Five invariants, 52 checks
| Invariant | Checks |
|---|---|
| 1 Link yourself only | L2–L9 · B1–B4 · N3 |
| 2 Delegation = allow-list ∩ role | L1 · D1–D7 · S1–S5 · R2 |
| 3 AI proposes, people decide | D3 · D5 · PR1–PR3 · A2–A4 · R3 |
| 4 No personal data | E1–E4 · N1 · N2 · A1 · R2 · L10 |
| 5 Identity from your system | L3 · D1 · D2 · S2 · A2 · N3 |
| Protocol hygiene | P1–P6 · M1–M3 |
BRIDGE_BASE_URL=http://127.0.0.1:8080 \
BRIDGE_FIXTURES=./test/fixtures.mjs \
BRIDGE_MANIFEST_FILE=./bridge.manifest.yaml \
node --test packages/protocol/conformance/http.test.mjs
52 passed, 0 known gaps, 0 skippedMutation tests: against mocks that deliberately break an invariant, the matching checks fail — proof that the suite bites.
Packages
OpenAPI · JSON Schema · validators · bridge-validate · conformance suite
Bridge v1 for your business system (Node.js · PostgreSQL)
AI-plane core: app registry · delegation · tools · message frame
identity · tools · events · notify · approvals · assistant · memory · persona · reader
React UI parts: chat linking · notification settings · AI employee settings · connectors
Authenticating gateway from the BFF to the AI plane (RPC allow-list)