@jskit-ai/kernel 0.1.4

package/shared/support/returnToPath.js

@@ -0,0 +1,153 @@
+import { normalizePathname } from "../surface/paths.js";
+
+function normalizeHttpOrigin(value = "") {
+  const rawValue = String(value || "").trim();
+  if (!rawValue) {
+    return "";
+  }
+
+  try {
+    const parsed = new URL(rawValue);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return "";
+    }
+    return parsed.origin;
+  } catch {
+    return "";
+  }
+}
+
+function normalizeAllowedOrigins(allowedOrigins = []) {
+  const source = Array.isArray(allowedOrigins) ? allowedOrigins : [allowedOrigins];
+  const normalizedOrigins = [];
+
+  for (const originValue of source) {
+    const normalizedOrigin = normalizeHttpOrigin(originValue);
+    if (!normalizedOrigin || normalizedOrigins.includes(normalizedOrigin)) {
+      continue;
+    }
+    normalizedOrigins.push(normalizedOrigin);
+  }
+
+  return normalizedOrigins;
+}
+
+function appendNormalizedOrigin(origins, value) {
+  const normalizedOrigin = normalizeHttpOrigin(value);
+  if (!normalizedOrigin || origins.includes(normalizedOrigin)) {
+    return;
+  }
+  origins.push(normalizedOrigin);
+}
+
+function resolveAllowedOriginsFromSurfaceDefinitions(surfaceDefinitions = {}, { seedOrigins = [] } = {}) {
+  const resolvedOrigins = normalizeAllowedOrigins(seedOrigins);
+  const source =
+    surfaceDefinitions && typeof surfaceDefinitions === "object" && !Array.isArray(surfaceDefinitions)
+      ? surfaceDefinitions
+      : {};
+
+  for (const definition of Object.values(source)) {
+    if (!definition || typeof definition !== "object") {
+      continue;
+    }
+
+    appendNormalizedOrigin(resolvedOrigins, definition.origin);
+  }
+
+  return resolvedOrigins;
+}
+
+function normalizeBlockedPathnames(blockedPathnames = []) {
+  const source = Array.isArray(blockedPathnames) ? blockedPathnames : [blockedPathnames];
+  const normalizedPathnames = [];
+
+  for (const pathnameValue of source) {
+    const rawPathname = String(pathnameValue || "").trim();
+    if (!rawPathname) {
+      continue;
+    }
+    const normalizedPathname = normalizePathname(rawPathname);
+    if (normalizedPathnames.includes(normalizedPathname)) {
+      continue;
+    }
+    normalizedPathnames.push(normalizedPathname);
+  }
+
+  return normalizedPathnames;
+}
+
+function resolveAllowedOriginsFromPlacementContext(contextValue = null, { includeWindowOrigin = true } = {}) {
+  const seedOrigins = [];
+
+  if (includeWindowOrigin && typeof window === "object" && window?.location?.origin) {
+    appendNormalizedOrigin(seedOrigins, window.location.origin);
+  }
+
+  const surfaceConfig =
+    contextValue && typeof contextValue === "object" && contextValue.surfaceConfig && typeof contextValue.surfaceConfig === "object"
+      ? contextValue.surfaceConfig
+      : {};
+  const surfacesById =
+    surfaceConfig.surfacesById && typeof surfaceConfig.surfacesById === "object" ? surfaceConfig.surfacesById : {};
+  return resolveAllowedOriginsFromSurfaceDefinitions(surfacesById, {
+    seedOrigins
+  });
+}
+
+function normalizeReturnToPath(
+  value,
+  {
+    fallback = "/",
+    allowedOrigins = [],
+    blockedPathnames = [],
+    pickFirstArrayValue = false
+  } = {}
+) {
+  const source = pickFirstArrayValue && Array.isArray(value) ? value[0] : value;
+  const rawValue = String(source || "").trim();
+  if (!rawValue) {
+    return fallback;
+  }
+
+  const normalizedBlockedPathnames = normalizeBlockedPathnames(blockedPathnames);
+
+  if (rawValue.startsWith("/") && !rawValue.startsWith("//")) {
+    const normalizedPathname = normalizePathname(rawValue);
+    if (normalizedBlockedPathnames.includes(normalizedPathname)) {
+      return fallback;
+    }
+    return rawValue;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(rawValue);
+  } catch {
+    return fallback;
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return fallback;
+  }
+
+  const normalizedAllowedOrigins = normalizeAllowedOrigins(allowedOrigins);
+  if (normalizedAllowedOrigins.length > 0 && !normalizedAllowedOrigins.includes(parsed.origin)) {
+    return fallback;
+  }
+
+  const normalizedPathname = normalizePathname(parsed.pathname);
+  if (normalizedBlockedPathnames.includes(normalizedPathname)) {
+    return fallback;
+  }
+
+  return parsed.toString();
+}
+
+export {
+  normalizeAllowedOrigins,
+  normalizeHttpOrigin,
+  normalizeReturnToPath,
+  resolveAllowedOriginsFromSurfaceDefinitions,
+  resolveAllowedOriginsFromPlacementContext
+};

package/shared/support/returnToPath.test.js

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  normalizeAllowedOrigins,
+  normalizeHttpOrigin,
+  normalizeReturnToPath,
+  resolveAllowedOriginsFromSurfaceDefinitions,
+  resolveAllowedOriginsFromPlacementContext
+} from "./returnToPath.js";
+
+test("normalizeHttpOrigin keeps valid http origins only", () => {
+  assert.equal(normalizeHttpOrigin("https://app.example.com/path?q=1"), "https://app.example.com");
+  assert.equal(normalizeHttpOrigin("http://localhost:3000"), "http://localhost:3000");
+  assert.equal(normalizeHttpOrigin("javascript:alert(1)"), "");
+});
+
+test("normalizeAllowedOrigins deduplicates and filters invalid origins", () => {
+  assert.deepEqual(normalizeAllowedOrigins([
+    "https://app.example.com",
+    "https://app.example.com/console",
+    "http://localhost:5173",
+    "",
+    "ftp://files.example.com"
+  ]), [
+    "https://app.example.com",
+    "http://localhost:5173"
+  ]);
+});
+
+test("normalizeReturnToPath allows internal paths and permitted absolute urls", () => {
+  assert.equal(normalizeReturnToPath("/w/acme/projects?tab=active", {
+    fallback: "/"
+  }), "/w/acme/projects?tab=active");
+  assert.equal(normalizeReturnToPath("https://app.example.com/w/acme", {
+    fallback: "/",
+    allowedOrigins: ["https://app.example.com"]
+  }), "https://app.example.com/w/acme");
+});
+
+test("normalizeReturnToPath rejects blocked paths, invalid schemes, and untrusted origins", () => {
+  assert.equal(normalizeReturnToPath("/auth/login?returnTo=%2F", {
+    fallback: "/",
+    blockedPathnames: ["/auth/login"]
+  }), "/");
+  assert.equal(normalizeReturnToPath("https://auth.example.com/auth/signout", {
+    fallback: "/",
+    allowedOrigins: ["https://auth.example.com"],
+    blockedPathnames: ["/auth/signout"]
+  }), "/");
+  assert.equal(normalizeReturnToPath("https://evil.example.com/phishing", {
+    fallback: "/",
+    allowedOrigins: ["https://app.example.com"]
+  }), "/");
+  assert.equal(normalizeReturnToPath("javascript:alert(1)", {
+    fallback: "/"
+  }), "/");
+  assert.equal(normalizeReturnToPath("/account", {
+    fallback: "/",
+    blockedPathnames: ["account"]
+  }), "/");
+});
+
+test("normalizeReturnToPath can read first value from array payloads", () => {
+  assert.equal(normalizeReturnToPath(["/dashboard", "/ignored"], {
+    fallback: "/",
+    pickFirstArrayValue: true
+  }), "/dashboard");
+});
+
+test("resolveAllowedOriginsFromSurfaceDefinitions includes seed origins and surface origins", () => {
+  const origins = resolveAllowedOriginsFromSurfaceDefinitions(
+    {
+      home: { origin: "https://home.example.com" },
+      app: { origin: "https://app.example.com" },
+      duplicate: { origin: "https://home.example.com" },
+      invalid: { origin: "mailto:hello@example.com" }
+    },
+    {
+      seedOrigins: ["https://public.example.com", "https://home.example.com"]
+    }
+  );
+
+  assert.deepEqual(origins, [
+    "https://public.example.com",
+    "https://home.example.com",
+    "https://app.example.com"
+  ]);
+});
+
+test("resolveAllowedOriginsFromPlacementContext collects current and surface origins", () => {
+  const originalWindow = globalThis.window;
+  globalThis.window = {
+    location: {
+      origin: "https://current.example.com"
+    }
+  };
+
+  try {
+    const origins = resolveAllowedOriginsFromPlacementContext({
+      surfaceConfig: {
+        surfacesById: {
+          home: { origin: "https://home.example.com" },
+          app: { origin: "https://app.example.com" },
+          duplicate: { origin: "https://home.example.com" },
+          invalid: { origin: "mailto:hello@example.com" }
+        }
+      }
+    });
+
+    assert.deepEqual(origins, [
+      "https://current.example.com",
+      "https://home.example.com",
+      "https://app.example.com"
+    ]);
+  } finally {
+    if (typeof originalWindow === "undefined") {
+      delete globalThis.window;
+    } else {
+      globalThis.window = originalWindow;
+    }
+  }
+});

package/shared/support/sorting.js

@@ -0,0 +1,15 @@
+function sortStrings(values = []) {
+  return [...new Set((Array.isArray(values) ? values : []).map((value) => String(value || "").trim()).filter(Boolean))].sort(
+    (left, right) => left.localeCompare(right)
+  );
+}
+
+function sortById(items = [], { idSelector = (item) => item?.id } = {}) {
+  return [...(Array.isArray(items) ? items : [])].sort((left, right) => {
+    const leftId = String(idSelector(left) || "").trim();
+    const rightId = String(idSelector(right) || "").trim();
+    return leftId.localeCompare(rightId);
+  });
+}
+
+export { sortStrings, sortById };

package/shared/support/tokens.js

@@ -0,0 +1,23 @@
+const KERNEL_TOKENS = Object.freeze({
+  Logger: Symbol.for("jskit.logger"),
+  Env: Symbol.for("jskit.env"),
+  Fastify: Symbol.for("jskit.fastify"),
+  HttpRouter: Symbol.for("jskit.http.router"),
+  Request: Symbol.for("jskit.http.request"),
+  Reply: Symbol.for("jskit.http.reply"),
+  RequestId: Symbol.for("jskit.http.requestId"),
+  RequestScope: Symbol.for("jskit.http.requestScope"),
+  Knex: Symbol.for("jskit.database.knex"),
+  TransactionManager: Symbol.for("jskit.database.transactionManager"),
+  Storage: Symbol.for("jskit.storage"),
+  SurfaceRuntime: Symbol.for("jskit.surface.runtime")
+});
+
+function isContainerToken(value) {
+  if (typeof value === "string") {
+    return value.trim().length > 0;
+  }
+  return typeof value === "symbol" || typeof value === "function";
+}
+
+export { KERNEL_TOKENS, isContainerToken };

package/shared/support/tokens.test.js

@@ -0,0 +1,17 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { isContainerToken } from "./tokens.js";
+
+test("isContainerToken accepts valid container token types", () => {
+  assert.equal(isContainerToken("appConfig"), true);
+  assert.equal(isContainerToken(Symbol.for("jskit.test")), true);
+  assert.equal(isContainerToken(() => {}), true);
+});
+
+test("isContainerToken rejects empty and unsupported token values", () => {
+  assert.equal(isContainerToken(""), false);
+  assert.equal(isContainerToken("   "), false);
+  assert.equal(isContainerToken(null), false);
+  assert.equal(isContainerToken(123), false);
+  assert.equal(isContainerToken({}), false);
+});

package/shared/support/visibility.js

@@ -0,0 +1,56 @@
+import { normalizeOpaqueId, normalizeText } from "./normalize.js";
+import { ROUTE_VISIBILITY_PUBLIC, ROUTE_VISIBILITY_USER } from "./policies.js";
+
+const ROUTE_VISIBILITY_LEVELS = Object.freeze([ROUTE_VISIBILITY_PUBLIC, ROUTE_VISIBILITY_USER]);
+const ROUTE_VISIBILITY_LEVEL_SET = new Set(ROUTE_VISIBILITY_LEVELS);
+
+function normalizeRouteVisibilityToken(value, { fallback = ROUTE_VISIBILITY_PUBLIC } = {}) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (normalized) {
+    return normalized;
+  }
+
+  const normalizedFallback = normalizeText(fallback).toLowerCase();
+  if (normalizedFallback) {
+    return normalizedFallback;
+  }
+
+  return ROUTE_VISIBILITY_PUBLIC;
+}
+
+function normalizeRouteVisibility(value, { fallback = ROUTE_VISIBILITY_PUBLIC } = {}) {
+  const normalized = normalizeRouteVisibilityToken(value, { fallback });
+  if (ROUTE_VISIBILITY_LEVEL_SET.has(normalized)) {
+    return normalized;
+  }
+
+  const normalizedFallback = normalizeRouteVisibilityToken(fallback, {
+    fallback: ROUTE_VISIBILITY_PUBLIC
+  });
+  if (ROUTE_VISIBILITY_LEVEL_SET.has(normalizedFallback)) {
+    return normalizedFallback;
+  }
+
+  return ROUTE_VISIBILITY_PUBLIC;
+}
+
+function normalizeVisibilityScopeKind(value) {
+  const normalized = normalizeText(value).toLowerCase();
+  return normalized || null;
+}
+
+function normalizeVisibilityContext(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const normalizedVisibility = normalizeRouteVisibilityToken(source.visibility);
+  const normalizedScopeKind = normalizeVisibilityScopeKind(source.scopeKind);
+
+  return Object.freeze({
+    visibility: normalizedVisibility,
+    scopeKind: normalizedScopeKind,
+    requiresActorScope: source.requiresActorScope === true,
+    scopeOwnerId: normalizeOpaqueId(source.scopeOwnerId),
+    userOwnerId: normalizeOpaqueId(source.userOwnerId)
+  });
+}
+
+export { ROUTE_VISIBILITY_LEVELS, normalizeRouteVisibilityToken, normalizeRouteVisibility, normalizeVisibilityContext };

package/shared/support/visibility.test.js

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { normalizeRouteVisibilityToken, normalizeRouteVisibility, normalizeVisibilityContext } from "./visibility.js";
+
+test("normalizeRouteVisibility keeps kernel core visibility contract", () => {
+  assert.equal(normalizeRouteVisibility("PUBLIC"), "public");
+  assert.equal(normalizeRouteVisibility("user"), "user");
+  assert.equal(normalizeRouteVisibility("workspace"), "public");
+  assert.equal(normalizeRouteVisibility("invalid"), "public");
+  assert.equal(normalizeRouteVisibility("invalid", { fallback: "user" }), "user");
+  assert.equal(normalizeRouteVisibility(""), "public");
+});
+
+test("normalizeRouteVisibilityToken normalizes visibility tokens for module-level resolvers", () => {
+  assert.equal(normalizeRouteVisibilityToken("workspace"), "workspace");
+  assert.equal(normalizeRouteVisibilityToken("WORKSPACE_USER"), "workspace_user");
+  assert.equal(normalizeRouteVisibilityToken(""), "public");
+  assert.equal(normalizeRouteVisibilityToken("", { fallback: "workspace" }), "workspace");
+});
+
+test("normalizeVisibilityContext normalizes mode and owner identifiers", () => {
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "user", userOwnerId: "7" }), {
+    visibility: "user",
+    scopeKind: null,
+    requiresActorScope: false,
+    scopeOwnerId: null,
+    userOwnerId: "7"
+  });
+
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace_user", scopeOwnerId: "4", userOwnerId: 9 }), {
+    visibility: "workspace_user",
+    scopeKind: null,
+    requiresActorScope: false,
+    scopeOwnerId: "4",
+    userOwnerId: 9
+  });
+
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace", scopeOwnerId: "0" }), {
+    visibility: "workspace",
+    scopeKind: null,
+    requiresActorScope: false,
+    scopeOwnerId: "0",
+    userOwnerId: null
+  });
+});

package/shared/surface/apiPaths.js

@@ -0,0 +1,84 @@
+import { matchesPathPrefix, normalizePathname } from "./paths.js";
+
+const API_BASE_PATH = "/api";
+const API_PREFIX = "/api";
+const API_PREFIX_SLASH = `${API_PREFIX}/`;
+const API_DOCS_PATH = `${API_PREFIX}/docs`;
+const API_REALTIME_PATH = `${API_PREFIX}/realtime`;
+const VERSIONED_API_PATH_PATTERN = /^\/api\/v[0-9]+(?:$|\/)/;
+
+function isApiPath(pathname) {
+  return matchesPathPrefix(pathname, API_BASE_PATH);
+}
+
+function isVersionedApiPath(pathname) {
+  return VERSIONED_API_PATH_PATTERN.test(normalizePathname(pathname));
+}
+
+function toVersionedApiPath(pathname) {
+  const normalizedPathname = normalizePathname(pathname);
+  if (!isApiPath(normalizedPathname)) {
+    return normalizedPathname;
+  }
+
+  if (isVersionedApiPath(normalizedPathname)) {
+    return normalizedPathname;
+  }
+
+  if (normalizedPathname === API_BASE_PATH) {
+    return API_PREFIX;
+  }
+
+  return `${API_PREFIX}${normalizedPathname.slice(API_BASE_PATH.length)}`;
+}
+
+function toVersionedApiPrefix(pathnameOrPrefix) {
+  const versionedPath = toVersionedApiPath(pathnameOrPrefix || API_BASE_PATH);
+  if (!isApiPath(versionedPath)) {
+    return normalizePathname(versionedPath);
+  }
+
+  if (versionedPath === API_PREFIX) {
+    return API_PREFIX_SLASH;
+  }
+
+  return `${versionedPath}/`;
+}
+
+function buildVersionedApiPath(suffix) {
+  const rawSuffix = String(suffix || "").trim();
+  if (!rawSuffix || rawSuffix === "/") {
+    return API_PREFIX;
+  }
+
+  const normalizedSuffix = normalizePathname(rawSuffix.startsWith("/") ? rawSuffix : `/${rawSuffix}`);
+  if (isApiPath(normalizedSuffix)) {
+    return toVersionedApiPath(normalizedSuffix);
+  }
+
+  if (normalizedSuffix === "/") {
+    return API_PREFIX;
+  }
+
+  return `${API_PREFIX}${normalizedSuffix}`;
+}
+
+function isVersionedApiPrefixMatch(pathname) {
+  const normalizedPathname = normalizePathname(pathname);
+  return normalizedPathname === API_PREFIX || normalizedPathname.startsWith(API_PREFIX_SLASH);
+}
+
+export {
+  API_BASE_PATH,
+  API_PREFIX,
+  API_PREFIX_SLASH,
+  API_DOCS_PATH,
+  API_REALTIME_PATH,
+  normalizePathname,
+  isApiPath,
+  isVersionedApiPath,
+  toVersionedApiPath,
+  toVersionedApiPrefix,
+  buildVersionedApiPath,
+  isVersionedApiPrefixMatch
+};

package/shared/surface/escapeRegExp.js

@@ -0,0 +1,5 @@
+function escapeRegExp(value) {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export { escapeRegExp };

package/shared/surface/index.js

@@ -0,0 +1,6 @@
+export {
+  normalizeSurfaceId,
+  normalizeSurfacePagesRoot,
+  deriveSurfaceRouteBaseFromPagesRoot
+} from "./registry.js";
+export { createSurfacePathHelpers } from "./paths.js";