@avelonjs/neon 0.3.0

package/src/social/driver.ts

@@ -0,0 +1,118 @@
+import { Invalid, Unauthenticated, type SocialDriver, type SocialIdentity } from '@avelonjs/core'
+import type { NeonSocialProfile } from './types'
+
+/** Exact capability declaration for the Neon social driver. */
+export const neonSocialCapabilities = {
+  providers: ['github', 'google'] as const,
+} as const
+
+type Provider = (typeof neonSocialCapabilities.providers)[number]
+
+/** Construction options for {@link createNeonSocial}. */
+export interface NeonSocialOptions {
+  /** Neon Auth / Better Auth base URL. */
+  authUrl?: string
+  /** Configured social connection name. */
+  instance?: string
+}
+
+function isProvider(provider: string): provider is Provider {
+  return neonSocialCapabilities.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' } })
+}
+
+/**
+ * Neon Auth social driver.
+ *
+ * `redirect()` builds a Better Auth social sign-in URL and records CSRF state on the driver
+ * instance. `callback()` verifies that state, then exchanges the authorization code over HTTP.
+ */
+export class NeonSocial implements SocialDriver<
+  typeof neonSocialCapabilities,
+  { authUrl: string },
+  NeonSocialProfile
+> {
+  readonly name = 'neon'
+  readonly instance: string
+  readonly capabilities = neonSocialCapabilities
+
+  readonly #authUrl: string
+  readonly #states = new Map<Provider, string>()
+  #nextState = 1
+
+  constructor(options: Required<NeonSocialOptions>) {
+    this.instance = options.instance
+    this.#authUrl = options.authUrl.replace(/\/$/, '')
+  }
+
+  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}/sign-in/social`)
+    url.searchParams.set('provider', provider)
+    url.searchParams.set('callbackURL', callbackUrl)
+    url.searchParams.set('state', expectedState)
+    return url.toString()
+  }
+
+  async callback(
+    provider: string,
+    params: Readonly<Record<string, string>>,
+    callbackUrl: string,
+  ): Promise<SocialIdentity<NeonSocialProfile>> {
+    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}/callback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        code: params.code,
+        provider,
+        callbackURL: callbackUrl,
+      }),
+    })
+    const body = (await response.json()) as {
+      error?: string
+      user?: { id?: string; email?: string; 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.name ?? user.email ?? user.id,
+        ...(user.email === undefined ? {} : { email: user.email }),
+      },
+    }
+  }
+}
+
+/** Creates a Neon social driver from options or environment defaults. */
+export function createNeonSocial(options: NeonSocialOptions = {}): NeonSocial {
+  return new NeonSocial({
+    authUrl: options.authUrl ?? process.env.NEON_AUTH_URL ?? 'http://127.0.0.1:3000/api/auth',
+    instance: options.instance ?? 'default',
+  })
+}

package/src/social/index.ts

@@ -0,0 +1,8 @@
+export {
+  createNeonSocial,
+  NeonSocial,
+  neonSocialCapabilities,
+  type NeonSocialOptions,
+} from './driver'
+export { LocalSocialServer } from './local-auth'
+export type { NeonSocialProfile } from './types'

package/src/social/local-auth.ts

@@ -0,0 +1,55 @@
+/**
+ * Minimal Better Auth-shaped OAuth token endpoint for social conformance.
+ *
+ * Real deployments point {@link createNeonSocial} at Neon Auth. This server exists so the HTTP
+ * callback exchange can run without a hosted OAuth app.
+ */
+export class LocalSocialServer {
+  #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
+  }
+
+  /** 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(/^\/api\/auth/, '')
+
+    if (request.method === 'POST' && path === '/callback') {
+      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({
+        user: {
+          id: `subject-${body.code}`,
+          email: 'actor@example.test',
+          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 Neon social driver. */
+export interface NeonSocialProfile {
+  /** 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,182 @@
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import {
+  NotFound,
+  type SignedUrlStorageSurface,
+  type StorageDriver,
+  type StorageObject,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Neon S3 storage driver. */
+export const neonStorageCapabilities = {
+  signedUrls: true,
+  transforms: [] as const,
+} as const
+
+/** Construction options for {@link createNeonStorage}. */
+export interface NeonStorageOptions {
+  /** S3 bucket name. */
+  bucket?: string
+  /** Configured disk name. */
+  instance?: string
+  /** AWS region. Defaults to `AWS_REGION` or `us-east-1`. */
+  region?: string
+  /** Optional custom endpoint for R2, MinIO, or {@link LocalS3Server}. */
+  endpoint?: string
+  /** Access key. Defaults to `AWS_ACCESS_KEY_ID`. */
+  accessKeyId?: string
+  /** Secret key. Defaults to `AWS_SECRET_ACCESS_KEY`. */
+  secretAccessKey?: string
+}
+
+function notFound(path: string): never {
+  throw new NotFound(`Storage object ${path} was not found.`, {
+    metadata: { resource: 'storage-object', identifier: path },
+  })
+}
+
+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 isMissing(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false
+  const name = Reflect.get(error, 'name')
+  const code = Reflect.get(error, '$metadata')
+  const httpStatus =
+    typeof code === 'object' && code !== null ? Reflect.get(code, 'httpStatusCode') : undefined
+  return name === 'NotFound' || name === 'NoSuchKey' || httpStatus === 404
+}
+
+/**
+ * S3 storage driver used by the Neon stack.
+ *
+ * Neon has no object store. Bytes go to S3 (or an S3-compatible endpoint). Signed read URLs are
+ * SigV4 query URLs from the AWS SDK.
+ */
+export class NeonStorage
+  implements StorageDriver<typeof neonStorageCapabilities, S3Client>, SignedUrlStorageSurface
+{
+  readonly name = 'neon'
+  readonly instance: string
+  readonly capabilities = neonStorageCapabilities
+
+  readonly #client: S3Client
+  readonly #bucket: string
+
+  constructor(options: {
+    bucket: string
+    instance: string
+    region: string
+    endpoint?: string
+    accessKeyId: string
+    secretAccessKey: string
+  }) {
+    this.instance = options.instance
+    this.#bucket = options.bucket
+    this.#client = new S3Client({
+      region: options.region,
+      // Vendor boundary: the AWS SDK client plus checksum flags that keep custom endpoints honest.
+      forcePathStyle: options.endpoint !== undefined,
+      ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+      credentials: {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+      },
+      requestChecksumCalculation: 'WHEN_REQUIRED',
+      responseChecksumValidation: 'WHEN_REQUIRED',
+    })
+  }
+
+  raw(): S3Client {
+    return this.#client
+  }
+
+  async put(
+    path: string,
+    contents: Uint8Array | AsyncIterable<Uint8Array>,
+    options?: { readonly contentType?: string },
+  ): Promise<StorageObject> {
+    const stored = await readContents(contents)
+    await this.#client.send(
+      new PutObjectCommand({
+        Bucket: this.#bucket,
+        Key: path,
+        Body: stored,
+        ...(options?.contentType === undefined ? {} : { ContentType: options.contentType }),
+      }),
+    )
+    return {
+      path,
+      size: stored.byteLength,
+      ...(options?.contentType === undefined ? {} : { contentType: options.contentType }),
+    }
+  }
+
+  async get(path: string): Promise<Uint8Array> {
+    try {
+      const response = await this.#client.send(
+        new GetObjectCommand({ Bucket: this.#bucket, Key: path }),
+      )
+      const body = response.Body
+      if (body === undefined) notFound(path)
+      return new Uint8Array(await body.transformToByteArray())
+    } catch (error: unknown) {
+      if (isMissing(error)) notFound(path)
+      throw error
+    }
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.#client.send(new DeleteObjectCommand({ Bucket: this.#bucket, Key: path }))
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await this.#client.send(new HeadObjectCommand({ Bucket: this.#bucket, Key: path }))
+      return true
+    } catch (error: unknown) {
+      if (isMissing(error)) return false
+      throw error
+    }
+  }
+
+  async signedUrl(path: string, expiresInSeconds: number): Promise<string> {
+    if (!(await this.exists(path))) notFound(path)
+    return getSignedUrl(this.#client, new GetObjectCommand({ Bucket: this.#bucket, Key: path }), {
+      expiresIn: expiresInSeconds,
+    })
+  }
+}
+
+/** Creates an S3 storage driver from options or environment defaults. */
+export function createNeonStorage(options: NeonStorageOptions = {}): NeonStorage {
+  return new NeonStorage({
+    bucket: options.bucket ?? process.env.NEON_S3_BUCKET ?? process.env.AWS_S3_BUCKET ?? 'avelon',
+    instance: options.instance ?? 'default',
+    region: options.region ?? process.env.AWS_REGION ?? 'us-east-1',
+    endpoint: options.endpoint ?? process.env.AWS_ENDPOINT_URL_S3 ?? process.env.AWS_ENDPOINT_URL,
+    accessKeyId: options.accessKeyId ?? process.env.AWS_ACCESS_KEY_ID ?? 'test',
+    secretAccessKey: options.secretAccessKey ?? process.env.AWS_SECRET_ACCESS_KEY ?? 'test',
+  })
+}

package/src/storage/index.ts

@@ -0,0 +1,7 @@
+export {
+  createNeonStorage,
+  NeonStorage,
+  neonStorageCapabilities,
+  type NeonStorageOptions,
+} from './driver'
+export { LocalS3Server, signedUrlExpiryMs } from './local-s3'

package/src/storage/local-s3.ts

@@ -0,0 +1,128 @@
+interface StoredObject {
+  bytes: Uint8Array
+  contentType?: string
+}
+
+function objectKey(bucket: string, key: string): string {
+  return `${bucket}/${key}`
+}
+
+function parsePath(pathname: string): { bucket: string; key: string } | undefined {
+  const parts = pathname.split('/').filter((part) => part.length > 0)
+  const bucket = parts[0]
+  if (bucket === undefined) return undefined
+  return { bucket, key: parts.slice(1).join('/') }
+}
+
+/** Parses SigV4 query expiry. Returns epoch ms, or undefined when the request is not signed. */
+export function signedUrlExpiryMs(url: URL): number | undefined {
+  const date = url.searchParams.get('X-Amz-Date')
+  const expires = Number(url.searchParams.get('X-Amz-Expires'))
+  if (date === null || date.length < 16 || !Number.isFinite(expires)) return undefined
+  const iso = `${date.slice(0, 4)}-${date.slice(4, 6)}-${date.slice(6, 8)}T${date.slice(9, 11)}:${date.slice(11, 13)}:${date.slice(13, 15)}Z`
+  const started = Date.parse(iso)
+  if (Number.isNaN(started)) return undefined
+  return started + expires * 1000
+}
+
+/**
+ * Minimal path-style S3 HTTP server for storage conformance.
+ *
+ * Real deployments point {@link createNeonStorage} at AWS S3, R2, or MinIO. This listener ignores
+ * SigV4 signatures and enforces `X-Amz-Date` / `X-Amz-Expires` so signed-URL expiry stays real.
+ */
+export class LocalS3Server {
+  readonly #objects = new Map<string, StoredObject>()
+  #server: ReturnType<typeof Bun.serve> | undefined
+  #url = ''
+
+  /** Path-style S3 endpoint, e.g. `http://127.0.0.1:9000`. */
+  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}`
+    return this.#url
+  }
+
+  /** Clears stored objects without restarting the listener. */
+  reset(): void {
+    this.#objects.clear()
+  }
+
+  /** Stops the server and clears fixture state. */
+  async stop(): Promise<void> {
+    this.#server?.stop(true)
+    this.#server = undefined
+    this.reset()
+  }
+
+  async #handle(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    const parsed = parsePath(url.pathname)
+    if (parsed === undefined || parsed.key.length === 0) {
+      return s3Error(404, 'NoSuchKey', 'The specified key does not exist.')
+    }
+    const id = objectKey(parsed.bucket, parsed.key)
+
+    if (request.method === 'PUT') {
+      const buffer = new Uint8Array(await request.arrayBuffer())
+      const contentType = request.headers.get('content-type') ?? undefined
+      this.#objects.set(id, {
+        bytes: buffer,
+        ...(contentType === undefined ? {} : { contentType }),
+      })
+      return new Response(null, { status: 200, headers: { ETag: `"${buffer.byteLength}"` } })
+    }
+
+    if (request.method === 'DELETE') {
+      this.#objects.delete(id)
+      return new Response(null, { status: 204 })
+    }
+
+    const expiry = signedUrlExpiryMs(url)
+    if (expiry !== undefined && expiry <= Date.now()) {
+      return new Response('expired', { status: 403 })
+    }
+
+    const stored = this.#objects.get(id)
+    if (stored === undefined) {
+      return s3Error(404, 'NoSuchKey', 'The specified key does not exist.')
+    }
+
+    const headers: Record<string, string> = {
+      'Content-Type': stored.contentType ?? 'application/octet-stream',
+      'Content-Length': String(stored.bytes.byteLength),
+      ETag: `"${stored.bytes.byteLength}"`,
+    }
+
+    if (request.method === 'HEAD') {
+      return new Response(null, { status: 200, headers })
+    }
+
+    if (request.method === 'GET') {
+      const copy = new ArrayBuffer(stored.bytes.byteLength)
+      new Uint8Array(copy).set(stored.bytes)
+      return new Response(copy, { status: 200, headers })
+    }
+
+    return s3Error(405, 'MethodNotAllowed', 'The specified method is not allowed.')
+  }
+}
+
+function s3Error(status: number, code: string, message: string): Response {
+  const body = `<?xml version="1.0" encoding="UTF-8"?><Error><Code>${code}</Code><Message>${message}</Message></Error>`
+  return new Response(body, {
+    status,
+    headers: { 'Content-Type': 'application/xml' },
+  })
+}