zkShare

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

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

Privacy and security model

The platform is designed around three trust boundaries:

What this means in practice

• Users can 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 through verify_proof.
• Agents can hold and exchange context across sessions or tool boundaries without surfacing the raw values to downstream systems. Sharing produces a single-use, time-bound share_token bound to a recipient agent identifier.
• Businesses integrating 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.md is the canonical reference for the threat model, the trust model summary, vulnerability disclosure, the operator checklist, and third-party LLM exposure controls.

API contract

Authoritative request and response shapes live in types/index.ts and openapi.json.

Model Context Protocol (MCP)

The npm package zkshare-mcp (npm, source packages/zkshare-mcp/) is a stdio MCP server exposing tools (zkshare_store, zkshare_prove, …) that call POST https://zkshare.io/api/v1/context (or your ZKSHARE_API_URL) with ZKSHARE_API_KEY.

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

End users: Node.js ≥ 18, then npx -y zkshare-mcp — no clone. Configure your host (example below).

Contributors: from the repo root pnpm install, then pnpm mcp to run the local package; source is packages/zkshare-mcp/.

Advanced client-sealed store bodies stay on HTTPS/OpenAPI — not via MCP tools.

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

Error codes

Architecture

• Runtime: /api/v1/context is 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 under supabase/migrations/. Tables: api_keys, facts, audit_logs, share_tokens. The facts table stores ciphertext, IV, auth tag, commitment, a vector(1536) embedding, and a client_encrypted flag.
• Search: match_facts(api_key_id, logical_user_id, query_embedding, match_count) is a security definer function with an IVFFlat index. It returns server-sealed rows only. Updating the function's row type requires DROP 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.ts redirects unauthenticated visitors away from /dashboard.
  • HTTP API: x-api-key header. 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 from anon and authenticated roles. The application uses the Supabase service role server-side only.
• Rate limiting: Upstash Redis (sliding window) when configured; an in-process fallback is used in local development.
• Encryption keys:
  • 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.

Repository layout

Local development