@edge-base/server 0.2.5 → 0.2.7

package/src/routes/room.ts

@@ -45,109 +45,26 @@ const roomConnectDiagnosticSchema = z.object({
   pendingCount: z.number().optional(),
   maxPending: z.number().optional(),
 });
-const roomRealtimeSessionDescriptionSchema = z.object({
-  sdp: z.string().openapi({ description: 'WebRTC session description payload' }),
-  type: z.enum(['offer', 'answer']).openapi({ description: 'Session description type' }),
+const roomSummarySchema = z.object({
+  namespace: z.string(),
+  roomId: z.string(),
+  metadata: z.record(z.string(), z.unknown()),
+  occupancy: z.object({
+    activeMembers: z.number(),
+    activeConnections: z.number(),
+  }),
+  updatedAt: z.string(),
 });
-const roomRealtimeTrackSchema = z.object({
-  location: z.enum(['local', 'remote']).openapi({ description: 'Track direction relative to the caller' }),
-  mid: z.string().optional().openapi({ description: 'WebRTC media ID' }),
-  sessionId: z.string().optional().openapi({ description: 'Provider session ID associated with this track' }),
-  trackName: z.string().optional().openapi({ description: 'Track name used by the provider' }),
-  bidirectionalMediaStream: z.boolean().optional().openapi({ description: 'Whether the track should be bidirectional' }),
-  kind: z.string().optional().openapi({ description: 'Track kind reported by the provider' }),
-  simulcast: z.object({
-    preferredRid: z.string().optional(),
-    priorityOrdering: z.enum(['none', 'asciibetical']).optional(),
-    ridNotAvailable: z.enum(['none', 'asciibetical']).optional(),
-  }).optional().openapi({ description: 'Optional simulcast preferences' }),
-  errorCode: z.string().optional().openapi({ description: 'Provider-level error code for this track' }),
-  errorDescription: z.string().optional().openapi({ description: 'Provider-level error description for this track' }),
+const roomSummaryBatchBodySchema = z.object({
+  namespace: z.string().openapi({ description: 'Room namespace shared by the requested room IDs' }),
+  ids: z.array(z.string()).min(1).max(100).openapi({ description: 'Room IDs to summarize' }),
 });
-const roomRealtimeCreateSessionBodySchema = z.object({
-  connectionId: z.string().optional().openapi({ description: 'Specific room connection ID to bind the realtime session to' }),
-  correlationId: z.string().optional().openapi({ description: 'Optional provider correlation ID' }),
-  thirdparty: z.boolean().optional().openapi({ description: 'Forward Cloudflare Realtime thirdparty mode' }),
-  sessionDescription: roomRealtimeSessionDescriptionSchema.optional(),
+const roomSummaryCollectionSchema = z.object({
+  namespace: z.string(),
+  items: z.array(roomSummarySchema),
+  deniedIds: z.array(z.string()),
+  updatedAt: z.string(),
 });
-const roomCloudflareRealtimeKitCreateSessionBodySchema = z.object({
-  connectionId: z.string().optional().openapi({ description: 'Specific room connection ID to bind the Cloudflare RealtimeKit participant to' }),
-  customParticipantId: z.string().optional().openapi({ description: 'Optional custom participant identifier for the provisioned RealtimeKit participant' }),
-  name: z.string().optional().openapi({ description: 'Optional display name for the provisioned RealtimeKit participant' }),
-  picture: z.string().optional().openapi({ description: 'Optional avatar URL for the provisioned RealtimeKit participant' }),
-});
-const roomRealtimeCreateSessionResponseSchema = z.object({
-  sessionId: z.string().openapi({ description: 'Realtime provider session ID' }),
-  sessionDescription: roomRealtimeSessionDescriptionSchema.optional(),
-  errorCode: z.string().optional(),
-  errorDescription: z.string().optional(),
-  connectionId: z.string().optional().openapi({ description: 'Room connection ID associated with the session' }),
-  reused: z.boolean().optional().openapi({ description: 'Whether an existing provider session was reused' }),
-});
-const roomCloudflareRealtimeKitCreateSessionResponseSchema = z.object({
-  sessionId: z.string().openapi({ description: 'Cloudflare RealtimeKit participant ID' }),
-  meetingId: z.string().openapi({ description: 'Cloudflare RealtimeKit meeting ID backing the room session' }),
-  participantId: z.string().openapi({ description: 'Cloudflare RealtimeKit participant ID' }),
-  authToken: z.string().openapi({ description: 'RealtimeKit auth token for the provisioned participant' }),
-  presetName: z.string().optional().openapi({ description: 'RealtimeKit preset used for the provisioned participant' }),
-  connectionId: z.string().optional().openapi({ description: 'Room connection ID associated with the session' }),
-  reused: z.boolean().optional().openapi({ description: 'Whether an existing provider participant was reused' }),
-});
-const roomRealtimeSessionStateSchema = z.object({
-  sessionId: z.string().openapi({ description: 'Realtime provider session ID' }),
-  connectionId: z.string().optional().openapi({ description: 'Room connection ID associated with the session' }),
-  createdAt: z.number().openapi({ description: 'Unix epoch milliseconds when the session was created' }),
-  updatedAt: z.number().openapi({ description: 'Unix epoch milliseconds when the session was last updated' }),
-});
-const roomRealtimeIceServerSchema = z.object({
-  urls: z.union([z.array(z.string()), z.string()]).openapi({ description: 'ICE server URL or URL list' }),
-  username: z.string().optional(),
-  credential: z.string().optional(),
-});
-const roomRealtimeIceServersBodySchema = z.object({
-  ttl: z.number().optional().openapi({ description: 'Requested TURN credential TTL in seconds' }),
-});
-const roomRealtimeIceServersResponseSchema = z.object({
-  iceServers: z.array(roomRealtimeIceServerSchema).openapi({ description: 'ICE servers returned by Cloudflare TURN' }),
-});
-const roomRealtimeTracksResponseSchema = z.object({
-  errorCode: z.string().optional(),
-  errorDescription: z.string().optional(),
-  requiresImmediateRenegotiation: z.boolean().optional(),
-  sessionDescription: roomRealtimeSessionDescriptionSchema.optional(),
-  tracks: z.array(roomRealtimeTrackSchema).optional(),
-});
-const roomRealtimeTracksBodySchema = z.object({
-  sessionId: z.string().openapi({ description: 'Realtime provider session ID' }),
-  connectionId: z.string().optional().openapi({ description: 'Specific room connection ID to bind the track operation to' }),
-  sessionDescription: roomRealtimeSessionDescriptionSchema.optional(),
-  tracks: z.array(roomRealtimeTrackSchema).min(1).openapi({ description: 'Tracks to create or subscribe to' }),
-  autoDiscover: z.boolean().optional().openapi({ description: 'Ask the provider to auto-discover remote tracks' }),
-  publish: z.object({
-    kind: z.enum(['audio', 'video', 'screen']).optional(),
-    trackId: z.string().optional(),
-    deviceId: z.string().optional(),
-    muted: z.boolean().optional(),
-  }).optional().openapi({ description: 'Optional room media state updates to apply after track creation' }),
-});
-const roomRealtimeRenegotiateBodySchema = z.object({
-  sessionId: z.string().openapi({ description: 'Realtime provider session ID' }),
-  connectionId: z.string().optional().openapi({ description: 'Specific room connection ID to bind the renegotiation to' }),
-  sessionDescription: roomRealtimeSessionDescriptionSchema,
-});
-const roomRealtimeCloseTracksBodySchema = z.object({
-  sessionId: z.string().openapi({ description: 'Realtime provider session ID' }),
-  connectionId: z.string().optional().openapi({ description: 'Specific room connection ID to bind the close operation to' }),
-  sessionDescription: roomRealtimeSessionDescriptionSchema.optional(),
-  tracks: z.array(z.object({
-    mid: z.string().openapi({ description: 'Track MID to close' }),
-  })).min(1).openapi({ description: 'Tracks to close' }),
-  force: z.boolean().optional().openapi({ description: 'Force close even if the provider reports the track as active' }),
-  unpublish: z.object({
-    kind: z.enum(['audio', 'video', 'screen']).optional(),
-  }).optional().openapi({ description: 'Optional room media state cleanup after closing tracks' }),
-});
-
 function isRoomOperationPublic(
   namespaceConfig: RoomNamespaceConfig | null | undefined,
   operation: 'metadata' | 'join' | 'action',
@@ -157,6 +74,22 @@ function isRoomOperationPublic(
   return !!namespaceConfig.public[operation];
 }
 
+function warnRoomDevelopmentFallback(
+  namespace: string,
+  operation: 'metadata' | 'join' | 'action',
+): void {
+  const warningKey = `${namespace}:${operation}`;
+  if (roomFallbackWarnings.has(warningKey)) {
+    return;
+  }
+  roomFallbackWarnings.add(warningKey);
+  console.warn(
+    `[Room] ${warningKey} is allowed because release=false and no explicit room rule was found. `
+    + `This fallback is local-dev only. Add rooms.${namespace}.access.${operation} or set `
+    + `rooms.${namespace}.public.${operation}=true to make the behavior explicit.`,
+  );
+}
+
 function getRoomAuthContext(
   auth: {
     id?: string;
@@ -188,11 +121,11 @@ export async function proxyRoomDoRequest(
   const roomId = c.req.query('id');
 
   if (!namespace || !roomId) {
-    return c.json({ code: 400, message: 'namespace and id query parameters required' }, 400);
+    return c.json({ code: 400, message: "Missing required query parameters 'namespace' and 'id' for room requests." }, 400);
   }
 
   if (options?.requireAuth && !c.get('auth')) {
-    return c.json({ code: 401, message: 'Authentication required' }, 401);
+    return c.json({ code: 401, message: 'Authentication required. Sign in before trying to access this room.' }, 401);
   }
 
   const config = parseConfig(c.env);
@@ -433,6 +366,42 @@ const getRoomMetadata = createRoute({
   },
 });
 
+const getRoomSummary = createRoute({
+  operationId: 'getRoomSummary',
+  method: 'get',
+  path: '/summary',
+  tags: ['client'],
+  summary: 'Get room summary',
+  description: 'Returns lobby-safe room metadata plus current occupancy without joining the room.',
+  request: {
+    query: roomQuerySchema,
+  },
+  responses: {
+    200: { description: 'Room summary', content: { 'application/json': { schema: roomSummarySchema } } },
+    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
+    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+    404: { description: 'Not found', content: { 'application/json': { schema: errorResponseSchema } } },
+  },
+});
+
+const getRoomSummaries = createRoute({
+  operationId: 'getRoomSummaries',
+  method: 'post',
+  path: '/summaries',
+  tags: ['client'],
+  summary: 'Get summaries for multiple rooms',
+  description: 'Returns lobby-safe room metadata plus current occupancy for multiple room IDs in the same namespace.',
+  request: {
+    body: { content: { 'application/json': { schema: roomSummaryBatchBodySchema } }, required: true },
+  },
+  responses: {
+    200: { description: 'Room summaries', content: { 'application/json': { schema: roomSummaryCollectionSchema } } },
+    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
+    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+    404: { description: 'Room feature not configured', content: { 'application/json': { schema: errorResponseSchema } } },
+  },
+});
+
 roomRoute.openapi(getRoomMetadata, async (c) => {
   const namespace = c.req.query('namespace');
   const roomId = c.req.query('id');
@@ -459,11 +428,7 @@ roomRoute.openapi(getRoomMetadata, async (c) => {
       return c.json({ code: 403, message: 'Room metadata requires access.metadata or public.metadata in release mode' }, 403);
     }
     if (!config.release) {
-      const warningKey = `${namespace}:metadata`;
-      if (!roomFallbackWarnings.has(warningKey)) {
-        roomFallbackWarnings.add(warningKey);
-        console.warn(`[Room] ${warningKey} is using development-mode allow-by-default. Add rooms.${namespace}.access.metadata or public.metadata to make this explicit.`);
-      }
+      warnRoomDevelopmentFallback(namespace, 'metadata');
     }
   }
   if (metadataAccess) {
@@ -498,184 +463,142 @@ roomRoute.openapi(getRoomMetadata, async (c) => {
   return doStub.fetch(doRequest);
 });
 
-const getRoomRealtimeSession = createRoute({
-  operationId: 'getRoomRealtimeSession',
-  method: 'get',
-  path: '/media/realtime/session',
-  tags: ['client'],
-  summary: 'Get the active room realtime media session',
-  description: 'Returns the provider session currently bound to the authenticated room member.',
-  request: {
-    query: roomQuerySchema.extend({
-      connectionId: z.string().optional().openapi({ description: 'Optional room connection ID override' }),
-    }),
-  },
-  responses: {
-    200: { description: 'Active room realtime session', content: { 'application/json': { schema: roomRealtimeSessionStateSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'No active session or runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
-});
+roomRoute.openapi(getRoomSummary, async (c) => {
+  const namespace = c.req.query('namespace');
+  const roomId = c.req.query('id');
 
-const createRoomRealtimeSession = createRoute({
-  operationId: 'createRoomRealtimeSession',
-  method: 'post',
-  path: '/media/realtime/session',
-  tags: ['client'],
-  summary: 'Create a room realtime media session',
-  description: 'Creates a Cloudflare Realtime session for the authenticated room member.',
-  request: {
-    query: roomQuerySchema,
-    body: { content: { 'application/json': { schema: roomRealtimeCreateSessionBodySchema } }, required: false },
-  },
-  responses: {
-    200: { description: 'Realtime session created', content: { 'application/json': { schema: roomRealtimeCreateSessionResponseSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'Room runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-    409: { description: 'Conflicting existing published media', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
-});
+  if (!namespace || !roomId) {
+    return c.json({ code: 400, message: 'namespace and id query parameters required' }, 400);
+  }
 
-const createRoomCloudflareRealtimeKitSession = createRoute({
-  operationId: 'createRoomCloudflareRealtimeKitSession',
-  method: 'post',
-  path: '/media/cloudflare_realtimekit/session',
-  tags: ['client'],
-  summary: 'Create a room Cloudflare RealtimeKit session',
-  description: 'Creates a Cloudflare RealtimeKit session for the authenticated room member.',
-  request: {
-    query: roomQuerySchema,
-    body: { content: { 'application/json': { schema: roomCloudflareRealtimeKitCreateSessionBodySchema } }, required: false },
-  },
-  responses: {
-    200: { description: 'Cloudflare RealtimeKit session created', content: { 'application/json': { schema: roomCloudflareRealtimeKitCreateSessionResponseSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'Room runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-    409: { description: 'Conflicting existing published media', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
-});
+  const config = parseConfig(c.env);
+  const namespaceConfig = config.rooms?.[namespace];
+  if (config.release) {
+    if (!config.rooms?.[namespace]) {
+      return c.json({
+        code: 403,
+        message: `Room namespace '${namespace}' not configured`,
+      }, 403);
+    }
+  }
 
-const createRoomRealtimeIceServers = createRoute({
-  operationId: 'createRoomRealtimeIceServers',
-  method: 'post',
-  path: '/media/realtime/turn',
-  tags: ['client'],
-  summary: 'Generate TURN / ICE credentials for room realtime media',
-  description: 'Generates ICE server credentials for the authenticated room member.',
-  request: {
-    query: roomQuerySchema,
-    body: { content: { 'application/json': { schema: roomRealtimeIceServersBodySchema } }, required: false },
-  },
-  responses: {
-    200: { description: 'ICE servers generated', content: { 'application/json': { schema: roomRealtimeIceServersResponseSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'Room runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
-});
+  const metadataAccess = namespaceConfig?.access?.metadata;
+  if (!metadataAccess) {
+    if (config.release && !isRoomOperationPublic(namespaceConfig, 'metadata')) {
+      return c.json({ code: 403, message: 'Room summary requires access.metadata or public.metadata in release mode' }, 403);
+    }
+    if (!config.release) {
+      warnRoomDevelopmentFallback(namespace, 'metadata');
+    }
+  }
+  if (metadataAccess) {
+    const auth = (c.get('auth') as { id?: string; role?: string; email?: string | null; custom?: Record<string, unknown> | null; isAnonymous?: boolean; meta?: Record<string, unknown> } | null | undefined) ?? null;
+    const allowed = await Promise.resolve(metadataAccess(
+      getRoomAuthContext(auth),
+      roomId,
+    )).catch(() => false);
+    if (!allowed) {
+      return c.json({ code: 403, message: 'Denied by room metadata access rule' }, 403);
+    }
+  }
 
-const addRoomRealtimeTracks = createRoute({
-  operationId: 'addRoomRealtimeTracks',
-  method: 'post',
-  path: '/media/realtime/tracks/new',
-  tags: ['client'],
-  summary: 'Add realtime media tracks to a room session',
-  description: 'Creates or subscribes realtime tracks for the authenticated room member.',
-  request: {
-    query: roomQuerySchema,
-    body: { content: { 'application/json': { schema: roomRealtimeTracksBodySchema } }, required: true },
-  },
-  responses: {
-    200: { description: 'Realtime tracks updated', content: { 'application/json': { schema: roomRealtimeTracksResponseSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'Room runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
-});
+  const runtime = resolveRoomRuntime(c.env);
+  if (!runtime.binding) {
+    return c.json({ code: 404, message: `Room runtime '${runtime.target}' not configured` }, 404);
+  }
 
-const renegotiateRoomRealtimeSession = createRoute({
-  operationId: 'renegotiateRoomRealtimeSession',
-  method: 'put',
-  path: '/media/realtime/renegotiate',
-  tags: ['client'],
-  summary: 'Renegotiate a room realtime media session',
-  description: 'Submits a new session description for an existing room realtime media session.',
-  request: {
-    query: roomQuerySchema,
-    body: { content: { 'application/json': { schema: roomRealtimeRenegotiateBodySchema } }, required: true },
-  },
-  responses: {
-    200: { description: 'Realtime session renegotiated', content: { 'application/json': { schema: roomRealtimeTracksResponseSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'Room runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
-});
+  const doName = `${namespace}::${roomId}`;
+  const doId = runtime.binding.idFromName(doName);
+  const doStub = runtime.binding.get(doId);
 
-const closeRoomRealtimeTracks = createRoute({
-  operationId: 'closeRoomRealtimeTracks',
-  method: 'put',
-  path: '/media/realtime/tracks/close',
-  tags: ['client'],
-  summary: 'Close room realtime media tracks',
-  description: 'Closes provider tracks for the authenticated room member and optionally unpublishes room media state.',
-  request: {
-    query: roomQuerySchema,
-    body: { content: { 'application/json': { schema: roomRealtimeCloseTracksBodySchema } }, required: true },
-  },
-  responses: {
-    200: { description: 'Realtime tracks closed', content: { 'application/json': { schema: roomRealtimeTracksResponseSchema } } },
-    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
-    401: { description: 'Authentication required', content: { 'application/json': { schema: errorResponseSchema } } },
-    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
-    404: { description: 'Room runtime not found', content: { 'application/json': { schema: errorResponseSchema } } },
-  },
+  const url = new URL(c.req.url);
+  url.pathname = '/summary';
+  url.searchParams.set('room', doName);
+  const doRequest = new Request(url.toString(), {
+    method: 'GET',
+    headers: c.req.raw.headers,
+  });
+
+  return doStub.fetch(doRequest);
 });
 
-roomRoute.openapi(getRoomRealtimeSession, async (c) =>
-  proxyRoomDoRequest(c, '/media/realtime/session', 'GET', { requireAuth: true }));
-
-roomRoute.openapi(createRoomRealtimeSession, async (c) =>
-  proxyRoomDoRequest(c, '/media/realtime/session', 'POST', {
-    requireAuth: true,
-    validatedJson: c.req.valid('json'),
-  }));
-
-roomRoute.openapi(createRoomRealtimeIceServers, async (c) =>
-  proxyRoomDoRequest(c, '/media/realtime/turn', 'POST', {
-    requireAuth: true,
-    validatedJson: c.req.valid('json'),
-  }));
-
-roomRoute.openapi(addRoomRealtimeTracks, async (c) =>
-  proxyRoomDoRequest(c, '/media/realtime/tracks/new', 'POST', {
-    requireAuth: true,
-    validatedJson: c.req.valid('json'),
-  }));
-
-roomRoute.openapi(renegotiateRoomRealtimeSession, async (c) =>
-  proxyRoomDoRequest(c, '/media/realtime/renegotiate', 'PUT', {
-    requireAuth: true,
-    validatedJson: c.req.valid('json'),
-  }));
-
-roomRoute.openapi(closeRoomRealtimeTracks, async (c) =>
-  proxyRoomDoRequest(c, '/media/realtime/tracks/close', 'PUT', {
-    requireAuth: true,
-    validatedJson: c.req.valid('json'),
-  }));
-
-roomRoute.openapi(createRoomCloudflareRealtimeKitSession, async (c) =>
-  proxyRoomDoRequest(c, '/media/cloudflare_realtimekit/session', 'POST', {
-    requireAuth: true,
-    validatedJson: c.req.valid('json'),
-  }));
+roomRoute.openapi(getRoomSummaries, async (c) => {
+  const body = c.req.valid('json') as z.infer<typeof roomSummaryBatchBodySchema>;
+  const namespace = body.namespace;
+  const roomIds = [...new Set(body.ids)];
+
+  const config = parseConfig(c.env);
+  const namespaceConfig = config.rooms?.[namespace];
+  if (config.release && !namespaceConfig) {
+    return c.json({
+      code: 403,
+      message: `Room namespace '${namespace}' not configured`,
+    }, 403);
+  }
+
+  const metadataAccess = namespaceConfig?.access?.metadata;
+  if (!metadataAccess) {
+    if (config.release && !isRoomOperationPublic(namespaceConfig, 'metadata')) {
+      return c.json({ code: 403, message: 'Room summaries require access.metadata or public.metadata in release mode' }, 403);
+    }
+    if (!config.release) {
+      warnRoomDevelopmentFallback(namespace, 'metadata');
+    }
+  }
+
+  const runtime = resolveRoomRuntime(c.env);
+  if (!runtime.binding) {
+    return c.json({ code: 404, message: `Room runtime '${runtime.target}' not configured` }, 404);
+  }
+
+  const auth = (c.get('auth') as { id?: string; role?: string; email?: string | null; custom?: Record<string, unknown> | null; isAnonymous?: boolean; meta?: Record<string, unknown> } | null | undefined) ?? null;
+  const authContext = getRoomAuthContext(auth);
+  const allowedRoomIds: string[] = [];
+  const deniedIds: string[] = [];
+
+  if (metadataAccess) {
+    for (const roomId of roomIds) {
+      const allowed = await Promise.resolve(metadataAccess(authContext, roomId)).catch(() => false);
+      if (allowed) {
+        allowedRoomIds.push(roomId);
+      } else {
+        deniedIds.push(roomId);
+      }
+    }
+  } else {
+    allowedRoomIds.push(...roomIds);
+  }
+
+  const items = await Promise.all(
+    allowedRoomIds.map(async (roomId) => {
+      const doName = `${namespace}::${roomId}`;
+      const doId = runtime.binding!.idFromName(doName);
+      const doStub = runtime.binding!.get(doId);
+
+      const url = new URL(c.req.url);
+      url.pathname = '/summary';
+      url.searchParams.set('room', doName);
+      const doResponse = await doStub.fetch(new Request(url.toString(), {
+        method: 'GET',
+        headers: c.req.raw.headers,
+      }));
+
+      if (!doResponse.ok) {
+        const errorPayload = await doResponse.json().catch(() => null) as { message?: string } | null;
+        throw new Error(
+          errorPayload?.message
+            ?? `Failed to load room summary for '${roomId}' in namespace '${namespace}'.`,
+        );
+      }
+
+      return doResponse.json() as Promise<z.infer<typeof roomSummarySchema>>;
+    }),
+  );
+
+  return c.json({
+    namespace,
+    items,
+    deniedIds,
+    updatedAt: new Date().toISOString(),
+  });
+});

package/src/routes/schema-endpoint.ts

@@ -45,14 +45,14 @@ schemaRoute.openapi(getSchema, async (c) => {
       buildConstraintCtx(c.env, c.req),
     );
     if (skResult === 'invalid') {
-      throw new EdgeBaseError(401, 'Unauthorized. Invalid Service Key.');
+      throw new EdgeBaseError(401, 'Invalid X-EdgeBase-Service-Key for schema reads.');
     }
     const serviceKeyBypass = skResult === 'valid';
 
     if (!serviceKeyBypass) {
       const auth = c.get('auth');
       if (!auth) {
-        throw new EdgeBaseError(401, 'Authentication required.');
+        throw new EdgeBaseError(401, 'Authentication required to read the schema endpoint.');
       }
     }
   }

package/src/routes/sql.ts

@@ -39,6 +39,10 @@ import { executeProviderAwareSql } from '../lib/provider-aware-sql.js';
 
 export const sqlRoute = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
 
+function invalidSqlJsonMessage(): string {
+  return 'Invalid JSON body for SQL execution. Send application/json with { namespace, sql, params? }.';
+}
+
 /**
  * POST /api/sql
  * Body: { namespace: string, id?: string, sql: string, params?: unknown[] }
@@ -81,19 +85,19 @@ sqlRoute.openapi(executeSql, async (c) => {
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidSqlJsonMessage() }, 400);
   }
 
   const { namespace, id, sql, params } = body;
 
   if (!namespace || typeof namespace !== 'string') {
-    return c.json({ code: 400, message: 'namespace is required' }, 400);
+    return c.json({ code: 400, message: "Missing required field 'namespace' for SQL execution." }, 400);
   }
   if (id !== undefined && id !== null && typeof id !== 'string') {
-    return c.json({ code: 400, message: 'id must be a string' }, 400);
+    return c.json({ code: 400, message: "Field 'id' must be a string when provided for SQL execution." }, 400);
   }
   if (!sql || typeof sql !== 'string') {
-    return c.json({ code: 400, message: 'sql is required' }, 400);
+    return c.json({ code: 400, message: "Missing required field 'sql' for SQL execution." }, 400);
   }
 
   // Validate namespace is declared in databases config (§1)
@@ -124,10 +128,10 @@ sqlRoute.openapi(executeSql, async (c) => {
     buildConstraintCtx(c.env, c.req),
   );
   if (skResult === 'missing') {
-    return c.json({ code: 403, message: 'Service Key required to execute SQL' }, 403);
+    return c.json({ code: 403, message: `X-EdgeBase-Service-Key is required to execute SQL for database namespace '${namespace}'.` }, 403);
   }
   if (skResult === 'invalid') {
-    return c.json({ code: 401, message: 'Unauthorized. Invalid Service Key.' }, 401);
+    return c.json({ code: 401, message: `Invalid X-EdgeBase-Service-Key for SQL execution in database namespace '${namespace}'.` }, 401);
   }
 
   try {

package/src/routes/storage.ts

@@ -297,7 +297,7 @@ function checkServiceKey(env: Env, header: string | undefined, scope: string, re
   const { result } = validateKey(header, scope, config, env, undefined, constraintCtx);
   if (result === 'valid') return true;
   if (result === 'invalid') {
-    throw new EdgeBaseError(401, 'Unauthorized. Invalid Service Key.', undefined, 'unauthenticated');
+    throw new EdgeBaseError(401, `Invalid X-EdgeBase-Service-Key for storage scope '${scope}'.`, undefined, 'unauthenticated');
   }
   return false; // 'missing' → continue to normal rules
 }
@@ -1236,7 +1236,9 @@ storage.openapi(deleteBatch, async (c) => {
       // afterDelete — plugin-registered storage hooks (per-file, non-blocking)
       executeStorageHooks('afterDelete', { ...fileMeta, bucket: bucketName }, auth, c.executionCtx, c.env, getWorkerUrl(c.req.url, c.env));
     } catch (e) {
-      const msg = e instanceof EdgeBaseError ? e.message : 'Unknown error.';
+      const msg = e instanceof EdgeBaseError
+        ? e.message
+        : 'Delete failed with an unexpected storage error. Check worker logs for details.';
       failed.push({ key, error: msg });
     }
   }