electric-proxy-auth

This skill builds on electric-shapes. Read it first for ShapeStream configuration. # Electric — Proxy and Auth ## Setup ```ts import { ELECTRIC_PROTOCOL_QUERY_PARAMS } from '@electric-sql/client' // Server route (Next.js App Router example) export async function GET(request: Request) { const url = new URL(request.url) const originUrl = new URL('/v1/shape', process.env.ELECTRIC_URL) // Only forward Electric protocol params — never table/where from client url.searchParams.forEach((value, key) => { if (ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) { originUrl.searchParams.set(key, value) } }) // Server decides shape definition originUrl.searchParams.set('table', 'todos') originUrl.searchParams.set('secret', process.env.ELECTRIC_SOURCE_SECRET!) const response = await fetch(originUrl) const headers = new Headers(response.headers) headers.delete('content-encoding') headers.delete('content-length') return new Response(response.body, { status: response.status, statusText: response.statusText, headers, }) } ``` Client usage: ```ts import { ShapeStream } from '@electric-sql/client' const stream = new ShapeStream({ url: '/api/todos', // Points to your proxy, not Electric directly }) ``` ## Core Patterns ### Tenant isolation with WHERE params ```ts // In proxy route — inject user context server-side const user = await getAuthUser(request) originUrl.searchParams.set('table', 'todos') originUrl.searchParams.set('where', 'org_id = $1') originUrl.searchParams.set('params[1]', user.orgId) ``` ### Auth token refresh on 401 ```ts const stream = new ShapeStream({ url: '/api/todos', headers: { Authorization: async () => `Bearer ${await getToken()}`, }, onError: async (error) => { if (error instanceof FetchError && error.status === 401) { const newToken = await refreshToken() return { headers: { Authorization: `Bearer ${newToken}` } } } return {} }, }) ``` ### CORS configuration for cross-origin proxies ```ts // In proxy response headers headers.set( 'Access-Control-Expose-Headers', 'electric-offset, electric-handle, electric-schema, electric-cursor' ) ``` ### Subset security (AND semantics) Electric combines the main shape WHERE (set in proxy) with subset WHERE (from POST body) using AND. Subsets can only narrow results, never widen them: ```sql -- Main shape: WHERE org_id = $1 (set by proxy) -- Subset: WHERE status = 'active' (from client POST) -- Effective: WHERE org_id = $1 AND status = 'active' ``` Even `WHERE 1=1` in the subset cannot bypass the main shape's WHERE. ## Common Mistakes ### CRITICAL Forwarding all client params to Electric Wrong: ```ts url.searchParams.forEach((value, key) => { originUrl.searchParams.set(key, value) }) ``` Correct: ```ts import { ELECTRIC_PROTOCOL_QUERY_PARAMS } from '@electric-sql/client' url.searchParams.forEach((value, key) => { if (ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) { originUrl.searchParams.set(key, value) } }) originUrl.searchParams.set('table', 'todos') ``` Forwarding all params lets the client control `table`, `where`, and `columns`, accessing any Postgres table. Only forward `ELECTRIC_PROTOCOL_QUERY_PARAMS`. Source: `examples/proxy-auth/app/shape-proxy/route.ts` ### CRITICAL Not deleting content-encoding and content-length headers Wrong: ```ts return new Response(response.body, { status: response.status, headers: response.headers, }) ``` Correct: ```ts const headers = new Headers(response.headers) headers.delete('content-encoding') headers.delete('content-length') return new Response(response.body, { status: response.status, headers }) ``` `fetch()` decompresses the response body but keeps the original `content-encoding` and `content-length` headers, causing browser decoding failures. Source: `examples/proxy-auth/app/shape-proxy/route.ts:49-56` ### CRITICAL Exposing ELECTRIC_SECRET or SOURCE_SECRET to browser Wrong: ```ts // Client-side code const url = `/v1/shape?table=todos&secret=${import.meta.env.VITE_ELECTRIC_SOURCE_SECRET}` ``` Correct: ```ts // Server proxy only originUrl.searchParams.set('secret', process.env.ELECTRIC_SOURCE_SECRET!) ``` Bundlers like Vite expose `VITE_*` env vars to client code. The secret must only be injected server-side in the proxy. Source: `AGENTS.md:17-20` ### CRITICAL SQL injection in WHERE clause via string interpolation Wrong: ```ts originUrl.searchParams.set('where', `org_id = '${user.orgId}'`) ``` Correct: ```ts originUrl.searchParams.set('where', 'org_id = $1') originUrl.searchParams.set('params[1]', user.orgId) ``` String interpolation in WHERE clauses enables SQL injection. Use positional params (`$1`, `$2`). Source: `website/docs/guides/auth.md` ### HIGH Bun fetch concurrency cap (256) bottlenecks the proxy under load Wrong: ```sh bun run proxy.ts ``` Correct: ```sh BUN_CONFIG_MAX_HTTP_REQUESTS=4096 bun run proxy.ts ``` Bun caps simultaneous `fetch()` calls at **256 per process** by default. Excess requests queue silently — the proxy keeps accepting inbound connections but upstream calls to Electric stall, surfacing as latency spikes rather than errors. Raise `BUN_CONFIG_MAX_HTTP_REQUESTS` (max 65,336) to match your expected concurrent shape requests. Node and Deno do not impose this cap. Source: https://bun.com/docs/runtime/networking/fetch ### HIGH Not exposing Electric response headers via CORS Wrong: ```ts // No CORS header configuration — browser strips custom headers return new Response(response.body, { headers }) ``` Correct: ```ts headers.set( 'Access-Control-Expose-Headers', 'electric-offset, electric-handle, electric-schema, electric-cursor' ) return new Response(response.body, { headers }) ``` The client throws `MissingHeadersError` if Electric response headers are stripped by CORS. Expose `electric-offset`, `electric-handle`, `electric-schema`, and `electric-cursor`. Source: `packages/typescript-client/src/error.ts:109-118` ### CRITICAL Calling Electric directly from production client Wrong: ```ts new ShapeStream({ url: 'https://my-electric.example.com/v1/shape', params: { table: 'todos' }, }) ``` Correct: ```ts new ShapeStream({ url: '/api/todos', // Your proxy route }) ``` Electric's HTTP API is public by default with no auth. Always proxy through your server so the server controls shape definitions and injects secrets. Source: `AGENTS.md:19-20` See also: electric-shapes/SKILL.md — Shape URLs must point to proxy routes, not directly to Electric. See also: electric-deployment/SKILL.md — Production requires ELECTRIC_SECRET and proxy; dev uses ELECTRIC_INSECURE=true. See also: electric-postgres-security/SKILL.md — Proxy injects secrets that Postgres security enforces. ## Version Targets @electric-sql/client v1.5.10.