@objectstack/rest 4.0.4 → 4.0.5

package/dist/index.js

@@ -209,11 +209,360 @@ var RouteGroupBuilder = class {
 };
 
 // src/rest-server.ts
+var logError = (...args) => globalThis.console?.error(...args);
+function mapDataError(error, object) {
+  if (error?.code === "PERMISSION_DENIED" || error?.name === "PermissionDeniedError" || typeof error?.message === "string" && error.message.startsWith("[Security] Access denied")) {
+    return {
+      status: 403,
+      body: {
+        error: error?.message ?? "Permission denied",
+        code: "PERMISSION_DENIED",
+        ...object ? { object } : {}
+      }
+    };
+  }
+  const raw = String(error?.message ?? error ?? "");
+  const lower = raw.toLowerCase();
+  if (raw.includes("[ProjectKernelFactory]") && (lower.includes("missing database_url") || lower.includes("not found"))) {
+    const isProvisioning = lower.includes("status='provisioning'") || lower.includes("status='pending'");
+    const isFailed = lower.includes("status='failed'");
+    return {
+      status: isProvisioning ? 503 : isFailed ? 502 : 404,
+      body: {
+        error: raw,
+        code: isProvisioning ? "PROJECT_PROVISIONING" : isFailed ? "PROJECT_PROVISIONING_FAILED" : "PROJECT_NOT_FOUND"
+      }
+    };
+  }
+  const looksLikeUnknownObject = lower.includes("no such table") || lower.includes("relation") && lower.includes("does not exist") || lower.includes("table not found") || lower.includes("unknown object") || lower.includes("object not found") || lower.includes("no driver available") || object !== void 0 && lower.includes(`'${object.toLowerCase()}'`) && lower.includes("not");
+  if (looksLikeUnknownObject) {
+    return {
+      status: 404,
+      body: {
+        error: object ? `Object '${object}' is not registered` : "Object not found",
+        code: "object_not_found",
+        object
+      }
+    };
+  }
+  return { status: 400, body: { error: raw || "Bad request" } };
+}
+function isExpectedDataStatus(status) {
+  return status === 403 || status === 404 || status === 502 || status === 503;
+}
 var RestServer = class {
-  constructor(server, protocol, config = {}) {
+  constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultProjectIdProvider, authServiceProvider, objectQLProvider) {
     this.protocol = protocol;
     this.config = this.normalizeConfig(config);
     this.routeManager = new RouteManager(server);
+    this.kernelManager = kernelManager;
+    this.envRegistry = envRegistry;
+    this.defaultProjectIdProvider = defaultProjectIdProvider;
+    this.authServiceProvider = authServiceProvider;
+    this.objectQLProvider = objectQLProvider;
+  }
+  /**
+   * Resolve the protocol for a given request. When `projectId` is present
+   * and a KernelManager is wired, fetch the per-project kernel's
+   * `protocol` service so metadata / data / UI reads hit the project's
+   * own registry and datastore.
+   *
+   * When `projectId` is absent on an unscoped route and an `envRegistry`
+   * is wired (runtime mode), the resolution chain is:
+   *   1. Hostname → projectId (`envRegistry.resolveByHostname`)
+   *   2. `X-Project-Id` header → projectId (`envRegistry.resolveById`)
+   *   3. Default-project fallback (`defaultProjectIdProvider`, set by
+   *      `createSingleProjectPlugin`)
+   *   4. Control-plane protocol captured at boot.
+   *
+   * Special case: `projectId === 'platform'` is a reserved virtual id used
+   * by Studio to address the control plane through the regular project
+   * URL shape (`/projects/platform/...`). It is NOT a row in the projects
+   * table, so we must never call `KernelManager.getOrCreate('platform')`.
+   * Instead, return the control-plane protocol directly. This lets Studio
+   * (and any other client) speak a single, uniform URL family without
+   * duplicating route logic for the platform surface.
+   */
+  async resolveProtocol(projectId, req) {
+    if (projectId === "platform") return this.protocol;
+    if (!projectId && req && this.envRegistry && this.kernelManager) {
+      const host = this.extractHostname(req);
+      if (host) {
+        try {
+          const result = await this.envRegistry.resolveByHostname(host);
+          if (result?.projectId) projectId = result.projectId;
+        } catch {
+        }
+      }
+      if (!projectId && typeof this.envRegistry.resolveById === "function") {
+        const headerVal = this.extractProjectIdHeader(req);
+        if (headerVal) {
+          try {
+            const driver = await this.envRegistry.resolveById(headerVal);
+            if (driver) projectId = headerVal;
+          } catch {
+          }
+        }
+      }
+    }
+    if (!projectId && this.defaultProjectIdProvider) {
+      try {
+        const def = this.defaultProjectIdProvider();
+        if (def) projectId = def;
+      } catch {
+      }
+    }
+    if (!projectId || !this.kernelManager) return this.protocol;
+    const kernel = await this.kernelManager.getOrCreate(projectId);
+    return kernel.getServiceAsync("protocol");
+  }
+  /**
+   * Resolve the i18n service for the request's project (or control plane
+   * when no project id is in scope). Returns `undefined` when no service is
+   * registered, so callers can short-circuit and skip translation rather
+   * than failing.
+   *
+   * Mirrors `resolveProtocol`'s lookup chain: explicit `projectId` from the
+   * route → kernel-managed `i18n` service. Control-plane / unscoped
+   * requests intentionally return `undefined` because the platform kernel
+   * does not own per-app translation bundles.
+   */
+  async resolveI18nService(projectId) {
+    if (!projectId || projectId === "platform" || !this.kernelManager) return void 0;
+    try {
+      const kernel = await this.kernelManager.getOrCreate(projectId);
+      return await kernel.getServiceAsync("i18n");
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Resolve the request's execution context (RBAC/RLS/FLS) by looking up
+   * the better-auth session via the project's `auth` service. Returns
+   * `undefined` for anonymous requests so callers can pass `context` as-is
+   * to the protocol layer (the SecurityPlugin treats undefined as anon).
+   */
+  async resolveExecCtx(projectId, req) {
+    try {
+      let authService;
+      let kernel;
+      if (projectId && projectId !== "platform" && this.kernelManager) {
+        kernel = await this.kernelManager.getOrCreate(projectId);
+        authService = await kernel.getServiceAsync("auth").catch(() => void 0);
+      }
+      if (!authService && this.defaultProjectIdProvider && this.kernelManager) {
+        try {
+          const def = this.defaultProjectIdProvider();
+          if (def) {
+            kernel = await this.kernelManager.getOrCreate(def);
+            authService = await kernel.getServiceAsync("auth").catch(() => void 0);
+          }
+        } catch {
+        }
+      }
+      if (!authService && this.authServiceProvider) {
+        authService = await this.authServiceProvider(projectId).catch(() => void 0);
+      }
+      if (!authService) return void 0;
+      let api = authService.api;
+      if (!api && typeof authService.getApi === "function") {
+        api = await authService.getApi();
+      }
+      if (!api?.getSession) return void 0;
+      const rawHeaders = req?.headers;
+      let headers;
+      if (rawHeaders && typeof rawHeaders.get === "function") {
+        headers = rawHeaders;
+      } else if (rawHeaders && typeof rawHeaders === "object") {
+        headers = new globalThis.Headers();
+        for (const [k, v] of Object.entries(rawHeaders)) {
+          if (Array.isArray(v)) v.forEach((x) => headers.append(k, String(x)));
+          else if (v != null) headers.set(k, String(v));
+        }
+      } else {
+        return void 0;
+      }
+      const session = await api.getSession({ headers });
+      if (!session?.user?.id) return void 0;
+      const userId = session.user.id;
+      const tenantId = session.session?.activeOrganizationId ?? void 0;
+      const permissions = [];
+      const roles = [];
+      try {
+        let ql;
+        if (kernel) {
+          ql = await kernel.getServiceAsync("objectql").catch(() => void 0);
+        }
+        if (!ql && this.objectQLProvider) {
+          ql = await this.objectQLProvider(projectId).catch(() => void 0);
+        }
+        if (ql && typeof ql.find === "function") {
+          const sysOpts = { context: { isSystem: true } };
+          const memberRows = await ql.find("sys_member", {
+            where: tenantId ? { user_id: userId, organization_id: tenantId } : { user_id: userId },
+            limit: 50,
+            ...sysOpts
+          }).catch(() => []);
+          for (const m of memberRows ?? []) {
+            if (typeof m.role === "string") {
+              for (const r of m.role.split(",").map((s) => s.trim()).filter(Boolean)) {
+                if (!roles.includes(r)) roles.push(r);
+              }
+            }
+          }
+          const upsRows = await ql.find("sys_user_permission_set", {
+            where: { user_id: userId },
+            limit: 100,
+            ...sysOpts
+          }).catch(() => []);
+          const psIds = /* @__PURE__ */ new Set();
+          for (const r of upsRows ?? []) {
+            const orgScope = r.organization_id ?? null;
+            if (!orgScope || tenantId && orgScope === tenantId) {
+              const pid = r.permission_set_id ?? r.permissionSetId;
+              if (pid) psIds.add(pid);
+            }
+          }
+          if (psIds.size > 0) {
+            const psRows = await ql.find("sys_permission_set", {
+              where: { id: { $in: Array.from(psIds) } },
+              limit: 500,
+              ...sysOpts
+            }).catch(() => []);
+            for (const ps of psRows ?? []) {
+              if (ps.name && !permissions.includes(ps.name)) permissions.push(ps.name);
+            }
+          }
+        }
+      } catch {
+      }
+      return {
+        userId,
+        tenantId,
+        roles,
+        permissions,
+        isSystem: false
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Build a `TranslationBundle` (`Record<locale, TranslationData>`) from an
+   * `II18nService` instance. Returns `undefined` when no locales are
+   * registered so callers can avoid translation work.
+   */
+  buildTranslationBundle(i18n) {
+    if (!i18n || typeof i18n.getLocales !== "function" || typeof i18n.getTranslations !== "function") {
+      return void 0;
+    }
+    const locales = i18n.getLocales();
+    if (!locales.length) return void 0;
+    const bundle = {};
+    for (const locale of locales) {
+      const data = i18n.getTranslations(locale);
+      if (data && typeof data === "object") bundle[locale] = data;
+    }
+    return Object.keys(bundle).length ? bundle : void 0;
+  }
+  /**
+   * Parse the highest-priority locale from an `Accept-Language` header.
+   * Falls back to a `?locale=` query parameter, then to the i18n service's
+   * default locale. Returns `undefined` when no preference is expressed
+   * (callers will then return untranslated metadata).
+   */
+  extractLocale(req, i18n) {
+    const headers = req?.headers;
+    let header;
+    if (headers) {
+      header = typeof headers.get === "function" ? headers.get("accept-language") ?? void 0 : headers["accept-language"] ?? headers["Accept-Language"];
+    }
+    if (typeof header === "string" && header.length > 0) {
+      const top = header.split(",")[0]?.split(";")[0]?.trim();
+      if (top) return top;
+    }
+    const queryLocale = req?.query?.locale;
+    if (typeof queryLocale === "string" && queryLocale.length > 0) return queryLocale;
+    if (i18n && typeof i18n.getDefaultLocale === "function") {
+      const def = i18n.getDefaultLocale();
+      if (typeof def === "string" && def.length > 0) return def;
+    }
+    return void 0;
+  }
+  /**
+   * Translate a single metadata document (view or action) when an i18n
+   * service is registered for the request's project and the requested
+   * locale yields a match. Falls through unchanged for unsupported types
+   * or missing translations.
+   */
+  async translateMetaItem(req, type, projectId, item) {
+    if (!item || typeof item !== "object") return item;
+    if (type !== "view" && type !== "action") return item;
+    const i18n = await this.resolveI18nService(projectId);
+    const bundle = this.buildTranslationBundle(i18n);
+    if (!bundle) return item;
+    const locale = this.extractLocale(req, i18n);
+    if (!locale) return item;
+    const { translateMetadataDocument } = await import("@objectstack/spec/system");
+    return translateMetadataDocument(type, item, bundle, { locale });
+  }
+  /**
+   * Translate a list of metadata documents using `translateMetaItem`.
+   */
+  async translateMetaItems(req, type, projectId, items) {
+    if (!Array.isArray(items)) return items;
+    if (type !== "view" && type !== "action") return items;
+    const i18n = await this.resolveI18nService(projectId);
+    const bundle = this.buildTranslationBundle(i18n);
+    if (!bundle) return items;
+    const locale = this.extractLocale(req, i18n);
+    if (!locale) return items;
+    const { translateMetadataDocument } = await import("@objectstack/spec/system");
+    return items.map((item) => translateMetadataDocument(type, item, bundle, { locale }));
+  }
+  /**
+   * Pull the request hostname (without port) from a Node-style `req` or
+   * a Fetch-style request wrapper. Returns undefined when no Host header
+   * is available.
+   */
+  extractHostname(req) {
+    const headers = req?.headers;
+    let host;
+    if (headers) {
+      if (typeof headers.get === "function") {
+        host = headers.get("host") ?? void 0;
+      } else {
+        host = headers.host ?? headers.Host;
+      }
+    }
+    if (!host && typeof req?.hostname === "string") host = req.hostname;
+    if (!host && typeof req?.url === "string") {
+      try {
+        host = new globalThis.URL(req.url).host;
+      } catch {
+      }
+    }
+    if (!host) return void 0;
+    return String(host).split(":")[0].toLowerCase();
+  }
+  /**
+   * Pull the `X-Project-Id` header from a Node- or Fetch-style request.
+   * Header names are case-insensitive; we probe both casings to cover
+   * adapters that don't normalize headers (e.g. raw Node http).
+   */
+  extractProjectIdHeader(req) {
+    const headers = req?.headers;
+    if (!headers) return void 0;
+    let val;
+    if (typeof headers.get === "function") {
+      val = headers.get("x-project-id") ?? headers.get("X-Project-Id");
+    } else {
+      val = headers["x-project-id"] ?? headers["X-Project-Id"];
+    }
+    if (Array.isArray(val)) val = val[0];
+    if (typeof val !== "string") return void 0;
+    const trimmed = val.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
   }
   /**
    * Normalize configuration with defaults
@@ -234,6 +583,8 @@ var RestServer = class {
         enableUi: api.enableUi ?? true,
         enableBatch: api.enableBatch ?? true,
         enableDiscovery: api.enableDiscovery ?? true,
+        enableProjectScoping: api.enableProjectScoping ?? false,
+        projectResolution: api.projectResolution ?? "auto",
         documentation: api.documentation,
         responseFormat: api.responseFormat
       },
@@ -286,51 +637,88 @@ var RestServer = class {
     const { api } = this.config;
     return api.apiPath ?? `${api.basePath}/${api.version}`;
   }
+  /**
+   * Get the project-scoped base path for a given unscoped base.
+   * Example: `/api/v1` → `/api/v1/projects/:projectId`.
+   */
+  getScopedBasePath(basePath) {
+    return `${basePath}/projects/:projectId`;
+  }
   /**
    * Register all REST API routes
+   *
+   * When `enableProjectScoping` is true, routes are registered under
+   * `/api/v1/projects/:projectId/...`. The `projectResolution` strategy
+   * controls whether unscoped legacy routes remain available:
+   *   - `required` → only scoped routes registered.
+   *   - `optional` / `auto` → both scoped and unscoped routes registered.
    */
   registerRoutes() {
     const basePath = this.getApiBasePath();
-    if (this.config.api.enableDiscovery) {
-      this.registerDiscoveryEndpoints(basePath);
-    }
-    if (this.config.api.enableMetadata) {
-      this.registerMetadataEndpoints(basePath);
-    }
-    if (this.config.api.enableUi) {
-      this.registerUiEndpoints(basePath);
-    }
-    if (this.config.api.enableCrud) {
-      this.registerCrudEndpoints(basePath);
-    }
-    if (this.config.api.enableBatch) {
-      this.registerBatchEndpoints(basePath);
+    const { enableProjectScoping, projectResolution } = this.config.api;
+    const registerForBase = (bp) => {
+      if (this.config.api.enableDiscovery) {
+        this.registerDiscoveryEndpoints(bp);
+      }
+      if (this.config.api.enableMetadata) {
+        this.registerMetadataEndpoints(bp);
+      }
+      if (this.config.api.enableUi) {
+        this.registerUiEndpoints(bp);
+      }
+      if (this.config.api.enableCrud) {
+        this.registerCrudEndpoints(bp);
+      }
+      if (this.config.api.enableBatch) {
+        this.registerBatchEndpoints(bp);
+      }
+    };
+    if (enableProjectScoping) {
+      const scopedBase = this.getScopedBasePath(basePath);
+      if (projectResolution === "required") {
+        registerForBase(scopedBase);
+      } else {
+        registerForBase(basePath);
+        registerForBase(scopedBase);
+      }
+    } else {
+      registerForBase(basePath);
     }
   }
   /**
    * Register discovery endpoints
    */
   registerDiscoveryEndpoints(basePath) {
-    const discoveryHandler = async (_req, res) => {
+    const isScoped = basePath.includes("/projects/:projectId");
+    const discoveryHandler = async (req, res) => {
       try {
         const discovery = await this.protocol.getDiscovery();
         discovery.version = this.config.api.version;
+        const realBase = isScoped ? basePath.replace(":projectId", req.params?.projectId ?? ":projectId") : basePath;
         if (discovery.routes) {
           if (this.config.api.enableCrud) {
-            discovery.routes.data = `${basePath}${this.config.crud.dataPrefix}`;
+            discovery.routes.data = `${realBase}${this.config.crud.dataPrefix}`;
           }
           if (this.config.api.enableMetadata) {
-            discovery.routes.metadata = `${basePath}${this.config.metadata.prefix}`;
+            discovery.routes.metadata = `${realBase}${this.config.metadata.prefix}`;
           }
           if (this.config.api.enableUi) {
-            discovery.routes.ui = `${basePath}/ui`;
+            discovery.routes.ui = `${realBase}/ui`;
           }
           if (discovery.routes.auth) {
-            discovery.routes.auth = `${basePath}/auth`;
+            const unscopedBase = isScoped ? basePath.replace(/\/projects\/:projectId$/, "") : basePath;
+            discovery.routes.auth = `${unscopedBase}/auth`;
           }
         }
+        discovery.scoping = {
+          enabled: this.config.api.enableProjectScoping,
+          resolution: this.config.api.projectResolution,
+          scoped: isScoped,
+          projectId: isScoped ? req.params?.projectId : void 0
+        };
         res.json(discovery);
       } catch (error) {
+        logError("[REST] Unhandled error:", error);
         res.status(500).json({ error: error.message });
       }
     };
@@ -359,15 +747,19 @@ var RestServer = class {
   registerMetadataEndpoints(basePath) {
     const { metadata } = this.config;
     const metaPath = `${basePath}${metadata.prefix}`;
+    const isScoped = basePath.includes("/projects/:projectId");
     if (metadata.endpoints.types !== false) {
       this.routeManager.register({
         method: "GET",
         path: metaPath,
-        handler: async (_req, res) => {
+        handler: async (req, res) => {
           try {
-            const types = await this.protocol.getMetaTypes();
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const types = await p.getMetaTypes();
             res.json(types);
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(500).json({ error: error.message });
           }
         },
@@ -384,9 +776,18 @@ var RestServer = class {
         handler: async (req, res) => {
           try {
             const packageId = req.query?.package || void 0;
-            const items = await this.protocol.getMetaItems({ type: req.params.type, packageId });
-            res.json(items);
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const items = await p.getMetaItems({
+              type: req.params.type,
+              packageId,
+              ...projectId ? { projectId } : {}
+            });
+            const translated = await this.translateMetaItems(req, req.params.type, projectId, items);
+            res.header("Vary", "Accept-Language");
+            res.json(translated);
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(404).json({ error: error.message });
           }
         },
@@ -402,15 +803,18 @@ var RestServer = class {
         path: `${metaPath}/:type/:name`,
         handler: async (req, res) => {
           try {
-            if (metadata.enableCache && this.protocol.getMetaItemCached) {
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            if (metadata.enableCache && p.getMetaItemCached) {
               const cacheRequest = {
                 ifNoneMatch: req.headers["if-none-match"],
                 ifModifiedSince: req.headers["if-modified-since"]
               };
-              const result = await this.protocol.getMetaItemCached({
+              const result = await p.getMetaItemCached({
                 type: req.params.type,
                 name: req.params.name,
-                cacheRequest
+                cacheRequest,
+                ...projectId ? { projectId } : {}
               });
               if (result.notModified) {
                 res.status(304).send();
@@ -428,13 +832,20 @@ var RestServer = class {
                 const maxAge = result.cacheControl.maxAge ? `, max-age=${result.cacheControl.maxAge}` : "";
                 res.header("Cache-Control", directives + maxAge);
               }
-              res.json(result.data);
+              res.header("Vary", "Accept-Language");
+              res.json(await this.translateMetaItem(req, req.params.type, projectId, result.data));
             } else {
               const packageId = req.query?.package || void 0;
-              const item = await this.protocol.getMetaItem({ type: req.params.type, name: req.params.name, packageId });
-              res.json(item);
+              const item = await p.getMetaItem({
+                type: req.params.type,
+                name: req.params.name,
+                packageId
+              });
+              res.header("Vary", "Accept-Language");
+              res.json(await this.translateMetaItem(req, req.params.type, projectId, item));
             }
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(404).json({ error: error.message });
           }
         },
@@ -449,17 +860,21 @@ var RestServer = class {
       path: `${metaPath}/:type/:name`,
       handler: async (req, res) => {
         try {
-          if (!this.protocol.saveMetaItem) {
+          const projectId = isScoped ? req.params?.projectId : void 0;
+          const p = await this.resolveProtocol(projectId, req);
+          if (!p.saveMetaItem) {
             res.status(501).json({ error: "Save operation not supported by protocol implementation" });
             return;
           }
-          const result = await this.protocol.saveMetaItem({
+          const result = await p.saveMetaItem({
             type: req.params.type,
             name: req.params.name,
-            item: req.body
+            item: req.body,
+            ...projectId ? { projectId } : {}
           });
           res.json(result);
         } catch (error) {
+          logError("[REST] Unhandled error:", error);
           res.status(400).json({ error: error.message });
         }
       },
@@ -474,21 +889,26 @@ var RestServer = class {
    */
   registerUiEndpoints(basePath) {
     const uiPath = `${basePath}/ui`;
+    const isScoped = basePath.includes("/projects/:projectId");
     this.routeManager.register({
       method: "GET",
       path: `${uiPath}/view/:object/:type`,
       handler: async (req, res) => {
         try {
-          if (this.protocol.getUiView) {
-            const view = await this.protocol.getUiView({
+          const projectId = isScoped ? req.params?.projectId : void 0;
+          const p = await this.resolveProtocol(projectId, req);
+          if (p.getUiView) {
+            const view = await p.getUiView({
               object: req.params.object,
-              type: req.params.type
+              type: req.params.type,
+              ...projectId ? { projectId } : {}
             });
             res.json(view);
           } else {
             res.status(501).json({ error: "UI View resolution not supported by protocol implementation" });
           }
         } catch (error) {
+          logError("[REST] Unhandled error:", error);
           res.status(404).json({ error: error.message });
         }
       },
@@ -504,6 +924,7 @@ var RestServer = class {
   registerCrudEndpoints(basePath) {
     const { crud } = this.config;
     const dataPath = `${basePath}${crud.dataPrefix}`;
+    const isScoped = basePath.includes("/projects/:projectId");
     const operations = crud.operations;
     if (operations.list) {
       this.routeManager.register({
@@ -511,13 +932,24 @@ var RestServer = class {
         path: `${dataPath}/:object`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.findData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const context = await this.resolveExecCtx(projectId, req);
+            const result = await p.findData({
               object: req.params.object,
-              query: req.query
+              query: req.query,
+              ...projectId ? { projectId } : {},
+              ...context ? { context } : {}
             });
             res.json(result);
           } catch (error) {
-            res.status(400).json({ error: error.message });
+            const mapped = mapDataError(error, req.params?.object);
+            if (mapped.status === 404 || mapped.status === 503 || mapped.status === 502) {
+              res.status(mapped.status).json(mapped.body);
+            } else {
+              logError("[REST] Unhandled error:", error);
+              res.status(mapped.status).json(mapped.body);
+            }
           }
         },
         metadata: {
@@ -532,16 +964,23 @@ var RestServer = class {
         path: `${dataPath}/:object/:id`,
         handler: async (req, res) => {
           try {
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
             const { select, expand } = req.query || {};
-            const result = await this.protocol.getData({
+            const context = await this.resolveExecCtx(projectId, req);
+            const result = await p.getData({
               object: req.params.object,
               id: req.params.id,
               ...select != null ? { select } : {},
-              ...expand != null ? { expand } : {}
+              ...expand != null ? { expand } : {},
+              ...projectId ? { projectId } : {},
+              ...context ? { context } : {}
             });
             res.json(result);
           } catch (error) {
-            res.status(404).json({ error: error.message });
+            const mapped = mapDataError(error, req.params?.object);
+            if (!isExpectedDataStatus(mapped.status)) logError("[REST] Unhandled error:", error);
+            res.status(mapped.status === 400 ? 404 : mapped.status).json(mapped.body);
           }
         },
         metadata: {
@@ -556,13 +995,20 @@ var RestServer = class {
         path: `${dataPath}/:object`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.createData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const context = await this.resolveExecCtx(projectId, req);
+            const result = await p.createData({
               object: req.params.object,
-              data: req.body
+              data: req.body,
+              ...projectId ? { projectId } : {},
+              ...context ? { context } : {}
             });
             res.status(201).json(result);
           } catch (error) {
-            res.status(400).json({ error: error.message });
+            const mapped = mapDataError(error, req.params?.object);
+            if (!isExpectedDataStatus(mapped.status)) logError("[REST] Unhandled error:", error);
+            res.status(mapped.status).json(mapped.body);
           }
         },
         metadata: {
@@ -577,14 +1023,21 @@ var RestServer = class {
         path: `${dataPath}/:object/:id`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.updateData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const context = await this.resolveExecCtx(projectId, req);
+            const result = await p.updateData({
               object: req.params.object,
               id: req.params.id,
-              data: req.body
+              data: req.body,
+              ...projectId ? { projectId } : {},
+              ...context ? { context } : {}
             });
             res.json(result);
           } catch (error) {
-            res.status(400).json({ error: error.message });
+            const mapped = mapDataError(error, req.params?.object);
+            if (!isExpectedDataStatus(mapped.status)) logError("[REST] Unhandled error:", error);
+            res.status(mapped.status).json(mapped.body);
           }
         },
         metadata: {
@@ -599,13 +1052,20 @@ var RestServer = class {
         path: `${dataPath}/:object/:id`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.deleteData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const context = await this.resolveExecCtx(projectId, req);
+            const result = await p.deleteData({
               object: req.params.object,
-              id: req.params.id
+              id: req.params.id,
+              ...projectId ? { projectId } : {},
+              ...context ? { context } : {}
             });
             res.json(result);
           } catch (error) {
-            res.status(400).json({ error: error.message });
+            const mapped = mapDataError(error, req.params?.object);
+            if (!isExpectedDataStatus(mapped.status)) logError("[REST] Unhandled error:", error);
+            res.status(mapped.status).json(mapped.body);
           }
         },
         metadata: {
@@ -621,6 +1081,7 @@ var RestServer = class {
   registerBatchEndpoints(basePath) {
     const { crud, batch } = this.config;
     const dataPath = `${basePath}${crud.dataPrefix}`;
+    const isScoped = basePath.includes("/projects/:projectId");
     const operations = batch.operations;
     if (batch.enableBatchEndpoint && this.protocol.batchData) {
       this.routeManager.register({
@@ -628,12 +1089,16 @@ var RestServer = class {
         path: `${dataPath}/:object/batch`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.batchData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const result = await p.batchData({
               object: req.params.object,
-              request: req.body
+              request: req.body,
+              ...projectId ? { projectId } : {}
             });
             res.json(result);
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(400).json({ error: error.message });
           }
         },
@@ -649,12 +1114,16 @@ var RestServer = class {
         path: `${dataPath}/:object/createMany`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.createManyData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const result = await p.createManyData({
               object: req.params.object,
-              records: req.body || []
+              records: req.body || [],
+              ...projectId ? { projectId } : {}
             });
             res.status(201).json(result);
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(400).json({ error: error.message });
           }
         },
@@ -670,12 +1139,16 @@ var RestServer = class {
         path: `${dataPath}/:object/updateMany`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.updateManyData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const result = await p.updateManyData({
               object: req.params.object,
-              ...req.body
+              ...req.body,
+              ...projectId ? { projectId } : {}
             });
             res.json(result);
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(400).json({ error: error.message });
           }
         },
@@ -691,12 +1164,16 @@ var RestServer = class {
         path: `${dataPath}/:object/deleteMany`,
         handler: async (req, res) => {
           try {
-            const result = await this.protocol.deleteManyData({
+            const projectId = isScoped ? req.params?.projectId : void 0;
+            const p = await this.resolveProtocol(projectId, req);
+            const result = await p.deleteManyData({
               object: req.params.object,
-              ...req.body
+              ...req.body,
+              ...projectId ? { projectId } : {}
             });
             res.json(result);
           } catch (error) {
+            logError("[REST] Unhandled error:", error);
             res.status(400).json({ error: error.message });
           }
         },
@@ -721,6 +1198,123 @@ var RestServer = class {
   }
 };
 
+// src/package-routes.ts
+function registerPackageRoutes(server, packageService, basePath = "/api/v1", options = {}) {
+  const packagesPath = `${basePath}/packages`;
+  server.post(packagesPath, async (req, res) => {
+    try {
+      const { manifest, metadata } = req.body || {};
+      if (!manifest || !metadata) {
+        res.status(400).json({ error: "Missing required fields: manifest, metadata" });
+        return;
+      }
+      if (!manifest.id || !manifest.version) {
+        res.status(400).json({ error: "Invalid manifest: id and version are required" });
+        return;
+      }
+      const result = await packageService.publish({ manifest, metadata });
+      if (result.success) {
+        res.json({
+          success: true,
+          message: `Published ${manifest.id}@${manifest.version}`,
+          package: {
+            id: manifest.id,
+            version: manifest.version
+          }
+        });
+        return;
+      }
+      res.status(400).json({ success: false, error: result.error });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  server.get(packagesPath, async (_req, res) => {
+    try {
+      const packagesMap = /* @__PURE__ */ new Map();
+      if (options.protocol && typeof options.protocol.getMetaItems === "function") {
+        try {
+          const result = await options.protocol.getMetaItems({ type: "package" });
+          if (result?.items) {
+            for (const item of result.items) {
+              const id = item.manifest?.id || item.id;
+              if (id) {
+                packagesMap.set(id, {
+                  ...item,
+                  source: "registry"
+                });
+              }
+            }
+          }
+        } catch {
+        }
+      }
+      try {
+        const dbPackages = await packageService.list();
+        for (const pkg of dbPackages) {
+          const id = pkg.manifest?.id || pkg.id;
+          if (id) {
+            packagesMap.set(id, {
+              ...packagesMap.get(id),
+              ...pkg,
+              source: packagesMap.has(id) ? "both" : "database"
+            });
+          }
+        }
+      } catch {
+      }
+      const packages = Array.from(packagesMap.values());
+      res.json({ packages, total: packages.length });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  server.get(`${packagesPath}/:id`, async (req, res) => {
+    try {
+      const packageId = req.params.id;
+      const version = req.query?.version || "latest";
+      const pkg = await packageService.get(packageId, version);
+      if (pkg) {
+        res.json({ package: { ...pkg, source: "database" } });
+        return;
+      }
+      if (options.protocol && typeof options.protocol.getMetaItems === "function") {
+        try {
+          const result = await options.protocol.getMetaItems({ type: "package" });
+          const match = result?.items?.find(
+            (item) => (item.manifest?.id || item.id) === packageId
+          );
+          if (match) {
+            res.json({ package: { ...match, source: "registry" } });
+            return;
+          }
+        } catch {
+        }
+      }
+      res.status(404).json({ error: "Package not found" });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  server.delete(`${packagesPath}/:id`, async (req, res) => {
+    try {
+      const packageId = req.params.id;
+      const version = req.query?.version;
+      const result = await packageService.delete(packageId, version);
+      if (result.success) {
+        res.json({
+          success: true,
+          message: `Deleted ${packageId}${version ? `@${version}` : ""}`
+        });
+        return;
+      }
+      res.status(400).json({ success: false });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+}
+
 // src/rest-api-plugin.ts
 function createRestApiPlugin(config = {}) {
   return {
@@ -741,6 +1335,39 @@ function createRestApiPlugin(config = {}) {
         protocol = ctx.getService(protocolService);
       } catch (e) {
       }
+      let kernelManager;
+      const kernelManagerService = config.kernelManagerServiceName || "kernel-manager";
+      try {
+        kernelManager = ctx.getService(kernelManagerService);
+      } catch (e) {
+      }
+      let envRegistry;
+      try {
+        envRegistry = ctx.getService("env-registry");
+      } catch (e) {
+      }
+      const defaultProjectIdProvider = () => {
+        try {
+          const dp = ctx.getService("default-project");
+          return dp?.projectId;
+        } catch {
+          return void 0;
+        }
+      };
+      const authServiceProvider = async (_projectId) => {
+        try {
+          return ctx.getService("auth");
+        } catch {
+          return void 0;
+        }
+      };
+      const objectQLProvider = async (_projectId) => {
+        try {
+          return ctx.getService("objectql");
+        } catch {
+          return void 0;
+        }
+      };
       if (!server) {
         ctx.logger.warn(`RestApiPlugin: HTTP Server service '${serverService}' not found. REST routes skipped.`);
         return;
@@ -751,13 +1378,38 @@ function createRestApiPlugin(config = {}) {
       }
       ctx.logger.info("Hydrating REST API from Protocol...");
       try {
-        const restServer = new RestServer(server, protocol, config.api);
+        const restServer = new RestServer(server, protocol, config.api, kernelManager, envRegistry, defaultProjectIdProvider, authServiceProvider, objectQLProvider);
         restServer.registerRoutes();
         ctx.logger.info("REST API successfully registered");
       } catch (err) {
         ctx.logger.error("Failed to register REST API routes", { error: err.message });
         throw err;
       }
+      try {
+        const packageService = ctx.getService("package");
+        if (packageService) {
+          const basePath = config.api?.api?.basePath || "/api";
+          const version = config.api?.api?.version || "v1";
+          const versionedBase = `${basePath}/${version}`;
+          const enableProjectScoping = config.api?.api?.enableProjectScoping ?? false;
+          const projectResolution = config.api?.api?.projectResolution ?? "auto";
+          if (enableProjectScoping && projectResolution === "required") {
+            registerPackageRoutes(server, packageService, `${versionedBase}/projects/:projectId`, {
+              protocol
+            });
+          } else {
+            registerPackageRoutes(server, packageService, versionedBase, { protocol });
+            if (enableProjectScoping) {
+              registerPackageRoutes(server, packageService, `${versionedBase}/projects/:projectId`, {
+                protocol
+              });
+            }
+          }
+          ctx.logger.info("Package management routes registered");
+        }
+      } catch (e) {
+        ctx.logger.debug("Package service not available, package routes skipped");
+      }
     }
   };
 }