@avelonjs/supabase 0.1.0

package/src/identity/local-auth.ts

@@ -0,0 +1,209 @@
+import { createHash, randomUUID } from 'node:crypto'
+
+interface LocalUser {
+  id: string
+  email: string
+  passwordHash: string
+}
+
+interface LocalSession {
+  id: string
+  userId: string
+  accessToken: string
+  refreshToken: string
+  expiresAt: number
+}
+
+interface LocalReset {
+  email: string
+  token: string
+}
+
+function hashPassword(password: string): string {
+  return createHash('sha256').update(password).digest('hex')
+}
+
+/**
+ * Minimal GoTrue-shaped Auth HTTP server for live identity conformance.
+ *
+ * Real deployments point the same driver at Supabase Auth; this server exists so cookie and
+ * password flows can be verified without the full Docker stack.
+ */
+export class LocalAuthServer {
+  readonly #users = new Map<string, LocalUser>()
+  readonly #sessions = new Map<string, LocalSession>()
+  readonly #resets = new Map<string, LocalReset>()
+  #server: ReturnType<typeof Bun.serve> | undefined
+  #url = ''
+
+  /** Base Auth URL, e.g. `http://127.0.0.1:54321/auth/v1`. */
+  get url(): string {
+    return this.#url
+  }
+
+  /** Starts the server on an ephemeral port. */
+  async start(): Promise<string> {
+    const self = this
+    this.#server = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        return self.#handle(request)
+      },
+    })
+    this.#url = `http://127.0.0.1:${this.#server.port}/auth/v1`
+    return this.#url
+  }
+
+  /** Clears users, sessions, and reset tokens without restarting the listener. */
+  reset(): void {
+    this.#users.clear()
+    this.#sessions.clear()
+    this.#resets.clear()
+  }
+
+  /** Stops the server and clears fixture state. */
+  async stop(): Promise<void> {
+    this.#server?.stop(true)
+    this.#server = undefined
+    this.reset()
+  }
+
+  /** Returns the recovery token issued for an email, if any. */
+  recoveryToken(email: string): string | undefined {
+    return [...this.#resets.values()].find((entry) => entry.email === email)?.token
+  }
+
+  async #handle(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    const path = url.pathname.replace(/^\/auth\/v1/, '')
+
+    if (request.method === 'POST' && path === '/signup') {
+      const body = (await request.json()) as { email?: string; password?: string }
+      if (!body.email || !body.password) return json({ error: 'invalid' }, 400)
+      if ([...this.#users.values()].some((user) => user.email === body.email)) {
+        return json({ error: 'user_exists' }, 422)
+      }
+      const user: LocalUser = {
+        id: randomUUID(),
+        email: body.email,
+        passwordHash: hashPassword(body.password),
+      }
+      this.#users.set(user.id, user)
+      const session = this.#createSession(user.id)
+      return json({
+        user: { id: user.id, email: user.email },
+        access_token: session.accessToken,
+        refresh_token: session.refreshToken,
+        expires_in: 3600,
+        token_type: 'bearer',
+      })
+    }
+
+    if (request.method === 'POST' && path === '/token' && url.searchParams.get('grant_type') === 'password') {
+      const body = (await request.json()) as { email?: string; password?: string }
+      const user = [...this.#users.values()].find((entry) => entry.email === body.email)
+      if (!user || user.passwordHash !== hashPassword(body.password ?? '')) {
+        return json({ error: 'invalid_grant', error_description: 'Invalid login credentials' }, 400)
+      }
+      const session = this.#createSession(user.id)
+      return json({
+        user: { id: user.id, email: user.email },
+        access_token: session.accessToken,
+        refresh_token: session.refreshToken,
+        expires_in: 3600,
+        token_type: 'bearer',
+      })
+    }
+
+    if (request.method === 'GET' && path === '/user') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return json({ error: 'not_authenticated' }, 401)
+      const user = this.#users.get(session.userId)
+      if (!user) return json({ error: 'not_authenticated' }, 401)
+      return json({ id: user.id, email: user.email })
+    }
+
+    if (request.method === 'POST' && path === '/logout') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return json({ error: 'not_authenticated' }, 401)
+      this.#sessions.delete(session.accessToken)
+      return new Response(null, { status: 204 })
+    }
+
+    if (request.method === 'PUT' && path === '/user') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return json({ error: 'not_authenticated' }, 401)
+      const user = this.#users.get(session.userId)
+      if (!user) return json({ error: 'not_authenticated' }, 401)
+      const body = (await request.json()) as { password?: string }
+      if (!body.password) return json({ error: 'invalid' }, 400)
+      user.passwordHash = hashPassword(body.password)
+      return json({ id: user.id, email: user.email })
+    }
+
+    if (request.method === 'POST' && path === '/recover') {
+      const body = (await request.json()) as { email?: string }
+      if (body.email) {
+        const token = `assay-reset-${randomUUID()}`
+        this.#resets.set(token, { email: body.email, token })
+      }
+      return json({})
+    }
+
+    if (request.method === 'PUT' && path === '/user' && url.searchParams.has('token')) {
+      return json({ error: 'use verify' }, 400)
+    }
+
+    if (request.method === 'POST' && path === '/verify') {
+      const body = (await request.json()) as {
+        type?: string
+        token?: string
+        password?: string
+      }
+      if (body.type === 'recovery' && body.token && body.password) {
+        const reset = this.#resets.get(body.token)
+        if (!reset) return json({ error: 'invalid_token' }, 400)
+        const user = [...this.#users.values()].find((entry) => entry.email === reset.email)
+        if (!user) return json({ error: 'invalid_token' }, 400)
+        user.passwordHash = hashPassword(body.password)
+        this.#resets.delete(body.token)
+        return json({ user: { id: user.id, email: user.email } })
+      }
+      return json({ error: 'invalid' }, 400)
+    }
+
+    if (request.method === 'POST' && path === '/otp') {
+      return json({})
+    }
+
+    return json({ error: 'not_found' }, 404)
+  }
+
+  #createSession(userId: string): LocalSession {
+    const session: LocalSession = {
+      id: randomUUID(),
+      userId,
+      accessToken: randomUUID(),
+      refreshToken: randomUUID(),
+      expiresAt: Date.now() + 60 * 60 * 1000,
+    }
+    this.#sessions.set(session.accessToken, session)
+    return session
+  }
+
+  #sessionFromAuth(request: Request): LocalSession | undefined {
+    const header = request.headers.get('authorization')
+    if (header === null || !header.startsWith('Bearer ')) return undefined
+    const token = header.slice('Bearer '.length)
+    const session = this.#sessions.get(token)
+    if (session === undefined || session.expiresAt <= Date.now()) return undefined
+    return session
+  }
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}

package/src/identity/types.ts

@@ -0,0 +1,19 @@
+/** Actor returned by the Supabase identity driver. */
+export interface SupabaseActor {
+  /** Stable actor identifier. */
+  id: string
+  /** Sign-in email address. */
+  email: string
+}
+
+/** Session returned by the Supabase identity driver. */
+export interface SupabaseSession {
+  /** Stable session identifier. */
+  id: string
+  /** Access token retained for subsequent Auth API calls. */
+  accessToken: string
+  /** Refresh token used for rotation when present. */
+  refreshToken: string
+  /** Time after which the access token should be treated as expired. */
+  expiresAt: Date
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './database'
+export * from './identity'
+export * from './queue'
+export * from './social'
+export * from './storage'
+export * from './tokens'

package/src/queue/driver.ts

@@ -0,0 +1,268 @@
+import { SQL } from 'bun'
+import type {
+  DeadLetterQueueSurface,
+  DelayedQueueSurface,
+  FailedQueueJob,
+  QueueDriver,
+  QueueJob,
+  QueueReceipt,
+  RetryQueueSurface,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Supabase queue driver. */
+export const supabaseQueueCapabilities = {
+  delayed: true,
+  retries: true,
+  deadLetter: true,
+} as const
+
+/** Construction options for {@link createSupabaseQueue}. */
+export interface SupabaseQueueOptions {
+  /** Postgres URL used to persist jobs. */
+  url?: string
+  /** Configured queue connection name. */
+  instance?: string
+  /** Attempts before a job is dead-lettered. */
+  maxTries?: number
+}
+
+interface JobRow {
+  id: string
+  queue: string | null
+  name: string
+  payload: unknown
+  attempt: number
+  available_at: Date | string
+}
+
+interface FailedRow extends JobRow {
+  error: string
+  failed_at: Date | string
+}
+
+function defaultUrl(): string {
+  return (
+    process.env.SUPABASE_DB_URL ??
+    process.env.POSTGRES_URL ??
+    process.env.DATABASE_URL ??
+    'postgresql://postgres:avelon@127.0.0.1:5432/avelon_supabase'
+  )
+}
+
+function asDate(value: Date | string): Date {
+  return value instanceof Date ? value : new Date(value)
+}
+
+function failureMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function toJob(row: JobRow): QueueJob {
+  return {
+    name: row.name,
+    payload: decodePayload(row.payload),
+    ...(row.queue === null ? {} : { queue: row.queue }),
+  }
+}
+
+function decodePayload(value: unknown): unknown {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value) as unknown
+  } catch {
+    return value
+  }
+}
+
+function encodePayload(value: unknown): string {
+  return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS avelon_jobs (
+  id text PRIMARY KEY,
+  queue text,
+  name text NOT NULL,
+  payload jsonb NOT NULL,
+  attempt integer NOT NULL DEFAULT 0,
+  available_at timestamptz NOT NULL,
+  locked_at timestamptz
+);
+CREATE TABLE IF NOT EXISTS avelon_failed_jobs (
+  id text PRIMARY KEY,
+  queue text,
+  name text NOT NULL,
+  payload jsonb NOT NULL,
+  attempt integer NOT NULL,
+  error text NOT NULL,
+  failed_at timestamptz NOT NULL
+);
+`
+
+/**
+ * Postgres queue driver using `FOR UPDATE SKIP LOCKED`.
+ *
+ * The Wave A package names pgmq. This environment does not ship that extension, so the durable
+ * semantics are implemented with skip-locked tables rather than silently declaring the capability
+ * false. Swap the SQL dialect for pgmq when the extension is present in CI.
+ */
+export class SupabaseQueue
+  implements
+    QueueDriver<typeof supabaseQueueCapabilities, SQL>,
+    DelayedQueueSurface,
+    RetryQueueSurface,
+    DeadLetterQueueSurface
+{
+  readonly name = 'supabase'
+  readonly instance: string
+  readonly capabilities = supabaseQueueCapabilities
+
+  readonly #sql: SQL
+  readonly #maxTries: number
+
+  constructor(options: { url: string; instance: string; maxTries: number }) {
+    this.instance = options.instance
+    this.#sql = new SQL(options.url)
+    this.#maxTries = options.maxTries
+  }
+
+  raw(): SQL {
+    return this.#sql
+  }
+
+  async reset(): Promise<void> {
+    await this.#sql.unsafe('DROP TABLE IF EXISTS avelon_failed_jobs')
+    await this.#sql.unsafe('DROP TABLE IF EXISTS avelon_jobs')
+    await this.#sql.unsafe(SCHEMA_SQL)
+  }
+
+  async close(): Promise<void> {
+    await this.#sql.close()
+  }
+
+  async enqueue<TPayload>(job: QueueJob<TPayload>): Promise<string> {
+    return this.#insert(job, new Date())
+  }
+
+  async enqueueAt<TPayload>(job: QueueJob<TPayload>, availableAt: Date): Promise<string> {
+    return this.#insert(job, availableAt)
+  }
+
+  async drain(
+    handler: (receipt: QueueReceipt) => Promise<void>,
+    options?: { readonly queue?: string; readonly limit?: number },
+  ): Promise<number> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const limit = options?.limit ?? 2_147_483_647
+    const rows = (await this.#sql.unsafe(
+      `WITH picked AS MATERIALIZED (
+         SELECT id FROM avelon_jobs
+         WHERE available_at <= now()
+           AND locked_at IS NULL
+           AND ($1::boolean OR queue IS NOT DISTINCT FROM $2)
+         ORDER BY available_at ASC
+         FOR UPDATE SKIP LOCKED
+         LIMIT $3
+       )
+       UPDATE avelon_jobs AS jobs
+          SET locked_at = now(), attempt = jobs.attempt + 1
+         FROM picked
+        WHERE jobs.id = picked.id
+       RETURNING jobs.id, jobs.queue, jobs.name, jobs.payload, jobs.attempt, jobs.available_at`,
+      [options?.queue === undefined, options?.queue ?? null, limit],
+    )) as JobRow[]
+
+    for (const row of rows) {
+      const receipt: QueueReceipt = { id: row.id, job: toJob(row), attempt: row.attempt }
+      try {
+        await handler(receipt)
+        await this.#sql.unsafe(`DELETE FROM avelon_jobs WHERE id = $1`, [row.id])
+      } catch (error: unknown) {
+        if (this.capabilities.retries && row.attempt < this.#maxTries) {
+          await this.#sql.unsafe(
+            `UPDATE avelon_jobs SET locked_at = NULL WHERE id = $1`,
+            [row.id],
+          )
+          continue
+        }
+        if (this.capabilities.deadLetter) {
+          await this.#sql.unsafe(
+            `INSERT INTO avelon_failed_jobs (id, queue, name, payload, attempt, error, failed_at)
+             VALUES ($1, $2, $3, $4::jsonb, $5, $6, now())`,
+            [row.id, row.queue, row.name, encodePayload(row.payload), row.attempt, failureMessage(error)],
+          )
+        }
+        await this.#sql.unsafe(`DELETE FROM avelon_jobs WHERE id = $1`, [row.id])
+      }
+    }
+
+    return rows.length
+  }
+
+  async retry(id: string, delaySeconds?: number): Promise<void> {
+    const delay = delaySeconds ?? 0
+    await this.#sql.unsafe(
+      `UPDATE avelon_jobs
+          SET locked_at = NULL, available_at = now() + ($2 * interval '1 second')
+        WHERE id = $1`,
+      [id, delay],
+    )
+  }
+
+  async failed(queue?: string): Promise<readonly FailedQueueJob[]> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const rows = (await this.#sql.unsafe(
+      `SELECT id, queue, name, payload, attempt, error, failed_at
+         FROM avelon_failed_jobs
+        WHERE ($1::text IS NULL OR queue IS NOT DISTINCT FROM $1)
+        ORDER BY failed_at ASC`,
+      [queue ?? null],
+    )) as FailedRow[]
+    return rows.map((row) => ({
+      id: row.id,
+      job: toJob(row),
+      attempt: row.attempt,
+      error: row.error,
+      failedAt: asDate(row.failed_at),
+    }))
+  }
+
+  async replay(id: string): Promise<void> {
+    const rows = (await this.#sql.unsafe(
+      `DELETE FROM avelon_failed_jobs WHERE id = $1
+       RETURNING id, queue, name, payload`,
+      [id],
+    )) as Array<Pick<FailedRow, 'id' | 'queue' | 'name' | 'payload'>>
+    const row = rows[0]
+    if (row === undefined) return
+    await this.#sql.unsafe(
+      `INSERT INTO avelon_jobs (id, queue, name, payload, attempt, available_at, locked_at)
+       VALUES ($1, $2, $3, $4::jsonb, 0, now(), NULL)`,
+      [row.id, row.queue, row.name, encodePayload(row.payload)],
+    )
+  }
+
+  async forget(id: string): Promise<void> {
+    await this.#sql.unsafe(`DELETE FROM avelon_failed_jobs WHERE id = $1`, [id])
+  }
+
+  async #insert<TPayload>(job: QueueJob<TPayload>, availableAt: Date): Promise<string> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const id = crypto.randomUUID()
+    await this.#sql.unsafe(
+      `INSERT INTO avelon_jobs (id, queue, name, payload, attempt, available_at, locked_at)
+       VALUES ($1, $2, $3, $4::jsonb, 0, $5, NULL)`,
+      [id, job.queue ?? null, job.name, encodePayload(job.payload), availableAt.toISOString()],
+    )
+    return id
+  }
+}
+
+/** Creates a Postgres skip-locked queue driver from options or environment defaults. */
+export function createSupabaseQueue(options: SupabaseQueueOptions = {}): SupabaseQueue {
+  return new SupabaseQueue({
+    url: options.url ?? defaultUrl(),
+    instance: options.instance ?? 'default',
+    maxTries: options.maxTries ?? 3,
+  })
+}

package/src/queue/index.ts

@@ -0,0 +1,6 @@
+export {
+  createSupabaseQueue,
+  SupabaseQueue,
+  supabaseQueueCapabilities,
+  type SupabaseQueueOptions,
+} from './driver'

package/src/social/driver.ts

@@ -0,0 +1,130 @@
+import {
+  Invalid,
+  Unauthenticated,
+  type SocialDriver,
+  type SocialIdentity,
+} from '@avelonjs/core'
+import type { SupabaseSocialProfile } from './types'
+
+/** Exact capability declaration for the Supabase social driver. */
+export const supabaseSocialCapabilities = {
+  providers: ['github', 'google'] as const,
+} as const
+
+type Provider = (typeof supabaseSocialCapabilities.providers)[number]
+
+/** Construction options for {@link createSupabaseSocial}. */
+export interface SupabaseSocialOptions {
+  /** GoTrue Auth base URL, e.g. `http://127.0.0.1:54321/auth/v1`. */
+  authUrl?: string
+  /** Publishable API key sent as `apikey`. */
+  apiKey?: string
+  /** Configured social connection name. */
+  instance?: string
+}
+
+function isProvider(provider: string): provider is Provider {
+  return supabaseSocialCapabilities.providers.some((candidate) => candidate === provider)
+}
+
+function invalid(field: string, message: string): never {
+  throw new Invalid(message, { metadata: { fields: { [field]: [message] } } })
+}
+
+function unauthenticated(message: string): never {
+  throw new Unauthenticated(message, { metadata: { guard: 'social' } })
+}
+
+/**
+ * Supabase Auth social driver.
+ *
+ * `redirect()` builds a GoTrue authorize URL and records CSRF state on the driver instance.
+ * `callback()` verifies that state, then exchanges the authorization code over HTTP.
+ */
+export class SupabaseSocial
+  implements SocialDriver<typeof supabaseSocialCapabilities, { authUrl: string }, SupabaseSocialProfile>
+{
+  readonly name = 'supabase'
+  readonly instance: string
+  readonly capabilities = supabaseSocialCapabilities
+
+  readonly #authUrl: string
+  readonly #apiKey: string
+  readonly #states = new Map<Provider, string>()
+  #nextState = 1
+
+  constructor(options: Required<SupabaseSocialOptions>) {
+    this.instance = options.instance
+    this.#authUrl = options.authUrl.replace(/\/$/, '')
+    this.#apiKey = options.apiKey
+  }
+
+  raw(): { authUrl: string } {
+    return { authUrl: this.#authUrl }
+  }
+
+  async redirect(provider: string, callbackUrl: string, state?: string): Promise<string> {
+    if (!isProvider(provider)) invalid('provider', 'Provider is not configured.')
+    const expectedState = state ?? `assay-state-${this.#nextState++}`
+    this.#states.set(provider, expectedState)
+    const url = new URL(`${this.#authUrl}/authorize`)
+    url.searchParams.set('provider', provider)
+    url.searchParams.set('redirect_to', callbackUrl)
+    url.searchParams.set('state', expectedState)
+    return url.toString()
+  }
+
+  async callback(
+    provider: string,
+    params: Readonly<Record<string, string>>,
+    callbackUrl: string,
+  ): Promise<SocialIdentity<SupabaseSocialProfile>> {
+    if (!isProvider(provider)) invalid('provider', 'Provider is not configured.')
+    const expectedState = this.#states.get(provider)
+    if (!expectedState || !params.state || params.state !== expectedState) {
+      unauthenticated('Authorization state could not be verified.')
+    }
+    this.#states.delete(provider)
+    if (params.error) unauthenticated(`Authorization failed: ${params.error}.`)
+    if (!params.code) invalid('code', 'Authorization code is required.')
+
+    const response = await fetch(`${this.#authUrl}/token`, {
+      method: 'POST',
+      headers: {
+        apikey: this.#apiKey,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        code: params.code,
+        provider,
+        redirect_to: callbackUrl,
+      }),
+    })
+    const body = (await response.json()) as {
+      error?: string
+      provider?: string
+      user?: { id?: string; email?: string; user_metadata?: { full_name?: string } }
+    }
+    const user = body.user
+    if (!response.ok || user === undefined || typeof user.id !== 'string') {
+      unauthenticated(body.error ?? 'Authorization code exchange failed.')
+    }
+    return {
+      provider,
+      subject: user.id,
+      profile: {
+        displayName: user.user_metadata?.full_name ?? user.email ?? user.id,
+        ...(user.email === undefined ? {} : { email: user.email }),
+      },
+    }
+  }
+}
+
+/** Creates a Supabase social driver from options or environment defaults. */
+export function createSupabaseSocial(options: SupabaseSocialOptions = {}): SupabaseSocial {
+  return new SupabaseSocial({
+    authUrl: options.authUrl ?? process.env.SUPABASE_AUTH_URL ?? 'http://127.0.0.1:54321/auth/v1',
+    apiKey: options.apiKey ?? process.env.SUPABASE_ANON_KEY ?? 'local-anon-key',
+    instance: options.instance ?? 'default',
+  })
+}

package/src/social/index.ts

@@ -0,0 +1,8 @@
+export {
+  createSupabaseSocial,
+  SupabaseSocial,
+  supabaseSocialCapabilities,
+  type SupabaseSocialOptions,
+} from './driver'
+export { LocalSocialServer } from './local-auth'
+export type { SupabaseSocialProfile } from './types'