@edge-base/server 0.2.4 → 0.2.6

package/src/lib/d1-handler.ts

@@ -126,6 +126,21 @@ export async function handleD1Request(
   return c.json({ code: 405, message: 'Method not allowed' }, 405);
 }
 
+function invalidD1BodyMessage(context: string): string {
+  return `Invalid JSON body for ${context}. Send application/json with the expected fields.`;
+}
+
+function d1RuleRejectedMessage(
+  tableName: string,
+  action: 'read' | 'insert' | 'delete' | 'list' | 'count' | 'search',
+  id?: string,
+): string {
+  if (id) {
+    return `Access denied. The '${action}' access rule for table '${tableName}' rejected record '${id}'.`;
+  }
+  return `Access denied. The '${action}' access rule for table '${tableName}' rejected this request.`;
+}
+
 // ─── D1 Binding Resolution ───
 
 function resolveD1Binding(env: Env, namespace: string): D1ResolvedDb {
@@ -395,7 +410,7 @@ async function handleList(
 ): Promise<Response> {
   const tableAccess = getTableAccess(tableConfig);
   if (!isServiceKey && tableAccess?.read === false) {
-    const error = forbiddenError('Access denied.');
+    const error = forbiddenError(d1RuleRejectedMessage(tableName, 'list'));
     return c.json(error.toJSON(), error.status as 403);
   }
 
@@ -478,7 +493,7 @@ async function handleCount(
 ): Promise<Response> {
   const tableAccess = getTableAccess(tableConfig);
   if (!isServiceKey && tableAccess?.read === false) {
-    const error = forbiddenError('Access denied.');
+    const error = forbiddenError(d1RuleRejectedMessage(tableName, 'count'));
     return c.json(error.toJSON(), error.status as 403);
   }
 
@@ -501,7 +516,7 @@ async function handleSearch(
 ): Promise<Response> {
   const tableAccess = getTableAccess(tableConfig);
   if (!isServiceKey && tableAccess?.read === false) {
-    const error = forbiddenError('Access denied.');
+    const error = forbiddenError(d1RuleRejectedMessage(tableName, 'search'));
     return c.json(error.toJSON(), error.status as 403);
   }
 
@@ -595,7 +610,7 @@ async function handleGet(
   const tableHooks = getTableHooks(tableConfig);
   if (!isServiceKey && tableAccess?.read !== undefined) {
     if (!(await evalRowRule(tableAccess.read, auth, row))) {
-      return c.json({ code: 403, message: 'Access denied.' }, 403);
+      return c.json({ code: 403, message: d1RuleRejectedMessage(tableName, 'read', id) }, 403);
     }
   }
 
@@ -627,7 +642,7 @@ async function handleInsert(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidD1BodyMessage(`inserting into table '${tableName}'`) }, 400);
   }
   body = applySchemaFieldAliases(body, tableConfig.schema);
 
@@ -636,7 +651,7 @@ async function handleInsert(
   const tableHooks = getTableHooks(tableConfig);
   if (!isServiceKey && tableAccess?.insert !== undefined) {
     if (!(await evalInsertRule(tableAccess.insert, auth))) {
-      return c.json({ code: 403, message: 'Insert not allowed.' }, 403);
+      return c.json({ code: 403, message: d1RuleRejectedMessage(tableName, 'insert') }, 403);
     }
   }
 
@@ -798,14 +813,14 @@ async function handleUpdate(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidD1BodyMessage(`updating table '${tableName}'`) }, 400);
   }
   body = applySchemaFieldAliases(body, tableConfig.schema);
 
   // Validate against schema
   const validation = validateUpdate(body, tableConfig.schema);
   if (!validation.valid) {
-    return c.json({ code: 400, message: 'Request body failed validation. See data for field-level errors.', data: Object.fromEntries(Object.entries(validation.errors).map(([k, v]) => [k, { code: 'invalid', message: v }])) }, 400);
+    return c.json({ code: 400, message: `Update payload for table '${tableName}' failed validation. See data for field-level errors.`, data: Object.fromEntries(Object.entries(validation.errors).map(([k, v]) => [k, { code: 'invalid', message: v }])) }, 400);
   }
 
   // Fetch existing record to check rules
@@ -946,7 +961,7 @@ async function handleDelete(
   const tableHooks = getTableHooks(tableConfig);
   if (!isServiceKey && tableAccess?.delete !== undefined) {
     if (!(await evalRowRule(tableAccess.delete, auth, existingRow))) {
-      return c.json({ code: 403, message: 'Delete not allowed.' }, 403);
+      return c.json({ code: 403, message: d1RuleRejectedMessage(tableName, 'delete', id) }, 403);
     }
   }
 
@@ -1016,7 +1031,7 @@ async function handleBatch(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidD1BodyMessage(`batch operations on table '${tableName}'`) }, 400);
   }
 
   // Batch size limit: 500 total ops
@@ -1030,7 +1045,7 @@ async function handleBatch(
   const tableAccess = getTableAccess(tableConfig);
   if (!isServiceKey && body.inserts?.length && tableAccess?.insert !== undefined) {
     if (!(await evalInsertRule(tableAccess.insert, auth))) {
-      return c.json({ code: 403, message: 'Insert not allowed.' }, 403);
+      return c.json({ code: 403, message: d1RuleRejectedMessage(tableName, 'insert') }, 403);
     }
   }
 
@@ -1059,7 +1074,7 @@ async function handleBatch(
     for (const item of body.inserts) {
       const validation = validateInsert(item, tableConfig.schema);
       if (!validation.valid) {
-        return c.json({ code: 400, message: 'Batch insert request failed validation. See data for field-level errors.', data: Object.fromEntries(Object.entries(validation.errors).map(([k, v]) => [k, { code: 'invalid', message: v }])) }, 400);
+        return c.json({ code: 400, message: `Batch insert payload for table '${tableName}' failed validation. See data for field-level errors.`, data: Object.fromEntries(Object.entries(validation.errors).map(([k, v]) => [k, { code: 'invalid', message: v }])) }, 400);
       }
     }
   }
@@ -1072,14 +1087,14 @@ async function handleBatch(
     }));
     for (const entry of body.updates) {
       if (!entry.id) {
-        return c.json({ code: 400, message: 'Each batch update entry must include an id.' }, 400);
+        return c.json({ code: 400, message: `Each batch update entry for table '${tableName}' must include an id.` }, 400);
       }
       if (!entry.data || typeof entry.data !== 'object') {
-        return c.json({ code: 400, message: 'Each batch update entry must include a data object.' }, 400);
+        return c.json({ code: 400, message: `Each batch update entry for table '${tableName}' must include a data object.` }, 400);
       }
       const validation = validateUpdate(entry.data, tableConfig.schema);
       if (!validation.valid) {
-        return c.json({ code: 400, message: 'Batch update request failed validation. See data for field-level errors.', data: Object.fromEntries(Object.entries(validation.errors).map(([k, v]) => [k, { code: 'invalid', message: v }])) }, 400);
+        return c.json({ code: 400, message: `Batch update payload for table '${tableName}' failed validation. See data for field-level errors.`, data: Object.fromEntries(Object.entries(validation.errors).map(([k, v]) => [k, { code: 'invalid', message: v }])) }, 400);
       }
     }
   }
@@ -1087,7 +1102,7 @@ async function handleBatch(
   // Check delete rules (table-level)
   if (!isServiceKey && body.deletes?.length && tableAccess?.delete !== undefined) {
     if (!(await evalRowRule(tableAccess.delete, auth, {}))) {
-      return c.json({ code: 403, message: 'Delete not allowed.' }, 403);
+      return c.json({ code: 403, message: d1RuleRejectedMessage(tableName, 'delete') }, 403);
     }
   }
 
@@ -1249,7 +1264,7 @@ async function handleBatchByFilter(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidD1BodyMessage(`batch-by-filter on table '${tableName}'`) }, 400);
   }
 
   if (!body.action || !['delete', 'update'].includes(body.action)) {

package/src/lib/postgres-handler.ts

@@ -61,6 +61,18 @@ interface PgResolvedDb {
   namespace: string;
 }
 
+function postgresInvalidJsonMessage(context: string, tableName: string): string {
+  return `Invalid JSON body for ${context} on table '${tableName}'. Send application/json with the expected fields.`;
+}
+
+function postgresRuleRejectedMessage(tableName: string, action: 'insert' | 'update' | 'delete'): string {
+  return `Access denied by access rules for ${action} on table '${tableName}'.`;
+}
+
+function postgresValidationMessage(context: string, tableName: string): string {
+  return `Validation failed for ${context} on table '${tableName}'. See data for field-level errors.`;
+}
+
 // ─── Main Handler ───
 
 /**
@@ -526,7 +538,7 @@ async function handleInsert(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: postgresInvalidJsonMessage('insert', tableName) }, 400);
   }
 
   // Check insert rule
@@ -534,7 +546,7 @@ async function handleInsert(
   const tableHooks = getTableHooks(tableConfig);
   if (!isServiceKey && tableAccess?.insert !== undefined) {
     if (!(await evalInsertRule(tableAccess.insert, auth))) {
-      return c.json({ code: 403, message: 'Insert not allowed.' }, 403);
+      return c.json({ code: 403, message: postgresRuleRejectedMessage(tableName, 'insert') }, 403);
     }
   }
 
@@ -663,7 +675,7 @@ async function handleUpdate(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: postgresInvalidJsonMessage(`update record '${id}'`, tableName) }, 400);
   }
 
   // Validate against schema
@@ -671,7 +683,7 @@ async function handleUpdate(
   if (!validation.valid) {
     return c.json({
       code: 400,
-      message: 'Validation failed.',
+      message: postgresValidationMessage(`update record '${id}'`, tableName),
       data: toFieldErrorData(validation.errors),
       errors: validation.errors,
     }, 400);
@@ -690,7 +702,7 @@ async function handleUpdate(
   const tableHooks = getTableHooks(tableConfig);
   if (!isServiceKey && tableAccess?.update !== undefined) {
     if (!(await evalRowRule(tableAccess.update, auth, existingRow))) {
-      return c.json({ code: 403, message: 'Update not allowed.' }, 403);
+      return c.json({ code: 403, message: postgresRuleRejectedMessage(tableName, 'update') }, 403);
     }
   }
 
@@ -792,7 +804,7 @@ async function handleDelete(
   const tableHooks = getTableHooks(tableConfig);
   if (!isServiceKey && tableAccess?.delete !== undefined) {
     if (!(await evalRowRule(tableAccess.delete, auth, existingRow))) {
-      return c.json({ code: 403, message: 'Delete not allowed.' }, 403);
+      return c.json({ code: 403, message: postgresRuleRejectedMessage(tableName, 'delete') }, 403);
     }
   }
 
@@ -870,7 +882,7 @@ async function handleBatch(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: postgresInvalidJsonMessage('batch insert', tableName) }, 400);
   }
 
   const inserts = Array.isArray(body.inserts)
@@ -901,7 +913,7 @@ async function handleBatch(
   const tableAccess = getTableAccess(tableConfig);
   if (!isServiceKey && inserts.length > 0 && tableAccess?.insert !== undefined) {
     if (!(await evalInsertRule(tableAccess.insert, auth))) {
-      return c.json({ code: 403, message: 'Insert not allowed.' }, 403);
+      return c.json({ code: 403, message: postgresRuleRejectedMessage(tableName, 'insert') }, 403);
     }
   }
 
@@ -915,7 +927,7 @@ async function handleBatch(
     if (!validation.valid) {
       return c.json({
         code: 400,
-        message: 'Validation failed.',
+        message: postgresValidationMessage('batch insert', tableName),
         data: toFieldErrorData(validation.errors),
         errors: validation.errors,
       }, 400);
@@ -1000,7 +1012,7 @@ async function handleBatchByFilter(
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: postgresInvalidJsonMessage('batch-by-filter', tableName) }, 400);
   }
 
   if (!body.action || !['delete', 'update'].includes(body.action)) {
@@ -1038,7 +1050,7 @@ async function handleBatchByFilter(
     const tableAccess = getTableAccess(tableConfig);
     if (!isServiceKey && tableAccess?.delete !== undefined) {
       if (typeof tableAccess.delete === 'boolean' && !tableAccess.delete) {
-        return c.json({ code: 403, message: 'Delete not allowed.' }, 403);
+        return c.json({ code: 403, message: postgresRuleRejectedMessage(tableName, 'delete') }, 403);
       }
     }
 
@@ -1071,7 +1083,7 @@ async function handleBatchByFilter(
   const tableAccess = getTableAccess(tableConfig);
   if (!isServiceKey && tableAccess?.update !== undefined) {
     if (typeof tableAccess.update === 'boolean' && !tableAccess.update) {
-      return c.json({ code: 403, message: 'Update not allowed.' }, 403);
+      return c.json({ code: 403, message: postgresRuleRejectedMessage(tableName, 'update') }, 403);
     }
   }
 

package/src/lib/route-parser.ts

@@ -360,6 +360,9 @@ export function parseRoute(method: string, path: string): ParsedRoute {
       if (segments[2] === 'metadata') {
         result.subcategory = 'metadata';
         result.operation = 'getMetadata';
+      } else if (segments[2] === 'summary') {
+        result.subcategory = 'summary';
+        result.operation = 'getSummary';
       } else if (segments[2] === 'connect-check') {
         result.subcategory = 'connect-check';
         result.operation = 'connectCheck';

package/src/lib/runtime-startup.ts

@@ -0,0 +1,53 @@
+// Compile-time constant — injected by wrangler [define] in wrangler.test.toml
+declare const EDGEBASE_TEST_BUILD: boolean | undefined;
+
+let startupPromise: Promise<void> | null = null;
+
+async function detectWorkersTestRuntime(): Promise<boolean> {
+  try {
+    await import('cloudflare:test');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureServerStartup(): Promise<void> {
+  if (startupPromise) {
+    return startupPromise;
+  }
+
+  startupPromise = (async () => {
+    const [{ resolveStartupConfig }, generatedConfigModule, { initFunctionRegistry }, doRouterModule] = await Promise.all([
+      import('./startup-config.js'),
+      import('../generated-config.js'),
+      import('../_functions-registry.js'),
+      import('./do-router.js'),
+    ]);
+
+    try {
+      const processEnv = typeof process !== 'undefined' ? process.env : undefined;
+      const isTestBuild = typeof EDGEBASE_TEST_BUILD !== 'undefined';
+      const preferTestConfig = await detectWorkersTestRuntime() || isTestBuild;
+      const existingConfig = doRouterModule.parseConfig();
+      const resolvedConfig = await resolveStartupConfig(
+        generatedConfigModule.default,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async () => import('../../edgebase.test.config.ts' as any),
+        processEnv,
+        { preferTestConfig },
+      );
+
+      if (resolvedConfig && Object.keys(existingConfig).length === 0) {
+        doRouterModule.setConfig(resolvedConfig);
+      }
+    } catch (err) {
+      console.error('[EdgeBase] Failed to initialize config at startup:', err);
+      throw err;
+    }
+
+    initFunctionRegistry();
+  })();
+
+  return startupPromise;
+}

package/src/lib/schemas.ts

@@ -139,13 +139,23 @@ export const trackEventsBodySchema = z.object({
  * Returns Zod validation errors in the standard { code, message } format.
  */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-export function zodDefaultHook(result: { success: boolean; error?: { issues?: Array<{ message: string }>; errors?: Array<{ message: string }> } }, c: any) {
+function formatZodIssue(issue: { message?: string; path?: Array<string | number> }): string {
+  const message = typeof issue.message === 'string' ? issue.message : 'Invalid value';
+  const path = Array.isArray(issue.path) && issue.path.length > 0
+    ? issue.path.map((segment) => typeof segment === 'number' ? `[${segment}]` : String(segment)).join('.').replace(/\.\[/g, '[')
+    : '';
+  return path ? `${path}: ${message}` : message;
+}
+
+export function zodDefaultHook(result: { success: boolean; error?: { issues?: Array<{ message: string; path?: Array<string | number> }>; errors?: Array<{ message: string; path?: Array<string | number> }> } }, c: any) {
   if (!result.success) {
     // Zod v4 uses `issues`, Zod v3 uses `errors`
     const items = (result.error as any)?.issues ?? (result.error as any)?.errors ?? [];
     return c.json({
       code: 400,
-      message: items.map((e: any) => e.message).join(', '),
+      message: items.length > 0
+        ? items.map((e: any) => formatZodIssue(e)).join(', ')
+        : 'Request validation failed.',
     }, 400);
   }
 }

package/src/middleware/captcha-verify.ts

@@ -18,6 +18,7 @@ interface CaptchaConfig {
 }
 
 type HonoContext = Context<{ Bindings: Env }>;
+const captchaWarnings = new Set<string>();
 
 interface SiteverifyResponse {
   success: boolean;
@@ -139,7 +140,14 @@ export function captchaMiddleware(expectedAction: string) {
       try {
         const config = parseConfig(c.env);
         if (config?.captcha === true) {
-          console.warn('⚠️ Captcha skipped: no Turnstile keys provisioned.');
+          if (!captchaWarnings.has('missing-turnstile-keys')) {
+            captchaWarnings.add('missing-turnstile-keys');
+            console.warn(
+              '[Auth] CAPTCHA is enabled, but Turnstile keys are missing. '
+              + 'Requests will continue without CAPTCHA in local dev. '
+              + 'Add captchaSiteKey and TURNSTILE_SECRET, or set captcha: false to silence this warning.',
+            );
+          }
         }
       } catch { /* ignore */ }
       await next();
@@ -170,7 +178,13 @@ export function captchaMiddleware(expectedAction: string) {
     // Handle siteverify API failure (timeout, network error)
     if (result['error-codes']?.includes('timeout-or-network-error')) {
       if (failMode === 'open') {
-        console.warn('⚠️ Turnstile siteverify failed (timeout/network). Allowing request (failMode=open).');
+        if (!captchaWarnings.has('siteverify-fail-open')) {
+          captchaWarnings.add('siteverify-fail-open');
+          console.warn(
+            '[Auth] Turnstile siteverify failed because of a timeout or network error. '
+            + 'The request is being allowed because captcha.failMode is set to "open".',
+          );
+        }
         await next();
         return;
       }
@@ -214,4 +228,3 @@ export const _test = {
   hasServiceKey,
   siteverify,
 };
-

package/src/middleware/error-handler.ts

@@ -45,7 +45,7 @@ export const errorHandlerMiddleware: MiddlewareHandler<HonoEnv> = async (c, next
     return c.json(
       {
         code: 500,
-        message: 'Internal server error.',
+        message: `Internal server error while handling '${c.req.path}'. Check the worker logs for the original exception.`,
         slug: 'internal-error',
       },
       500,

package/src/middleware/rules.ts

@@ -41,6 +41,13 @@ type HonoContext = Context<{ Bindings: Env }>;
 const WORKER_RULE_TIMEOUT_MS = 50;
 const DB_ACCESS_RULE_TIMEOUT_MS = 2000;
 
+function tableRuleRejected(tableName: string, action: string): EdgeBaseError {
+  return new EdgeBaseError(
+    403,
+    `Access denied. The '${action}' access rule for table '${tableName}' rejected this request.`,
+  );
+}
+
 /**
  * Normalize a raw rule value (function | boolean | string) into a callable.
  *
@@ -174,7 +181,7 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
     return next();
   }
   if (keyResult === 'invalid') {
-    throw new EdgeBaseError(401, 'Unauthorized. Invalid Service Key.');
+    throw new EdgeBaseError(401, `Invalid X-EdgeBase-Service-Key for scope '${requiredScope}'.`);
   }
   // keyResult === 'missing' → continue to normal rules evaluation
 
@@ -182,7 +189,10 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
   if (!config.databases) {
     // No databases config → release mode check
     if (!config.release) return next();
-    throw new EdgeBaseError(403, `Access denied. No databases config defined.`);
+    throw new EdgeBaseError(
+      403,
+      'Access denied. No databases config is defined for this server. Add config.databases or set release: false while developing locally.',
+    );
   }
 
   // namespace comes directly from the URL (/api/db/:namespace/...)
@@ -192,13 +202,19 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
   if (!dbBlock) {
     // Namespace not found in config → deny
     if (!config.release) return next();
-    throw new EdgeBaseError(403, `Access denied. Namespace '${tableNamespace}' is not configured.`);
+    throw new EdgeBaseError(
+      403,
+      `Access denied. Namespace '${tableNamespace}' is not configured. Check the API path or add this namespace to config.databases.`,
+    );
   }
 
   if (dbBlock.tables && !dbBlock.tables[tableName]) {
     // Table not defined in this DB block
     if (!config.release) return next();
-    throw new EdgeBaseError(403, `Access denied. Table '${tableName}' has no access rules defined.`);
+    throw new EdgeBaseError(
+      403,
+      `Access denied. Table '${tableName}' is missing access rules. Add access.* rules or disable release mode for local-only development.`,
+    );
   }
 
   // ── Step 3: DB-level access check (§4) ──
@@ -232,7 +248,10 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
 
   if (!tableRules) {
     if (!config.release) return next();
-    throw new EdgeBaseError(403, `Access denied. No access rules defined for '${tableName}'.`);
+    throw new EdgeBaseError(
+      403,
+      `Access denied. No access rules are defined for table '${tableName}'. Add access.* rules or disable release mode for local-only development.`,
+    );
   }
 
   // Determine action
@@ -259,7 +278,7 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
       : !config.release;
 
     if (!insertPass && !updatePass) {
-      throw new EdgeBaseError(403, 'Access denied by access rules.');
+      throw tableRuleRejected(tableName, 'upsert');
     }
     return next();
   }
@@ -274,9 +293,9 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
       }
       if (insertRuleFn) {
         const canInsert = await evalWithTimeout(() => insertRuleFn(auth), WORKER_RULE_TIMEOUT_MS);
-        if (!canInsert) throw new EdgeBaseError(403, 'Access denied by access rules.');
+        if (!canInsert) throw tableRuleRejected(tableName, 'batch insert');
       } else if (config.release) {
-        throw new EdgeBaseError(403, 'Access denied by access rules.');
+        throw tableRuleRejected(tableName, 'batch insert');
       }
     }
     return next();
@@ -292,7 +311,7 @@ export async function rulesMiddleware(c: HonoContext, next: Next): Promise<Respo
       throw new EdgeBaseError(403, `Access denied. No 'insert' rule defined for '${tableName}'.`);
     }
     const canInsert = await evalWithTimeout(() => insertRuleFn(auth), WORKER_RULE_TIMEOUT_MS);
-    if (!canInsert) throw new EdgeBaseError(403, 'Access denied by access rules.');
+    if (!canInsert) throw tableRuleRejected(tableName, 'insert');
     return next();
   }
 

package/src/routes/admin-auth.ts

@@ -51,7 +51,7 @@ adminAuthRoute.onError((err, c) => {
     return c.json(err.toJSON(), err.code as 400);
   }
   console.error('Admin Auth unhandled error:', err);
-  return c.json({ code: 500, message: 'Internal server error.' }, 500);
+  return c.json({ code: 500, message: 'Admin auth request failed unexpectedly. Check the worker logs for the original exception.' }, 500);
 });
 
 // Service Key middleware — scoped validation
@@ -65,10 +65,10 @@ adminAuthRoute.use('*', async (c, next) => {
   const provided = explicitServiceKey ?? resolveServiceKeyCandidate(c.req, extractBearerToken(c.req));
   const { result } = validateKey(provided, 'auth:admin:*:*', config, c.env, undefined, buildConstraintCtx(c.env, c.req));
   if (result === 'missing') {
-    throw new EdgeBaseError(403, 'Service Key required for admin auth operations.');
+    throw new EdgeBaseError(403, 'X-EdgeBase-Service-Key is required for admin auth operations.');
   }
   if (result === 'invalid') {
-    throw new EdgeBaseError(401, 'Unauthorized. Service Key required.');
+    throw new EdgeBaseError(401, 'Invalid X-EdgeBase-Service-Key for admin auth operations.');
   }
   await ensureAuthSchema(getAuthDb(c));
   await next();

package/src/routes/admin.ts

@@ -362,7 +362,7 @@ adminRoute.onError((err, c) => {
     return c.json(err.toJSON(), err.code as 400);
   }
   console.error('Admin Dashboard unhandled error:', err);
-  return c.json({ code: 500, message: 'Internal server error.' }, 500);
+  return c.json({ code: 500, message: 'Admin dashboard request failed unexpectedly. Check the worker logs for the original exception.' }, 500);
 });
 
 // ─────────────────────────────────────────────
@@ -2133,7 +2133,12 @@ api.openapi(adminImportTable, async (c) => {
       }
     } catch (err) {
       for (let j = 0; j < chunk.length; j++) {
-        errors.push({ row: i + j, message: err instanceof Error ? err.message : 'Unknown error' });
+        errors.push({
+          row: i + j,
+          message: err instanceof Error
+            ? err.message
+            : 'Import failed with an unexpected admin API error. Check worker logs for details.',
+        });
       }
     }
   }
@@ -3436,7 +3441,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `D1 ${r.name}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/d1/database/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3446,7 +3451,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `Vectorize ${indexName}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/vectorize/v2/indexes/${indexName}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3455,7 +3460,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `Hyperdrive ${r.name}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/hyperdrive/configs/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3492,7 +3497,7 @@ api.openapi(adminDestroyApp, async (c) => {
       // Turnstile uses zone-level API, not account
       const result = await cfApi(accountId, apiToken, 'DELETE', `/challenges/widgets/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3503,7 +3508,7 @@ api.openapi(adminDestroyApp, async (c) => {
     if (result.ok) {
       deleted.push(label);
     } else {
-      failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3513,7 +3518,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `KV ${r.name}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/storage/kv/namespaces/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 

package/src/routes/analytics-api.ts

@@ -29,10 +29,10 @@ function requireServiceKey(c: { env: Env; req: { header: (name: string) => strin
   const constraintCtx = buildConstraintCtx(c.env as never, c.req);
   const { result } = validateKey(provided, 'analytics:*:*:*', config, c.env as never, undefined, constraintCtx);
   if (result === 'missing') {
-    throw new EdgeBaseError(403, 'Service Key required for analytics queries.');
+    throw new EdgeBaseError(403, 'X-EdgeBase-Service-Key is required for analytics queries.');
   }
   if (result === 'invalid') {
-    throw new EdgeBaseError(401, 'Invalid Service Key.');
+    throw new EdgeBaseError(401, 'Invalid X-EdgeBase-Service-Key for analytics queries.');
   }
 }
 
@@ -107,7 +107,7 @@ analyticsApi.openapi(trackEvents, async (c) => {
   try {
     body = await c.req.json();
   } catch {
-    throw new EdgeBaseError(400, 'Invalid JSON body.');
+    throw new EdgeBaseError(400, 'Invalid JSON body for analytics tracking. Send application/json with { events: [...] }.');
   }
 
   const events = body.events;

package/src/routes/auth.ts

@@ -1238,7 +1238,7 @@ authRoute.openapi(signinAnonymous, async (c) => {
 
     const user = await authService.getUserById(db, userId);
     if (user) {
-      syncUserPublic(c.env, c.executionCtx, userId, authService.buildPublicUserData(user));
+      await syncUserPublic(c.env, c.executionCtx, userId, authService.buildPublicUserData(user), true);
 
       return c.json({
         user: authService.sanitizeUser(user),