@avelonjs/supabase 0.1.0

package/src/social/local-auth.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal GoTrue-shaped OAuth token endpoint for social conformance.
+ *
+ * Real deployments point {@link createSupabaseSocial} at Supabase Auth. This server exists so the
+ * HTTP callback exchange can run without the full Docker stack.
+ */
+export class LocalSocialServer {
+  #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
+  }
+
+  /** Stops the fixture listener. */
+  async stop(): Promise<void> {
+    this.#server?.stop(true)
+    this.#server = undefined
+  }
+
+  async #handle(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    const path = url.pathname.replace(/^\/auth\/v1/, '')
+
+    if (request.method === 'POST' && path === '/token') {
+      const body = (await request.json()) as { code?: string; provider?: string }
+      if (body.code !== 'valid-code') {
+        return Response.json({ error: 'invalid_grant' }, { status: 400 })
+      }
+      return Response.json({
+        provider: body.provider ?? 'github',
+        user: {
+          id: `subject-${body.code}`,
+          email: 'actor@example.test',
+          user_metadata: { full_name: 'Assay Actor' },
+        },
+      })
+    }
+
+    return Response.json({ error: 'not_found' }, { status: 404 })
+  }
+}

package/src/social/types.ts

@@ -0,0 +1,7 @@
+/** Provider profile returned by the Supabase social driver. */
+export interface SupabaseSocialProfile {
+  /** Display name when the provider supplies one. */
+  displayName: string
+  /** Email address when the provider supplies one. */
+  email?: string
+}

package/src/storage/driver.ts

@@ -0,0 +1,228 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { SQL } from 'bun'
+import {
+  NotFound,
+  type SignedUrlStorageSurface,
+  type StorageDriver,
+  type StorageObject,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Supabase storage driver. */
+export const supabaseStorageCapabilities = {
+  signedUrls: true,
+  transforms: [] as const,
+} as const
+
+/** Construction options for {@link createSupabaseStorage}. */
+export interface SupabaseStorageOptions {
+  /** Postgres URL used to persist object bytes. */
+  url?: string
+  /** Configured disk name. */
+  instance?: string
+  /** HMAC secret used to sign read URLs. */
+  signingSecret?: string
+}
+
+interface StoredRow {
+  path: string
+  contents: Uint8Array | Buffer
+  content_type: string | null
+  size: number
+}
+
+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'
+  )
+}
+
+async function readContents(contents: Uint8Array | AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  if (contents instanceof Uint8Array) return contents.slice()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of contents) {
+    const copy = chunk.slice()
+    chunks.push(copy)
+    size += copy.byteLength
+  }
+  const result = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return result
+}
+
+function notFound(path: string): never {
+  throw new NotFound(`Storage object ${path} was not found.`, {
+    metadata: { resource: 'storage-object', identifier: path },
+  })
+}
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS avelon_storage_objects (
+  path text PRIMARY KEY,
+  contents bytea NOT NULL,
+  content_type text,
+  size integer NOT NULL
+);
+`
+
+/**
+ * Postgres-backed storage driver with HMAC signed read URLs.
+ *
+ * Object bytes persist in `avelon_storage_objects`. Signed URLs are served by an in-process HTTP
+ * listener because the v1 contract requires a fetchable read URL with a real expiry, and this
+ * environment has no Supabase Storage service.
+ */
+export class SupabaseStorage
+  implements
+    StorageDriver<typeof supabaseStorageCapabilities, SQL>,
+    SignedUrlStorageSurface
+{
+  readonly name = 'supabase'
+  readonly instance: string
+  readonly capabilities = supabaseStorageCapabilities
+
+  readonly #sql: SQL
+  readonly #secret: string
+  #server: ReturnType<typeof Bun.serve> | undefined
+  #origin = ''
+
+  constructor(options: { url: string; instance: string; signingSecret: string }) {
+    this.instance = options.instance
+    this.#sql = new SQL(options.url)
+    this.#secret = options.signingSecret
+  }
+
+  raw(): SQL {
+    return this.#sql
+  }
+
+  /** Recreates the empty object table and starts the signed-URL listener. */
+  async reset(): Promise<void> {
+    await this.#sql.unsafe('DROP TABLE IF EXISTS avelon_storage_objects')
+    await this.#sql.unsafe(SCHEMA_SQL)
+    await this.#ensureServer()
+  }
+
+  async close(): Promise<void> {
+    this.#server?.stop(true)
+    this.#server = undefined
+    await this.#sql.close()
+  }
+
+  async put(
+    path: string,
+    contents: Uint8Array | AsyncIterable<Uint8Array>,
+    options?: { readonly contentType?: string },
+  ): Promise<StorageObject> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const stored = await readContents(contents)
+    await this.#sql.unsafe(
+      `INSERT INTO avelon_storage_objects (path, contents, content_type, size)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (path) DO UPDATE SET contents = EXCLUDED.contents, content_type = EXCLUDED.content_type, size = EXCLUDED.size`,
+      [path, stored, options?.contentType ?? null, stored.byteLength],
+    )
+    return {
+      path,
+      size: stored.byteLength,
+      ...(options?.contentType === undefined ? {} : { contentType: options.contentType }),
+    }
+  }
+
+  async get(path: string): Promise<Uint8Array> {
+    const row = await this.#row(path)
+    if (!row) notFound(path)
+    return toBytes(row.contents)
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    await this.#sql.unsafe(`DELETE FROM avelon_storage_objects WHERE path = $1`, [path])
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.#row(path)) !== undefined
+  }
+
+  async signedUrl(path: string, expiresInSeconds: number): Promise<string> {
+    if (!(await this.exists(path))) notFound(path)
+    await this.#ensureServer()
+    const expiresAt = Math.floor(Date.now() / 1000) + expiresInSeconds
+    const signature = sign(this.#secret, path, expiresAt)
+    const url = new URL('/object', this.#origin)
+    url.searchParams.set('path', path)
+    url.searchParams.set('exp', String(expiresAt))
+    url.searchParams.set('sig', signature)
+    return url.toString()
+  }
+
+  async #row(path: string): Promise<StoredRow | undefined> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const rows = (await this.#sql.unsafe(
+      `SELECT path, contents, content_type, size FROM avelon_storage_objects WHERE path = $1`,
+      [path],
+    )) as StoredRow[]
+    return rows[0]
+  }
+
+  async #ensureServer(): Promise<void> {
+    if (this.#server) return
+    const self = this
+    this.#server = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        const url = new URL(request.url)
+        if (url.pathname !== '/object') return new Response('not found', { status: 404 })
+        const path = url.searchParams.get('path') ?? ''
+        const exp = Number(url.searchParams.get('exp'))
+        const sig = url.searchParams.get('sig') ?? ''
+        if (!Number.isFinite(exp) || exp * 1000 <= Date.now()) {
+          return new Response('expired', { status: 403 })
+        }
+        const expected = sign(self.#secret, path, exp)
+        if (!safeEqual(expected, sig)) return new Response('invalid signature', { status: 403 })
+        const row = await self.#row(path)
+        if (!row) return new Response('not found', { status: 404 })
+        const bytes = toBytes(row.contents)
+        const buffer = new ArrayBuffer(bytes.byteLength)
+        new Uint8Array(buffer).set(bytes)
+        return new Response(buffer, {
+          headers: {
+            'Content-Type': row.content_type ?? 'application/octet-stream',
+          },
+        })
+      },
+    })
+    this.#origin = `http://127.0.0.1:${this.#server.port}`
+  }
+}
+
+function toBytes(contents: Uint8Array | Buffer): Uint8Array {
+  return contents instanceof Uint8Array ? contents.slice() : new Uint8Array(contents)
+}
+
+function sign(secret: string, path: string, expiresAt: number): string {
+  return createHmac('sha256', secret).update(`${path}:${expiresAt}`).digest('hex')
+}
+
+function safeEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left)
+  const b = Buffer.from(right)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+/** Creates a Postgres-backed storage driver from options or environment defaults. */
+export function createSupabaseStorage(options: SupabaseStorageOptions = {}): SupabaseStorage {
+  return new SupabaseStorage({
+    url: options.url ?? defaultUrl(),
+    instance: options.instance ?? 'default',
+    signingSecret: options.signingSecret ?? process.env.AVELON_STORAGE_SIGNING_SECRET ?? 'avelon-storage-secret',
+  })
+}

package/src/storage/index.ts

@@ -0,0 +1,6 @@
+export {
+  createSupabaseStorage,
+  SupabaseStorage,
+  supabaseStorageCapabilities,
+  type SupabaseStorageOptions,
+} from './driver'

package/src/tokens/driver.ts

@@ -0,0 +1,216 @@
+import { SQL } from 'bun'
+import {
+  DriverFault,
+  Unauthenticated,
+  type IssuedToken,
+  type TokenDriver,
+  type TokenIssueOptions,
+  type TokenRecord,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Supabase token driver. */
+export const supabaseTokenCapabilities = {
+  abilities: true,
+  expiration: true,
+} as const
+
+/** Construction options for {@link createSupabaseTokens}. */
+export interface SupabaseTokenOptions {
+  /** Postgres URL used to persist hashed tokens. Defaults to `SUPABASE_DB_URL` / `POSTGRES_URL`. */
+  url?: string
+  /** Configured token issuer name. */
+  instance?: string
+  /** Current actor subject stored on issued tokens. */
+  subject?: string
+}
+
+interface StoredRow {
+  id: string
+  subject: string
+  name: string
+  abilities: string[]
+  created_at: Date | string
+  expires_at: Date | string | null
+  hash: string
+  revoked: boolean
+}
+
+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 unauthenticated(): never {
+  throw new Unauthenticated('The API token is invalid or expired.', {
+    metadata: { guard: 'tokens' },
+  })
+}
+
+async function hash(plainText: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(plainText))
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function asDate(value: Date | string): Date {
+  return value instanceof Date ? value : new Date(value)
+}
+
+function toRecord(row: StoredRow): TokenRecord {
+  return {
+    id: row.id,
+    subject: row.subject,
+    name: row.name,
+    abilities: [...row.abilities],
+    createdAt: asDate(row.created_at),
+    expiresAt: row.expires_at === null ? null : asDate(row.expires_at),
+  }
+}
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS avelon_signets (
+  id text PRIMARY KEY,
+  subject text NOT NULL,
+  name text NOT NULL,
+  abilities jsonb NOT NULL DEFAULT '[]'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz,
+  hash text NOT NULL UNIQUE,
+  revoked boolean NOT NULL DEFAULT false
+);
+`
+
+/**
+ * Postgres-backed Signet driver used by the Supabase package.
+ *
+ * Supabase Auth does not issue named API tokens. Hashed credentials live in `avelon_signets` so
+ * verify/list/revoke are durable and the plaintext secret is returned only at issuance.
+ */
+export class SupabaseTokens implements TokenDriver<typeof supabaseTokenCapabilities, SQL> {
+  readonly name = 'supabase'
+  readonly instance: string
+  readonly capabilities = supabaseTokenCapabilities
+
+  readonly #sql: SQL
+  readonly #subject: string
+
+  constructor(options: Required<Omit<SupabaseTokenOptions, 'url' | 'subject'>> & {
+    url: string
+    subject: string
+  }) {
+    this.instance = options.instance
+    this.#subject = options.subject
+    this.#sql = new SQL(options.url)
+  }
+
+  raw(): SQL {
+    return this.#sql
+  }
+
+  /** Recreates the empty signet table used by live conformance. */
+  async reset(): Promise<void> {
+    await this.#sql.unsafe('DROP TABLE IF EXISTS avelon_signets')
+    await this.#sql.unsafe(SCHEMA_SQL)
+  }
+
+  async close(): Promise<void> {
+    await this.#sql.close()
+  }
+
+  async verify(plainText: string): Promise<TokenRecord> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const candidateHash = await hash(plainText)
+    const rows = (await this.#sql.unsafe(
+      `SELECT id, subject, name, abilities, created_at, expires_at, hash, revoked
+       FROM avelon_signets WHERE hash = $1`,
+      [candidateHash],
+    )) as StoredRow[]
+    const row = rows[0]
+    const expiresAt = row?.expires_at === null || row?.expires_at === undefined ? null : asDate(row.expires_at)
+    if (
+      row === undefined ||
+      row.revoked ||
+      (expiresAt !== null && expiresAt.getTime() <= Date.now())
+    ) {
+      unauthenticated()
+    }
+    return toRecord({ ...row, abilities: normalizeAbilities(row.abilities) })
+  }
+
+  async issue(name: string, options: TokenIssueOptions = {}): Promise<IssuedToken> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const id = crypto.randomUUID()
+    const plainText = `avelon-signet-${id}`
+    const createdAt = new Date()
+    const expiresAt = options.expiresAt ? new Date(options.expiresAt) : null
+    const abilities = [...(options.abilities ?? [])]
+    const rows = (await this.#sql.unsafe(
+      `INSERT INTO avelon_signets (id, subject, name, abilities, created_at, expires_at, hash, revoked)
+       VALUES ($1, $2, $3, $4::jsonb, $5, $6, $7, false)
+       RETURNING id, subject, name, abilities, created_at, expires_at, hash, revoked`,
+      [
+        id,
+        this.#subject,
+        name,
+        JSON.stringify(abilities),
+        createdAt.toISOString(),
+        expiresAt?.toISOString() ?? null,
+        await hash(plainText),
+      ],
+    )) as StoredRow[]
+    const stored = rows[0]
+    if (stored === undefined) {
+      throw new DriverFault('Token issuance did not return a row.', {
+        metadata: { driver: 'tokens', operation: 'issue' },
+      })
+    }
+    const record = toRecord({ ...stored, abilities: normalizeAbilities(stored.abilities) })
+    return {
+      ...record,
+      expiresAt: options.expiresAt ? new Date(options.expiresAt.getTime()) : record.expiresAt,
+      plainText,
+    }
+  }
+
+  async list(): Promise<readonly TokenRecord[]> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    const rows = (await this.#sql.unsafe(
+      `SELECT id, subject, name, abilities, created_at, expires_at, hash, revoked
+       FROM avelon_signets WHERE subject = $1 ORDER BY created_at ASC`,
+      [this.#subject],
+    )) as StoredRow[]
+    return rows.map((row) => toRecord({ ...row, abilities: normalizeAbilities(row.abilities) }))
+  }
+
+  async revoke(id: string): Promise<void> {
+    await this.#sql.unsafe(SCHEMA_SQL)
+    await this.#sql.unsafe(`UPDATE avelon_signets SET revoked = true WHERE id = $1`, [id])
+  }
+}
+
+function normalizeAbilities(value: unknown): string[] {
+  if (Array.isArray(value)) return value.filter((entry): entry is string => typeof entry === 'string')
+  if (typeof value === 'string') {
+    try {
+      const parsed: unknown = JSON.parse(value)
+      return Array.isArray(parsed)
+        ? parsed.filter((entry): entry is string => typeof entry === 'string')
+        : []
+    } catch {
+      return []
+    }
+  }
+  return []
+}
+
+/** Creates a Postgres-backed token driver from options or environment defaults. */
+export function createSupabaseTokens(options: SupabaseTokenOptions = {}): SupabaseTokens {
+  return new SupabaseTokens({
+    url: options.url ?? defaultUrl(),
+    instance: options.instance ?? 'default',
+    subject: options.subject ?? 'assay-subject',
+  })
+}

package/src/tokens/index.ts

@@ -0,0 +1,6 @@
+export {
+  createSupabaseTokens,
+  SupabaseTokens,
+  supabaseTokenCapabilities,
+  type SupabaseTokenOptions,
+} from './driver'