@avelonjs/neon 0.3.0

package/src/identity/local-auth.ts

@@ -0,0 +1,304 @@
+import { createHash, randomUUID } from 'node:crypto'
+
+interface LocalUser {
+  id: string
+  email: string
+  passwordHash: string
+  totpEnabled: boolean
+  emailVerified: boolean
+}
+
+interface LocalSession {
+  id: string
+  userId: string
+  token: string
+  expiresAt: number
+}
+
+interface LocalReset {
+  email: string
+  token: string
+}
+
+interface LocalVerification {
+  email: string
+  token: string
+}
+
+function hashPassword(password: string): string {
+  return createHash('sha256').update(password).digest('hex')
+}
+
+/**
+ * Minimal Better Auth-shaped HTTP server for live identity conformance.
+ *
+ * Real deployments point the same driver at Neon Auth. This server exists so cookie and password
+ * flows can be verified without a hosted Neon Auth project.
+ */
+export class LocalAuthServer {
+  readonly #users = new Map<string, LocalUser>()
+  readonly #sessions = new Map<string, LocalSession>()
+  readonly #resets = new Map<string, LocalReset>()
+  readonly #verifications = new Map<string, LocalVerification>()
+  readonly #magicLinks = new Map<string, string>()
+  #server: ReturnType<typeof Bun.serve> | undefined
+  #url = ''
+
+  /** Base Auth URL, e.g. `http://127.0.0.1:3000/api/auth`. */
+  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}/api/auth`
+    return this.#url
+  }
+
+  /** Clears users, sessions, reset tokens, and verification tokens without restarting the listener. */
+  reset(): void {
+    this.#users.clear()
+    this.#sessions.clear()
+    this.#resets.clear()
+    this.#verifications.clear()
+    this.#magicLinks.clear()
+  }
+
+  /** Stops the server and clears fixture state. */
+  async stop(): Promise<void> {
+    this.#server?.stop(true)
+    this.#server = undefined
+    this.reset()
+  }
+
+  /** Returns the magic-link token issued for an email, if any. */
+  magicLinkToken(email: string): string | undefined {
+    return [...this.#magicLinks.entries()].find(([, value]) => value === email)?.[0]
+  }
+
+  /** 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
+  }
+
+  /** Returns the email confirmation token issued for an email, if any. */
+  verificationToken(email: string): string | undefined {
+    return [...this.#verifications.values()].find((entry) => entry.email === email)?.token
+  }
+
+  async #handle(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    const path = url.pathname.replace(/^\/api\/auth/, '')
+
+    if (request.method === 'POST' && path === '/sign-up/email') {
+      const body = (await request.json()) as { email?: string; password?: string }
+      if (!body.email || !body.password) {
+        return fail(400, 'INVALID_EMAIL', 'Invalid email')
+      }
+      if ([...this.#users.values()].some((user) => user.email === body.email)) {
+        return fail(422, 'USER_ALREADY_EXISTS', 'User already exists')
+      }
+      const user: LocalUser = {
+        id: randomUUID(),
+        email: body.email,
+        passwordHash: hashPassword(body.password),
+        totpEnabled: true,
+        emailVerified: false,
+      }
+      this.#users.set(user.id, user)
+      return json(this.#sessionPayload(user))
+    }
+
+    if (request.method === 'POST' && path === '/sign-in/email') {
+      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 fail(401, 'INVALID_EMAIL_OR_PASSWORD', 'Invalid email or password')
+      }
+      return json(this.#sessionPayload(user))
+    }
+
+    if (request.method === 'GET' && path === '/get-session') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      const user = this.#users.get(session.userId)
+      if (!user) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      return json({
+        user: {
+          id: user.id,
+          email: user.email,
+          emailVerified: user.emailVerified,
+          twoFactorEnabled: user.totpEnabled,
+        },
+        session: {
+          id: session.id,
+          token: session.token,
+          expiresAt: new Date(session.expiresAt).toISOString(),
+        },
+      })
+    }
+
+    if (request.method === 'POST' && path === '/sign-out') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      this.#sessions.delete(session.token)
+      return json({})
+    }
+
+    if (request.method === 'POST' && path === '/change-password') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      const user = this.#users.get(session.userId)
+      if (!user) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      const body = (await request.json()) as { newPassword?: string }
+      if (!body.newPassword) return fail(400, 'BAD_REQUEST', 'Missing required fields')
+      user.passwordHash = hashPassword(body.newPassword)
+      return json({ user: { id: user.id, email: user.email } })
+    }
+
+    if (request.method === 'POST' && path === '/forget-password') {
+      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 === 'POST' && path === '/reset-password') {
+      const body = (await request.json()) as { token?: string; newPassword?: string }
+      if (!body.token || !body.newPassword)
+        return fail(400, 'BAD_REQUEST', 'Missing required fields')
+      const reset = this.#resets.get(body.token)
+      if (!reset) return fail(400, 'INVALID_TOKEN', 'Invalid token')
+      const user = [...this.#users.values()].find((entry) => entry.email === reset.email)
+      if (!user) return fail(400, 'INVALID_TOKEN', 'Invalid token')
+      user.passwordHash = hashPassword(body.newPassword)
+      this.#resets.delete(body.token)
+      return json({ user: { id: user.id, email: user.email } })
+    }
+
+    if (request.method === 'POST' && path === '/sign-in/magic-link') {
+      const body = (await request.json()) as { email?: string }
+      if (body.email) this.#magicLinks.set(`assay-magic-${randomUUID()}`, body.email)
+      return json({ status: true })
+    }
+
+    if (request.method === 'GET' && path === '/magic-link/verify') {
+      const token = url.searchParams.get('token')
+      const email = token === null ? undefined : this.#magicLinks.get(token)
+      const user = email
+        ? [...this.#users.values()].find((entry) => entry.email === email)
+        : undefined
+      if (token === null || !user) return fail(401, 'INVALID_TOKEN', 'Invalid token')
+      this.#magicLinks.delete(token)
+      return json(this.#sessionPayload(user))
+    }
+
+    if (request.method === 'GET' && path === '/two-factor/status') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      const user = this.#users.get(session.userId)
+      if (!user) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      return json({ enabled: user.totpEnabled })
+    }
+
+    if (request.method === 'POST' && path === '/two-factor/verify-totp') {
+      const session = this.#sessionFromAuth(request)
+      if (!session) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      const user = this.#users.get(session.userId)
+      if (!user) return fail(401, 'UNAUTHORIZED', 'Session is not valid')
+      const body = (await request.json()) as { code?: string }
+      if (!user.totpEnabled || body.code !== '123456') {
+        return fail(400, 'INVALID_TWO_FACTOR_CODE', 'Invalid two factor code')
+      }
+      return json({})
+    }
+
+    if (request.method === 'POST' && path === '/send-verification-email') {
+      const body = (await request.json()) as { email?: string }
+      if (body.email && [...this.#users.values()].some((user) => user.email === body.email)) {
+        const token = `assay-verify-${randomUUID()}`
+        this.#verifications.set(token, { email: body.email, token })
+      }
+      return json({})
+    }
+
+    if (request.method === 'GET' && path === '/verify-email') {
+      const token = url.searchParams.get('token')
+      if (!token) return fail(400, 'BAD_REQUEST', 'Missing required fields')
+      const verification = this.#verifications.get(token)
+      if (!verification) return fail(400, 'INVALID_TOKEN', 'Invalid token')
+      const user = [...this.#users.values()].find((entry) => entry.email === verification.email)
+      if (!user) return fail(400, 'INVALID_TOKEN', 'Invalid token')
+      user.emailVerified = true
+      this.#verifications.delete(token)
+      return json({ user: { id: user.id, email: user.email, emailVerified: true } })
+    }
+
+    return fail(404, 'NOT_FOUND', 'Requested path is invalid')
+  }
+
+  #sessionPayload(user: LocalUser): AuthPayload {
+    const session = this.#createSession(user.id)
+    return {
+      user: { id: user.id, email: user.email },
+      token: session.token,
+      session: {
+        id: session.id,
+        token: session.token,
+        expiresAt: new Date(session.expiresAt).toISOString(),
+      },
+    }
+  }
+
+  #createSession(userId: string): LocalSession {
+    const session: LocalSession = {
+      id: randomUUID(),
+      userId,
+      token: randomUUID(),
+      expiresAt: Date.now() + 60 * 60 * 1000,
+    }
+    this.#sessions.set(session.token, 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
+  }
+}
+
+interface AuthPayload {
+  user: { id: string; email: string }
+  token: string
+  session: { id: string; token: string; expiresAt: string }
+}
+
+/**
+ * A Better Auth error envelope.
+ *
+ * Neon Auth answers a failure with a SCREAMING_SNAKE `code` and a `message` sentence. The driver
+ * classifies on that envelope, so this server emits it rather than a shape invented to match.
+ */
+function fail(status: number, code: string, message: string): Response {
+  return json({ code, message }, status)
+}
+
+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 Neon identity driver. */
+export interface NeonActor {
+  /** Stable actor identifier. */
+  id: string
+  /** Sign-in email address. */
+  email: string
+}
+
+/** Session returned by the Neon identity driver. */
+export interface NeonSession {
+  /** Stable session identifier. */
+  id: string
+  /** Session token retained for subsequent Auth API calls. */
+  accessToken: string
+  /** Refresh token used for rotation when present. */
+  refreshToken: string
+  /** Time after which the session 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,271 @@
+import { SQL } from 'bun'
+import type {
+  DeadLetterQueueSurface,
+  DelayedQueueSurface,
+  FailedQueueJob,
+  QueueDriver,
+  QueueJob,
+  QueueReceipt,
+  RetryQueueSurface,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Neon queue driver. */
+export const neonQueueCapabilities = {
+  delayed: true,
+  retries: true,
+  deadLetter: true,
+} as const
+
+/** Construction options for {@link createNeonQueue}. */
+export interface NeonQueueOptions {
+  /** Neon or 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.NEON_DATABASE_URL ??
+    process.env.POSTGRES_URL ??
+    process.env.DATABASE_URL ??
+    'postgresql://postgres:avelon@127.0.0.1:5432/avelon_test'
+  )
+}
+
+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
+);
+`
+
+/**
+ * Neon queue driver using Postgres `FOR UPDATE SKIP LOCKED`.
+ *
+ * Jobs live on the same Neon database as the rest of the stack. Skip-locked tables carry retry,
+ * delay, and dead-letter semantics without requiring pgmq.
+ */
+export class NeonQueue
+  implements
+    QueueDriver<typeof neonQueueCapabilities, SQL>,
+    DelayedQueueSurface,
+    RetryQueueSurface,
+    DeadLetterQueueSurface
+{
+  readonly name = 'neon'
+  readonly instance: string
+  readonly capabilities = neonQueueCapabilities
+
+  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 skip-locked queue driver from options or environment defaults. */
+export function createNeonQueue(options: NeonQueueOptions = {}): NeonQueue {
+  return new NeonQueue({
+    url: options.url ?? defaultUrl(),
+    instance: options.instance ?? 'default',
+    maxTries: options.maxTries ?? 3,
+  })
+}

package/src/queue/index.ts

@@ -0,0 +1 @@
+export { createNeonQueue, NeonQueue, neonQueueCapabilities, type NeonQueueOptions } from './driver'