skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
neondatabase/electric56 installs

electric-proxy-auth

Set 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, Bun fetch concurrency cap (BUN_CONFIG_MAX_HTTP_REQUESTS default 256), 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.

How do I install this agent skill?

npx skills add https://github.com/neondatabase/electric --skill electric-proxy-auth
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides comprehensive security guidelines and implementation patterns for building a secure server-side proxy for Electric SQL applications. It specifically addresses and mitigates risks such as SQL injection, unauthorized parameter manipulation, and credential exposure by demonstrating correct usage of whitelisting and server-side environment variables.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

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 Bun fetch concurrency cap (256) bottlenecks the proxy under load

Wrong:

bun run proxy.ts

Correct:

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:

// 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.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/neondatabase/electric/electric-proxy-auth">View electric-proxy-auth on skillZs</a>