@jskit-ai/kernel 0.1.4

package/server/runtime/securityAudit.js

@@ -0,0 +1,269 @@
+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 };

package/server/runtime/securityAudit.test.js

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildAuditEventBase, __testables } from "./securityAudit.js";
+
+const { resolveAuditSurface } = __testables;
+
+test("resolveAuditSurface prefers explicit surface", () => {
+  assert.equal(resolveAuditSurface("/", " Admin "), "admin");
+});
+
+test("resolveAuditSurface resolves surface from pathname resolver before default", () => {
+  const resolved = resolveAuditSurface(
+    "/admin/users",
+    "",
+    (pathname) => (pathname.startsWith("/admin") ? "console" : ""),
+    "home"
+  );
+
+  assert.equal(resolved, "console");
+});
+
+test("resolveAuditSurface uses configured default and falls back to empty surface", () => {
+  assert.equal(resolveAuditSurface("/", "", null, "home"), "home");
+  assert.equal(resolveAuditSurface("/", "", null, ""), "");
+});
+
+test("buildAuditEventBase uses default surface id when request surface is missing", () => {
+  const event = buildAuditEventBase(
+    {
+      id: "req-1",
+      method: "GET",
+      headers: {}
+    },
+    {
+      defaultSurfaceId: "console"
+    }
+  );
+
+  assert.equal(event.surface, "console");
+});

package/server/runtime/serviceAuthorization.js

@@ -0,0 +1,113 @@
+import { normalizeObject, normalizeOpaqueId, normalizeText } from "../../shared/support/normalize.js";
+import { hasPermission, normalizePermissionList } from "../../shared/support/permissions.js";
+import { AppError } from "./errors.js";
+
+const AUTH_REQUIRE_MODES = new Set(["none", "authenticated", "all", "any"]);
+
+function resolveServiceContext(source = {}) {
+  const payload = normalizeObject(source);
+
+  if (payload.context && typeof payload.context === "object" && !Array.isArray(payload.context)) {
+    return payload.context;
+  }
+
+  if (payload.actionContext && typeof payload.actionContext === "object" && !Array.isArray(payload.actionContext)) {
+    return payload.actionContext;
+  }
+
+  return payload;
+}
+
+function resolveRequireMode(value) {
+  const mode = normalizeText(value || "authenticated").toLowerCase();
+  if (!AUTH_REQUIRE_MODES.has(mode)) {
+    throw new TypeError("requireAuth options.require must be one of: none, authenticated, all, any.");
+  }
+  return mode;
+}
+
+function normalizeRequireAuthOptions(options = {}, { context = "requireAuth options" } = {}) {
+  const source = normalizeObject(options);
+  const mode = resolveRequireMode(source.require);
+  const permissions = normalizePermissionList(source.permissions);
+
+  return Object.freeze({
+    require: mode,
+    permissions: Object.freeze(permissions),
+    message: normalizeText(source.message),
+    code: normalizeText(source.code),
+    context
+  });
+}
+
+function requireAuthenticatedActor(context = {}, options = {}) {
+  const actor = normalizeObject(context.actor);
+  const actorId = normalizeOpaqueId(actor.id);
+
+  if (actorId == null) {
+    throw new AppError(401, options.message || "Authentication required.", {
+      code: options.code || "AUTHENTICATION_REQUIRED"
+    });
+  }
+
+  return {
+    ...actor,
+    id: actorId
+  };
+}
+
+function requireAuth(source = {}, options = {}) {
+  const context = resolveServiceContext(source);
+  const settings = normalizeRequireAuthOptions(options);
+  const mode = settings.require;
+
+  if (mode === "none") {
+    return null;
+  }
+
+  const actor = requireAuthenticatedActor(context, settings);
+
+  if (mode === "authenticated") {
+    return actor;
+  }
+
+  const requiredPermissions = normalizePermissionList(settings.permissions);
+  if (requiredPermissions.length < 1) {
+    return actor;
+  }
+  const actorPermissions = normalizePermissionList(context.permissions);
+
+  if (mode === "all") {
+    for (const permission of requiredPermissions) {
+      if (hasPermission(actorPermissions, permission)) {
+        continue;
+      }
+
+      throw new AppError(403, settings.message || "Forbidden.", {
+        code: settings.code || "PERMISSION_DENIED",
+        details: {
+          permission
+        }
+      });
+    }
+    return actor;
+  }
+
+  const allowed = requiredPermissions.some((permission) => hasPermission(actorPermissions, permission));
+  if (!allowed) {
+    throw new AppError(403, settings.message || "Forbidden.", {
+      code: settings.code || "PERMISSION_DENIED",
+      details: {
+        requiredPermissions
+      }
+    });
+  }
+
+  return actor;
+}
+
+export {
+  resolveServiceContext,
+  hasPermission,
+  requireAuth
+};

package/server/runtime/serviceAuthorization.test.js

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { requireAuth } from "./serviceAuthorization.js";
+
+test("requireAuth allows public mode without actor", () => {
+  assert.doesNotThrow(() =>
+    requireAuth(
+      {
+        context: {}
+      },
+      {
+        require: "none"
+      }
+    )
+  );
+});
+
+test("requireAuth accepts actor context", () => {
+  const actor = requireAuth({
+    context: {
+      actor: {
+        id: 7
+      }
+    }
+  });
+
+  assert.equal(actor.id, 7);
+});
+
+test("requireAuth accepts non-numeric actor ids", () => {
+  const actor = requireAuth({
+    context: {
+      actor: {
+        id: "user-7"
+      }
+    }
+  });
+
+  assert.equal(actor.id, "user-7");
+});
+
+test("requireAuth throws when actor is missing", () => {
+  assert.throws(
+    () => requireAuth({ context: {} }),
+    (error) => error?.statusCode === 401 && error?.code === "AUTHENTICATION_REQUIRED"
+  );
+});
+
+test("requireAuth enforces all permissions", () => {
+  assert.throws(
+    () =>
+      requireAuth(
+        {
+          context: {
+            actor: { id: 1 },
+            permissions: ["workspace.settings.view"]
+          }
+        },
+        {
+          require: "all",
+          permissions: ["workspace.settings.update"]
+        }
+      ),
+    (error) => error?.statusCode === 403 && error?.code === "PERMISSION_DENIED"
+  );
+});
+
+test("requireAuth allows wildcard permission for any mode", () => {
+  assert.doesNotThrow(() =>
+    requireAuth(
+      {
+        context: {
+          actor: { id: 1 },
+          permissions: ["*"]
+        }
+      },
+      {
+        require: "any",
+        permissions: ["workspace.settings.view", "workspace.settings.update"]
+      }
+    )
+  );
+});
+
+test("requireAuth allows namespace wildcard permissions", () => {
+  assert.doesNotThrow(() =>
+    requireAuth(
+      {
+        context: {
+          actor: { id: 1 },
+          permissions: ["crud_contacts.*"]
+        }
+      },
+      {
+        require: "all",
+        permissions: ["crud_contacts.update"]
+      }
+    )
+  );
+});

package/server/runtime/serviceRegistration.test.js

@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createContainer } from "../container/index.js";
+import {
+  installServiceRegistrationApi,
+  resolveServiceRegistrations
+} from "../registries/serviceRegistrationRegistry.js";
+
+test("installServiceRegistrationApi exposes app.service and publishes declared events", async () => {
+  const app = createContainer();
+  const published = [];
+  app.singleton("domainEvents", () => ({
+    async publish(payload) {
+      published.push(payload);
+      return null;
+    }
+  }));
+
+  installServiceRegistrationApi(app);
+  assert.equal(typeof app.service, "function");
+
+  app.service(
+    "test.customers.service",
+    () => ({
+      async createRecord() {
+        return { id: 41 };
+      }
+    }),
+    {
+      events: {
+        createRecord: [
+          {
+            type: "entity.changed",
+            source: "crud",
+            entity: "record",
+            operation: "created",
+            realtime: {
+              event: "customers.record.changed"
+            }
+          }
+        ]
+      }
+    }
+  );
+
+  const service = app.make("test.customers.service");
+  const result = await service.createRecord({
+    context: {
+      actor: { id: 7 },
+      visibilityContext: {
+        scopeOwnerId: 13
+      }
+    }
+  });
+
+  assert.equal(result.id, 41);
+  assert.equal(service.serviceEvents.createRecord[0].realtime.audience, "event_scope");
+  assert.equal(published.length, 1);
+  assert.equal(published[0].source, "crud");
+  assert.equal(published[0].operation, "created");
+  assert.equal(published[0].meta?.service?.token, "test.customers.service");
+  assert.equal(published[0].meta?.service?.method, "createRecord");
+  assert.equal(published[0].meta?.realtime?.event, "customers.record.changed");
+});
+
+test("app.service rejects deprecated permissions metadata", () => {
+  const app = createContainer();
+  app.singleton("domainEvents", () => ({
+    async publish() {
+      return null;
+    }
+  }));
+  installServiceRegistrationApi(app);
+
+  assert.throws(
+    () =>
+      app.service(
+        "test.secure.service",
+        () => ({
+          async listRecords() {
+            return [];
+          }
+        }),
+        {
+          permissions: {
+            listRecords: {
+              require: "authenticated"
+            }
+          }
+        }
+      ),
+    /metadata\.permissions is no longer supported/
+  );
+});
+
+test("resolveServiceRegistrations returns declared service metadata", () => {
+  const app = createContainer();
+  app.singleton("domainEvents", () => ({
+    async publish() {
+      return null;
+    }
+  }));
+  installServiceRegistrationApi(app);
+
+  app.service(
+    "test.registry.service",
+    () => ({
+      async createRecord() {
+        return { id: 1 };
+      }
+    })
+  );
+
+  const entries = resolveServiceRegistrations(app);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].serviceToken, "test.registry.service");
+  assert.deepEqual(entries[0].metadata, {
+    events: {}
+  });
+});
+
+test("app.service keeps realtime audience callbacks", () => {
+  const app = createContainer();
+  app.singleton("domainEvents", () => ({
+    async publish() {
+      return null;
+    }
+  }));
+  installServiceRegistrationApi(app);
+
+  const audience = () => ({ userId: 7 });
+  app.service(
+    "test.audience.service",
+    () => ({
+      async updateRecord() {
+        return { id: 2 };
+      }
+    }),
+    {
+      events: {
+        updateRecord: [
+          {
+            type: "entity.changed",
+            source: "crud",
+            entity: "record",
+            operation: "updated",
+            realtime: {
+              event: "customers.record.changed",
+              audience
+            }
+          }
+        ]
+      }
+    }
+  );
+
+  const service = app.make("test.audience.service");
+  assert.equal(typeof service.serviceEvents.updateRecord[0].realtime.audience, "function");
+});
+
+test("app.service accepts opaque realtime audience string presets", () => {
+  const app = createContainer();
+  app.singleton("domainEvents", () => ({
+    async publish() {
+      return null;
+    }
+  }));
+  installServiceRegistrationApi(app);
+
+  app.service(
+    "test.opaque.audience.service",
+    () => ({
+      async updateRecord() {
+        return { id: 2 };
+      }
+    }),
+    {
+      events: {
+        updateRecord: [
+          {
+            type: "entity.changed",
+            source: "crud",
+            entity: "record",
+            operation: "updated",
+            realtime: {
+              event: "customers.record.changed",
+              audience: "workspace_member"
+            }
+          }
+        ]
+      }
+    }
+  );
+
+  const service = app.make("test.opaque.audience.service");
+  assert.equal(service.serviceEvents.updateRecord[0].realtime.audience, "workspace_member");
+});