@electric-sql/client 1.5.11 → 1.5.12

package/skills/electric-postgres-security/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: electric-postgres-security
+description: >
+  Pre-deploy security checklist for Postgres with Electric. Checks REPLICATION
+  role, SELECT grants, CREATE on database, table ownership, REPLICA IDENTITY
+  FULL on all synced tables, publication management (auto vs manual with
+  ELECTRIC_MANUAL_TABLE_PUBLISHING), connection pooler exclusion for
+  DATABASE_URL (use direct connection), and ELECTRIC_POOLED_DATABASE_URL
+  for pooled queries. Load before deploying Electric to production or when
+  diagnosing Postgres permission errors.
+type: security
+library: electric
+library_version: '1.5.10'
+requires:
+  - electric-proxy-auth
+sources:
+  - 'electric-sql/electric:website/docs/guides/postgres-permissions.md'
+  - 'electric-sql/electric:website/docs/guides/troubleshooting.md'
+  - 'electric-sql/electric:website/docs/guides/deployment.md'
+---
+
+This skill builds on electric-proxy-auth. Read it first for proxy security patterns.
+
+# Electric — Postgres Security Checklist
+
+Run through each section before deploying Electric to production.
+
+## User Permission Checks
+
+### Check: Electric user has REPLICATION role
+
+Expected:
+
+```sql
+SELECT rolreplication FROM pg_roles WHERE rolname = 'electric_user';
+-- Should return: true
+```
+
+Fail condition: `rolreplication = false` or user does not exist.
+Fix: `ALTER ROLE electric_user WITH REPLICATION;`
+
+### Check: Electric user has SELECT on synced tables
+
+Expected:
+
+```sql
+SELECT has_table_privilege('electric_user', 'todos', 'SELECT');
+-- Should return: true
+```
+
+Fail condition: Returns `false`.
+Fix: `GRANT SELECT ON todos TO electric_user;` or `GRANT SELECT ON ALL TABLES IN SCHEMA public TO electric_user;`
+
+### Check: Electric user has CREATE on database
+
+Expected:
+
+```sql
+SELECT has_database_privilege('electric_user', current_database(), 'CREATE');
+-- Should return: true (unless using manual publishing mode)
+```
+
+Fail condition: Returns `false` and not using `ELECTRIC_MANUAL_TABLE_PUBLISHING=true`.
+Fix: `GRANT CREATE ON DATABASE mydb TO electric_user;`
+
+## Table Configuration Checks
+
+### Check: REPLICA IDENTITY FULL on all synced tables
+
+Expected:
+
+```sql
+SELECT relname, relreplident
+FROM pg_class
+WHERE relname IN ('todos', 'users')
+  AND relreplident = 'f';  -- 'f' = FULL
+```
+
+Fail condition: `relreplident` is `'d'` (default) or `'n'` (nothing).
+Fix: `ALTER TABLE todos REPLICA IDENTITY FULL;`
+
+### Check: Tables are in the Electric publication
+
+Expected:
+
+```sql
+SELECT tablename FROM pg_publication_tables
+WHERE pubname = 'electric_publication_default';
+```
+
+Fail condition: Synced tables missing from the list.
+Fix (manual mode): `ALTER PUBLICATION electric_publication_default ADD TABLE todos;`
+
+## Connection Checks
+
+### Check: DATABASE_URL uses direct connection (not pooler)
+
+Expected:
+
+```
+DATABASE_URL=postgres://user:pass@db-host:5432/mydb
+```
+
+Fail condition: URL points to a connection pooler (e.g., PgBouncer on port 6432, Supabase pooler).
+Fix: Use direct Postgres connection for `DATABASE_URL`. Set `ELECTRIC_POOLED_DATABASE_URL` separately for pooled queries.
+
+### Check: wal_level is set to logical
+
+Expected:
+
+```sql
+SHOW wal_level;
+-- Should return: logical
+```
+
+Fail condition: Returns `replica` or `minimal`.
+Fix: Set `wal_level = logical` in `postgresql.conf` and restart Postgres.
+
+## Common Security Mistakes
+
+### CRITICAL Using connection pooler for DATABASE_URL
+
+Wrong:
+
+```sh
+DATABASE_URL=postgres://user:pass@pooler.example.com:6432/mydb
+```
+
+Correct:
+
+```sh
+DATABASE_URL=postgres://user:pass@db.example.com:5432/mydb
+ELECTRIC_POOLED_DATABASE_URL=postgres://user:pass@pooler.example.com:6432/mydb
+```
+
+Connection poolers (except PgBouncer 1.23+) do not support logical replication. Electric must connect directly to Postgres for its replication slot.
+
+Source: `website/docs/guides/deployment.md:91`
+
+### HIGH Missing REPLICA IDENTITY FULL on tables
+
+Wrong:
+
+```sql
+CREATE TABLE todos (id UUID PRIMARY KEY, text TEXT);
+-- Replica identity defaults to 'default' (PK only)
+```
+
+Correct:
+
+```sql
+CREATE TABLE todos (id UUID PRIMARY KEY, text TEXT);
+ALTER TABLE todos REPLICA IDENTITY FULL;
+```
+
+Without `REPLICA IDENTITY FULL`, Electric cannot stream the full row on updates and deletes. Updates may be missing non-PK columns.
+
+Source: `website/docs/guides/troubleshooting.md:373`
+
+### HIGH Electric user without REPLICATION role
+
+Wrong:
+
+```sql
+CREATE USER electric_user WITH PASSWORD 'secret';
+```
+
+Correct:
+
+```sql
+CREATE USER electric_user WITH PASSWORD 'secret' REPLICATION;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO electric_user;
+```
+
+Electric uses logical replication and requires the `REPLICATION` role on the database user.
+
+Source: `website/docs/guides/postgres-permissions.md`
+
+## Pre-Deploy Summary
+
+- [ ] Electric user has `REPLICATION` role
+- [ ] Electric user has `SELECT` on all synced tables
+- [ ] Electric user has `CREATE` on database (or manual publishing configured)
+- [ ] All synced tables have `REPLICA IDENTITY FULL`
+- [ ] All synced tables are in the Electric publication
+- [ ] `DATABASE_URL` uses direct Postgres connection (not pooler)
+- [ ] `wal_level = logical` in Postgres config
+- [ ] `ELECTRIC_SECRET` is set (not using `ELECTRIC_INSECURE=true`)
+- [ ] Secrets are injected server-side only (never in client bundle)
+
+See also: electric-proxy-auth/SKILL.md — Proxy injects secrets that Postgres security enforces.
+See also: electric-deployment/SKILL.md — Deployment requires correct Postgres configuration.
+
+## Version
+
+Targets Electric sync service v1.x.

package/skills/electric-proxy-auth/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: electric-proxy-auth
+description: >
+  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,
+  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.
+type: core
+library: electric
+library_version: '1.5.10'
+requires:
+  - electric-shapes
+sources:
+  - 'electric-sql/electric:packages/typescript-client/src/constants.ts'
+  - 'electric-sql/electric:examples/proxy-auth/app/shape-proxy/route.ts'
+  - 'electric-sql/electric:website/docs/guides/auth.md'
+  - 'electric-sql/electric:website/docs/guides/security.md'
+---
+
+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 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.

package/skills/electric-schema-shapes/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: electric-schema-shapes
+description: >
+  Design Postgres schema and Electric shape definitions together for a new
+  feature. Covers single-table shape constraint, cross-table joins using
+  multiple shapes, WHERE clause design for tenant isolation, column selection
+  for bandwidth optimization, replica mode choice (default vs full for
+  old_value), enum casting in WHERE clauses, and txid handshake setup with
+  pg_current_xact_id() for optimistic writes. Load when designing database
+  tables for use with Electric shapes.
+type: core
+library: electric
+library_version: '1.5.10'
+requires:
+  - electric-shapes
+sources:
+  - 'electric-sql/electric:AGENTS.md'
+  - 'electric-sql/electric:website/docs/guides/shapes.md'
+---
+
+This skill builds on electric-shapes. Read it first for ShapeStream configuration.
+
+# Electric — Schema and Shapes
+
+## Setup
+
+Design tables knowing each shape syncs one table. For cross-table data, use multiple shapes with client-side joins.
+
+```sql
+-- Schema designed for Electric shapes
+CREATE TABLE todos (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id UUID NOT NULL,
+  text TEXT NOT NULL,
+  completed BOOLEAN DEFAULT false,
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+ALTER TABLE todos REPLICA IDENTITY FULL;
+```
+
+```ts
+import { ShapeStream } from '@electric-sql/client'
+
+const todoStream = new ShapeStream({
+  url: '/api/todos', // Proxy sets: table=todos, where=org_id=$1
+})
+```
+
+## Core Patterns
+
+### Cross-table data with multiple shapes
+
+```ts
+// Each shape syncs one table — join client-side
+const todoStream = new ShapeStream({ url: '/api/todos' })
+const userStream = new ShapeStream({ url: '/api/users' })
+
+// With TanStack DB, use .join() in live queries:
+// q.from({ todo: todoCollection })
+//   .join({ user: userCollection }, ({ todo, user }) => eq(todo.userId, user.id))
+```
+
+### Choose replica mode
+
+```ts
+// Default: only changed columns sent on update
+const stream = new ShapeStream({ url: '/api/todos' })
+
+// Full: all columns + old_value on updates (more bandwidth, needed for diffs)
+const stream = new ShapeStream({
+  url: '/api/todos',
+  params: { replica: 'full' },
+})
+```
+
+### Backend txid handshake for optimistic writes
+
+Call `pg_current_xact_id()::xid::text` inside the same transaction as your mutation. If you query it outside the transaction, you get a different txid and the client will never reconcile.
+
+```ts
+// API endpoint — txid MUST be in the same transaction as the INSERT
+app.post('/api/todos', async (req, res) => {
+  const client = await pool.connect()
+  try {
+    await client.query('BEGIN')
+    const result = await client.query(
+      'INSERT INTO todos (id, text, org_id) VALUES ($1, $2, $3) RETURNING id',
+      [crypto.randomUUID(), req.body.text, req.body.orgId]
+    )
+    const txResult = await client.query(
+      'SELECT pg_current_xact_id()::xid::text AS txid'
+    )
+    await client.query('COMMIT')
+    // txid accepts number | bigint | `${bigint}`
+    res.json({ id: result.rows[0].id, txid: parseInt(txResult.rows[0].txid) })
+  } finally {
+    client.release()
+  }
+})
+```
+
+```ts
+// Client awaits txid before dropping optimistic state
+await todoCollection.utils.awaitTxId(txid)
+```
+
+## Common Mistakes
+
+### HIGH Designing shapes that span multiple tables
+
+Wrong:
+
+```ts
+const stream = new ShapeStream({
+  url: '/api/data',
+  params: {
+    table: 'todos JOIN users ON todos.user_id = users.id',
+  },
+})
+```
+
+Correct:
+
+```ts
+const todoStream = new ShapeStream({ url: '/api/todos' })
+const userStream = new ShapeStream({ url: '/api/users' })
+```
+
+Shapes are single-table only. Cross-table data requires multiple shapes joined client-side via TanStack DB live queries.
+
+Source: `AGENTS.md:104-105`
+
+### MEDIUM Using enum columns without casting to text in WHERE
+
+Wrong:
+
+```ts
+// Proxy route
+originUrl.searchParams.set('where', "status IN ('active', 'done')")
+```
+
+Correct:
+
+```ts
+originUrl.searchParams.set('where', "status::text IN ('active', 'done')")
+```
+
+Enum types in WHERE clauses require explicit `::text` cast. Without it, the query may fail or return unexpected results.
+
+Source: `packages/sync-service/lib/electric/replication/eval/env/known_functions.ex`
+
+### HIGH Not setting up txid handshake for optimistic writes
+
+Wrong:
+
+```ts
+// Backend: just INSERT, return id
+app.post('/api/todos', async (req, res) => {
+  const result = await db.query(
+    'INSERT INTO todos (text) VALUES ($1) RETURNING id',
+    [req.body.text]
+  )
+  res.json({ id: result.rows[0].id })
+})
+```
+
+Correct:
+
+```ts
+// Backend: INSERT and return txid in same transaction
+app.post('/api/todos', async (req, res) => {
+  const client = await pool.connect()
+  try {
+    await client.query('BEGIN')
+    const result = await client.query(
+      'INSERT INTO todos (text) VALUES ($1) RETURNING id',
+      [req.body.text]
+    )
+    const txResult = await client.query(
+      'SELECT pg_current_xact_id()::xid::text AS txid'
+    )
+    await client.query('COMMIT')
+    res.json({ id: result.rows[0].id, txid: parseInt(txResult.rows[0].txid) })
+  } finally {
+    client.release()
+  }
+})
+```
+
+Without txid, the UI flickers when optimistic state is dropped before the synced version arrives from Electric. The client uses `awaitTxId(txid)` to hold optimistic state until the real data syncs.
+
+Source: `AGENTS.md:116-119`
+
+See also: electric-shapes/SKILL.md — Shapes are immutable; dynamic filters require new ShapeStream instances.
+See also: electric-orm/SKILL.md — Schema design affects both shapes (read) and ORM queries (write).
+
+## Version
+
+Targets @electric-sql/client v1.5.10.