ZKshare

Privacy-oriented context API for users, AI agents, and back-office systems. A single HTTP entrypoint (POST /api/v1/context) handlesencrypted fact storage,commitment-based proof envelopes,semantic search over encrypted data,end-to-end-encrypted (client-sealed) facts, and aisolated sandbox executionfor sensitive computations. The implementation is a Next.js (App Router) application backed by PostgreSQL withpgvector.

This document is for developers integrating against the API and operators self-hosting the service. It isnota marketing brochure — pricing tiers, dashboards, and billing are optional layers defined separately in the application code.

The platform is designed around three trust boundaries:

- Userscan prove a property of a personal fact (for example, "the user prefers beach trips") to a third party without exposing the underlying value. The third party verifies the envelope throughverify_proof.
- Agentscan hold and exchange context across sessions or tool boundaries without surfacing the raw values to downstream systems. Sharing produces a single-use, time-boundshare_tokenbound to a recipient agent identifier.
- Businessesintegrating the API can offer privacy guarantees that are technical, not contractual — RLS denies direct table access, the encryption key is server-only, the proof HMAC secret is server-only, and the client-sealed path lets sensitive data stay outside the operator's reach entirely.

SECURITY.mdis the canonical reference for the threat model, the trust model summary, vulnerability disclosure, the operator checklist, and third-party LLM exposure controls.

Authoritative request and response shapes live intypes/index.tsandopenapi.json.

The npm packagezkshare-mcp(npm, sourcepackages/zkshare-mcp/) is astdio MCP serverexposing tools (zkshare_store,zkshare_prove, …) that callPOST https://zkshare.io/api/v1/context(or yourZKSHARE_API_URL) withZKSHARE_API_KEY.

Official MCP Registrycanonical name:io.github.sp0oby/zkshare—registry lookup·About the MCP Registry(discovery metadata; runnable package remains on npm).

// ~/.cursor/mcp.json { "mcpServers": { "zkshare": { "command": "npx", "args": ["-y", "zkshare-mcp"], "env": { "ZKSHARE_API_KEY": "zk_live_…", "ZKSHARE_API_URL": "https://zkshare.io" } } } }

- Runtime:/api/v1/contextis a Node.js route handler (not Edge) so AES-256-GCM, scrypt key derivation, and the Supabase service-role client behave deterministically.
- Persistence:PostgreSQL with extensions and tables managed by versioned migrations undersupabase/migrations/. Tables:api_keys,facts,audit_logs,share_tokens. Thefactstable stores ciphertext, IV, auth tag, commitment, avector(1536)embedding, and aclient_encryptedflag.
- Search:match_facts(api_key_id, logical_user_id, query_embedding, match_count)is asecurity definerfunction with an IVFFlat index. It returns server-sealed rows only. Updating the function's row type requiresDROP FUNCTION ... CASCADE-style replacement (a PostgreSQL constraint) — the migrations handle this explicitly.
- Authentication and authorization:

- End-user dashboard: Supabase Auth magic-link sign-in.middleware.tsredirects unauthenticated visitors away from/dashboard.
- HTTP API:x-api-keyheader. Keys are stored as SHA-256 hashes; only the prefix is shown in the dashboard. Rotating a key requires generating a new one — plaintext is never persisted.
- Database access: RLS denies all direct access fromanonandauthenticatedroles. The application uses the Supabaseservice roleserver-side only.

- ZKSHARE_ENCRYPTION_SECRET— server-side AES-256-GCM master secret (scrypt-derived; minimum 32 characters).
- ZKSHARE_PROOF_SECRET— HMAC secret for commitments and proof envelopes (minimum 16 characters).
- ZKSHARE_ENCLAVE_JWT_SECRET— HS256 secret for sandbox attestations (minimum 32 characters).
- All three are required for the relevant code paths. The application throws on startup if any are missing or too short.

pnpm install cp .env.local.example .env.local # Fill the Supabase, ZKSHARE_, and (optionally) LLM, Upstash, and Stripe values. # Defaults for LLM model slugs live in lib/llm-client.ts. pnpm dev

curl -sS -X POST http://localhost:3000/api/v1/context \ -H "x-api-key: zk_live_..." \ -H "Content-Type: application/json" \ -d '{"operation":"store","user_id":"user_123","fact_key":"example","value":"hello"}' curl -sS -X POST http://localhost:3000/api/v1/context \ -H "x-api-key: zk_live_..." \ -H "Content-Type: application/json" \ -d '{"operation":"prove","user_id":"user_123","fact_key":"example","query":"does the fact say hello?"}'

curl -sS -X POST http://localhost:3000/api/v1/context \ -H "x-api-key: zk_live_..." \ -H "Content-Type: application/json" \ -d '{"operation":"verify_proof","proof":"<base64url envelope from the prove response>"}'

SeeCONTRIBUTING.mdfor the local-development checklist, the verification commands required before opening a pull request, and how to flag changes that touch the data plane or cryptographic paths.

Pleasedo notopen a public issue for security vulnerabilities. The disclosure process and contact channels are documented inSECURITY.md.

MCP server for Christian scholarship and research — scripture, Greek/Hebrew word data, cross-references, patristic texts, and semantic search,