@edge-base/server 0.1.1

package/src/lib/auth-db-adapter.ts

@@ -0,0 +1,289 @@
+/**
+ * auth-db-adapter.ts — Abstraction layer for Auth database access.
+ *
+ * Provides a unified interface for D1 (SQLite) and PostgreSQL backends.
+ * All auth-service functions use AuthDb instead of D1Database directly,
+ * enabling transparent provider switching via config.auth.provider.
+ *
+ * Key differences handled by the adapter:
+ * - D1 uses `?` bind params, PostgreSQL uses `$1, $2, ...`
+ * - D1 `db.batch()` is atomic, PostgreSQL uses `BEGIN/COMMIT`
+ * - D1 `.all()` returns `{ results: T[] }`, pg `.query()` returns `{ rows: T[] }`
+ */
+import { Client } from 'pg';
+import { parseConfig } from './do-router.js';
+
+// ─── Interface ───
+
+export type AuthDbDialect = 'sqlite' | 'postgres';
+
+export interface AuthDb {
+  /** The SQL dialect (sqlite for D1, postgres for Neon/PostgreSQL). */
+  readonly dialect: AuthDbDialect;
+
+  /**
+   * Execute a query and return all matching rows.
+   * SQL uses `?` placeholders — the adapter converts to `$1, $2, ...` for PostgreSQL.
+   */
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+
+  /**
+   * Execute a query and return the first row, or null.
+   */
+  first<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+
+  /**
+   * Execute a statement that doesn't return rows (INSERT, UPDATE, DELETE).
+   */
+  run(sql: string, params?: unknown[]): Promise<void>;
+
+  /**
+   * Execute multiple statements atomically.
+   * D1: db.batch([...])
+   * PostgreSQL: BEGIN; ...; COMMIT;
+   */
+  batch(statements: { sql: string; params?: unknown[] }[]): Promise<void>;
+}
+
+// ─── D1 Implementation ───
+
+export class D1AuthDb implements AuthDb {
+  readonly dialect: AuthDbDialect = 'sqlite';
+
+  constructor(private readonly db: D1Database) {}
+
+  async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+    const stmt = params && params.length > 0
+      ? this.db.prepare(sql).bind(...params)
+      : this.db.prepare(sql);
+    const result = await stmt.all();
+    return (result.results ?? []) as T[];
+  }
+
+  async first<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+    const stmt = params && params.length > 0
+      ? this.db.prepare(sql).bind(...params)
+      : this.db.prepare(sql);
+    const row = await stmt.first();
+    return (row ?? null) as T | null;
+  }
+
+  async run(sql: string, params?: unknown[]): Promise<void> {
+    const stmt = params && params.length > 0
+      ? this.db.prepare(sql).bind(...params)
+      : this.db.prepare(sql);
+    await stmt.run();
+  }
+
+  async batch(statements: { sql: string; params?: unknown[] }[]): Promise<void> {
+    if (statements.length === 0) return;
+    await this.db.batch(
+      statements.map((s) =>
+        s.params && s.params.length > 0
+          ? this.db.prepare(s.sql).bind(...s.params)
+          : this.db.prepare(s.sql),
+      ),
+    );
+  }
+}
+
+// ─── PostgreSQL Implementation ───
+
+/**
+ * Convert `?` placeholders to `$1, $2, ...` for PostgreSQL.
+ * Handles `?` inside single-quoted strings by skipping them.
+ */
+function sqliteToPostgresParams(sql: string): string {
+  let idx = 0;
+  let inString = false;
+  let result = '';
+
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+
+    // Track single-quoted strings
+    if (ch === "'") {
+      if (inString && sql[i + 1] === "'") {
+        // Escaped quote ''
+        result += "''";
+        i++;
+        continue;
+      }
+      inString = !inString;
+      result += ch;
+      continue;
+    }
+
+    if (ch === '?' && !inString) {
+      idx++;
+      result += `$${idx}`;
+    } else {
+      result += ch;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert SQLite-specific SQL constructs to PostgreSQL equivalents.
+ * - `INSERT OR IGNORE` → `INSERT ... ON CONFLICT DO NOTHING`
+ * - `INSERT OR REPLACE` → `INSERT ... ON CONFLICT (pk) DO UPDATE SET ...`
+ */
+export function adaptSqlDialect(sql: string): string {
+  // 1. INSERT OR IGNORE → INSERT ... ON CONFLICT DO NOTHING
+  const ignoreAdapted = sql.replace(
+    /INSERT\s+OR\s+IGNORE\s+INTO/gi,
+    'INSERT INTO',
+  );
+
+  if (ignoreAdapted !== sql) {
+    let result = ignoreAdapted.trimEnd();
+    if (!result.endsWith(';')) {
+      result += ' ON CONFLICT DO NOTHING';
+    }
+    return result;
+  }
+
+  // 2. INSERT OR REPLACE → INSERT ... ON CONFLICT (pk) DO UPDATE SET ...
+  const replaceAdapted = sql.replace(
+    /INSERT\s+OR\s+REPLACE\s+INTO/gi,
+    'INSERT INTO',
+  );
+
+  if (replaceAdapted !== sql) {
+    // Extract column names: INSERT INTO "table" ("col1", "col2", ...) VALUES (...)
+    const colMatch = replaceAdapted.match(/INTO\s+"[^"]+"\s*\(([^)]+)\)/i);
+    if (colMatch) {
+      const cols = colMatch[1].split(',').map(c => c.trim().replace(/"/g, ''));
+      // First column is the PK (id, email, token, key, etc.)
+      const pk = cols[0];
+      const updateCols = cols.filter(c => c !== pk);
+
+      let result = replaceAdapted.trimEnd().replace(/;\s*$/, '');
+      if (updateCols.length > 0) {
+        const setClause = updateCols.map(c => `"${c}" = EXCLUDED."${c}"`).join(', ');
+        result += ` ON CONFLICT ("${pk}") DO UPDATE SET ${setClause}`;
+      } else {
+        result += ' ON CONFLICT DO NOTHING';
+      }
+      return result;
+    }
+    return replaceAdapted;
+  }
+
+  return sql;
+}
+
+export class PgAuthDb implements AuthDb {
+  readonly dialect: AuthDbDialect = 'postgres';
+
+  constructor(private readonly connectionString: string) {}
+
+  private adaptSql(sql: string): string {
+    return sqliteToPostgresParams(adaptSqlDialect(sql));
+  }
+
+  private async withClient<T>(fn: (client: Client) => Promise<T>): Promise<T> {
+    const client = new Client({ connectionString: this.connectionString });
+    try {
+      await client.connect();
+      return await fn(client);
+    } finally {
+      await client.end();
+    }
+  }
+
+  async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+    return this.withClient(async (client) => {
+      const result = await client.query(this.adaptSql(sql), params ?? []);
+      return result.rows as T[];
+    });
+  }
+
+  async first<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+    return this.withClient(async (client) => {
+      const result = await client.query(this.adaptSql(sql), params ?? []);
+      return (result.rows[0] ?? null) as T | null;
+    });
+  }
+
+  async run(sql: string, params?: unknown[]): Promise<void> {
+    await this.withClient(async (client) => {
+      await client.query(this.adaptSql(sql), params ?? []);
+    });
+  }
+
+  async batch(statements: { sql: string; params?: unknown[] }[]): Promise<void> {
+    if (statements.length === 0) return;
+    await this.withClient(async (client) => {
+      await client.query('BEGIN');
+      try {
+        for (const stmt of statements) {
+          await client.query(this.adaptSql(stmt.sql), stmt.params ?? []);
+        }
+        await client.query('COMMIT');
+      } catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+      }
+    });
+  }
+}
+
+// ─── Factory ───
+
+/**
+ * Resolve the Hyperdrive binding name for auth PostgreSQL.
+ * Convention: AUTH_POSTGRES
+ * The .env secret key: AUTH_POSTGRES_URL (or user-specified connectionString value)
+ */
+export function getAuthPostgresBindingName(): string {
+  return 'AUTH_POSTGRES';
+}
+
+/**
+ * Create an AuthDb instance from the environment and config.
+ * - Default / provider='d1' → D1AuthDb using env.AUTH_DB
+ * - provider='neon'|'postgres' → PgAuthDb using Hyperdrive connection string
+ *
+ * When authProvider / connectionStringKey are omitted, the adapter resolves them
+ * from config.auth.provider and config.auth.connectionString.
+ */
+export function resolveAuthDb(env: Record<string, unknown>, authProvider?: string, connectionStringKey?: string): AuthDb {
+  const config = parseConfig(env);
+  const provider = authProvider ?? config.auth?.provider ?? 'd1';
+  const resolvedConnectionStringKey = connectionStringKey ?? config.auth?.connectionString ?? 'AUTH_POSTGRES_URL';
+
+  if (provider === 'd1') {
+    const d1 = env.AUTH_DB as D1Database | undefined;
+    if (!d1) {
+      throw new Error('AUTH_DB D1 binding is not available in the environment.');
+    }
+    return new D1AuthDb(d1);
+  }
+
+  if (provider === 'neon' || provider === 'postgres') {
+    // Resolve Hyperdrive connection string
+    const bindingName = getAuthPostgresBindingName();
+    const hyperdrive = env[bindingName] as { connectionString?: string } | undefined;
+
+    if (hyperdrive?.connectionString) {
+      return new PgAuthDb(hyperdrive.connectionString);
+    }
+
+    // Fallback: direct connection string from env (local dev)
+    const envKey = resolvedConnectionStringKey;
+    const connStr = env[envKey] as string | undefined;
+    if (connStr) {
+      return new PgAuthDb(connStr);
+    }
+
+    throw new Error(
+      `Auth provider '${provider}' requires a PostgreSQL connection. ` +
+      `Expected Hyperdrive binding '${bindingName}' or env variable '${envKey}'.`,
+    );
+  }
+
+  throw new Error(`Unknown auth provider: '${provider}'.`);
+}

package/src/lib/auth-redirect.ts

@@ -0,0 +1,116 @@
+import { EdgeBaseError } from '@edge-base/shared';
+import { parseConfig } from './do-router.js';
+import type { Env } from '../types.js';
+
+export interface ClientRedirectInput {
+  redirectUrl?: string | null;
+  state?: string | null;
+}
+
+export interface ParsedClientRedirect {
+  redirectUrl: string | null;
+  state: string | null;
+}
+
+function normalizeUrl(value: string): string {
+  try {
+    return new URL(value).toString();
+  } catch {
+    throw new EdgeBaseError(400, 'Invalid redirect_url.');
+  }
+}
+
+function isAllowedRedirect(candidate: string, pattern: string): boolean {
+  const trimmed = pattern.trim();
+  if (!trimmed) return false;
+
+  if (trimmed.endsWith('*')) {
+    return candidate.startsWith(trimmed.slice(0, -1));
+  }
+
+  let allowedUrl: URL;
+  let candidateUrl: URL;
+  try {
+    allowedUrl = new URL(trimmed);
+    candidateUrl = new URL(candidate);
+  } catch {
+    return false;
+  }
+
+  // Origin-wide allowlist entry: https://app.example.com
+  if (allowedUrl.pathname === '/' && !allowedUrl.search && !allowedUrl.hash) {
+    return allowedUrl.origin === candidateUrl.origin;
+  }
+
+  return allowedUrl.toString() === candidateUrl.toString();
+}
+
+function getAllowedRedirectUrls(env: Env): string[] {
+  const config = parseConfig(env);
+  const entries = config?.auth?.allowedRedirectUrls;
+  if (!Array.isArray(entries)) return [];
+  return entries.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0);
+}
+
+export function appendRedirectParams(
+  redirectUrl: string,
+  params: Record<string, string | undefined | null>,
+): string {
+  const url = new URL(redirectUrl);
+  const fragmentParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') {
+      fragmentParams.set(key, value);
+    }
+  }
+  const fragment = fragmentParams.toString();
+  if (fragment) {
+    url.hash = fragment;
+  }
+  return url.toString();
+}
+
+export function parseClientRedirectUrl(env: Env, value: string | null | undefined): string | null {
+  if (!value) return null;
+  const normalized = normalizeUrl(value);
+  const allowed = getAllowedRedirectUrls(env);
+  if (allowed.length > 0 && !allowed.some((pattern) => isAllowedRedirect(normalized, pattern))) {
+    throw new EdgeBaseError(400, 'redirect_url is not allowed.');
+  }
+  return normalized;
+}
+
+export function parseClientRedirectState(value: string | null | undefined): string | null {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string') {
+    throw new EdgeBaseError(400, 'Invalid state.');
+  }
+  if (value.length > 1024) {
+    throw new EdgeBaseError(400, 'state must not exceed 1024 characters.');
+  }
+  return value;
+}
+
+export function parseClientRedirectInput(env: Env, input: ClientRedirectInput | null | undefined): ParsedClientRedirect {
+  return {
+    redirectUrl: parseClientRedirectUrl(env, input?.redirectUrl),
+    state: parseClientRedirectState(input?.state),
+  };
+}
+
+export function buildEmailActionUrl(options: {
+  redirectUrl: string | null;
+  fallbackUrl: string;
+  token: string;
+  type: string;
+  state?: string | null;
+}): string {
+  if (!options.redirectUrl) {
+    return options.fallbackUrl;
+  }
+  return appendRedirectParams(options.redirectUrl, {
+    token: options.token,
+    type: options.type,
+    state: options.state ?? null,
+  });
+}

package/src/lib/cidr.ts

@@ -0,0 +1,115 @@
+/**
+ * Pure IPv4/IPv6 CIDR matching utility.
+ * No external dependencies — suitable for Cloudflare Workers runtime.
+ *
+ * @module cidr
+ */
+
+/**
+ * Check if an IP address falls within a CIDR range.
+ * Supports IPv4 (e.g. '10.0.0.0/8') and IPv6 (e.g. '2001:db8::/32').
+ *
+ * Returns false for invalid inputs (malformed IP or CIDR).
+ */
+export function isIpInCidr(ip: string, cidr: string): boolean {
+  const slashIdx = cidr.indexOf('/');
+  if (slashIdx === -1) return false;
+
+  const cidrIp = cidr.substring(0, slashIdx);
+  const prefixLen = parseInt(cidr.substring(slashIdx + 1), 10);
+  if (isNaN(prefixLen) || prefixLen < 0) return false;
+
+  // Determine IP version
+  const isIPv6Input = ip.includes(':');
+  const isIPv6Cidr = cidrIp.includes(':');
+
+  // Must be same version
+  if (isIPv6Input !== isIPv6Cidr) return false;
+
+  if (isIPv6Input) {
+    if (prefixLen > 128) return false;
+    const ipBytes = parseIPv6(ip);
+    const cidrBytes = parseIPv6(cidrIp);
+    if (!ipBytes || !cidrBytes) return false;
+    return matchesPrefixBits(ipBytes, cidrBytes, prefixLen);
+  } else {
+    if (prefixLen > 32) return false;
+    const ipBytes = parseIPv4(ip);
+    const cidrBytes = parseIPv4(cidrIp);
+    if (!ipBytes || !cidrBytes) return false;
+    return matchesPrefixBits(ipBytes, cidrBytes, prefixLen);
+  }
+}
+
+/**
+ * Parse an IPv4 address string to a 4-byte Uint8Array.
+ * Returns null for invalid input.
+ */
+function parseIPv4(ip: string): Uint8Array | null {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return null;
+
+  const bytes = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) {
+    const n = parseInt(parts[i], 10);
+    if (isNaN(n) || n < 0 || n > 255 || parts[i] !== String(n)) return null;
+    bytes[i] = n;
+  }
+  return bytes;
+}
+
+/**
+ * Parse an IPv6 address string to a 16-byte Uint8Array.
+ * Handles '::' shorthand expansion.
+ * Returns null for invalid input.
+ */
+function parseIPv6(ip: string): Uint8Array | null {
+  // Handle :: expansion
+  let halves: string[];
+  if (ip.includes('::')) {
+    const [left, right] = ip.split('::');
+    if (ip.indexOf('::', ip.indexOf('::') + 2) !== -1) return null; // multiple ::
+    const leftGroups = left ? left.split(':') : [];
+    const rightGroups = right ? right.split(':') : [];
+    const missing = 8 - leftGroups.length - rightGroups.length;
+    if (missing < 0) return null;
+    halves = [...leftGroups, ...Array(missing).fill('0'), ...rightGroups];
+  } else {
+    halves = ip.split(':');
+  }
+
+  if (halves.length !== 8) return null;
+
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 8; i++) {
+    const val = parseInt(halves[i], 16);
+    if (isNaN(val) || val < 0 || val > 0xffff) return null;
+    // Validate hex string (no invalid chars)
+    if (!/^[0-9a-fA-F]{1,4}$/.test(halves[i]) && halves[i] !== '0') return null;
+    bytes[i * 2] = (val >> 8) & 0xff;
+    bytes[i * 2 + 1] = val & 0xff;
+  }
+  return bytes;
+}
+
+/**
+ * Compare the first `prefixLen` bits of two byte arrays.
+ * Returns true if they are identical in the prefix range.
+ */
+function matchesPrefixBits(a: Uint8Array, b: Uint8Array, prefixLen: number): boolean {
+  const fullBytes = Math.floor(prefixLen / 8);
+  const remainBits = prefixLen % 8;
+
+  // Compare full bytes
+  for (let i = 0; i < fullBytes; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+
+  // Compare remaining bits with mask
+  if (remainBits > 0 && fullBytes < a.length) {
+    const mask = 0xff << (8 - remainBits);
+    if ((a[fullBytes] & mask) !== (b[fullBytes] & mask)) return false;
+  }
+
+  return true;
+}

package/src/lib/client-ip.ts

@@ -0,0 +1,51 @@
+import { parseConfig } from './do-router.js';
+
+type HeaderReader = Request | { header: (name: string) => string | undefined; raw?: Request };
+
+function readHeader(reader: HeaderReader, name: string): string | undefined {
+  if (reader instanceof Request) {
+    return reader.headers.get(name) ?? undefined;
+  }
+  const direct = reader.header(name);
+  if (direct !== undefined) {
+    return direct;
+  }
+  return reader.raw?.headers.get(name) ?? undefined;
+}
+
+function parseForwardedIp(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const first = value.split(',')[0]?.trim();
+  return first && first.length > 0 ? first : undefined;
+}
+
+function isTrustSelfHostedProxyEnabled(env: unknown): boolean {
+  if (env && typeof env === 'object' && !Array.isArray(env)) {
+    const direct = (env as Record<string, unknown>).trustSelfHostedProxy;
+    if (typeof direct === 'boolean') {
+      return direct;
+    }
+  }
+
+  return parseConfig(env).trustSelfHostedProxy === true;
+}
+
+export function getTrustedClientIp(
+  env: unknown,
+  reader?: HeaderReader,
+): string | undefined {
+  if (!reader) return undefined;
+
+  const cfIp = parseForwardedIp(
+    readHeader(reader, 'cf-connecting-ip') ?? readHeader(reader, 'CF-Connecting-IP'),
+  );
+  if (cfIp) return cfIp;
+
+  if (!isTrustSelfHostedProxyEnabled(env)) {
+    return undefined;
+  }
+
+  return parseForwardedIp(
+    readHeader(reader, 'x-forwarded-for') ?? readHeader(reader, 'X-Forwarded-For'),
+  );
+}