@jskit-ai/kernel 0.1.4

package/shared/actions/policies.js

@@ -0,0 +1,342 @@
+import { Check, Errors } from "typebox/value";
+import { createActionRuntimeError } from "./actionDefinitions.js";
+import { normalizeLowerText, normalizeText } from "./textNormalization.js";
+import { hasPermission, normalizePermissionList } from "../support/permissions.js";
+import { isRecord, normalizeOpaqueId } from "../support/normalize.js";
+
+function createActionValidationError({
+  status = 400,
+  message = "Validation failed.",
+  code = "ACTION_VALIDATION_FAILED",
+  details,
+  cause
+} = {}) {
+  return createActionRuntimeError(status, message, {
+    code,
+    details,
+    cause
+  });
+}
+
+function ensureActionChannelAllowed(definition, context) {
+  const channel = normalizeLowerText(context?.channel);
+  const allowedChannels = Array.isArray(definition?.channels) ? definition.channels : [];
+
+  if (!channel || !allowedChannels.includes(channel)) {
+    throw createActionRuntimeError(403, "Forbidden.", {
+      code: "ACTION_CHANNEL_FORBIDDEN",
+      details: {
+        actionId: definition?.id,
+        channel
+      }
+    });
+  }
+}
+
+function ensureActionSurfaceAllowed(definition, context) {
+  const surface = normalizeLowerText(context?.surface);
+  const allowedSurfaces = Array.isArray(definition?.surfaces) ? definition.surfaces : [];
+
+  if (!surface || !allowedSurfaces.includes(surface)) {
+    throw createActionRuntimeError(403, "Forbidden.", {
+      code: "ACTION_SURFACE_FORBIDDEN",
+      details: {
+        actionId: definition?.id,
+        surface
+      }
+    });
+  }
+}
+
+function ensureActionPermissionAllowed(definition, context) {
+  const permission = isRecord(definition?.permission) ? definition.permission : { require: "none" };
+  const mode = normalizeLowerText(permission.require || "none");
+
+  if (mode === "none") {
+    return;
+  }
+
+  const actorId = normalizeOpaqueId(context?.actor?.id);
+  if (actorId == null) {
+    throw createActionRuntimeError(401, permission.message || "Authentication required.", {
+      code: permission.code || "ACTION_AUTHENTICATION_REQUIRED",
+      details: {
+        actionId: definition?.id
+      }
+    });
+  }
+
+  if (mode === "authenticated") {
+    return;
+  }
+
+  const requiredPermissions = normalizePermissionList(permission.permissions);
+  if (requiredPermissions.length < 1) {
+    return;
+  }
+
+  const actorPermissions = normalizePermissionList(context?.permissions);
+  if (mode === "all") {
+    for (const requiredPermission of requiredPermissions) {
+      if (hasPermission(actorPermissions, requiredPermission)) {
+        continue;
+      }
+
+      throw createActionRuntimeError(403, permission.message || "Forbidden.", {
+        code: permission.code || "ACTION_PERMISSION_DENIED",
+        details: {
+          actionId: definition?.id,
+          permission: requiredPermission
+        }
+      });
+    }
+
+    return;
+  }
+
+  const hasAnyPermission = requiredPermissions.some((requiredPermission) => hasPermission(actorPermissions, requiredPermission));
+  if (!hasAnyPermission) {
+    throw createActionRuntimeError(403, permission.message || "Forbidden.", {
+      code: permission.code || "ACTION_PERMISSION_DENIED",
+      details: {
+        actionId: definition?.id,
+        requiredPermissions
+      }
+    });
+  }
+}
+
+function normalizeSchemaValidationErrors(schema) {
+  const errors = Array.isArray(schema?.errors) ? schema.errors : [];
+  if (errors.length < 1) {
+    return null;
+  }
+
+  const fieldErrors = {};
+  for (const entry of errors) {
+    const rawFieldPath = normalizeText(entry?.path || entry?.instancePath || entry?.field || "");
+    const fieldPath = rawFieldPath
+      ? rawFieldPath.replace(/^\//, "").replace(/\//g, ".")
+      : "input";
+    const message = normalizeText(entry?.message || "Invalid value.") || "Invalid value.";
+    fieldErrors[fieldPath] = message;
+  }
+
+  return Object.keys(fieldErrors).length > 0 ? fieldErrors : null;
+}
+
+function buildSchemaValidatorError({ phase, definition } = {}) {
+  return createActionValidationError({
+    details: {
+      error: "Schema validator must return { ok, value, errors } or throw.",
+      phase,
+      actionId: definition?.id,
+      version: definition?.version
+    }
+  });
+}
+
+function normalizeTypeBoxValidationErrors(schema, payload) {
+  const issues = Check(schema, payload) ? [] : [...Errors(schema, payload)];
+  if (issues.length < 1) {
+    return null;
+  }
+
+  return normalizeSchemaValidationErrors({
+    errors: issues
+  });
+}
+
+function normalizeFunctionSchemaResult(result, payload, { phase, definition } = {}) {
+  if (!isRecord(result) || typeof result.ok !== "boolean") {
+    throw buildSchemaValidatorError({ phase, definition });
+  }
+
+  if (result.ok) {
+    if (Object.hasOwn(result, "value")) {
+      return result.value;
+    }
+    return payload;
+  }
+
+  const details = {};
+  if (Object.hasOwn(result, "errors")) {
+    if (Array.isArray(result.errors)) {
+      const fieldErrors = normalizeSchemaValidationErrors({ errors: result.errors });
+      if (fieldErrors) {
+        details.fieldErrors = fieldErrors;
+      } else {
+        details.errors = result.errors;
+      }
+    } else if (result.errors && typeof result.errors === "object") {
+      details.fieldErrors = result.errors;
+    } else if (result.errors != null) {
+      details.error = String(result.errors);
+    }
+  }
+
+  throw createActionValidationError({
+    details: Object.keys(details).length > 0 ? details : undefined
+  });
+}
+
+async function normalizeValidatorPayload(validator, payload, { phase, definition, context }) {
+  if (!validator || typeof validator !== "object") {
+    return payload;
+  }
+
+  if (typeof validator.normalize !== "function") {
+    return payload;
+  }
+
+  return await validator.normalize(payload, {
+    phase,
+    actionId: definition?.id,
+    version: definition?.version,
+    context
+  });
+}
+
+async function validateSchemaPayload(schema, payload, { phase, definition }) {
+  if (schema == null) {
+    return payload;
+  }
+
+  if (typeof schema === "function") {
+    const result = await schema(payload, {
+      phase,
+      actionId: definition?.id,
+      version: definition?.version
+    });
+    return normalizeFunctionSchemaResult(result, payload, { phase, definition });
+  }
+
+  if (!isRecord(schema)) {
+    throw buildSchemaValidatorError({ phase, definition });
+  }
+
+  if (typeof schema.parse === "function") {
+    return schema.parse(payload);
+  }
+
+  if (typeof schema.assert === "function") {
+    const assertionResult = await schema.assert(payload);
+    return assertionResult == null ? payload : assertionResult;
+  }
+
+  if (typeof schema.check === "function") {
+    const valid = await schema.check(payload);
+    if (!valid) {
+      throw createActionValidationError();
+    }
+    return payload;
+  }
+
+  if (typeof schema.validate === "function") {
+    const valid = await schema.validate(payload);
+    if (!valid) {
+      throw createActionValidationError({
+        details: {
+          fieldErrors: normalizeSchemaValidationErrors(schema)
+        }
+      });
+    }
+    return payload;
+  }
+
+  const fieldErrors = normalizeTypeBoxValidationErrors(schema, payload);
+  if (!fieldErrors) {
+    return payload;
+  }
+
+  throw createActionValidationError({
+    details: {
+      fieldErrors
+    }
+  });
+}
+
+async function normalizeActionInput(definition, input, context) {
+  try {
+    const normalizedInput = await normalizeValidatorPayload(definition?.inputValidator, input, {
+      phase: "input",
+      definition,
+      context
+    });
+
+    return await validateSchemaPayload(definition?.inputValidator?.schema, normalizedInput, {
+      phase: "input",
+      definition,
+      context
+    });
+  } catch (error) {
+    if (error?.code === "ACTION_VALIDATION_FAILED") {
+      throw error;
+    }
+
+    throw createActionValidationError({
+      details: {
+        error: String(error?.message || "Invalid input.")
+      },
+      cause: error
+    });
+  }
+}
+
+async function normalizeActionOutput(definition, output, context) {
+  if (!definition?.outputValidator) {
+    return output;
+  }
+
+  try {
+    const normalizedOutput = await normalizeValidatorPayload(definition.outputValidator, output, {
+      phase: "output",
+      definition,
+      context
+    });
+
+    return await validateSchemaPayload(definition.outputValidator.schema, normalizedOutput, {
+      phase: "output",
+      definition,
+      context
+    });
+  } catch (error) {
+    if (error?.code === "ACTION_VALIDATION_FAILED") {
+      throw createActionValidationError({
+        status: 500,
+        message: "Action output validation failed.",
+        code: "ACTION_OUTPUT_VALIDATION_FAILED",
+        details: error.details,
+        cause: error
+      });
+    }
+
+    throw createActionValidationError({
+      status: 500,
+      message: "Action output validation failed.",
+      code: "ACTION_OUTPUT_VALIDATION_FAILED",
+      details: {
+        error: String(error?.message || "Invalid output.")
+      },
+      cause: error
+    });
+  }
+}
+
+const __testables = {
+  normalizeText,
+  normalizeLowerText,
+  normalizeSchemaValidationErrors,
+  normalizeTypeBoxValidationErrors,
+  normalizeValidatorPayload,
+  validateSchemaPayload
+};
+
+export {
+  ensureActionChannelAllowed,
+  ensureActionSurfaceAllowed,
+  ensureActionPermissionAllowed,
+  normalizeActionInput,
+  normalizeActionOutput,
+  __testables
+};

package/shared/actions/policies.test.js

@@ -0,0 +1,233 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "typebox";
+
+import { ensureActionPermissionAllowed, normalizeActionInput, normalizeActionOutput } from "./policies.js";
+
+test("function schema returns normalized value when ok", async () => {
+  const definition = {
+    id: "tests.ok",
+    version: 1,
+    inputValidator: {
+      schema: () => ({
+        ok: true,
+        value: {
+          normalized: true
+        }
+      })
+    }
+  };
+
+  const result = await normalizeActionInput(definition, { raw: true }, {});
+  assert.deepEqual(result, { normalized: true });
+});
+
+test("function schema rejects non-validator results", async () => {
+  const definition = {
+    id: "tests.invalid",
+    version: 1,
+    inputValidator: {
+      schema: () => false
+    }
+  };
+
+  await assert.rejects(
+    () => normalizeActionInput(definition, { raw: true }, {}),
+    (error) => {
+      assert.equal(error.code, "ACTION_VALIDATION_FAILED");
+      assert.match(error.details?.error || "", /Schema validator must return/);
+      return true;
+    }
+  );
+});
+
+test("function schema propagates validation errors", async () => {
+  const definition = {
+    id: "tests.errors",
+    version: 2,
+    inputValidator: {
+      schema: () => ({
+        ok: false,
+        errors: {
+          input: "input is required"
+        }
+      })
+    }
+  };
+
+  await assert.rejects(
+    () => normalizeActionInput(definition, null, {}),
+    (error) => {
+      assert.equal(error.code, "ACTION_VALIDATION_FAILED");
+      assert.deepEqual(error.details?.fieldErrors, {
+        input: "input is required"
+      });
+      return true;
+    }
+  );
+});
+
+test("raw TypeBox action schemas validate normalized action input", async () => {
+  const definition = {
+    id: "tests.typebox",
+    version: 1,
+    inputValidator: {
+      schema: Type.Object(
+        {
+          workspaceSlug: Type.String({ minLength: 1 })
+        },
+        { additionalProperties: false }
+      ),
+      normalize(value = {}) {
+        return {
+          workspaceSlug: String(value.workspaceSlug || "").trim().toLowerCase()
+        };
+      }
+    }
+  };
+
+  const result = await normalizeActionInput(definition, { workspaceSlug: "  ACME  " }, {});
+  assert.deepEqual(result, { workspaceSlug: "acme" });
+});
+
+test("typebox input validation normalizes pointer field errors to plain keys", async () => {
+  const definition = {
+    id: "tests.typebox.errors",
+    version: 1,
+    inputValidator: {
+      schema: Type.Object(
+        {
+          name: Type.String({ maxLength: 1 })
+        },
+        { additionalProperties: false }
+      )
+    }
+  };
+
+  await assert.rejects(
+    () => normalizeActionInput(definition, { name: "too long" }, {}),
+    (error) => {
+      const fieldErrors = error.details?.fieldErrors || {};
+      assert.equal(typeof fieldErrors.name, "string");
+      assert.equal(Object.hasOwn(fieldErrors, "/name"), false);
+      return true;
+    }
+  );
+});
+
+test("action output normalization runs before output validation", async () => {
+  const definition = {
+    id: "tests.output",
+    version: 1,
+    outputValidator: {
+      schema: Type.Object(
+        {
+          ok: Type.Boolean()
+        },
+        { additionalProperties: false }
+      ),
+      normalize(payload = {}) {
+        return {
+          ok: Boolean(payload.ok)
+        };
+      }
+    }
+  };
+
+  const result = await normalizeActionOutput(definition, { ok: 1 }, {});
+  assert.deepEqual(result, { ok: true });
+});
+
+test("action permission denies unauthenticated access when required", () => {
+  assert.throws(
+    () =>
+      ensureActionPermissionAllowed(
+        {
+          id: "tests.secure",
+          permission: {
+            require: "authenticated"
+          }
+        },
+        {
+          permissions: []
+        }
+      ),
+    (error) => error?.statusCode === 401 && error?.code === "ACTION_AUTHENTICATION_REQUIRED"
+  );
+});
+
+test("action permission enforces required permissions", () => {
+  assert.throws(
+    () =>
+      ensureActionPermissionAllowed(
+        {
+          id: "tests.secure.perm",
+          permission: {
+            require: "all",
+            permissions: ["workspace.settings.update"]
+          }
+        },
+        {
+          actor: {
+            id: 7
+          },
+          permissions: ["workspace.settings.view"]
+        }
+      ),
+    (error) => error?.statusCode === 403 && error?.code === "ACTION_PERMISSION_DENIED"
+  );
+
+  assert.doesNotThrow(() =>
+    ensureActionPermissionAllowed(
+      {
+        id: "tests.secure.perm",
+        permission: {
+          require: "all",
+          permissions: ["workspace.settings.update"]
+        }
+      },
+      {
+        actor: {
+          id: 7
+        },
+        permissions: ["workspace.settings.update"]
+      }
+    )
+  );
+
+  assert.doesNotThrow(() =>
+    ensureActionPermissionAllowed(
+      {
+        id: "tests.secure.perm",
+        permission: {
+          require: "all",
+          permissions: ["workspace.settings.update"]
+        }
+      },
+      {
+        actor: {
+          id: 7
+        },
+        permissions: ["workspace.settings.*"]
+      }
+    )
+  );
+
+  assert.doesNotThrow(() =>
+    ensureActionPermissionAllowed(
+      {
+        id: "tests.secure.perm",
+        permission: {
+          require: "all",
+          permissions: ["workspace.settings.update"]
+        }
+      },
+      {
+        actor: {
+          id: "user-7"
+        },
+        permissions: ["workspace.settings.update"]
+      }
+    )
+  );
+});