@jskit-ai/kernel 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"

package/server/http/lib/kernel.test.js

@@ -96,17 +96,26 @@ test("registerRoutes attaches request.executeAction and applies action context c
 
   registerActionContextContributor(app, "test.auth.actionContextContributor", () => ({
     contributorId: "test.auth",
-    contribute({ request }) {
+    contribute({ request, definition }) {
       return {
         actor: request?.user || null,
         permissions: Array.isArray(request?.permissions) ? request.permissions.slice() : [],
         workspace: request?.workspace || null,
-        membership: request?.membership || null
+        membership: request?.membership || null,
+        requestMeta: {
+          definitionId: definition?.id || ""
+        }
       };
     }
   }));
 
   app.instance("actionExecutor", {
+    getDefinition(actionId) {
+      return {
+        id: actionId,
+        surfaces: ["coffie"]
+      };
+    },
     async execute(payload) {
       observed.push(payload);
       return {
@@ -195,6 +204,7 @@ test("registerRoutes attaches request.executeAction and applies action context c
   assert.equal(observed[0].context.surface, "coffie");
   assert.equal(observed[0].context.channel, "api");
   assert.equal(observed[0].context.requestMeta.commandId, "cmd-1");
+  assert.equal(observed[0].context.requestMeta.definitionId, "settings.read");
   assert.equal(observed[0].context.requestMeta.request, request);
 
   assert.equal(observed[1].actionId, "settings.override");

package/server/http/lib/requestActionExecutor.js

@@ -83,6 +83,7 @@ async function enrichActionExecutionContext({
   request = null,
   actionId = "",
   version = null,
+  definition = null,
   input = {},
   deps = {},
   channel = "api",
@@ -108,6 +109,7 @@ async function enrichActionExecutionContext({
       request,
       actionId: normalizedActionId,
       version: version == null ? null : version,
+      definition,
       input: normalizedInput,
       deps: normalizedDeps,
       channel: normalizedChannel,
@@ -201,6 +203,10 @@ function attachRequestActionExecutor({
     if (!actionExecutor || typeof actionExecutor.execute !== "function") {
       throw new RouteRegistrationError(`"${normalizedActionExecutorToken}" must provide execute().`);
     }
+    const definition =
+      typeof actionExecutor.getDefinition === "function"
+        ? actionExecutor.getDefinition(source.actionId, source.version == null ? null : source.version)
+        : null;
 
     const baseContext = buildActionExecutionContext({
       request,
@@ -213,6 +219,7 @@ function attachRequestActionExecutor({
       request,
       actionId: source.actionId,
       version: source.version == null ? null : source.version,
+      definition,
       input: normalizedInput,
       deps: normalizedDeps,
       channel: normalizedChannel,

package/server/runtime/fastifyBootstrap.js

@@ -144,6 +144,10 @@ function registerApiErrorHandler(
   const recordDbError = typeof onRecordDbError === "function" ? onRecordDbError : () => {};
   const captureServerError = typeof onCaptureServerError === "function" ? onCaptureServerError : () => {};
 
+  function shouldExposeAppErrorDetails(errorCode = "") {
+    return String(errorCode || "").trim() !== "ACTION_PERMISSION_DENIED";
+  }
+
   app.setErrorHandler((error, request, reply) => {
     const normalizedErrorCode = String(error?.code || "").trim();
     const isCsrfErrorCode = normalizedErrorCode.startsWith("FST_CSRF_");
@@ -177,7 +181,7 @@ function registerApiErrorHandler(
         error: error.message,
         code: appErrorCode
       };
-      if (error.details) {
+      if (error.details && shouldExposeAppErrorDetails(appErrorCode)) {
         payload.details = error.details;
         if (error.details.fieldErrors) {
           payload.fieldErrors = error.details.fieldErrors;

package/server/runtime/fastifyBootstrap.test.js

@@ -103,6 +103,28 @@ test("registerApiErrorHandler falls back to app_error code for AppError without
   assert.equal(reply.payload.code, "app_error");
 });
 
+test("registerApiErrorHandler hides internal permission details for action permission denials", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new AppError(403, "Forbidden.", {
+    code: "ACTION_PERMISSION_DENIED",
+    details: {
+      actionId: "crud.breeds.list",
+      permission: "crud.breeds.list"
+    }
+  });
+
+  fastify.errorHandler(error, {}, reply);
+
+  assert.equal(reply.statusCode, 403);
+  assert.deepEqual(reply.payload, {
+    error: "Forbidden.",
+    code: "ACTION_PERMISSION_DENIED"
+  });
+});
+
 test("registerApiErrorHandler includes internal_server_error code for unhandled 500 errors", () => {
   const fastify = createFastifyStub();
   registerApiErrorHandler(fastify, { isAppError });

package/server/runtime/serviceAuthorization.test.js

@@ -88,12 +88,12 @@ test("requireAuth allows namespace wildcard permissions", () => {
       {
         context: {
           actor: { id: 1 },
-          permissions: ["crud_contacts.*"]
+          permissions: ["crud.contacts.*"]
         }
       },
       {
         require: "all",
-        permissions: ["crud_contacts.update"]
+        permissions: ["crud.contacts.update"]
       }
     )
   );

package/shared/support/crudLookup.js

@@ -64,7 +64,7 @@ function resolveCrudLookupContainerKey(resource = {}, options = {}) {
   return normalizeCrudLookupContainerKey(lookup?.containerKey, options);
 }
 
-function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
+function resolveCrudLookupFieldEntries(resource = {}, { allowKeys = [] } = {}) {
   const source = resource && typeof resource === "object" && !Array.isArray(resource) ? resource : {};
   const entries = Array.isArray(source.fieldMeta) ? source.fieldMeta : [];
   const allowedKeySet = new Set(
@@ -97,12 +97,67 @@ function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
     }
 
     seenKeys.add(key);
-    keys.push(key);
+    keys.push(
+      Object.freeze({
+        key,
+        parentRouteParamKey: normalizeText(entry.parentRouteParamKey)
+      })
+    );
   }
 
   return Object.freeze(keys);
 }
 
+function resolveCrudLookupCreateSchemaKeys(resource = {}) {
+  const createSchemaProperties = resource?.operations?.create?.bodyValidator?.schema?.properties;
+  if (!createSchemaProperties || typeof createSchemaProperties !== "object" || Array.isArray(createSchemaProperties)) {
+    return Object.freeze([]);
+  }
+
+  return Object.freeze(Object.keys(createSchemaProperties));
+}
+
+function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
+  return Object.freeze(
+    resolveCrudLookupFieldEntries(resource, { allowKeys })
+      .map(({ key }) => key)
+  );
+}
+
+function resolveCrudParentFilterKeys(resource = {}) {
+  return resolveCrudLookupFieldKeys(resource, {
+    allowKeys: resolveCrudLookupCreateSchemaKeys(resource)
+  });
+}
+
+function resolveCrudLookupFieldKeyFromRouteParam(resource = {}, routeParamKey = "", { allowKeys = [] } = {}) {
+  const normalizedRouteParamKey = normalizeText(routeParamKey);
+  if (!normalizedRouteParamKey) {
+    return "";
+  }
+
+  const entries = resolveCrudLookupFieldEntries(resource, { allowKeys });
+  for (const entry of entries) {
+    if (entry.key === normalizedRouteParamKey) {
+      return entry.key;
+    }
+  }
+
+  for (const entry of entries) {
+    if (entry.parentRouteParamKey === normalizedRouteParamKey) {
+      return entry.key;
+    }
+  }
+
+  return "";
+}
+
+function resolveCrudParentFilterFieldKeyFromRouteParam(resource = {}, routeParamKey = "") {
+  return resolveCrudLookupFieldKeyFromRouteParam(resource, routeParamKey, {
+    allowKeys: resolveCrudLookupCreateSchemaKeys(resource)
+  });
+}
+
 export {
   DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
   normalizeCrudLookupApiPath,
@@ -110,5 +165,8 @@ export {
   resolveCrudLookupApiPathFromNamespace,
   normalizeCrudLookupContainerKey,
   resolveCrudLookupContainerKey,
-  resolveCrudLookupFieldKeys
+  resolveCrudLookupFieldKeys,
+  resolveCrudParentFilterKeys,
+  resolveCrudLookupFieldKeyFromRouteParam,
+  resolveCrudParentFilterFieldKeyFromRouteParam
 };

package/shared/support/crudLookup.test.js

@@ -7,7 +7,10 @@ import {
   resolveCrudLookupApiPathFromNamespace,
   normalizeCrudLookupContainerKey,
   resolveCrudLookupContainerKey,
-  resolveCrudLookupFieldKeys
+  resolveCrudParentFilterKeys,
+  resolveCrudLookupFieldKeys,
+  resolveCrudLookupFieldKeyFromRouteParam,
+  resolveCrudParentFilterFieldKeyFromRouteParam
 } from "./crudLookup.js";
 
 test("normalizeCrudLookupApiPath normalizes and rejects root", () => {
@@ -69,6 +72,7 @@ test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-l
       },
       {
         key: "vetId",
+        parentRouteParamKey: "primaryVetId",
         relation: {
           kind: "lookup",
           apiPath: "/vets",
@@ -81,3 +85,139 @@ test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-l
   assert.deepEqual(resolveCrudLookupFieldKeys(resource), ["contactId", "vetId"]);
   assert.deepEqual(resolveCrudLookupFieldKeys(resource, { allowKeys: ["vetId", "missing"] }), ["vetId"]);
 });
+
+test("resolveCrudLookupFieldKeyFromRouteParam matches parent route param aliases to canonical lookup field keys", () => {
+  const resource = {
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "serviceId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId"), "staffContactId");
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "staffContactId"), "staffContactId");
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "serviceId"), "serviceId");
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "unknown"), "");
+  assert.equal(
+    resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId", { allowKeys: ["serviceId"] }),
+    ""
+  );
+});
+
+test("resolveCrudLookupFieldKeyFromRouteParam prefers exact field keys before alias matches", () => {
+  const resource = {
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId"), "contactId");
+});
+
+test("resolveCrudParentFilterKeys keeps only lookup keys that are writable through create", () => {
+  const resource = {
+    operations: {
+      create: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              serviceId: { type: "integer" }
+            }
+          }
+        }
+      }
+    },
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "serviceId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.deepEqual(resolveCrudParentFilterKeys(resource), ["serviceId"]);
+});
+
+test("resolveCrudParentFilterFieldKeyFromRouteParam uses the same allowed keys as server parent filters", () => {
+  const resource = {
+    operations: {
+      create: {
+        bodyValidator: {
+          schema: {
+            type: "object",
+            properties: {
+              serviceId: { type: "integer" }
+            }
+          }
+        }
+      }
+    },
+    fieldMeta: [
+      {
+        key: "staffContactId",
+        parentRouteParamKey: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "serviceId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.equal(resolveCrudParentFilterFieldKeyFromRouteParam(resource, "contactId"), "");
+  assert.equal(resolveCrudParentFilterFieldKeyFromRouteParam(resource, "serviceId"), "serviceId");
+});

package/shared/validators/cursorPaginationQueryValidator.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { normalizeText } from "../support/normalize.js";
 import { normalizeObjectInput } from "./inputNormalization.js";
 import { positiveIntegerValidator } from "./recordIdParamsValidator.js";
 
@@ -7,7 +8,7 @@ function normalizeCursorPaginationQuery(input = {}) {
   const normalized = {};
 
   if (Object.hasOwn(source, "cursor")) {
-    normalized.cursor = positiveIntegerValidator.normalize(source.cursor);
+    normalized.cursor = normalizeText(source.cursor);
   }
 
   if (Object.hasOwn(source, "limit")) {

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -2,18 +2,20 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
 
-test("cursorPaginationQueryValidator normalizes numeric strings", () => {
+test("cursorPaginationQueryValidator normalizes numeric strings as cursor text", () => {
   assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "12", limit: "25" }), {
-    cursor: 12,
+    cursor: "12",
     limit: 25
   });
 });
 
-test("cursorPaginationQueryValidator normalizes invalid values to 0", () => {
-  assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "abc", limit: "-1" }), {
-    cursor: 0,
-    limit: 0
-  });
+test("cursorPaginationQueryValidator schema rejects opaque cursor strings", () => {
+  assert.equal(
+    cursorPaginationQueryValidator.schema.properties.cursor.anyOf.some(
+      (entry) => entry.type === "string" && entry.pattern === "^[1-9][0-9]*$"
+    ),
+    true
+  );
 });
 
 test("cursorPaginationQueryValidator keeps absent keys absent", () => {

package/shared/validators/htmlTimeSchemas.js

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+
+const HTML_TIME_STRING_SCHEMA = Type.String({
+  pattern: "^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d)?$",
+  minLength: 5
+});
+
+const NULLABLE_HTML_TIME_STRING_SCHEMA = Type.Union([HTML_TIME_STRING_SCHEMA, Type.Null()]);
+
+export {
+  HTML_TIME_STRING_SCHEMA,
+  NULLABLE_HTML_TIME_STRING_SCHEMA
+};

package/shared/validators/index.js

@@ -1,6 +1,10 @@
 export { normalizeObjectInput } from "./inputNormalization.js";
 export { createCursorListValidator } from "./createCursorListValidator.js";
 export { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
+export {
+  HTML_TIME_STRING_SCHEMA,
+  NULLABLE_HTML_TIME_STRING_SCHEMA
+} from "./htmlTimeSchemas.js";
 export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
 export { mergeValidators } from "./mergeValidators.js";
 export { nestValidator } from "./nestValidator.js";