@edge-base/server 0.2.1 → 0.2.3

package/src/lib/functions.ts

@@ -25,19 +25,22 @@ import type {
   ScheduleTrigger,
   HttpTrigger,
 } from '@edge-base/shared';
-import { getDbDoName, getD1BindingName, callDO, shouldRouteToD1 } from './do-router.js';
-import { executeDoSql } from './do-sql.js';
+import { getD1BindingName } from './do-router.js';
 import { D1AuthDb, type AuthDb } from './auth-db-adapter.js';
-import { handleD1Request } from './d1-handler.js';
-import { handlePgRequest } from './postgres-handler.js';
-import { buildInternalHandlerContext } from './internal-request.js';
+import { ensureAuthSchema } from './auth-d1.js';
 import type { Env } from '../types.js';
 import { createSignedToken } from '../routes/storage.js';
 import {
+  createManagedAdminUser,
   deleteManagedAdminUser,
   normalizeAdminUserUpdates,
   updateManagedAdminUser,
 } from './admin-user-management.js';
+import { hashPassword } from './password.js';
+import { generateId } from './uuid.js';
+import { DbRef, TableRef, DefaultDbApi, HttpClient, ContextManager } from '@edge-base/core';
+import { InternalHttpTransport } from './internal-transport.js';
+import { executeProviderAwareSql } from './provider-aware-sql.js';
 
 // ─── Function Context Types ───
 
@@ -48,21 +51,6 @@ export interface AuthContext {
   custom?: Record<string, unknown>;
 }
 
-export interface TableProxy {
-  insert(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-  upsert(
-    data: Record<string, unknown>,
-    options?: { conflictTarget?: string },
-  ): Promise<Record<string, unknown>>;
-  update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-  delete(id: string): Promise<{ deleted: boolean }>;
-  get(id: string): Promise<Record<string, unknown>>;
-  list(options?: {
-    limit?: number;
-    filter?: unknown;
-  }): Promise<{ items: Record<string, unknown>[] }>;
-}
-
 export interface AdminAuthContext {
   getUser(userId: string): Promise<Record<string, unknown>>;
   listUsers(options?: {
@@ -89,22 +77,41 @@ export interface AdminAuthContext {
  */
 export interface FunctionAdminContext {
   /** Cross-DO table access — rules bypassed, Service Key authenticated. */
-  table(name: string): TableProxy;
+  table(name: string): TableRef;
   /**
    * Access a specific DB namespace instance (§5).
-   * Replaces forTenant() — aligned with Database-first architecture (#133).
+   * Uses the same TableRef from @edge-base/core as the client SDK,
+   * ensuring API parity (getList, getOne, where, orderBy, limit, etc.).
    *
    * @example
    * // Static DB
-   * context.admin.db('shared').table('posts').list()
+   * context.admin.db('shared').table('posts').getList()
    * // Dynamic DB (tenant/user)
-   * context.admin.db('workspace', 'ws-456').table('documents').list()
+   * context.admin.db('workspace', 'ws-456').table('documents').getList()
+   * // With query builder
+   * context.admin.db('shared').table('posts').where('status', '==', 'published').limit(10).getList()
    */
-  db(namespace: string, id?: string): { table(name: string): TableProxy };
+  db(namespace: string, id?: string): DbRef;
   /** Admin user management. */
   auth: AdminAuthContext;
-  /** Raw SQL on a DB namespace DO. */
-  sql(
+  /**
+   * Execute raw SQL through the fastest provider-aware path available.
+   * Uses direct PostgreSQL / Neon, D1, or DO execution when possible,
+   * then falls back to the internal HTTP SQL route when needed.
+   *
+   * @example
+   * const rows = await ctx.admin.sqlProviderAware('shared', undefined, 'SELECT * FROM posts WHERE status = ?', ['published']);
+   */
+  sqlProviderAware(
+    namespace: string,
+    id: string | undefined,
+    query: string,
+    params?: unknown[],
+  ): Promise<unknown[]>;
+  /**
+   * @deprecated Use `sqlProviderAware()` instead.
+   */
+  sqlWithDirectD1Access(
     namespace: string,
     id: string | undefined,
     query: string,
@@ -139,9 +146,7 @@ export interface FunctionPushProxy {
     payload: Record<string, unknown>,
   ): Promise<{ sent: number; failed: number; removed: number }>;
   /** Get registered device tokens for a user — token values NOT exposed. */
-  getTokens(
-    userId: string,
-  ): Promise<
+  getTokens(userId: string): Promise<
     Array<{
       deviceId: string;
       platform: string;
@@ -181,12 +186,30 @@ export interface FunctionPushProxy {
 
 /** Storage proxy for App Functions — wraps R2Bucket with convenience methods. */
 export interface FunctionStorageProxy {
-  put(key: string, value: ReadableStream | ArrayBuffer | string, options?: { contentType?: string; customMetadata?: Record<string, string> }): Promise<void>;
-  get(key: string): Promise<{ body: ReadableStream; contentType: string; size: number; customMetadata: Record<string, string> } | null>;
+  put(
+    key: string,
+    value: ReadableStream | ArrayBuffer | string,
+    options?: { contentType?: string; customMetadata?: Record<string, string> },
+  ): Promise<void>;
+  get(key: string): Promise<{
+    body: ReadableStream;
+    contentType: string;
+    size: number;
+    customMetadata: Record<string, string>;
+  } | null>;
   delete(key: string): Promise<void>;
   getSignedUrl(key: string, options?: { expiresIn?: number }): Promise<string>;
-  list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ keys: Array<{ key: string; size: number; contentType: string }>; cursor?: string; truncated: boolean }>;
-  head(key: string): Promise<{ key: string; size: number; contentType: string; customMetadata: Record<string, string> } | null>;
+  list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{
+    keys: Array<{ key: string; size: number; contentType: string }>;
+    cursor?: string;
+    truncated: boolean;
+  }>;
+  head(key: string): Promise<{
+    key: string;
+    size: number;
+    contentType: string;
+    customMetadata: Record<string, string>;
+  } | null>;
 }
 
 /** KV proxy for App Functions — routes through Worker HTTP. */
@@ -291,20 +314,21 @@ export interface FunctionContext {
    *
    * @example
    * // Static DB
-   * await context.db('shared').table('posts').list()
+   * await context.db('shared').table('posts').getList()
    * // Dynamic DB
-   * await context.db('workspace', 'ws-456').table('documents').list()
+   * await context.db('workspace', 'ws-456').table('documents').getList()
+   * // With query builder
+   * await context.db('shared').table('posts').where('status', '==', 'published').limit(10).getList()
    */
   db: FunctionAdminContext['db'];
   /**
-   * Server-side EdgeBase admin client (§5,).
+   * Server-side EdgeBase admin client (§5).
    * Use context.admin.db(namespace, id?).table(name) for all DB access.
+   * Uses the same TableRef from @edge-base/core as the client SDK.
    *
    * @example
-   * // Static DB
-   * await context.admin.db('shared').table('posts').list()
-   * // Dynamic DB
-   * await context.admin.db('workspace', 'ws-456').table('documents').list()
+   * await context.admin.db('shared').table('posts').getList()
+   * await context.admin.db('shared').table('posts').where('userId', '==', uid).getList()
    */
   admin: FunctionAdminContext;
   /**
@@ -365,13 +389,14 @@ function getRegistryName(key: string, def: FunctionDefinition): string {
 
 export function registerFunction(name: string, def: FunctionDefinition): void {
   if (!def || typeof def !== 'object' || !def.trigger) {
-    const received = typeof def === 'function'
-      ? 'a plain function'
-      : `${typeof def} (${JSON.stringify(def)?.slice(0, 100)})`;
+    const received =
+      typeof def === 'function'
+        ? 'a plain function'
+        : `${typeof def} (${JSON.stringify(def)?.slice(0, 100)})`;
     throw new Error(
       `registerFunction('${name}'): expected a FunctionDefinition with a 'trigger' property, but received ${received}. ` +
-      `Functions must use defineFunction() from '@edge-base/shared' and be exported as named HTTP method exports ` +
-      `(e.g. export const GET = defineFunction(...)). See https://docs.edgebase.dev/functions for details.`,
+        `Functions must use defineFunction() from '@edge-base/shared' and be exported as named HTTP method exports ` +
+        `(e.g. export const GET = defineFunction(...)). See https://docs.edgebase.dev/functions for details.`,
     );
   }
   functionRegistry.set(buildRegistryKey(name, def), def);
@@ -678,7 +703,12 @@ export function wrapMethodExport(
   } else if (handler && typeof handler === 'object') {
     fn = (handler.handler ?? handler) as unknown as (ctx: unknown) => Promise<unknown>;
     captcha = handler.captcha;
-    if ('trigger' in handler && handler.trigger && typeof handler.trigger === 'object' && 'path' in handler.trigger) {
+    if (
+      'trigger' in handler &&
+      handler.trigger &&
+      typeof handler.trigger === 'object' &&
+      'path' in handler.trigger
+    ) {
       const triggerPath = handler.trigger.path;
       path = typeof triggerPath === 'string' ? triggerPath : undefined;
     }
@@ -697,284 +727,7 @@ export function wrapMethodExport(
   };
 }
 
-// ─── Table Proxy (Cross-DO) ───
-
-/**
- * Build a cross-DO table proxy.
- * All calls bypass access rules by using Service Key.
- */
-function buildTableProxy(
-  tableName: string,
-  namespace: DurableObjectNamespace,
-  config: EdgeBaseConfig,
-  workerUrl?: string,
-  serviceKey?: string,
-  env?: Env,
-  executionCtx?: ExecutionContext,
-  /** DB routing info (§5). If provided, overrides auto-detect. */
-  dbTarget?: { namespace: string; id?: string; doName: string },
-  routingOptions?: { preferDirectDo?: boolean },
-): TableProxy {
-  // Determine DO name: explicit DB target (§5) or auto-detect from config
-  let resolvedTarget: { namespace: string; id?: string; doName: string };
-  if (dbTarget) {
-    resolvedTarget = dbTarget;
-  } else {
-    // Auto-detect namespace for this table from config (§1)
-    let tableNamespace = 'shared';
-    for (const [ns, dbBlock] of Object.entries(config.databases ?? {})) {
-      if (dbBlock.tables?.[tableName]) {
-        tableNamespace = ns;
-        break;
-      }
-    }
-    resolvedTarget = {
-      namespace: tableNamespace,
-      doName: getDbDoName(tableNamespace),
-    };
-  }
-  const doName = resolvedTarget.doName;
-  const headers: Record<string, string> = { 'X-DO-Name': doName };
-  if (serviceKey) {
-    headers['X-EdgeBase-Service-Key'] = serviceKey;
-  }
-  // Add internal header to bypass rules
-  headers['X-EdgeBase-Internal'] = 'true';
-
-  const buildTablePath = (id?: string, query?: URLSearchParams): string => {
-    const base = resolvedTarget.id !== undefined
-      ? `/api/db/${resolvedTarget.namespace}/${resolvedTarget.id}/tables/${tableName}`
-      : `/api/db/${resolvedTarget.namespace}/tables/${tableName}`;
-    const withId = id ? `${base}/${id}` : base;
-    const search = query && Array.from(query.keys()).length > 0 ? `?${query.toString()}` : '';
-    return `${withId}${search}`;
-  };
-  const buildDirectTablePath = (id?: string, query?: URLSearchParams): string => {
-    const base = `/tables/${tableName}`;
-    const withId = id ? `${base}/${id}` : base;
-    const search = query && Array.from(query.keys()).length > 0 ? `?${query.toString()}` : '';
-    return `${withId}${search}`;
-  };
-
-  const requestViaWorker = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    path: string,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    return fetch(`${workerUrl}${path}`, {
-      method,
-      headers: {
-        'Content-Type': 'application/json',
-        ...headers,
-      },
-      body: body === undefined || method === 'GET' || method === 'DELETE'
-        ? undefined
-        : JSON.stringify(body),
-    });
-  };
-  const requestViaD1Handler = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    directPath: string,
-    query?: URLSearchParams,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    if (!env) {
-      throw new Error('D1 table proxy requires env.');
-    }
-
-    const request = new Request(
-      `http://internal/api/db/${resolvedTarget.namespace}${resolvedTarget.id ? `/${resolvedTarget.id}` : ''}${buildDirectTablePath(undefined, query).replace('/tables/' + tableName, directPath)}`,
-      {
-        method,
-        headers: {
-          'Content-Type': 'application/json',
-          ...headers,
-        },
-        body: body === undefined || method === 'GET' || method === 'DELETE'
-          ? undefined
-          : JSON.stringify(body),
-      },
-    );
-
-    return handleD1Request(
-      buildInternalHandlerContext({
-        env,
-        request,
-        body,
-        executionCtx,
-      }),
-      resolvedTarget.namespace,
-      tableName,
-      directPath,
-    );
-  };
-  const requestViaPgHandler = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    directPath: string,
-    query?: URLSearchParams,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    if (!env) {
-      throw new Error('PostgreSQL table proxy requires env.');
-    }
-
-    const request = new Request(
-      `http://internal/api/db/${resolvedTarget.namespace}${resolvedTarget.id ? `/${resolvedTarget.id}` : ''}${buildDirectTablePath(undefined, query).replace('/tables/' + tableName, directPath)}`,
-      {
-        method,
-        headers: {
-          'Content-Type': 'application/json',
-          ...headers,
-        },
-        body: body === undefined || method === 'GET' || method === 'DELETE'
-          ? undefined
-          : JSON.stringify(body),
-      },
-    );
-
-    return handlePgRequest(
-      buildInternalHandlerContext({
-        env,
-        request,
-        body,
-        executionCtx,
-      }),
-      resolvedTarget.namespace,
-      tableName,
-      directPath,
-    );
-  };
-  const requestViaDirectDo = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    directPath: string,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    const res = await callDO(namespace, doName, directPath, {
-      method,
-      body,
-      headers,
-    });
-
-    if (!resolvedTarget.id || res.status !== 201) {
-      return res;
-    }
-
-    const createPayload = await res.clone().json().catch(() => null) as
-      | { needsCreate?: boolean }
-      | null;
-    if (!createPayload?.needsCreate) {
-      return res;
-    }
-
-    return callDO(namespace, doName, directPath, {
-      method,
-      body,
-      headers: {
-        ...headers,
-        'X-DO-Create-Authorized': '1',
-      },
-    });
-  };
-  const requestTable = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    id?: string,
-    body?: Record<string, unknown>,
-    query?: URLSearchParams,
-  ): Promise<Response> => {
-    const directPath = buildDirectTablePath(id);
-    const directPathWithQuery = buildDirectTablePath(id, query);
-    const provider = config.databases?.[resolvedTarget.namespace]?.provider;
-
-    if (!routingOptions?.preferDirectDo && shouldRouteToD1(resolvedTarget.namespace, config) && env) {
-      return requestViaD1Handler(method, directPath, query, body);
-    }
-    if ((provider === 'neon' || provider === 'postgres') && env) {
-      return requestViaPgHandler(method, directPath, query, body);
-    }
-    if (env) {
-      return requestViaDirectDo(method, directPathWithQuery, body);
-    }
-    if (workerUrl) {
-      return requestViaWorker(method, buildTablePath(id, query), body);
-    }
-    return requestViaDirectDo(method, directPathWithQuery, body);
-  };
-
-  const insert = async (data: Record<string, unknown>): Promise<Record<string, unknown>> => {
-    const res = await requestTable('POST', undefined, data);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO insert failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const upsert = async (
-    data: Record<string, unknown>,
-    options?: { conflictTarget?: string },
-  ): Promise<Record<string, unknown>> => {
-    const query = new URLSearchParams();
-    query.set('upsert', 'true');
-    if (options?.conflictTarget) {
-      query.set('conflictTarget', options.conflictTarget);
-    }
-
-    const res = await requestTable('POST', undefined, data, query);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO upsert failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const update = async (
-    id: string,
-    data: Record<string, unknown>,
-  ): Promise<Record<string, unknown>> => {
-    const res = await requestTable('PATCH', id, data);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO update failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const del = async (id: string): Promise<{ deleted: boolean }> => {
-    const res = await requestTable('DELETE', id);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO delete failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as { deleted: boolean };
-  };
-
-  const get = async (id: string): Promise<Record<string, unknown>> => {
-    const res = await requestTable('GET', id);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO get failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const list = async (listOptions?: {
-    limit?: number;
-    filter?: unknown;
-  }): Promise<{ items: Record<string, unknown>[] }> => {
-    const query = new URLSearchParams();
-    if (listOptions?.limit) query.set('limit', String(listOptions.limit));
-    if (listOptions?.filter) query.set('filter', JSON.stringify(listOptions.filter));
-
-    const res = await requestTable('GET', undefined, undefined, query);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO list failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as { items: Record<string, unknown>[] };
-  };
-
-  return { insert, upsert, update, delete: del, get, list };
-}
+// ─── Admin DB Proxy (uses @edge-base/core TableRef via InternalHttpTransport) ───
 
 interface BuildAdminDbProxyOptions {
   databaseNamespace: DurableObjectNamespace;
@@ -986,25 +739,111 @@ interface BuildAdminDbProxyOptions {
   preferDirectDo?: boolean;
 }
 
+// ─── Shared SQL executor — provider-aware direct paths → HTTP fallback ───
+
+export interface SqlProviderAwareOptions {
+  env?: Env;
+  config: EdgeBaseConfig;
+  databaseNamespace?: DurableObjectNamespace;
+  workerUrl?: string;
+  serviceKey?: string;
+}
+
+/**
+ * Execute raw SQL with the fastest provider-aware path:
+ * 1. PostgreSQL / Neon direct query path
+ * 2. D1 direct binding
+ * 3. Durable Object direct call
+ * 4. HTTP fallback via workerUrl
+ *
+ * Shared by buildFunctionContext, auth hooks, storage hooks, and plugin migrations.
+ */
+export async function executeSqlProviderAware(
+  opts: SqlProviderAwareOptions,
+  namespace: string,
+  id: string | undefined,
+  query: string,
+  params?: unknown[],
+): Promise<unknown[]> {
+  const result = await executeProviderAwareSql(
+    {
+      env: opts.env,
+      config: opts.config,
+      databaseNamespace: opts.databaseNamespace,
+      workerUrl: opts.workerUrl,
+      serviceKey: opts.serviceKey,
+    },
+    namespace,
+    id,
+    query,
+    params ?? [],
+  );
+  return result.rows;
+}
+
+// Backwards-compatible aliases for existing internal callers and public surfaces.
+export const executeSqlWithDirectBindingAccess = executeSqlProviderAware;
+export const executeSqlWithDirectD1Access = executeSqlProviderAware;
+
+/**
+ * Build the admin DB proxy that returns real DbRef/TableRef instances
+ * from @edge-base/core, routed through InternalHttpTransport for
+ * direct D1/PG/DO access (no HTTP round-trip).
+ */
 export function buildAdminDbProxy(options: BuildAdminDbProxyOptions): FunctionAdminContext['db'] {
-  return (namespace: string, id?: string) => {
-    const doName = getDbDoName(namespace, id);
-
-    return {
-      table(tableName: string): TableProxy {
-        return buildTableProxy(
-          tableName,
-          options.databaseNamespace,
-          options.config,
-          options.workerUrl,
-          options.serviceKey,
-          options.env,
-          options.executionCtx,
-          { namespace, id, doName },
-          { preferDirectDo: options.preferDirectDo },
-        );
+  // Create HttpClient fallback for sql() tagged template support on TableRef.
+  // Trusted server contexts also receive a direct SQL executor below.
+  let httpClient: HttpClient | undefined;
+  if (options.workerUrl) {
+    httpClient = new HttpClient({
+      baseUrl: options.workerUrl,
+      serviceKey: options.serviceKey,
+      contextManager: new ContextManager(),
+    });
+  }
+  const sqlExecutor = (
+    namespace: string,
+    id: string | undefined,
+    query: string,
+    params?: unknown[],
+  ) =>
+    executeSqlProviderAware(
+      {
+        env: options.env,
+        config: options.config,
+        databaseNamespace: options.databaseNamespace,
+        workerUrl: options.workerUrl,
+        serviceKey: options.serviceKey,
       },
-    };
+      namespace,
+      id,
+      query,
+      params,
+    );
+
+  return (namespace: string, id?: string): DbRef => {
+    // Create a per-DbRef transport with explicit dbContext so that
+    // path parsing is unambiguous even when instanceId === 'tables'.
+    const transport = new InternalHttpTransport({
+      databaseNamespace: options.databaseNamespace,
+      config: options.config,
+      workerUrl: options.workerUrl,
+      serviceKey: options.serviceKey,
+      env: options.env,
+      executionCtx: options.executionCtx,
+      preferDirectDo: options.preferDirectDo,
+      dbContext: { namespace, instanceId: id },
+    });
+    const dbApi = new DefaultDbApi(transport);
+    return new DbRef(
+      dbApi,
+      namespace,
+      id,
+      undefined, // databaseLiveClient — not available server-side
+      undefined, // filterMatchFn
+      httpClient, // enables table().sql`...` tagged template
+      sqlExecutor,
+    );
   };
 }
 
@@ -1024,7 +863,7 @@ interface AdminAuthOptions {
 /**
  * Build admin auth context for App Functions.
  * Uses AUTH_DB D1 directly for all operations (D1-first architecture).
- * Cross-shard operations (listUsers, createUser) also available via Worker HTTP relay
+ * Cross-shard operations (listUsers) also available via Worker HTTP relay
  * when workerUrl is provided.
  */
 export function buildAdminAuthContext(options: AdminAuthOptions): AdminAuthContext {
@@ -1089,10 +928,51 @@ export function buildAdminAuthContext(options: AdminAuthOptions): AdminAuthConte
       displayName?: string;
       role?: string;
     }): Promise<Record<string, unknown>> {
+      // Direct D1 path — works without service key (same as updateUser/deleteUser)
+      if (d1Database) {
+        // Input validation (mirrors routes/admin-auth.ts guards)
+        if (!data.email || typeof data.email !== 'string')
+          throw new Error('Email and password are required.');
+        if (!data.password || typeof data.password !== 'string')
+          throw new Error('Email and password are required.');
+        const email = data.email.trim().toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+          throw new Error('Invalid email format.');
+        }
+        if (data.password.length < 8) throw new Error('Password must be at least 8 characters.');
+        if (data.password.length > 256) throw new Error('Password must not exceed 256 characters.');
+        if (data.displayName && data.displayName.length > 200) {
+          throw new Error('Display name must not exceed 200 characters.');
+        }
+        // Role validation (mirrors normalizeOptionalRole in routes/admin-auth.ts)
+        let role = 'user';
+        if (data.role !== undefined) {
+          if (typeof data.role !== 'string') throw new Error('Role must be a non-empty string.');
+          const trimmed = data.role.trim();
+          if (!trimmed) throw new Error('Role must be a non-empty string.');
+          if (trimmed.length > 100) throw new Error('Role must not exceed 100 characters.');
+          role = trimmed;
+        }
+
+        const db = new D1AuthDb(d1Database);
+        // Ensure auth tables exist (critical for fresh databases)
+        await ensureAuthSchema(db);
+        const user = await createManagedAdminUser(
+          db,
+          {
+            userId: generateId(),
+            email,
+            passwordHash: await hashPassword(data.password),
+            displayName: data.displayName,
+            role,
+            verified: true,
+          },
+          { kv: kvNamespace },
+        );
+        return authService.sanitizeUser(user, { includeAppMetadata: true });
+      }
       if (workerUrl && serviceKey) {
-        // HTTP relay: POST /api/auth/admin/users → Worker → D1
-        // createUser has complex side effects (email index, _users_public, etc.)
-        // so it routes through the admin route which handles the full flow.
+        // HTTP relay fallback: POST /api/auth/admin/users → Worker → D1
         const res = await fetch(`${workerUrl}/api/auth/admin/users`, {
           method: 'POST',
           headers: {
@@ -1111,7 +991,7 @@ export function buildAdminAuthContext(options: AdminAuthOptions): AdminAuthConte
         return result.user;
       }
       throw new Error(
-        'admin.auth.createUser() is not available in this context (requires workerUrl). ' +
+        'admin.auth.createUser() is not available in this context (requires D1 or workerUrl). ' +
           'Pass workerUrl to buildFunctionContext(), or use the external SDK.',
       );
     },
@@ -1215,6 +1095,25 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
     executionCtx: options.executionCtx,
     preferDirectDo: options.preferDirectDoDb,
   });
+  const sqlProviderAware = (
+    namespace: string,
+    id: string | undefined,
+    query: string,
+    params?: unknown[],
+  ) =>
+    executeSqlProviderAware(
+      {
+        env: options.env,
+        config: options.config,
+        databaseNamespace: options.databaseNamespace,
+        workerUrl: options.workerUrl,
+        serviceKey: options.serviceKey,
+      },
+      namespace,
+      id,
+      query,
+      params,
+    );
 
   // ─── context.admin — AdminEdgeBase-shaped internal proxy ───
   const admin: FunctionAdminContext = {
@@ -1223,77 +1122,9 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
     // ─── context.admin.db(namespace, id) — DB-first tenant access (§5) ───
     db: adminDb,
     auth: adminAuthContext,
-    async sql(
-      namespace: string,
-      id: string | undefined,
-      query: string,
-      params?: unknown[],
-    ): Promise<unknown[]> {
-      if (options.env) {
-        const dbBlock = options.config.databases?.[namespace];
-        const isDynamicNamespace = !!(dbBlock?.instance || dbBlock?.access?.canCreate || dbBlock?.access?.access);
-        if (isDynamicNamespace && !id) {
-          throw new Error(`admin.sql() requires an id for dynamic namespace '${namespace}'.`);
-        }
-
-        if (!id && shouldRouteToD1(namespace, options.config)) {
-          const bindingName = getD1BindingName(namespace);
-          const d1 = (options.env as unknown as Record<string, unknown>)[bindingName] as D1Database | undefined;
-          if (!d1) {
-            throw new Error(`D1 binding '${bindingName}' not found.`);
-          }
-          try {
-            const stmt = d1.prepare(query);
-            const bound = params && params.length > 0 ? stmt.bind(...params) : stmt;
-            const result = await bound.all();
-            const rows = (result.results ?? []) as unknown[];
-            return rows;
-          } catch (error) {
-            const message = error instanceof Error ? error.message : 'SQL execution failed';
-            throw new Error(message);
-          }
-        }
-
-        return executeDoSql({
-          databaseNamespace: options.databaseNamespace,
-          namespace,
-          id,
-          query,
-          params: params ?? [],
-          internal: true,
-        });
-      }
-
-      if (options.workerUrl && options.serviceKey) {
-        // HTTP route: POST /api/sql → Worker → DatabaseDO (§11)
-        const res = await fetch(`${options.workerUrl}/api/sql`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'X-EdgeBase-Service-Key': options.serviceKey,
-          },
-          body: JSON.stringify({ namespace, id, sql: query, params: params ?? [] }),
-        });
-        if (!res.ok) {
-          const err = (await res.json().catch(() => ({ message: 'SQL execution failed' }))) as {
-            message: string;
-          };
-          throw new Error(err.message);
-        }
-        const data = (await res.json()) as {
-          rows?: unknown[];
-          items?: unknown[];
-          results?: unknown[];
-        };
-        if (Array.isArray(data.rows)) return data.rows;
-        if (Array.isArray(data.items)) return data.items;
-        if (Array.isArray(data.results)) return data.results;
-        return [];
-      }
-      throw new Error(
-        'admin.sql() requires workerUrl. Pass workerUrl to buildFunctionContext(), or use the external SDK.',
-      );
-    },
+    // ─── Direct provider-aware SQL — delegates to shared executor ───
+    sqlProviderAware,
+    sqlWithDirectD1Access: sqlProviderAware,
     async broadcast(
       channel: string,
       event: string,
@@ -1302,11 +1133,13 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
       if (options.env?.DATABASE_LIVE) {
         const hubId = options.env.DATABASE_LIVE.idFromName('database-live:hub');
         const stub = options.env.DATABASE_LIVE.get(hubId);
-        const response = await stub.fetch(new Request('http://do/internal/broadcast', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ channel, event, payload: payload ?? {} }),
-        }));
+        const response = await stub.fetch(
+          new Request('http://do/internal/broadcast', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ channel, event, payload: payload ?? {} }),
+          }),
+        );
         if (!response.ok) {
           throw new Error(`client.broadcast() failed: ${response.status}`);
         }
@@ -1354,9 +1187,7 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
               method: 'POST',
               headers: {
                 'Content-Type': 'application/json',
-                ...(options.serviceKey
-                  ? { 'X-EdgeBase-Service-Key': options.serviceKey }
-                  : {}),
+                ...(options.serviceKey ? { 'X-EdgeBase-Service-Key': options.serviceKey } : {}),
                 'X-EdgeBase-Call-Depth': String(currentDepth + 1),
               },
               body: JSON.stringify(data ?? {}),
@@ -1414,13 +1245,31 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
 
     // KV / D1 / Vectorize proxies
     kv(namespace: string): FunctionKvProxy {
-      return buildFunctionKvProxy(namespace, options.config, options.env, options.workerUrl, options.serviceKey);
+      return buildFunctionKvProxy(
+        namespace,
+        options.config,
+        options.env,
+        options.workerUrl,
+        options.serviceKey,
+      );
     },
     d1(database: string): FunctionD1Proxy {
-      return buildFunctionD1Proxy(database, options.config, options.env, options.workerUrl, options.serviceKey);
+      return buildFunctionD1Proxy(
+        database,
+        options.config,
+        options.env,
+        options.workerUrl,
+        options.serviceKey,
+      );
     },
     vector(index: string): FunctionVectorizeProxy {
-      return buildFunctionVectorizeProxy(index, options.config, options.env, options.workerUrl, options.serviceKey);
+      return buildFunctionVectorizeProxy(
+        index,
+        options.config,
+        options.env,
+        options.workerUrl,
+        options.serviceKey,
+      );
     },
 
     // Push notification management
@@ -1659,11 +1508,14 @@ export function buildFunctionD1Proxy(
   return {
     async exec<T = Record<string, unknown>>(query: string, params?: unknown[]): Promise<T[]> {
       if (config && env) {
-        const bindingName = config.d1?.[database]?.binding
-          ?? (database === 'auth' ? 'AUTH_DB' : undefined)
-          ?? (database === 'control' ? 'CONTROL_DB' : undefined)
-          ?? getD1BindingName(database);
-        const binding = (env as unknown as Record<string, unknown>)[bindingName] as D1Database | undefined;
+        const bindingName =
+          config.d1?.[database]?.binding ??
+          (database === 'auth' ? 'AUTH_DB' : undefined) ??
+          (database === 'control' ? 'CONTROL_DB' : undefined) ??
+          getD1BindingName(database);
+        const binding = (env as unknown as Record<string, unknown>)[bindingName] as
+          | D1Database
+          | undefined;
         if (!binding) {
           throw new Error(`D1 binding '${bindingName}' not found.`);
         }
@@ -1715,7 +1567,7 @@ export function buildFunctionVectorizeProxy(
     if (values instanceof Float32Array || values instanceof Float64Array) {
       return Array.from(values);
     }
-    return Array.isArray(values) ? values as number[] : undefined;
+    return Array.isArray(values) ? (values as number[]) : undefined;
   };
 
   const mapMatches = (
@@ -1726,15 +1578,19 @@ export function buildFunctionVectorizeProxy(
       metadata?: Record<string, unknown>;
       namespace?: string;
     }>,
-  ) => matches.map((match) => ({
-    id: match.id,
-    score: match.score,
-    ...(match.values !== undefined ? { values: normalizeValues(match.values) } : {}),
-    ...(match.metadata !== undefined ? { metadata: match.metadata } : {}),
-    ...(match.namespace ? { namespace: match.namespace } : {}),
-  }));
-
-  const withNamespace = <T extends { namespace?: string }>(vectors: T[], namespace?: string): T[] => {
+  ) =>
+    matches.map((match) => ({
+      id: match.id,
+      score: match.score,
+      ...(match.values !== undefined ? { values: normalizeValues(match.values) } : {}),
+      ...(match.metadata !== undefined ? { metadata: match.metadata } : {}),
+      ...(match.namespace ? { namespace: match.namespace } : {}),
+    }));
+
+  const withNamespace = <T extends { namespace?: string }>(
+    vectors: T[],
+    namespace?: string,
+  ): T[] => {
     if (!namespace) return vectors;
     return vectors.map((vector) => (vector.namespace ? vector : { ...vector, namespace }));
   };
@@ -1752,7 +1608,10 @@ export function buildFunctionVectorizeProxy(
     if (directBinding) {
       switch (body.action) {
         case 'upsert': {
-          const vectors = withNamespace(body.vectors as VectorizeVector[], body.namespace as string | undefined);
+          const vectors = withNamespace(
+            body.vectors as VectorizeVector[],
+            body.namespace as string | undefined,
+          );
           let count = 0;
           let mutationId: string | undefined;
           for (const chunk of chunkArray(vectors, VECTOR_BATCH_LIMIT)) {
@@ -1765,7 +1624,10 @@ export function buildFunctionVectorizeProxy(
           return { count, ...(mutationId ? { mutationId } : {}) };
         }
         case 'insert': {
-          const vectors = withNamespace(body.vectors as VectorizeVector[], body.namespace as string | undefined);
+          const vectors = withNamespace(
+            body.vectors as VectorizeVector[],
+            body.namespace as string | undefined,
+          );
           let count = 0;
           let mutationId: string | undefined;
           for (const chunk of chunkArray(vectors, VECTOR_BATCH_LIMIT)) {
@@ -1788,9 +1650,11 @@ export function buildFunctionVectorizeProxy(
           return { matches: mapMatches(result.matches), count: result.count };
         }
         case 'queryById': {
-          const queryById = (directBinding as unknown as {
-            queryById?: (id: string, opts?: VectorizeQueryOptions) => Promise<VectorizeMatches>;
-          }).queryById;
+          const queryById = (
+            directBinding as unknown as {
+              queryById?: (id: string, opts?: VectorizeQueryOptions) => Promise<VectorizeMatches>;
+            }
+          ).queryById;
           if (typeof queryById !== 'function') {
             throw new Error('queryById is not available on this Vectorize binding');
           }
@@ -1805,7 +1669,11 @@ export function buildFunctionVectorizeProxy(
         }
         case 'getByIds': {
           const vectors = (
-            await Promise.all(chunkArray(body.ids as string[], VECTOR_BATCH_LIMIT).map((chunk) => directBinding.getByIds(chunk)))
+            await Promise.all(
+              chunkArray(body.ids as string[], VECTOR_BATCH_LIMIT).map((chunk) =>
+                directBinding.getByIds(chunk),
+              ),
+            )
           ).flat();
           return {
             vectors: vectors.map((vector) => ({
@@ -1833,12 +1701,22 @@ export function buildFunctionVectorizeProxy(
           const details = info as unknown as Record<string, unknown>;
           return {
             vectorCount: details.vectorCount ?? details.vectorsCount ?? 0,
-            dimensions: details.dimensions ?? (details.config as Record<string, unknown> | undefined)?.dimensions ?? 0,
-            metric: details.metric ?? (details.config as Record<string, unknown> | undefined)?.metric ?? 'cosine',
+            dimensions:
+              details.dimensions ??
+              (details.config as Record<string, unknown> | undefined)?.dimensions ??
+              0,
+            metric:
+              details.metric ??
+              (details.config as Record<string, unknown> | undefined)?.metric ??
+              'cosine',
             ...('id' in details ? { id: details.id } : {}),
             ...('name' in details ? { name: details.name } : {}),
-            ...('processedUpToDatetime' in details ? { processedUpToDatetime: details.processedUpToDatetime } : {}),
-            ...('processedUpToMutation' in details ? { processedUpToMutation: details.processedUpToMutation } : {}),
+            ...('processedUpToDatetime' in details
+              ? { processedUpToDatetime: details.processedUpToDatetime }
+              : {}),
+            ...('processedUpToMutation' in details
+              ? { processedUpToMutation: details.processedUpToMutation }
+              : {}),
           };
         }
       }