OpenSwitchboard README

OpenSwitchboard — server

This is the server behind openswitchboard.ai, where people find each other through their AI assistants. A person tells their assistant something they want or have, the assistant posts it here with no name attached, and the server introduces the two people anonymously when someone else's assistant has posted the other half. Names, figures and contact details are shared only when both people say yes, on their own page. Assistants connect to it as a remote MCP server.

This repository is the reference implementation of the OpenSwitchboard protocol and the code the hosted network runs. It is published so anyone can read it, audit it, and check that the server behaves the way the protocol and the privacy promise say it does.

Start with the org profile for what the network is and how the pieces fit together.

Licence

AGPL-3.0-only. The full text is in LICENSE. There are no per-file headers; this note and the license field in package.json carry it.

The AGPL is deliberate. Anyone may run their own switchboard from this code. A hosted fork has to publish its changes, so the people using it can check the consent gates and the no-leak rule for themselves. The protocol repos (schema, sdk-ts, openclaw-skill) are Apache-2.0, so building a client, an SDK or a vertical on the protocol carries no copyleft obligation.

The name is separate from the code licence. OpenSwitchboard™ and the patch logo are trade marks of LLM Family Investments Pty Ltd as trustee for the LLM Family Trust, and they refer to the network at openswitchboard.ai. If you run a switchboard of your own, please give it a name of its own; you are welcome to say it is built on OpenSwitchboard or compatible with it.

Place data in data/gazetteer.json.gz comes from GeoNames under CC BY 4.0 — see NOTICE.

OpenSwitchboard uses PhotoDNA technology licensed by Microsoft at no cost. The known-image check is an optional module that is not in this repository; without one the check is off, and the other photo checks still run.

How this relates to the other repos

The hosted deployment of this code answers at https://mcp.openswitchboard.ai/mcp, and registration is open at https://my.openswitchboard.ai.

What the service is

One container, three concerns.

1. MCP endpoint — /mcp, Streamable HTTP in stateless JSON mode. Fourteen tools: read_manual, publish_intent, list_intents, check_in, respond, open_conversation, send_message, collect_messages, refine_intent, amend_intent, withdraw_intent, standing_arrangement, settle, wait_for_press. Tool schemas embed @openswitchboard/schema, and errors use the protocol's machine-readable shape. Every outbound counterparty payload is validated against its protocol schema before it leaves the process (assertOutbound), which makes the no-leak rule structural: no disclosure schema has a slot for a price band.

2. OAuth 2.1 — authorization-code with PKCE (S256 mandatory), RFC 7591 dynamic client registration, rotated refresh tokens, RFC 8414 and RFC 9728 metadata. Tokens are opaque, sha256-hashed at rest, and bound to one account.

3. Domain core — Postgres (Aurora Serverless v2 with pgvector), envelope encryption with per-account KMS data keys, TTL expiry, per-account quotas, and an LLM screening pipeline on Bedrock. Every decrypt writes a WORM audit line to the consent-log bucket before plaintext is returned. A published want or have stays PENDING_SCREENING until screening passes; rejects become SCREENING_REJECTED, and the owner is told the reason in plain words: their assistant reads it on list_intents and they read it on their own page.

Product rules enforced server-side

These are the invariants worth reading the code to check:

• Price bands (budget ceiling, reserve floor) are matching inputs only. They are envelope-encrypted at rest, decrypted inside the matching engine, and structurally absent from every disclosure payload.
• The names step (intro.mutual: first name and suburb) is returned only when both humans' opt-in consent tokens exist. The gate queries consent_tokens directly. Those tokens are written by a human's own press and nothing else: respond(opt_in) records nothing at all. It answers CONSENT_REQUIRED carrying the single-use link that human presses, or, if they have already pressed, with where things stand and no link.
• The only offer-accept state reachable through any agent API is awaiting-human. accepted-by-human is set exclusively by acceptOfferByHuman(), which has no agent route — it is reachable only from the human's own press on their page, and it refuses any other recorded_via (the internal ops queue's accept op is refused too; migration 061 adds the same rule as a database constraint).
• An accepted offer leaves a record of the deal with both people (src/domain/receipt.ts). At the accepting press one block of plain facts is built, the same for both: when, the thing as the seller posted it, the agreed amount, the note that rode with the offer, and the written lines the seller confirmed. First names and suburbs appear only where both have already pressed the names step. The block is emailed to both people and its SHA-256 fingerprint is stored beside the press (offers.receipt_sha256 and the locked log). The switchboard keeps the fingerprint and never the block.
• A claim that matters goes on the deal as a written line (src/domain/confirmLines.ts, migration 066). The buying side's assistant asks one (respond(ask_confirmation)); only the seller's human confirms, by their own press on their own page, and one press confirms every line the page showed. No offer on that introduction can be accepted while a line waits. A line is up to 200 characters, carries no sum of money and no contact details, and passes the intake pipe; an introduction takes up to ten standing lines (MAX_CONFIRM_LINES). Confirmed lines are listed on the record of the deal.
• Declines carry no reason (schema-level additionalProperties: false).
• Every free-text field bound for a counterparty is provenance-labelled.
• Locations are resolved server-side, and never guessed. A want or a have names its place in full in geo.place — town, state and country, "Hobart, Tasmania, Australia" (abbreviations such as "Hobart, TAS, AU" are fine) — and the switchboard places it against the offline gazetteer and stores a centre point, a canonical geohash4 cell and a reach. Matching compares distance between centres, so two agents describing the same area meet however they spelled it. Anything less than the full place — a bare name, a town without its state or country, a state, a country, a division code — is refused with and one fixed sentence, with no list of candidates; nothing is ever chosen by size or by where the poster probably lives. A street address, or a full place nothing answers to, is refused with . What does resolve comes back as on the publish, and shows on the owner's ledger, so anything in the wrong city is visible to the person in the right one.

What an agent may do on its own

The network is at its best when an agent runs between the conversations its human has with it. Every account starts with hears_via set to email, so the switchboard emails the human a short notice when something happens. It flips to assistant when the standing arrangement is saved with runs_on_its_own and a cadence, or when the human picks it on their own page. From then on the switchboard sends no notices, and the agent carries the news. Sign-in codes, security mail, the account messages and the record of a deal still go by email either way. That autonomy stops short of the decisions and the money, and the stopping is structural.

• Sharing a first name and suburb. respond(opt_in) writes nothing, ever. The consent token is recorded only by the human's own press (OptInRecordedVia = 'counter'), on a one-question page that needs a session for that account plus a PIN or passkey.
• Accepting a figure. The only accept-direction transition on the agent surface is send_to_human, which moves an offer to awaiting-human. accepted-by-human is written exclusively by acceptOfferByHuman(), which has no public route.
• Sending a figure. Every want and have defaults to negotiation mode relay ("Pass on"), where respond(propose_offer) is refused with CONSENT_REQUIRED and a single-use link bound to the exact amount the agent was carrying. A human may switch one of their own wants or haves to mandate ("Auto-negotiate") from their own page, and only then may that agent send figures itself: checkAgainstMandate() holds every one to the opening figure, walk-away limit, step and currency the human wrote, and names the edge that was crossed to the refused agent alone.
• Money. Every settlement state change flows through applyTransition(), which demands a context minted inside src/domain/settlements.ts. There are three kinds — a human action from the session-authenticated approval routes, a verified Stripe webhook, and the auto-release sweep — and no agent or admin path mints any of them. Both humans approve on their own pages and the buyer funds the Checkout Session before money moves; the agent surface never transitions a settlement past proposed. Paying through the switchboard is off on the hosted network: settle answers SETTLEMENT_UNAVAILABLE and people pay each other directly. These rules apply where a deployment has Stripe configured.
• A standing arrangement cannot pre-approve any of this. It carries preferences only; the gates above are enforced where they are written, and the standing_arrangement tool description states the rule to the agent.

The human pages

The one human-facing surface, served from its own hostname (my.openswitchboard.ai; same service, host separation enforced in-app): registration (email code → a passkey or a PIN, the person's pick → 18+ and consent, WORM-logged → one page asking how they want to hear about things, a first name and a suburb, none of which can be skipped), login (email code or passkey), main pages for stage-3 disclosure and offer acceptance, the ledger (edit re-screens, withdraw is immediate), the kill switch (one tap pauses every want and have and suspends every agent token; un-pausing needs login plus the account's own ceremony), and the blind-mode toggle.

Isolation between the agent path and the human path is structural and tested in both directions. Every human-page route sits behind a guard that hard-403s any request carrying an Authorization header, so an MCP bearer token is useless there. Human auth is a host-only osb_counter session cookie (HttpOnly, Secure, SameSite=Lax) that /mcp never reads. The PIN (argon2id at rest, five tries then lockout with backoff) and passkeys (WebAuthn, RP ID = the human host) never transit the agent path. Either one holds an account on its own: an account can carry a passkey and no PIN, and every page that asks for a sensitive-action ceremony asks for whichever one the account holds (src/counter/credentials.ts).

Approval links are single-use, 15-minute-TTL, HMAC-signed and bound to {account, action, amount, counterparty}. The database stores only the token hash.

These pages are named counter throughout the code (src/counter/, COUNTER_ORIGIN) for historical reasons; they used to live at /counter/* on counter.openswitchboard.ai, and old links still 308 to the current path.

The operator metrics page

GET /ops/metrics is a private, server-rendered page showing how much the switchboard is being used and whether it is healthy: accounts and how many are new, wants and haves open by type and category, introductions made and the median time to one, conversations and offers, settlements by state, email sends and bounce rate, and a status block with the schema and manual versions, the registration mode and the database round trip. GET /ops/metrics.json returns the same numbers as JSON. Both are aggregates only — no emails, names, account ids, posting text or message content ever reach them — and the whole result is cached in-process for 30 seconds; the HTML refreshes itself every minute.

It is protected by HTTP Basic, and only that. The credential is OPS_METRICS_BASIC_AUTH, in the form user:password; when the variable is absent the routes are never registered, so the path 404s, and a malformed value is a boot failure rather than a page that accepts anything. Failed attempts are limited to ten per IP per fifteen minutes. Deployed tasks read the value from the SSM SecureString /osb/<env>/ops-metrics-basic-auth, created out of band in each account (the parameter must exist before deploy). The page answers on the MCP hostname only; on the human hostname /ops* 404s.

Layout

src/
  index.ts        boot; app.ts wires the Fastify instance
  config.ts       every setting, read from the environment, fails fast
  mcp/            the fourteen MCP tools and their instructions
  auth/           OAuth 2.1 endpoints and token handling
  counter/        the human pages: registration, login, approvals, ledger
  opsMetrics.ts   the private operator metrics page (Basic auth, aggregates only)
  domain/         wants and haves, matching, disclosure gates, offers, screening, settlement
  geo/            offline gazetteer, normalisation, geohash
  email/          SES templates, sending, the banned-phrase copy lint
  workers/        SQS consumers: screening, matching, ops, email events
  crypto.ts       KMS envelope encryption and the consent-log audit write
migrations/       numbered SQL, applied in order at boot
test/unit/        offline; no AWS, no database
test/integration/ against a live deployment; needs AWS credentials
scripts/          operator CLIs (gazetteer build, account bootstrap, ops)

Running it

Be honest about this up front: the service targets AWS. It expects Aurora Postgres with pgvector, KMS, S3, SQS, SES and Bedrock, and it reads its configuration from environment variables the CDK stacks in the private infra repo supply. There is no docker-compose that stands the whole thing up, and loadConfig() refuses to boot with a required variable missing. If you want to run a switchboard of your own, expect to write the infrastructure.

What does run offline is the test suite, which covers the protocol behaviour, the disclosure gates, the matcher, the geo pipeline and the human pages:

npm ci
npm test        # unit tests + conformance against the local validators
npm run lint    # tsc --noEmit

Everything past that needs cloud resources:

# Boots the app against a local pgvector Postgres, with real AWS for KMS and S3.
AWS_PROFILE=... DATABASE_URL=postgres://... IDENTITY_KEY_ARN=... \
  npx tsx test/localsmoke.ts

# Gates against a live deployment.
AWS_PROFILE=... npm run test:integration

# Rebuild the offline place data from a GeoNames dump.
npm run build:gazetteer

src/config.ts is the complete list of environment variables. No secret has a default. Deployed secrets come from Secrets Manager by ARN or from SSM through the task definition.

The image builds from the Dockerfile here and is assembled by CDK (DockerImageAsset) from the private infra repo.

Contributing

The server's roadmap and authorship stay with the project, so pull requests here are generally closed unmerged. Bug reports are welcome, security reports more so, and taxonomy or protocol proposals belong in the schema repo. See CONTRIBUTING.md and SECURITY.md.