feat(middleware): surface table-grants hint on 42501 in withPostgres

Append the caller-role grants hint to permission-denied errors and document
the grants requirement in the withPostgres JSDoc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mandarini

src/middleware/postgres/index.test.ts

@@ -120,4 +120,45 @@ describe('withPostgres', () => {
     expect(h.issued).toContain('rollback')
     expect(h.release).toHaveBeenCalled()
   })
+
+  it('appends a grants hint to permission-denied (42501) errors', async () => {
+    // begin, set_config, set role succeed; the user query hits missing grants.
+    h.clientQuery
+      .mockImplementationOnce(async (t: string) => {
+        h.issued.push(t)
+        return { rows: [] }
+      })
+      .mockImplementationOnce(async (t: string) => {
+        h.issued.push(t)
+        return { rows: [] }
+      })
+      .mockImplementationOnce(async (t: string) => {
+        h.issued.push(t)
+        return { rows: [] }
+      })
+      .mockImplementationOnce(async () => {
+        const err = new Error('permission denied for table notes') as Error & {
+          code: string
+        }
+        err.code = '42501'
+        throw err
+      })
+
+    const handler = withPostgres(async (_req, ctx) => {
+      await ctx.postgres.query('select * from notes')
+      return Response.json({ ok: true })
+    })
+
+    await expect(
+      handler(new Request('http://localhost'), {
+        _runtime: runtime,
+        jwtClaims: { role: 'authenticated' },
+      }),
+    ).rejects.toThrow(
+      /permission denied for table notes \(RLS-scoped queries run as the caller's role 'authenticated'/,
+    )
+
+    expect(h.issued).toContain('rollback')
+    expect(h.release).toHaveBeenCalled()
+  })
 })

src/middleware/postgres/index.ts

@@ -71,6 +71,11 @@ export interface WithPostgresConfig {
  * Standalone (no `withSupabase`), pair it with `withClaims` so `ctx.jwtClaims`
  * is present before it runs.
  *
+ * > **Table grants.** Queries run as `authenticated` or `anon`, so those
+ * > roles need explicit table privileges (e.g. `grant select, insert on
+ * > <table> to authenticated`) in addition to RLS policies. A missing grant
+ * > fails with `permission denied` (SQLSTATE 42501) before RLS is consulted.
+ *
  * > **Runtime note.** `pg` needs raw TCP, so this runs on Node/Deno (including
  * > the Supabase Edge runtime), **not** on Workers-style isolates.
  *
@@ -114,6 +119,10 @@ export const withPostgres = defineMiddleware<
           return res.rows as T[]
         } catch (e) {
           await client.query('rollback')
+          // 42501 insufficient_privilege: the role lacks table grants.
+          if (e instanceof Error && (e as { code?: string }).code === '42501') {
+            e.message += ` (RLS-scoped queries run as the caller's role '${role}' — grant that role the table privileges it needs, e.g. "grant select on <table> to ${role}")`
+          }
           throw e
         } finally {
           client.release()