@jskit-ai/users-core 0.1.4

package/src/server/common/services/workspaceContextService.js

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import {
+  TENANCY_MODE_NONE,
+  resolveTenancyProfile
+} from "../../../shared/tenancyProfile.js";
+import { coerceWorkspaceColor } from "../../../shared/settings.js";
+import {
+  resolveRolePermissions
+} from "../../../shared/roles.js";
+import {
+  mapWorkspaceSummary
+} from "../formatters/workspaceFormatter.js";
+import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+import { authenticatedUserValidator } from "../validators/authenticatedUserValidator.js";
+
+function toSlugPart(value) {
+  const normalized = normalizeLowerText(value)
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return normalized || "workspace";
+}
+
+function buildWorkspaceBaseSlug(user = {}) {
+  const username = normalizeLowerText(user.username);
+  if (username) {
+    return toSlugPart(username);
+  }
+  const displayName = normalizeText(user.displayName);
+  if (displayName) {
+    return toSlugPart(displayName);
+  }
+  const email = normalizeLowerText(user.email);
+  if (email.includes("@")) {
+    return toSlugPart(email.split("@")[0]);
+  }
+  return "workspace";
+}
+
+function buildWorkspaceName(user = {}) {
+  const displayName = normalizeText(user.displayName);
+  if (displayName) {
+    return `${displayName}'s Workspace`;
+  }
+  const email = normalizeLowerText(user.email);
+  if (email) {
+    return `${email}'s Workspace`;
+  }
+  return "Workspace";
+}
+
+function buildPermissionsFromMembership(membership, appConfig = {}) {
+  const roleId = normalizeLowerText(membership?.roleId || "member");
+  return resolveRolePermissions(roleId, appConfig);
+}
+
+function hashInviteToken(token) {
+  return createHash("sha256").update(normalizeText(token)).digest("hex");
+}
+
+function normalizeWorkspaceCreationInput(payload = {}) {
+  const source = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  return {
+    name: normalizeText(source.name),
+    requestedSlug: normalizeLowerText(source.slug)
+  };
+}
+
+function createService({
+  appConfig = {},
+  workspacesRepository,
+  workspaceMembershipsRepository,
+  workspaceSettingsRepository
+} = {}) {
+  if (
+    !workspacesRepository ||
+    !workspaceMembershipsRepository ||
+    !workspaceSettingsRepository
+  ) {
+    throw new Error("workspaceService requires repositories.");
+  }
+
+  const resolvedTenancyProfile = resolveTenancyProfile(appConfig);
+  const resolvedTenancyMode = resolvedTenancyProfile.mode;
+  const workspacePolicy = resolvedTenancyProfile.workspace;
+  const resolvedWorkspaceColor = coerceWorkspaceColor(appConfig.workspaceColor);
+  async function ensureUniqueWorkspaceSlug(baseSlug, options = {}) {
+    let suffix = 0;
+    while (suffix < 1000) {
+      suffix += 1;
+      const candidate = suffix === 1 ? toSlugPart(baseSlug) : `${toSlugPart(baseSlug)}-${suffix}`;
+      const existing = await workspacesRepository.findBySlug(candidate, options);
+      if (!existing) {
+        return candidate;
+      }
+    }
+    throw new AppError(500, "Unable to generate unique workspace slug.");
+  }
+
+  async function ensureWorkspaceSettingsForWorkspace(workspace, options = {}) {
+    return workspaceSettingsRepository.ensureForWorkspaceId(workspace?.id, {
+      ...options,
+      workspace
+    });
+  }
+
+  async function ensurePersonalWorkspaceForUser(user, options = {}) {
+    const normalizedUser = authenticatedUserValidator.normalize(user);
+    if (!normalizedUser) {
+      throw new AppError(400, "Invalid authenticated user payload.");
+    }
+
+    const existing = await workspacesRepository.findPersonalByOwnerUserId(normalizedUser.id, options);
+    if (existing) {
+      await workspaceMembershipsRepository.ensureOwnerMembership(existing.id, normalizedUser.id, options);
+      await ensureWorkspaceSettingsForWorkspace(existing, options);
+      return existing;
+    }
+
+    const slug = await ensureUniqueWorkspaceSlug(buildWorkspaceBaseSlug(normalizedUser), options);
+    const inserted = await workspacesRepository.insert(
+      {
+        slug,
+        name: buildWorkspaceName(normalizedUser),
+        ownerUserId: normalizedUser.id,
+        isPersonal: true,
+        avatarUrl: "",
+        color: resolvedWorkspaceColor
+      },
+      options
+    );
+
+    await workspaceMembershipsRepository.ensureOwnerMembership(inserted.id, normalizedUser.id, options);
+    await ensureWorkspaceSettingsForWorkspace(inserted, options);
+    return inserted;
+  }
+
+  async function listWorkspacesForUser(user, options = {}) {
+    const normalizedUser = authenticatedUserValidator.normalize(user);
+    if (!normalizedUser) {
+      return [];
+    }
+
+    if (resolvedTenancyMode === TENANCY_MODE_NONE) {
+      return [];
+    }
+
+    const list = await workspacesRepository.listForUserId(normalizedUser.id, options);
+    const accessible = list
+      .map((entry) => mapWorkspaceSummary(entry, { roleId: entry.roleId, status: entry.membershipStatus }))
+      .filter((entry) => entry.isAccessible);
+
+    return accessible;
+  }
+
+  async function listWorkspacesForAuthenticatedUser(user, options = {}) {
+    return listWorkspacesForUser(user, options);
+  }
+
+  async function provisionWorkspaceForNewUser(user, options = {}) {
+    const normalizedUser = authenticatedUserValidator.normalize(user);
+    if (!normalizedUser) {
+      throw new AppError(400, "Invalid authenticated user payload.");
+    }
+
+    if (workspacePolicy.autoProvision !== true) {
+      return null;
+    }
+
+    return ensurePersonalWorkspaceForUser(normalizedUser, options);
+  }
+
+  async function createWorkspaceForAuthenticatedUser(user, payload = {}, options = {}) {
+    const normalizedUser = authenticatedUserValidator.normalize(user);
+    if (!normalizedUser) {
+      throw new AppError(401, "Authentication required.");
+    }
+
+    if (workspacePolicy.allowSelfCreate !== true) {
+      throw new AppError(403, "Workspace creation is disabled for this tenancy mode.");
+    }
+
+    const createInput = normalizeWorkspaceCreationInput(payload);
+    if (!createInput.name) {
+      throw new AppError(400, "Workspace name is required.");
+    }
+
+    const slugBase = createInput.requestedSlug || toSlugPart(createInput.name);
+    const slug = await ensureUniqueWorkspaceSlug(slugBase, options);
+    const inserted = await workspacesRepository.insert(
+      {
+        slug,
+        name: createInput.name,
+        ownerUserId: normalizedUser.id,
+        isPersonal: false,
+        avatarUrl: "",
+        color: resolvedWorkspaceColor
+      },
+      options
+    );
+
+    await workspaceMembershipsRepository.ensureOwnerMembership(inserted.id, normalizedUser.id, options);
+    await ensureWorkspaceSettingsForWorkspace(inserted, options);
+    return inserted;
+  }
+
+  async function resolveWorkspaceContextForUserBySlug(user, workspaceSlug, options = {}) {
+    const normalizedUser = authenticatedUserValidator.normalize(user);
+    if (!normalizedUser) {
+      throw new AppError(401, "Authentication required.");
+    }
+
+    if (resolvedTenancyMode === TENANCY_MODE_NONE) {
+      throw new AppError(403, "Workspace context is disabled.");
+    }
+
+    const normalizedWorkspaceSlug = normalizeLowerText(workspaceSlug);
+    if (!normalizedWorkspaceSlug) {
+      throw new AppError(400, "workspaceSlug is required.");
+    }
+
+    const workspace = await workspacesRepository.findBySlug(normalizedWorkspaceSlug, options);
+
+    if (!workspace) {
+      throw new AppError(404, "Workspace not found.");
+    }
+
+    let membership = await workspaceMembershipsRepository.findByWorkspaceIdAndUserId(
+      workspace.id,
+      normalizedUser.id,
+      options
+    );
+    const actorOwnsWorkspace = Number(workspace.ownerUserId) === Number(normalizedUser.id);
+    const membershipIsActive = normalizeLowerText(membership?.status) === "active";
+
+    if (!membershipIsActive && actorOwnsWorkspace) {
+      membership = await workspaceMembershipsRepository.ensureOwnerMembership(workspace.id, normalizedUser.id, options);
+    }
+
+    if (!membership || normalizeLowerText(membership.status) !== "active") {
+      throw new AppError(403, "You do not have access to this workspace.");
+    }
+
+    const workspaceSettings = await ensureWorkspaceSettingsForWorkspace(workspace, options);
+    const permissions = buildPermissionsFromMembership(membership, appConfig);
+
+    return {
+      workspace,
+      membership,
+      permissions,
+      workspaceSettings
+    };
+  }
+
+  return Object.freeze({
+    toSlugPart,
+    buildWorkspaceName,
+    buildWorkspaceBaseSlug,
+    hashInviteToken,
+    ensurePersonalWorkspaceForUser,
+    provisionWorkspaceForNewUser,
+    createWorkspaceForAuthenticatedUser,
+    listWorkspacesForUser,
+    listWorkspacesForAuthenticatedUser,
+    resolveWorkspaceContextForUserBySlug
+  });
+}
+
+export { createService };

package/src/server/common/support/deepFreeze.js

@@ -0,0 +1,17 @@
+function deepFreeze(value, seen = new WeakSet()) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value)) {
+    return value;
+  }
+
+  seen.add(value);
+  for (const key of Object.keys(value)) {
+    deepFreeze(value[key], seen);
+  }
+
+  return Object.freeze(value);
+}
+
+export { deepFreeze };

package/src/server/common/support/realtimeServiceEvents.js

@@ -0,0 +1,94 @@
+import {
+  ACCOUNT_SETTINGS_CHANGED_EVENT,
+  USERS_BOOTSTRAP_CHANGED_EVENT
+} from "../../../shared/events/usersEvents.js";
+import { deepFreeze } from "./deepFreeze.js";
+
+function resolveActorScopedEntityId({ options } = {}) {
+  return Number(options?.context?.actor?.id || 0);
+}
+
+function resolveWorkspaceSlugPayload({ args } = {}) {
+  return {
+    workspaceSlug: String(args?.[0]?.slug || "").trim()
+  };
+}
+
+const ACCOUNT_SETTINGS_AND_BOOTSTRAP_EVENTS = deepFreeze([
+  {
+    type: "entity.changed",
+    source: "account",
+    entity: "settings",
+    operation: "updated",
+    entityId: resolveActorScopedEntityId,
+    realtime: {
+      event: ACCOUNT_SETTINGS_CHANGED_EVENT,
+      audience: "actor_user"
+    }
+  },
+  {
+    type: "entity.changed",
+    source: "users",
+    entity: "bootstrap",
+    operation: "updated",
+    entityId: resolveActorScopedEntityId,
+    realtime: {
+      event: USERS_BOOTSTRAP_CHANGED_EVENT,
+      audience: "actor_user"
+    }
+  }
+]);
+
+function createWorkspaceEntityAndBootstrapEvents({
+  workspaceEntity,
+  workspaceOperation,
+  workspaceRealtimeEvent,
+  workspaceEntityId = ({ args }) => args?.[0]?.id,
+  bootstrapEntityId = ({ args }) => args?.[0]?.id,
+  bootstrapAudience = "event_scope"
+} = {}) {
+  const normalizedWorkspaceEntity = String(workspaceEntity || "").trim();
+  const normalizedWorkspaceOperation = String(workspaceOperation || "")
+    .trim()
+    .toLowerCase();
+  const normalizedWorkspaceRealtimeEvent = String(workspaceRealtimeEvent || "").trim();
+  if (!normalizedWorkspaceEntity || !normalizedWorkspaceOperation || !normalizedWorkspaceRealtimeEvent) {
+    throw new Error(
+      "createWorkspaceEntityAndBootstrapEvents requires workspaceEntity, workspaceOperation, and workspaceRealtimeEvent."
+    );
+  }
+  if (typeof workspaceEntityId !== "function") {
+    throw new Error("createWorkspaceEntityAndBootstrapEvents requires workspaceEntityId to be a function.");
+  }
+  if (typeof bootstrapEntityId !== "function") {
+    throw new Error("createWorkspaceEntityAndBootstrapEvents requires bootstrapEntityId to be a function.");
+  }
+
+  return deepFreeze([
+    {
+      type: "entity.changed",
+      source: "workspace",
+      entity: normalizedWorkspaceEntity,
+      operation: normalizedWorkspaceOperation,
+      entityId: workspaceEntityId,
+      realtime: {
+        event: normalizedWorkspaceRealtimeEvent,
+        payload: resolveWorkspaceSlugPayload,
+        audience: "event_scope"
+      }
+    },
+    {
+      type: "entity.changed",
+      source: "users",
+      entity: "bootstrap",
+      operation: "updated",
+      entityId: bootstrapEntityId,
+      realtime: {
+        event: USERS_BOOTSTRAP_CHANGED_EVENT,
+        audience: bootstrapAudience
+      }
+    }
+  ]);
+}
+
+export { ACCOUNT_SETTINGS_AND_BOOTSTRAP_EVENTS, createWorkspaceEntityAndBootstrapEvents };

package/src/server/common/support/resolveActionUser.js

@@ -0,0 +1,11 @@
+function normalizeObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function resolveActionUser(context, input) {
+  const payload = normalizeObject(input);
+  const request = context?.requestMeta?.request || null;
+  return payload.user || request?.user || context?.actor || null;
+}
+
+export { resolveActionUser };

package/src/server/common/support/workspaceRoutePaths.js

@@ -0,0 +1,17 @@
+import {
+  USERS_WORKSPACE_API_BASE_PATH,
+  normalizeApiRelativePath
+} from "../../../shared/support/usersApiPaths.js";
+
+const USERS_WORKSPACE_ROUTE_BASE_PATH = USERS_WORKSPACE_API_BASE_PATH;
+
+function resolveWorkspaceRoutePath(relativePath = "/") {
+  const normalizedRelativePath = normalizeApiRelativePath(relativePath);
+  if (normalizedRelativePath === "/") {
+    return USERS_WORKSPACE_ROUTE_BASE_PATH;
+  }
+
+  return `${USERS_WORKSPACE_ROUTE_BASE_PATH}${normalizedRelativePath}`;
+}
+
+export { USERS_WORKSPACE_ROUTE_BASE_PATH, resolveWorkspaceRoutePath };

package/src/server/common/validators/README.md

@@ -0,0 +1,11 @@
+# `validators/`
+
+Put shared validators here when they are reused by multiple server slices/adapters.
+
+Allowed:
+- validator objects (`schema` + `normalize`)
+- transport-level reusable validators
+
+Not allowed:
+- feature-only validators used by one slice
+- business/domain decision logic

package/src/server/common/validators/authenticatedUserValidator.js

@@ -0,0 +1,42 @@
+import { Type } from "@fastify/type-provider-typebox";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+
+function normalizeAuthenticatedUser(input = {}) {
+  const source = normalizeObjectInput(input);
+  const id = Number(source.id);
+  if (!Number.isInteger(id) || id < 1) {
+    return null;
+  }
+
+  const email = normalizeLowerText(source.email);
+  return {
+    id,
+    email,
+    username: normalizeLowerText(source.username),
+    displayName: normalizeText(source.displayName) || email || `User ${id}`,
+    authProvider: normalizeLowerText(source.authProvider),
+    authProviderUserId: normalizeText(source.authProviderUserId),
+    avatarStorageKey: source.avatarStorageKey ? normalizeText(source.avatarStorageKey) : null,
+    avatarVersion: source.avatarVersion == null ? null : String(source.avatarVersion)
+  };
+}
+
+const authenticatedUserValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      id: Type.Integer({ minimum: 1 }),
+      email: Type.String({ minLength: 1 }),
+      username: Type.Optional(Type.String()),
+      displayName: Type.Optional(Type.String()),
+      authProvider: Type.Optional(Type.String()),
+      authProviderUserId: Type.Optional(Type.String()),
+      avatarStorageKey: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+      avatarVersion: Type.Optional(Type.Union([Type.String(), Type.Number(), Type.Null()]))
+    },
+    { additionalProperties: true }
+  ),
+  normalize: normalizeAuthenticatedUser
+});
+
+export { authenticatedUserValidator };

package/src/server/common/validators/routeParamsValidator.js

@@ -0,0 +1,62 @@
+import { Type } from "@fastify/type-provider-typebox";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeRouteParams(input = {}) {
+  const source = normalizeObjectInput(input);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "workspaceSlug")) {
+    normalized.workspaceSlug = normalizeText(source.workspaceSlug).toLowerCase();
+  }
+
+  if (Object.hasOwn(source, "memberUserId")) {
+    normalized.memberUserId = normalizeText(source.memberUserId);
+  }
+
+  if (Object.hasOwn(source, "inviteId")) {
+    normalized.inviteId = normalizeText(source.inviteId);
+  }
+
+  if (Object.hasOwn(source, "provider")) {
+    normalized.provider = normalizeText(source.provider);
+  }
+
+  return normalized;
+}
+
+function normalizeWorkspaceSlugParams(input = {}) {
+  const source = normalizeObjectInput(input);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "workspaceSlug")) {
+    normalized.workspaceSlug = normalizeText(source.workspaceSlug).toLowerCase();
+  }
+
+  return normalized;
+}
+
+const routeParamsValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      workspaceSlug: Type.Optional(Type.String({ minLength: 1 })),
+      memberUserId: Type.Optional(Type.String({ minLength: 1 })),
+      inviteId: Type.Optional(Type.String({ minLength: 1 })),
+      provider: Type.Optional(Type.String({ minLength: 1 }))
+    },
+    { additionalProperties: false }
+  ),
+  normalize: normalizeRouteParams
+});
+
+const workspaceSlugParamsValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
+    },
+    { additionalProperties: false }
+  ),
+  normalize: normalizeWorkspaceSlugParams
+});
+
+export { routeParamsValidator, workspaceSlugParamsValidator };

package/src/server/consoleSettings/bootConsoleSettingsRoutes.js

@@ -0,0 +1,64 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { consoleSettingsResource } from "../../shared/resources/consoleSettingsResource.js";
+
+function bootConsoleSettingsRoutes(app) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("bootConsoleSettingsRoutes requires application make().");
+  }
+
+  const router = app.make(KERNEL_TOKENS.HttpRouter);
+
+  router.register(
+    "GET",
+    "/api/console/settings",
+    {
+      auth: "required",
+      surface: "console",
+      meta: {
+        tags: ["console", "settings"],
+        summary: "Get console settings"
+      },
+      responseValidators: withStandardErrorResponses({
+        200: consoleSettingsResource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "console.settings.read"
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    "/api/console/settings",
+    {
+      auth: "required",
+      surface: "console",
+      meta: {
+        tags: ["console", "settings"],
+        summary: "Update console settings"
+      },
+      bodyValidator: consoleSettingsResource.operations.replace.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: consoleSettingsResource.operations.view.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "console.settings.update",
+        input: {
+          payload: request.input.body
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { bootConsoleSettingsRoutes };

package/src/server/consoleSettings/consoleService.js

@@ -0,0 +1,36 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
+
+function createService({ consoleSettingsRepository } = {}) {
+  if (!consoleSettingsRepository || typeof consoleSettingsRepository.ensureOwnerUserId !== "function") {
+    throw new Error("consoleService requires consoleSettingsRepository.ensureOwnerUserId().");
+  }
+
+  async function ensureInitialConsoleMember(userId, options = {}) {
+    const normalizedUserId = parsePositiveInteger(userId);
+    if (!normalizedUserId) {
+      throw new AppError(400, "Invalid console user.");
+    }
+
+    return consoleSettingsRepository.ensureOwnerUserId(normalizedUserId, options);
+  }
+
+  async function requireConsoleOwner(context = {}, options = {}) {
+    const actorUserId = parsePositiveInteger(context?.actor?.id);
+    if (!actorUserId) {
+      throw new AppError(401, "Authentication required.");
+    }
+
+    const ownerUserId = await ensureInitialConsoleMember(actorUserId, options);
+    if (actorUserId !== ownerUserId) {
+      throw new AppError(403, "Forbidden.");
+    }
+  }
+
+  return Object.freeze({
+    ensureInitialConsoleMember,
+    requireConsoleOwner
+  });
+}
+
+export { createService };

package/src/server/consoleSettings/consoleSettingsActions.js

@@ -0,0 +1,55 @@
+import {
+  EMPTY_INPUT_VALIDATOR
+} from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { consoleSettingsResource } from "../../shared/resources/consoleSettingsResource.js";
+
+const consoleSettingsActions = Object.freeze([
+  {
+    id: "console.settings.read",
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "console",
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: EMPTY_INPUT_VALIDATOR,
+    outputValidator: consoleSettingsResource.operations.view.outputValidator,
+    idempotency: "none",
+    audit: {
+      actionName: "console.settings.read"
+    },
+    observability: {},
+    async execute(_input, context, deps) {
+      return deps.consoleSettingsService.getSettings({
+        context
+      });
+    }
+  },
+  {
+    id: "console.settings.update",
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "console",
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: {
+      payload: consoleSettingsResource.operations.replace.bodyValidator
+    },
+    outputValidator: consoleSettingsResource.operations.replace.outputValidator,
+    idempotency: "optional",
+    audit: {
+      actionName: "console.settings.update"
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.consoleSettingsService.updateSettings(input.payload, {
+        context
+      });
+    }
+  }
+]);
+
+export { consoleSettingsActions };