@jskit-ai/users-core 0.1.4

package/src/server/accountSecurity/bootAccountSecurityRoutes.js

@@ -0,0 +1,183 @@
+import { Type } from "@fastify/type-provider-typebox";
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { userSettingsResource } from "../../shared/resources/userSettingsResource.js";
+
+function bootAccountSecurityRoutes(app) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("bootAccountSecurityRoutes requires application make().");
+  }
+
+  const router = app.make(KERNEL_TOKENS.HttpRouter);
+  const authService = app.make("authService");
+
+  router.register(
+    "POST",
+    "/api/settings/security/change-password",
+    {
+      auth: "required",
+      meta: {
+        tags: ["settings"],
+        summary: "Set or change authenticated user's password"
+      },
+      bodyValidator: userSettingsResource.operations.passwordChange.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: userSettingsResource.operations.passwordChange.outputValidator
+        },
+        { includeValidation400: true }
+      ),
+      rateLimit: {
+        max: 10,
+        timeWindow: "1 minute"
+      }
+    },
+    async function (request, reply) {
+      const result = await request.executeAction({
+        actionId: "settings.security.password.change",
+        input: {
+          payload: request.input.body
+        }
+      });
+
+      if (result?.session && typeof authService.writeSessionCookies === "function") {
+        authService.writeSessionCookies(reply, result.session);
+      }
+
+      reply.code(200).send({
+        ok: true,
+        message: result?.message || "Password updated."
+      });
+    }
+  );
+
+  router.register(
+    "PATCH",
+    "/api/settings/security/methods/password",
+    {
+      auth: "required",
+      meta: {
+        tags: ["settings"],
+        summary: "Enable or disable password sign-in method"
+      },
+      bodyValidator: userSettingsResource.operations.passwordMethodToggle.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: userSettingsResource.operations.passwordMethodToggle.outputValidator
+        },
+        { includeValidation400: true }
+      ),
+      rateLimit: {
+        max: 20,
+        timeWindow: "1 minute"
+      }
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "settings.security.password_method.toggle",
+        input: {
+          payload: request.input.body
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    "/api/settings/security/oauth/:provider/start",
+    {
+      auth: "required",
+      csrfProtection: false,
+      meta: {
+        tags: ["settings"],
+        summary: "Start linking an OAuth provider for authenticated user"
+      },
+      paramsValidator: userSettingsResource.operations.oauthLinkStart.paramsValidator,
+      queryValidator: userSettingsResource.operations.oauthLinkStart.queryValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          302: { schema: Type.Unknown() }
+        },
+        { includeValidation400: true }
+      ),
+      rateLimit: {
+        max: 20,
+        timeWindow: "1 minute"
+      }
+    },
+    async function (request, reply) {
+      const result = await request.executeAction({
+        actionId: "settings.security.oauth.link.start",
+        input: {
+          provider: request.input.params.provider,
+          returnTo: request.input.query.returnTo
+        }
+      });
+
+      reply.redirect(result.url);
+    }
+  );
+
+  router.register(
+    "DELETE",
+    "/api/settings/security/oauth/:provider",
+    {
+      auth: "required",
+      meta: {
+        tags: ["settings"],
+        summary: "Unlink an OAuth provider from authenticated account"
+      },
+      paramsValidator: userSettingsResource.operations.oauthUnlink.paramsValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: userSettingsResource.operations.oauthUnlink.outputValidator
+        },
+        { includeValidation400: true }
+      ),
+      rateLimit: {
+        max: 20,
+        timeWindow: "1 minute"
+      }
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "settings.security.oauth.unlink",
+        input: {
+          provider: request.input.params.provider
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "POST",
+    "/api/settings/security/logout-others",
+    {
+      auth: "required",
+      meta: {
+        tags: ["settings"],
+        summary: "Sign out from other active sessions"
+      },
+      responseValidators: withStandardErrorResponses({
+        200: userSettingsResource.operations.logoutOtherSessions.outputValidator
+      }),
+      rateLimit: {
+        max: 20,
+        timeWindow: "1 minute"
+      }
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "settings.security.sessions.logout_others",
+        input: {}
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { bootAccountSecurityRoutes };

package/src/server/accountSecurity/registerAccountSecurity.js

@@ -0,0 +1,31 @@
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { createService as createAccountSecurityService } from "./accountSecurityService.js";
+import { accountSecurityActions } from "./accountSecurityActions.js";
+
+const USERS_ACCOUNT_SECURITY_SERVICE_TOKEN = "users.accountSecurity.service";
+
+function registerAccountSecurity(app) {
+  if (!app || typeof app.singleton !== "function" || typeof app.actions !== "function") {
+    throw new Error("registerAccountSecurity requires application singleton()/actions().");
+  }
+
+  app.singleton(USERS_ACCOUNT_SECURITY_SERVICE_TOKEN, (scope) => {
+    const authService = scope.has("authService") ? scope.make("authService") : null;
+    return createAccountSecurityService({
+      userSettingsRepository: scope.make("userSettingsRepository"),
+      userProfilesRepository: scope.make("userProfilesRepository"),
+      authService
+    });
+  });
+
+  app.actions(
+    withActionDefaults(accountSecurityActions, {
+      domain: "settings",
+      dependencies: {
+        accountSecurityService: USERS_ACCOUNT_SECURITY_SERVICE_TOKEN
+      }
+    })
+  );
+}
+
+export { registerAccountSecurity };

package/src/server/common/README.md

@@ -0,0 +1,21 @@
+# Server Common
+
+This directory contains server-only runtime pieces reused by multiple slices in `users-core`.
+
+Use these folders:
+- `repositories/`: shared repositories and repository-only helpers.
+- `services/`: shared domain services consumed by multiple slices.
+- `contributors/`: shared action-context/bootstrap contributors.
+- `validators/`: shared request/response validators used by multiple adapters.
+- `formatters/`: shared payload formatters/projections for transport output.
+- `routes/`: shared route schema maps used by more than one route adapter.
+
+Keep these files here:
+- `diTokens.js`: shared DI tokens used across slices.
+- `registerCommonRepositories.js`: shared repository bindings.
+- `registerSharedApi.js`: shared API metadata registration.
+
+Do not put these in `common/`:
+- feature-only actions/services/repositories/controllers
+- one-off route payload shapes used by a single feature
+- UI/client code

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

@@ -0,0 +1,11 @@
+# `contributors/`
+
+Put shared runtime contributors here (for action context or bootstrap payload composition).
+
+Allowed:
+- contributors reused by multiple slices/actions
+- contributor logic that delegates domain work to services
+
+Not allowed:
+- feature-specific contributors used by one slice only
+- direct repository access when a service already owns that domain

package/src/server/common/contributors/workspaceActionContextContributor.js

@@ -0,0 +1,79 @@
+import {
+  normalizeObject,
+  requireServiceMethod
+} from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import {
+  normalizeScopedRouteVisibility,
+  USERS_ROUTE_VISIBILITY_PUBLIC,
+  USERS_ROUTE_VISIBILITY_WORKSPACE,
+  USERS_ROUTE_VISIBILITY_WORKSPACE_USER
+} from "../../../shared/support/usersVisibility.js";
+import { resolveActionUser } from "../support/resolveActionUser.js";
+
+const WORKSPACE_CONTEXT_ACTION_IDS = Object.freeze([
+  "workspace.roles.list",
+  "workspace.settings.read",
+  "workspace.settings.update",
+  "workspace.members.list",
+  "workspace.member.role.update",
+  "workspace.member.remove",
+  "workspace.invites.list",
+  "workspace.invite.create",
+  "workspace.invite.revoke"
+]);
+const WORKSPACE_VISIBILITY_ACTION_CONTEXT_SET = new Set([
+  USERS_ROUTE_VISIBILITY_WORKSPACE,
+  USERS_ROUTE_VISIBILITY_WORKSPACE_USER
+]);
+
+function createWorkspaceActionContextContributor({ workspaceService } = {}) {
+  const contributorId = "users.workspace.context";
+
+  requireServiceMethod(workspaceService, "resolveWorkspaceContextForUserBySlug", contributorId);
+
+  return Object.freeze({
+    contributorId,
+    async contribute({ actionId, input, context, request } = {}) {
+      const payload = normalizeObject(input);
+      if (!Object.hasOwn(payload, "workspaceSlug")) {
+        return {};
+      }
+
+      const actionName = String(actionId || "").trim();
+      const hasLegacyWorkspaceActionId = WORKSPACE_CONTEXT_ACTION_IDS.includes(actionName);
+      const routeVisibility = normalizeScopedRouteVisibility(request?.routeOptions?.config?.visibility, {
+        fallback: USERS_ROUTE_VISIBILITY_PUBLIC
+      });
+      const hasWorkspaceRouteVisibility = WORKSPACE_VISIBILITY_ACTION_CONTEXT_SET.has(routeVisibility);
+      if (!hasLegacyWorkspaceActionId && !hasWorkspaceRouteVisibility) {
+        return {};
+      }
+
+      const resolvedWorkspaceContext = await workspaceService.resolveWorkspaceContextForUserBySlug(
+        resolveActionUser(context, payload),
+        payload.workspaceSlug,
+        { request }
+      );
+
+      const contribution = {
+        requestMeta: {
+          resolvedWorkspaceContext
+        }
+      };
+
+      if (!context?.workspace) {
+        contribution.workspace = resolvedWorkspaceContext.workspace;
+      }
+      if (!context?.membership) {
+        contribution.membership = resolvedWorkspaceContext.membership;
+      }
+      if (!Array.isArray(context?.permissions) || context.permissions.length < 1) {
+        contribution.permissions = resolvedWorkspaceContext.permissions;
+      }
+
+      return contribution;
+    }
+  });
+}
+
+export { createWorkspaceActionContextContributor };

package/src/server/common/contributors/workspaceAuthPolicyContextResolver.js

@@ -0,0 +1,34 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function createWorkspaceAuthPolicyContextResolver({ workspaceService } = {}) {
+  if (!workspaceService || typeof workspaceService.resolveWorkspaceContextForUserBySlug !== "function") {
+    throw new Error(
+      "workspace auth policy context resolver requires workspaceService.resolveWorkspaceContextForUserBySlug()."
+    );
+  }
+
+  return async function resolveWorkspaceAuthPolicyContext({ request, actor, meta } = {}) {
+    const contextPolicy = normalizeText(meta?.contextPolicy || "none").toLowerCase() || "none";
+    const permission = normalizeText(meta?.permission);
+    if (contextPolicy === "none" && !permission) {
+      return {};
+    }
+
+    const workspaceSlug = normalizeText(request?.params?.workspaceSlug).toLowerCase();
+    if (!workspaceSlug || !actor) {
+      return {};
+    }
+
+    const resolvedWorkspaceContext = await workspaceService.resolveWorkspaceContextForUserBySlug(actor, workspaceSlug, {
+      request
+    });
+
+    return {
+      workspace: resolvedWorkspaceContext?.workspace || null,
+      membership: resolvedWorkspaceContext?.membership || null,
+      permissions: Array.isArray(resolvedWorkspaceContext?.permissions) ? resolvedWorkspaceContext.permissions : []
+    };
+  };
+}
+
+export { createWorkspaceAuthPolicyContextResolver };

package/src/server/common/contributors/workspaceRouteVisibilityResolver.js

@@ -0,0 +1,79 @@
+import { normalizeOpaqueId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
+
+function buildVisibilityContribution({ visibility, scopeOwnerId = 0, userOwnerId = null } = {}) {
+  const requiresActorScope = visibility === "workspace_user";
+  const contribution = {
+    scopeKind: requiresActorScope ? "workspace_user" : "workspace",
+    requiresActorScope
+  };
+
+  if (scopeOwnerId > 0) {
+    contribution.scopeOwnerId = scopeOwnerId;
+  }
+  if (requiresActorScope && userOwnerId != null) {
+    contribution.userOwnerId = userOwnerId;
+  }
+
+  return contribution;
+}
+
+function createWorkspaceRouteVisibilityResolver({ workspaceService } = {}) {
+  if (!workspaceService || typeof workspaceService.resolveWorkspaceContextForUserBySlug !== "function") {
+    throw new Error("workspace route visibility resolver requires workspaceService.resolveWorkspaceContextForUserBySlug().");
+  }
+
+  return Object.freeze({
+    resolverId: "users.workspace.visibility",
+    async resolve({ visibility, context, request, input } = {}) {
+      if (visibility !== "workspace" && visibility !== "workspace_user") {
+        return {};
+      }
+
+      const actor = context?.actor || request?.user || null;
+      const userOwnerId = normalizeOpaqueId(actor?.id);
+      const workspace =
+        context?.workspace || context?.requestMeta?.resolvedWorkspaceContext?.workspace || request?.workspace || null;
+      const scopeOwnerId = parsePositiveInteger(workspace?.id);
+      if (!scopeOwnerId) {
+        const workspaceSlug = normalizeText(input?.workspaceSlug).toLowerCase();
+
+        if (!workspaceSlug || !actor) {
+          return visibility === "workspace_user"
+            ? buildVisibilityContribution({
+                visibility,
+                userOwnerId
+              })
+            : {};
+        }
+
+        const resolvedWorkspaceContext = await workspaceService.resolveWorkspaceContextForUserBySlug(actor, workspaceSlug, {
+          request
+        });
+        const resolvedWorkspaceOwnerId = parsePositiveInteger(resolvedWorkspaceContext?.workspace?.id);
+        if (!resolvedWorkspaceOwnerId) {
+          return visibility === "workspace_user"
+            ? buildVisibilityContribution({
+                visibility,
+                userOwnerId
+              })
+            : {};
+        }
+
+        return buildVisibilityContribution({
+          visibility,
+          scopeOwnerId: resolvedWorkspaceOwnerId,
+          userOwnerId
+        });
+      }
+
+      return buildVisibilityContribution({
+        visibility,
+        scopeOwnerId,
+        userOwnerId
+      });
+    }
+  });
+}
+
+export { createWorkspaceRouteVisibilityResolver };

package/src/server/common/diTokens.js

@@ -0,0 +1,21 @@
+const USERS_WORKSPACE_PENDING_INVITATIONS_SERVICE_TOKEN = "users.workspace.pending-invitations.service";
+const USERS_WORKSPACE_ENABLED_TOKEN = "users.workspace.enabled";
+const USERS_WORKSPACE_TENANCY_ENABLED_TOKEN = "users.workspace.tenancy.enabled";
+const USERS_WORKSPACE_INVITATIONS_ENABLED_TOKEN = "users.workspace.invitations.enabled";
+const USERS_WORKSPACE_SELF_CREATE_ENABLED_TOKEN = "users.workspace.self-create.enabled";
+const USERS_TENANCY_PROFILE_TOKEN = "users.tenancy.profile";
+const USERS_AVATAR_STORAGE_SERVICE_TOKEN = "users.avatar.storage.service";
+const USERS_AVATAR_SERVICE_TOKEN = "users.avatar.service";
+const USERS_PROFILE_SYNC_SERVICE_TOKEN = "users.profile.sync.service";
+
+export {
+  USERS_WORKSPACE_PENDING_INVITATIONS_SERVICE_TOKEN,
+  USERS_WORKSPACE_ENABLED_TOKEN,
+  USERS_WORKSPACE_TENANCY_ENABLED_TOKEN,
+  USERS_WORKSPACE_INVITATIONS_ENABLED_TOKEN,
+  USERS_WORKSPACE_SELF_CREATE_ENABLED_TOKEN,
+  USERS_TENANCY_PROFILE_TOKEN,
+  USERS_AVATAR_STORAGE_SERVICE_TOKEN,
+  USERS_AVATAR_SERVICE_TOKEN,
+  USERS_PROFILE_SYNC_SERVICE_TOKEN
+};

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

@@ -0,0 +1,11 @@
+# `formatters/`
+
+Put shared transport/output projection logic here.
+
+Allowed:
+- shaping domain records into API payloads used in multiple slices
+
+Not allowed:
+- business rules
+- repository reads/writes
+- HTTP adapter/controller code

package/src/server/common/formatters/accountAvatarFormatter.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { normalizeLowerText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+import { DEFAULT_USER_SETTINGS } from "../../../shared/settings.js";
+
+const ACCOUNT_AVATAR_FILE_PATH = "/api/settings/profile/avatar";
+
+function createGravatarUrl(email, size = 64) {
+  const normalizedEmail = normalizeLowerText(email);
+  const hash = createHash("sha256").update(normalizedEmail).digest("hex");
+  return `https://www.gravatar.com/avatar/${hash}?d=mp&s=${Number(size) || 64}`;
+}
+
+function createUploadedAvatarUrl(profile = {}) {
+  const storageKey = String(profile?.avatarStorageKey || "").trim();
+  if (!storageKey) {
+    return null;
+  }
+
+  const avatarVersion = String(profile?.avatarVersion || "").trim();
+  if (!avatarVersion) {
+    return ACCOUNT_AVATAR_FILE_PATH;
+  }
+
+  return `${ACCOUNT_AVATAR_FILE_PATH}?v=${encodeURIComponent(avatarVersion)}`;
+}
+
+function accountAvatarFormatter(profile, settings) {
+  const size = Number(settings?.avatarSize || DEFAULT_USER_SETTINGS.avatarSize);
+  const uploadedUrl = createUploadedAvatarUrl(profile);
+  const gravatarUrl = createGravatarUrl(profile?.email, size);
+
+  return {
+    uploadedUrl,
+    gravatarUrl,
+    effectiveUrl: uploadedUrl || gravatarUrl,
+    hasUploadedAvatar: Boolean(uploadedUrl),
+    size,
+    version: profile?.avatarVersion || null
+  };
+}
+
+export { accountAvatarFormatter };

package/src/server/common/formatters/accountSecurityStatusFormatter.js

@@ -0,0 +1,71 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeMfa(source) {
+  const mfaSource = isRecord(source?.mfa) ? source.mfa : {};
+  const methods = [];
+  for (const entry of Array.isArray(mfaSource.methods) ? mfaSource.methods : []) {
+    const normalized = normalizeText(entry);
+    if (!normalized) {
+      continue;
+    }
+    methods.push(normalized);
+  }
+
+  return {
+    status: normalizeText(mfaSource.status) || "not_enabled",
+    enrolled: Boolean(mfaSource.enrolled),
+    methods
+  };
+}
+
+function normalizeAuthMethods(sourceMethods) {
+  const methods = [];
+  let enabledMethodsCount = 0;
+
+  for (const method of Array.isArray(sourceMethods) ? sourceMethods : []) {
+    const normalizedMethod = {
+      id: normalizeText(method?.id),
+      kind: normalizeText(method?.kind),
+      provider: method?.provider == null ? null : normalizeText(method.provider),
+      label: normalizeText(method?.label || method?.id),
+      configured: method?.configured === true,
+      enabled: method?.enabled === true,
+      canEnable: method?.canEnable === true,
+      canDisable: method?.canDisable === true,
+      supportsSecretUpdate: method?.supportsSecretUpdate === true,
+      requiresCurrentPassword: method?.requiresCurrentPassword === true
+    };
+
+    if (normalizedMethod.enabled) {
+      enabledMethodsCount += 1;
+    }
+    methods.push(normalizedMethod);
+  }
+
+  return {
+    methods,
+    enabledMethodsCount
+  };
+}
+
+function accountSecurityStatusFormatter(securityStatus = {}) {
+  const source = isRecord(securityStatus) ? securityStatus : {};
+  const authPolicy = isRecord(source.authPolicy) ? source.authPolicy : {};
+  const { methods: authMethods, enabledMethodsCount } = normalizeAuthMethods(source.authMethods);
+  const minimumEnabledMethods = Number(authPolicy.minimumEnabledMethods);
+
+  return {
+    mfa: normalizeMfa(source),
+    sessions: {
+      canSignOutOtherDevices: true
+    },
+    authPolicy: {
+      minimumEnabledMethods: minimumEnabledMethods > 0 ? minimumEnabledMethods : 1,
+      enabledMethodsCount
+    },
+    authMethods
+  };
+}
+
+export { accountSecurityStatusFormatter };

package/src/server/common/formatters/accountSettingsResponseFormatter.js

@@ -0,0 +1,62 @@
+import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+import {
+  USER_SETTINGS_SECTIONS,
+  userSettingsFields
+} from "../../../shared/resources/userSettingsFields.js";
+import { accountAvatarFormatter } from "./accountAvatarFormatter.js";
+import { accountSecurityStatusFormatter } from "./accountSecurityStatusFormatter.js";
+
+function resolveAuthProfileSettings(authService) {
+  if (!authService || typeof authService.getSettingsProfileAuthInfo !== "function") {
+    return {
+      emailManagedBy: "auth",
+      emailChangeFlow: "auth"
+    };
+  }
+
+  const authProfileSettings = authService.getSettingsProfileAuthInfo();
+  return {
+    emailManagedBy: normalizeLowerText(authProfileSettings?.emailManagedBy) || "auth",
+    emailChangeFlow: normalizeLowerText(authProfileSettings?.emailChangeFlow) || "auth"
+  };
+}
+
+function formatUserSettingsSection(section, settings = {}) {
+  const source = settings && typeof settings === "object" ? settings : {};
+  const formatted = {};
+
+  for (const field of userSettingsFields) {
+    if (field.section !== section) {
+      continue;
+    }
+    const rawValue = Object.hasOwn(source, field.key)
+      ? source[field.key]
+      : field.resolveDefault({
+          settings: source
+        });
+    formatted[field.key] = field.normalizeOutput(rawValue, {
+      settings: source
+    });
+  }
+
+  return formatted;
+}
+
+function accountSettingsResponseFormatter({ profile, settings, securityStatus, authService }) {
+  const authProfileSettings = resolveAuthProfileSettings(authService);
+
+  return {
+    profile: {
+      displayName: normalizeText(profile?.displayName),
+      email: normalizeLowerText(profile?.email),
+      emailManagedBy: authProfileSettings.emailManagedBy,
+      emailChangeFlow: authProfileSettings.emailChangeFlow,
+      avatar: accountAvatarFormatter(profile, settings)
+    },
+    security: accountSecurityStatusFormatter(securityStatus),
+    preferences: formatUserSettingsSection(USER_SETTINGS_SECTIONS.PREFERENCES, settings),
+    notifications: formatUserSettingsSection(USER_SETTINGS_SECTIONS.NOTIFICATIONS, settings)
+  };
+}
+
+export { accountSettingsResponseFormatter };