@edge-base/server 0.2.5 → 0.2.7

package/src/index.ts

@@ -12,6 +12,14 @@ export { LogsDO } from './durable-objects/logs-do.js';
 
 let appPromise: Promise<Awaited<ReturnType<typeof buildApp>>> | null = null;
 
+function assetUnavailableMessage(
+  assetName: 'admin dashboard' | 'harness assets',
+): string {
+  const label = `${assetName[0].toUpperCase()}${assetName.slice(1)}`;
+  const verb = assetName === 'admin dashboard' ? 'is' : 'are';
+  return `${label} ${verb} not deployed for this worker. Deploy the assets bundle or configure ADMIN_ORIGIN if they are hosted elsewhere.`;
+}
+
 async function buildApp() {
   await ensureServerStartup();
 
@@ -179,7 +187,7 @@ async function buildApp() {
     }
 
     if (!env.ASSETS) {
-      return c.json({ code: 404, message: 'Admin dashboard not deployed.' }, 404);
+      return c.json({ code: 404, message: assetUnavailableMessage('admin dashboard') }, 404);
     }
 
     const url = new URL(c.req.url);
@@ -198,7 +206,7 @@ async function buildApp() {
       return env.ASSETS.fetch(c.req.raw);
     }
 
-    return c.json({ code: 404, message: 'Admin dashboard not deployed.' }, 404);
+    return c.json({ code: 404, message: assetUnavailableMessage('admin dashboard') }, 404);
   });
 
   app.get('/_app/*', async (c) => {
@@ -207,7 +215,7 @@ async function buildApp() {
       return env.ASSETS.fetch(c.req.raw);
     }
 
-    return c.json({ code: 404, message: 'Admin dashboard not deployed.' }, 404);
+    return c.json({ code: 404, message: assetUnavailableMessage('admin dashboard') }, 404);
   });
 
   app.get('/admin/*', async (c) => {
@@ -219,7 +227,7 @@ async function buildApp() {
     if (env.ASSETS) {
       return env.ASSETS.fetch(createAdminAssetRequest(c.req.raw));
     }
-    return c.json({ code: 404, message: 'Admin dashboard not deployed.' }, 404);
+    return c.json({ code: 404, message: assetUnavailableMessage('admin dashboard') }, 404);
   });
 
   app.get('/admin', async (c) => {
@@ -231,7 +239,7 @@ async function buildApp() {
     if (env.ASSETS) {
       return env.ASSETS.fetch(createAdminAssetRequest(c.req.raw));
     }
-    return c.json({ code: 404, message: 'Admin dashboard not deployed.' }, 404);
+    return c.json({ code: 404, message: assetUnavailableMessage('admin dashboard') }, 404);
   });
 
   app.get('/harness', (c) => {
@@ -243,7 +251,7 @@ async function buildApp() {
     if (env.ASSETS) {
       return env.ASSETS.fetch(c.req.raw);
     }
-    return c.json({ code: 404, message: 'Harness assets not deployed.' }, 404);
+    return c.json({ code: 404, message: assetUnavailableMessage('harness assets') }, 404);
   });
 
   app.get('/harness/assets/*', async (c) => {
@@ -251,7 +259,7 @@ async function buildApp() {
     if (env.ASSETS) {
       return env.ASSETS.fetch(c.req.raw);
     }
-    return c.json({ code: 404, message: 'Harness assets not deployed.' }, 404);
+    return c.json({ code: 404, message: assetUnavailableMessage('harness assets') }, 404);
   });
 
   app.get('/harness/*', (c) => {
@@ -268,7 +276,10 @@ async function buildApp() {
   });
 
   app.notFound((c) => {
-    return c.json({ code: 404, message: 'Not found.' }, 404);
+    return c.json({
+      code: 404,
+      message: `Path '${new URL(c.req.url).pathname}' was not found on this EdgeBase server.`,
+    }, 404);
   });
 
   app.onError((err, c) => {
@@ -302,7 +313,10 @@ async function buildApp() {
       return c.json(body, e.code as number as 400);
     }
     console.error('Unhandled error:', err);
-    return c.json({ code: 500, message: 'Internal server error.' }, 500);
+    return c.json({
+      code: 500,
+      message: `Internal server error while handling '${new URL(c.req.url).pathname}'. Check the worker logs for the original exception.`,
+    }, 500);
   });
 
   return app;

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/openapi.ts

@@ -47,10 +47,7 @@ const USER_BEARER_PATHS = new Set([
   '/api/push/topic/unsubscribe',
 ]);
 
-const USER_BEARER_PREFIXES = [
-  '/api/room/media/realtime/',
-  '/api/room/media/cloudflare_realtimekit/',
-];
+const USER_BEARER_PREFIXES: string[] = [];
 
 const SERVICE_KEY_ONLY_PATHS = new Set([
   '/api/db/broadcast',

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/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();