@avelonjs/neon 0.3.0

package/src/tokens/driver.ts

@@ -0,0 +1,220 @@
+import { SQL } from 'bun'
+import {
+  DriverFault,
+  Unauthenticated,
+  type IssuedToken,
+  type TokenDriver,
+  type TokenIssueOptions,
+  type TokenRecord,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Neon token driver. */
+export const neonTokenCapabilities = {
+  abilities: true,
+  expiration: true,
+} as const
+
+/** Construction options for {@link createNeonTokens}. */
+export interface NeonTokenOptions {
+  /** Neon or Postgres URL used to persist hashed tokens. */
+  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.NEON_DATABASE_URL ??
+    process.env.POSTGRES_URL ??
+    process.env.DATABASE_URL ??
+    'postgresql://postgres:avelon@127.0.0.1:5432/avelon_test'
+  )
+}
+
+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 Neon package.
+ *
+ * Neon 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 NeonTokens implements TokenDriver<typeof neonTokenCapabilities, SQL> {
+  readonly name = 'neon'
+  readonly instance: string
+  readonly capabilities = neonTokenCapabilities
+
+  readonly #sql: SQL
+  readonly #subject: string
+
+  constructor(
+    options: Required<Omit<NeonTokenOptions, '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 createNeonTokens(options: NeonTokenOptions = {}): NeonTokens {
+  return new NeonTokens({
+    url: options.url ?? defaultUrl(),
+    instance: options.instance ?? 'default',
+    subject: options.subject ?? 'assay-subject',
+  })
+}

package/src/tokens/index.ts

@@ -0,0 +1,6 @@
+export {
+  createNeonTokens,
+  NeonTokens,
+  neonTokenCapabilities,
+  type NeonTokenOptions,
+} from './driver'