electric-proxy-auth
coreSet up a server-side proxy to forward Electric shape requests securely. Covers ELECTRIC_PROTOCOL_QUERY_PARAMS forwarding, server-side shape definition (table, where, params), content-encoding/content-length header cleanup, CORS configuration for electric-offset/electric-handle/ electric-schema/electric-cursor headers, auth token injection, ELECTRIC_SECRET/SOURCE_SECRET server-side only, tenant isolation via WHERE positional params, onError 401 token refresh, and subset security (AND semantics). Load when creating proxy routes, adding auth, or configuring CORS for Electric.
This skill builds on electric-shapes. Read it first for ShapeStream configuration.
Electric — Proxy and Auth
Setup
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:
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
// 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
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
// 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:
-- 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:
url.searchParams.forEach((value, key) => {
originUrl.searchParams.set(key, value)
})
Correct:
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:
return new Response(response.body, {
status: response.status,
headers: response.headers,
})
Correct:
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:
// Client-side code
const url = `/v1/shape?table=todos&secret=${import.meta.env.VITE_ELECTRIC_SOURCE_SECRET}`
Correct:
// 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:
originUrl.searchParams.set('where', `org_id = '${user.orgId}'`)
Correct:
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 Not exposing Electric response headers via CORS
Wrong:
// No CORS header configuration — browser strips custom headers
return new Response(response.body, { headers })
Correct:
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:
new ShapeStream({
url: 'https://my-electric.example.com/v1/shape',
params: { table: 'todos' },
})
Correct:
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.