@jskit-ai/kernel 0.1.244 → 0.1.246

package/server/runtime/moduleConfig.js

@@ -1,223 +0,0 @@
-import { deepFreeze } from "../../shared/support/deepFreeze.js";
-import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
-import { validateSchemaPayload } from "../../shared/validators/schemaPayloadValidation.js";
-
-function normalizeModuleId(value) {
-  const moduleId = normalizeText(value);
-  if (!moduleId) {
-    throw new TypeError("defineModuleConfig requires a non-empty moduleId.");
-  }
-  return moduleId;
-}
-
-function normalizeSchema(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError("defineModuleConfig requires a schema object.");
-  }
-  return value;
-}
-
-function formatIssues(issues = []) {
-  return issues
-    .slice(0, 8)
-    .map((issue) => `${issue.path}: ${issue.message}`)
-    .join("; ");
-}
-
-function buildInvalidConfigMessage(moduleId, issues = []) {
-  const summary = formatIssues(issues);
-  if (!summary) {
-    return `Invalid config for module "${moduleId}".`;
-  }
-  return `Invalid config for module "${moduleId}": ${summary}`;
-}
-
-function normalizeCustomValidationIssues(result) {
-  if (result == null || result === true) {
-    return [];
-  }
-
-  if (result === false) {
-    return [
-      {
-        path: "(custom)",
-        message: "Custom module config validation failed."
-      }
-    ];
-  }
-
-  if (typeof result === "string") {
-    return [
-      {
-        path: "(custom)",
-        message: normalizeText(result) || "Custom module config validation failed."
-      }
-    ];
-  }
-
-  if (Array.isArray(result)) {
-    return result
-      .map((entry) => {
-        if (typeof entry === "string") {
-          return {
-            path: "(custom)",
-            message: normalizeText(entry) || "Custom module config validation failed."
-          };
-        }
-
-        if (!entry || typeof entry !== "object") {
-          return null;
-        }
-
-        return {
-          path: normalizeText(entry.path, { fallback: "(custom)" }),
-          message: normalizeText(entry.message, { fallback: "Custom module config validation failed." })
-        };
-      })
-      .filter(Boolean);
-  }
-
-  if (result && typeof result === "object" && Array.isArray(result.issues)) {
-    return normalizeCustomValidationIssues(result.issues);
-  }
-
-  return [
-    {
-      path: "(custom)",
-      message: "Custom module config validation failed."
-    }
-  ];
-}
-
-class ModuleConfigError extends Error {
-  constructor(message, { moduleId = "", issues = [], cause } = {}) {
-    super(String(message || "Module config error."));
-    this.name = "ModuleConfigError";
-    this.moduleId = normalizeText(moduleId);
-    this.issues = Object.freeze(Array.isArray(issues) ? [...issues] : []);
-    if (cause !== undefined) {
-      this.cause = cause;
-    }
-  }
-}
-
-function validateSchemaOrThrow({ moduleId, schema, value, coerce = false }) {
-  const schemaDefinition = {
-    schema,
-    mode: "replace"
-  };
-
-  try {
-    return validateSchemaPayload(schemaDefinition, value, {
-      phase: "input",
-      context: `module config "${moduleId}"`
-    });
-  } catch (cause) {
-    const fieldErrors = normalizeObject(cause?.fieldErrors);
-    const issues = Object.keys(fieldErrors).length > 0
-      ? Object.keys(fieldErrors).map((path) => ({
-          path,
-          message: normalizeText(fieldErrors[path], { fallback: "Invalid value." }),
-          keyword: ""
-        }))
-      : [
-          {
-            path: "(root)",
-            message: normalizeText(cause?.message, { fallback: "Invalid value." }),
-            keyword: ""
-          }
-        ];
-
-    throw new ModuleConfigError(buildInvalidConfigMessage(moduleId, issues), {
-      moduleId,
-      issues,
-      cause
-    });
-  }
-}
-
-function defineModuleConfig({
-  moduleId,
-  schema,
-  load = ({ env }) => env,
-  transform = null,
-  validate = null,
-  coerce = false,
-  freeze = true
-} = {}) {
-  const normalizedModuleId = normalizeModuleId(moduleId);
-  const normalizedSchema = normalizeSchema(schema);
-
-  if (typeof load !== "function") {
-    throw new TypeError(`defineModuleConfig("${normalizedModuleId}") requires load to be a function.`);
-  }
-  if (transform != null && typeof transform !== "function") {
-    throw new TypeError(`defineModuleConfig("${normalizedModuleId}") requires transform to be a function when provided.`);
-  }
-  if (validate != null && typeof validate !== "function") {
-    throw new TypeError(`defineModuleConfig("${normalizedModuleId}") requires validate to be a function when provided.`);
-  }
-
-  function resolve(options = {}) {
-    const source = normalizeObject(options);
-    const env = source.env && typeof source.env === "object" ? source.env : process.env;
-    const context = source.context;
-    const hasRaw = Object.prototype.hasOwnProperty.call(source, "raw");
-
-    let loadedConfig;
-    try {
-      loadedConfig = hasRaw ? source.raw : load({ env, context, moduleId: normalizedModuleId });
-    } catch (cause) {
-      throw new ModuleConfigError(`Failed to load config for module "${normalizedModuleId}".`, {
-        moduleId: normalizedModuleId,
-        cause
-      });
-    }
-
-    let candidate = loadedConfig;
-    if (typeof transform === "function") {
-      candidate = transform(candidate, { env, context, moduleId: normalizedModuleId });
-    }
-
-    let resolvedConfig = validateSchemaOrThrow({
-      moduleId: normalizedModuleId,
-      schema: normalizedSchema,
-      value: candidate,
-      coerce: Boolean(coerce)
-    });
-
-    if (typeof validate === "function") {
-      let customValidationResult;
-      try {
-        customValidationResult = validate(resolvedConfig, { env, context, moduleId: normalizedModuleId });
-      } catch (cause) {
-        throw new ModuleConfigError(`Invalid config for module "${normalizedModuleId}" from custom validation.`, {
-          moduleId: normalizedModuleId,
-          cause
-        });
-      }
-
-      const issues = normalizeCustomValidationIssues(customValidationResult);
-      if (issues.length > 0) {
-        throw new ModuleConfigError(buildInvalidConfigMessage(normalizedModuleId, issues), {
-          moduleId: normalizedModuleId,
-          issues
-        });
-      }
-    }
-
-    if (freeze) {
-      resolvedConfig = deepFreeze(resolvedConfig);
-    }
-
-    return resolvedConfig;
-  }
-
-  return Object.freeze({
-    moduleId: normalizedModuleId,
-    schema: normalizedSchema,
-    resolve
-  });
-}
-
-export { ModuleConfigError, defineModuleConfig };

package/server/runtime/moduleConfig.test.js

@@ -1,165 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { createSchema } from "json-rest-schema";
-
-import { ModuleConfigError, defineModuleConfig } from "./moduleConfig.js";
-
-test("defineModuleConfig resolves valid config and freezes nested objects", () => {
-  const moduleConfig = defineModuleConfig({
-    moduleId: "contacts",
-    schema: createSchema({
-      mode: {
-        type: "string",
-        required: true,
-        enum: ["standard", "strict"]
-      },
-      maxContacts: {
-        type: "integer",
-        required: true,
-        min: 1
-      },
-      limits: {
-        type: "object",
-        required: true,
-        validator(value) {
-          if (!value || typeof value !== "object" || Array.isArray(value)) {
-            return "limits must be an object";
-          }
-          const inviteExpiryHours = Number(value.inviteExpiryHours);
-          if (!Number.isInteger(inviteExpiryHours) || inviteExpiryHours < 1 || inviteExpiryHours > 168) {
-            return "inviteExpiryHours must be an integer between 1 and 168";
-          }
-          return undefined;
-        }
-      }
-    }),
-    load({ env }) {
-      return {
-        mode: String(env.CONTACTS_MODE || "standard"),
-        maxContacts: Number(env.CONTACTS_MAX || 5000),
-        limits: {
-          inviteExpiryHours: Number(env.CONTACTS_INVITE_EXPIRY_HOURS || 24)
-        }
-      };
-    }
-  });
-
-  const config = moduleConfig.resolve({
-    env: {
-      CONTACTS_MODE: "strict",
-      CONTACTS_MAX: "1000",
-      CONTACTS_INVITE_EXPIRY_HOURS: "36"
-    }
-  });
-
-  assert.equal(config.mode, "strict");
-  assert.equal(config.maxContacts, 1000);
-  assert.equal(config.limits.inviteExpiryHours, 36);
-  assert.equal(Object.isFrozen(config), true);
-  assert.equal(Object.isFrozen(config.limits), true);
-});
-
-test("defineModuleConfig reports schema validation issues with module-scoped details", () => {
-  const moduleConfig = defineModuleConfig({
-    moduleId: "contacts",
-    schema: createSchema({
-      maxContacts: {
-        type: "integer",
-        required: true,
-        min: 1
-      }
-    })
-  });
-
-  assert.throws(
-    () => moduleConfig.resolve({ raw: { maxContacts: 0, unexpected: true } }),
-    (error) => {
-      assert.equal(error instanceof ModuleConfigError, true);
-      assert.equal(error.moduleId, "contacts");
-      assert.equal(error.issues.length >= 1, true);
-      assert.equal(String(error.message).includes('module "contacts"'), true);
-      return true;
-    }
-  );
-});
-
-test("defineModuleConfig supports coercion via json-rest-schema casts", () => {
-  const moduleConfig = defineModuleConfig({
-    moduleId: "contacts",
-    coerce: true,
-    schema: createSchema({
-      maxContacts: { type: "integer", required: true, min: 1 },
-      enabled: { type: "boolean", required: true }
-    })
-  });
-
-  const config = moduleConfig.resolve({
-    raw: {
-      maxContacts: "42",
-      enabled: "true"
-    }
-  });
-
-  assert.equal(config.maxContacts, 42);
-  assert.equal(config.enabled, true);
-});
-
-test("defineModuleConfig supports custom cross-field validate hook", () => {
-  const moduleConfig = defineModuleConfig({
-    moduleId: "contacts",
-    schema: createSchema({
-      mode: {
-        type: "string",
-        required: true,
-        enum: ["standard", "strict"]
-      },
-      requireAuditTrail: {
-        type: "boolean",
-        required: true
-      }
-    }),
-    validate(value) {
-      if (value.mode === "strict" && value.requireAuditTrail !== true) {
-        return [
-          {
-            path: "requireAuditTrail",
-            message: "must be true when mode is strict"
-          }
-        ];
-      }
-      return true;
-    }
-  });
-
-  assert.throws(
-    () =>
-      moduleConfig.resolve({
-        raw: {
-          mode: "strict",
-          requireAuditTrail: false
-        }
-      }),
-    /requireAuditTrail: must be true when mode is strict/
-  );
-});
-
-test("defineModuleConfig rejects invalid module config definitions", () => {
-  assert.throws(() => defineModuleConfig({}), /moduleId/);
-  assert.throws(
-    () =>
-      defineModuleConfig({
-        moduleId: "contacts",
-        schema: null
-      }),
-    /schema/
-  );
-  assert.throws(
-    () =>
-      defineModuleConfig({
-        moduleId: "contacts",
-        schema: createSchema({}),
-        load: "not-a-function"
-      }),
-    /load/
-  );
-});

package/server/runtime/pagination.js

@@ -1,13 +0,0 @@
-import { parsePositiveInteger } from "./integers.js";
-
-function normalizePagination(pagination = {}, { defaultPage = 1, defaultPageSize = 20, maxPageSize = 100 } = {}) {
-  const rawPage = parsePositiveInteger(pagination?.page);
-  const rawPageSize = parsePositiveInteger(pagination?.pageSize);
-
-  return {
-    page: rawPage || defaultPage,
-    pageSize: Math.max(1, Math.min(maxPageSize, rawPageSize || defaultPageSize))
-  };
-}
-
-export { normalizePagination };

package/server/runtime/realtimeNormalization.js

@@ -1,21 +0,0 @@
-import { normalizePositiveInteger, normalizeText } from "../../shared/support/normalize.js";
-
-function normalizePositiveIntegerOrNull(value) {
-  const normalized = normalizePositiveInteger(value);
-  if (normalized < 1) {
-    return null;
-  }
-
-  return normalized;
-}
-
-function normalizeScopeKind(value) {
-  const normalized = normalizeText(value).toLowerCase();
-  if (!normalized || normalized === "global") {
-    return "global";
-  }
-
-  return normalized;
-}
-
-export { normalizePositiveIntegerOrNull, normalizeScopeKind };

package/server/runtime/routeUtils.js

@@ -1,20 +0,0 @@
-import { AppError } from "./errors.js";
-import { defaultMissingHandler } from "../support/defaultMissingHandler.js";
-
-function normalizeIdempotencyKey(value) {
-  const normalized = String(value || "").trim();
-  return normalized || "";
-}
-
-function requireIdempotencyKey(request) {
-  const idempotencyKey = normalizeIdempotencyKey(request?.headers?.["idempotency-key"]);
-  if (!idempotencyKey) {
-    throw new AppError(400, "Idempotency-Key header is required.", {
-      code: "IDEMPOTENCY_KEY_REQUIRED"
-    });
-  }
-
-  return idempotencyKey;
-}
-
-export { defaultMissingHandler, normalizeIdempotencyKey, requireIdempotencyKey };

package/server/runtime/securityAudit.js

@@ -1,269 +0,0 @@
-import { parsePositiveInteger } from "./integers.js";
-import { safePathnameFromRequest, resolveClientIpAddress } from "./requestUrl.js";
-import { normalizeSurfaceId } from "../../shared/surface/registry.js";
-import { normalizeOpaqueId } from "../../shared/support/normalize.js";
-import { resolveDefaultSurfaceId } from "../support/appConfig.js";
-
-function resolveAuditSurface(pathnameValue, explicitSurface = "", resolveSurfaceFromPathname = null, defaultSurfaceId = "") {
-  const normalizedExplicit = normalizeSurfaceId(explicitSurface);
-  if (normalizedExplicit) {
-    return normalizedExplicit;
-  }
-
-  if (typeof resolveSurfaceFromPathname === "function") {
-    const resolvedSurface = normalizeSurfaceId(resolveSurfaceFromPathname(pathnameValue));
-    if (resolvedSurface) {
-      return resolvedSurface;
-    }
-  }
-
-  return resolveDefaultSurfaceId(null, {
-    defaultSurfaceId
-  });
-}
-
-function buildAuditEventBase(request, { resolveSurfaceFromPathname = null, defaultSurfaceId = "" } = {}) {
-  const pathnameValue = safePathnameFromRequest(request);
-  return {
-    actorId: normalizeOpaqueId(request?.user?.id),
-    actorEmail: String(request?.user?.email || "")
-      .trim()
-      .toLowerCase(),
-    surface: resolveAuditSurface(pathnameValue, request?.surface, resolveSurfaceFromPathname, defaultSurfaceId),
-    requestId: String(request?.id || "").trim(),
-    method: String(request?.method || "")
-      .trim()
-      .toUpperCase(),
-    path: pathnameValue,
-    ipAddress: resolveClientIpAddress(request),
-    userAgent: String(request?.headers?.["user-agent"] || "")
-  };
-}
-
-function buildAuditError(error) {
-  const status = parsePositiveInteger(error?.status || error?.statusCode);
-  return {
-    name: String(error?.name || "Error"),
-    code: String(error?.code || ""),
-    status: status || null
-  };
-}
-
-function normalizeObjectPayload(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return {};
-  }
-
-  return value;
-}
-
-function resolveObjectPayload(value, context) {
-  const resolvedValue = typeof value === "function" ? value(context) : value;
-  return normalizeObjectPayload(resolvedValue);
-}
-
-function mergeMetadataPayloads(...payloads) {
-  const merged = {};
-  for (const payloadEntry of payloads) {
-    const payload = normalizeObjectPayload(payloadEntry);
-    for (const [key, value] of Object.entries(payload)) {
-      merged[key] = value;
-    }
-  }
-
-  return merged;
-}
-
-function buildEventPayload({ action, outcome, shared, event, metadata, context }) {
-  const sharedPayload = resolveObjectPayload(shared, context);
-  const eventPayload = resolveObjectPayload(event, context);
-  const sharedMetadata = resolveObjectPayload(metadata, context);
-  const eventMetadata = resolveObjectPayload(eventPayload.metadata, context);
-  const mergedMetadata = mergeMetadataPayloads(sharedMetadata, eventMetadata);
-
-  const payload = {
-    ...sharedPayload,
-    ...eventPayload,
-    action,
-    outcome
-  };
-
-  if (Object.keys(mergedMetadata).length > 0) {
-    payload.metadata = mergedMetadata;
-  } else {
-    delete payload.metadata;
-  }
-
-  return payload;
-}
-
-function mergeFailureMetadata(error, metadata) {
-  const normalizedMetadata =
-    metadata && typeof metadata === "object" && !Array.isArray(metadata) ? { ...metadata } : {};
-  if (!Object.hasOwn(normalizedMetadata, "error")) {
-    normalizedMetadata.error = buildAuditError(error);
-  }
-
-  return normalizedMetadata;
-}
-
-function logAuditFailure(request, payload, message) {
-  if (!request?.log || typeof request.log.warn !== "function") {
-    return;
-  }
-
-  request.log.warn(payload, message);
-}
-
-function safeBuildEventPayload({ request, action, outcome, shared, event, metadata, context, stage }) {
-  try {
-    return buildEventPayload({
-      action,
-      outcome,
-      shared,
-      event,
-      metadata,
-      context
-    });
-  } catch (error) {
-    logAuditFailure(
-      request,
-      {
-        action,
-        outcome,
-        stage,
-        callbackError: buildAuditError(error)
-      },
-      "security.audit.callback_failed"
-    );
-    return {
-      action,
-      outcome
-    };
-  }
-}
-
-async function recordAuditEvent({ auditService, request, event, resolveSurfaceFromPathname = null, defaultSurfaceId = "" }) {
-  await auditService.recordSafe(
-    {
-      ...buildAuditEventBase(request, {
-        resolveSurfaceFromPathname,
-        defaultSurfaceId
-      }),
-      ...event
-    },
-    request?.log
-  );
-}
-
-async function safeRecordAuditEvent({ auditService, request, event, resolveSurfaceFromPathname = null, defaultSurfaceId = "" }) {
-  try {
-    await recordAuditEvent({
-      auditService,
-      request,
-      event,
-      resolveSurfaceFromPathname,
-      defaultSurfaceId
-    });
-  } catch (error) {
-    logAuditFailure(
-      request,
-      {
-        action: String(event?.action || ""),
-        outcome: String(event?.outcome || ""),
-        recordError: buildAuditError(error)
-      },
-      "security.audit.record_unexpected_failure"
-    );
-  }
-}
-
-async function withAuditEvent({
-  auditService,
-  request,
-  action,
-  execute,
-  shared,
-  metadata,
-  onSuccess,
-  onFailure,
-  resolveSurfaceFromPathname = null,
-  defaultSurfaceId = ""
-}) {
-  if (!auditService || typeof auditService.recordSafe !== "function") {
-    throw new TypeError("withAuditEvent auditService.recordSafe is required.");
-  }
-  if (typeof execute !== "function") {
-    throw new TypeError("withAuditEvent execute callback is required.");
-  }
-
-  try {
-    const result = await execute();
-    const successEvent = safeBuildEventPayload({
-      request,
-      action,
-      outcome: "success",
-      shared,
-      event: onSuccess,
-      metadata,
-      context: {
-        request,
-        result,
-        error: null,
-        outcome: "success"
-      },
-      stage: "success"
-    });
-    await safeRecordAuditEvent({
-      auditService,
-      request,
-      event: successEvent,
-      resolveSurfaceFromPathname,
-      defaultSurfaceId
-    });
-    return result;
-  } catch (error) {
-    const failureEvent = safeBuildEventPayload({
-      request,
-      action,
-      outcome: "failure",
-      shared,
-      event: onFailure,
-      metadata,
-      context: {
-        request,
-        result: null,
-        error,
-        outcome: "failure"
-      },
-      stage: "failure"
-    });
-
-    await safeRecordAuditEvent({
-      auditService,
-      request,
-      event: {
-        ...failureEvent,
-        metadata: mergeFailureMetadata(error, failureEvent.metadata)
-      },
-      resolveSurfaceFromPathname,
-      defaultSurfaceId
-    });
-    throw error;
-  }
-}
-
-const __testables = {
-  normalizeSurfaceId,
-  resolveAuditSurface,
-  buildAuditEventBase,
-  buildAuditError,
-  normalizeObjectPayload,
-  resolveObjectPayload,
-  mergeMetadataPayloads,
-  buildEventPayload,
-  mergeFailureMetadata,
-  safeBuildEventPayload
-};
-
-export { buildAuditEventBase, buildAuditError, recordAuditEvent, withAuditEvent, __testables };