@jskit-ai/auth-core 0.1.99 → 0.1.100

package/src/shared/authCapabilities.js

@@ -0,0 +1,184 @@
+import { normalizeOAuthProviderId } from "./oauthProviders.js";
+
+const AUTH_PASSWORD_RECOVERY_DELIVERIES = Object.freeze(["smtp", "dev-log", "dev-response", "disabled"]);
+
+const AUTH_OPTIONAL_OPERATION_FEATURES = Object.freeze({
+  register: "password.register",
+  resendRegisterConfirmation: "emailConfirmation",
+  login: "password.login",
+  requestOtpLogin: "otp.login",
+  verifyOtpLogin: "otp.login",
+  oauthStart: "oauthLogin.enabled",
+  oauthComplete: "oauthLogin.enabled",
+  requestPasswordReset: "passwordRecovery.request",
+  completePasswordRecovery: "passwordRecovery.complete",
+  resetPassword: "passwordRecovery.complete",
+  changePassword: "password.change",
+  updateDisplayName: "profileUpdate",
+  getSecurityStatus: "securityStatus",
+  setPasswordSignInEnabled: "password.methodToggle",
+  startProviderLink: "providerLinking.start",
+  unlinkProvider: "providerLinking.unlink",
+  signOutOtherSessions: "signOutOtherSessions",
+  devLoginAs: "devLoginAs"
+});
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return fallback === true;
+}
+
+function normalizeAuthProviderId(value, { fallback = "unknown" } = {}) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (/^[a-z][a-z0-9_-]{1,63}$/.test(normalized)) {
+    return normalized;
+  }
+
+  return fallback;
+}
+
+function normalizeProviderLabel(value, providerId) {
+  const label = String(value || "").trim();
+  if (label) {
+    return label;
+  }
+  return providerId.charAt(0).toUpperCase() + providerId.slice(1);
+}
+
+function normalizeOAuthProviderEntries(value) {
+  const source = Array.isArray(value) ? value : [];
+  const providers = [];
+  const seen = new Set();
+
+  for (const entry of source) {
+    const rawId = typeof entry === "string" ? entry : entry?.id;
+    const id = normalizeOAuthProviderId(rawId, { fallback: null });
+    if (!id || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    providers.push(Object.freeze({
+      id,
+      label: String((typeof entry === "object" && entry ? entry.label : "") || id).trim() || id
+    }));
+  }
+
+  return Object.freeze(providers);
+}
+
+function normalizeRecoveryDelivery(value, { request = false, complete = false } = {}) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (AUTH_PASSWORD_RECOVERY_DELIVERIES.includes(normalized)) {
+    return normalized;
+  }
+  return request || complete ? "disabled" : "disabled";
+}
+
+function normalizeAuthCapabilities(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const providerSource = source.provider && typeof source.provider === "object" ? source.provider : {};
+  const providerId = normalizeAuthProviderId(providerSource.id || source.providerId, { fallback: "unknown" });
+  const featuresSource = source.features && typeof source.features === "object" ? source.features : {};
+
+  const passwordSource = featuresSource.password && typeof featuresSource.password === "object"
+    ? featuresSource.password
+    : {};
+  const recoverySource = featuresSource.passwordRecovery && typeof featuresSource.passwordRecovery === "object"
+    ? featuresSource.passwordRecovery
+    : {};
+  const otpSource = featuresSource.otp && typeof featuresSource.otp === "object"
+    ? featuresSource.otp
+    : {};
+  const oauthSource = featuresSource.oauthLogin && typeof featuresSource.oauthLogin === "object"
+    ? featuresSource.oauthLogin
+    : {};
+  const providerLinkingSource = featuresSource.providerLinking && typeof featuresSource.providerLinking === "object"
+    ? featuresSource.providerLinking
+    : {};
+  const oauthProviders = normalizeOAuthProviderEntries(oauthSource.providers);
+  const oauthDefaultProvider = normalizeOAuthProviderId(oauthSource.defaultProvider, { fallback: null });
+  const recoveryRequest = normalizeBoolean(recoverySource.request);
+  const recoveryComplete = normalizeBoolean(recoverySource.complete);
+
+  return Object.freeze({
+    provider: Object.freeze({
+      id: providerId,
+      label: normalizeProviderLabel(providerSource.label, providerId)
+    }),
+    features: Object.freeze({
+      password: Object.freeze({
+        login: normalizeBoolean(passwordSource.login),
+        register: normalizeBoolean(passwordSource.register),
+        change: normalizeBoolean(passwordSource.change),
+        methodToggle: normalizeBoolean(passwordSource.methodToggle)
+      }),
+      passwordRecovery: Object.freeze({
+        request: recoveryRequest,
+        complete: recoveryComplete,
+        delivery: normalizeRecoveryDelivery(recoverySource.delivery, {
+          request: recoveryRequest,
+          complete: recoveryComplete
+        })
+      }),
+      otp: Object.freeze({
+        login: normalizeBoolean(otpSource.login)
+      }),
+      oauthLogin: Object.freeze({
+        enabled: normalizeBoolean(oauthSource.enabled) && oauthProviders.length > 0,
+        providers: oauthProviders,
+        defaultProvider: oauthProviders.some((provider) => provider.id === oauthDefaultProvider)
+          ? oauthDefaultProvider
+          : null
+      }),
+      emailConfirmation: normalizeBoolean(featuresSource.emailConfirmation),
+      profileUpdate: normalizeBoolean(featuresSource.profileUpdate),
+      providerLinking: Object.freeze({
+        start: normalizeBoolean(providerLinkingSource.start),
+        unlink: normalizeBoolean(providerLinkingSource.unlink)
+      }),
+      securityStatus: normalizeBoolean(featuresSource.securityStatus),
+      signOutOtherSessions: normalizeBoolean(featuresSource.signOutOtherSessions),
+      appProfileProjection: normalizeBoolean(featuresSource.appProfileProjection),
+      devLoginAs: normalizeBoolean(featuresSource.devLoginAs)
+    })
+  });
+}
+
+function getCapabilityFeature(capabilities, path) {
+  const normalizedPath = String(path || "").trim();
+  if (!normalizedPath) {
+    return undefined;
+  }
+
+  let current = normalizeAuthCapabilities(capabilities).features;
+  for (const segment of normalizedPath.split(".")) {
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, segment)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function isAuthOperationSupported(capabilities, operationName) {
+  const path = AUTH_OPTIONAL_OPERATION_FEATURES[String(operationName || "").trim()];
+  if (!path) {
+    return true;
+  }
+  return getCapabilityFeature(capabilities, path) === true;
+}
+
+export {
+  AUTH_PASSWORD_RECOVERY_DELIVERIES,
+  AUTH_OPTIONAL_OPERATION_FEATURES,
+  normalizeAuthProviderId,
+  normalizeAuthCapabilities,
+  getCapabilityFeature,
+  isAuthOperationSupported
+};

package/src/shared/authSecurityStatus.js

@@ -0,0 +1,111 @@
+import { AUTH_METHOD_MINIMUM_ENABLED } from "./authMethods.js";
+
+function normalizeBoolean(value, fallback = false) {
+  return typeof value === "boolean" ? value : fallback === true;
+}
+
+function countEnabledMethods(methods) {
+  return methods.filter((method) => method?.enabled === true).length;
+}
+
+function normalizeAuthMethodStatus(entry) {
+  const source = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : {};
+  const id = String(source.id || "").trim();
+  const kind = String(source.kind || "").trim();
+  if (!id || !kind) {
+    return null;
+  }
+
+  const method = {
+    id,
+    kind,
+    configured: normalizeBoolean(source.configured),
+    enabled: normalizeBoolean(source.enabled),
+    canDisable: normalizeBoolean(source.canDisable)
+  };
+
+  for (const key of [
+    "provider",
+    "label",
+    "canEnable",
+    "canUnlink",
+    "supportsSecretUpdate",
+    "requiresCurrentPassword"
+  ]) {
+    if (Object.hasOwn(source, key)) {
+      method[key] = source[key];
+    }
+  }
+
+  return Object.freeze(method);
+}
+
+function normalizeSecurityActions(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return Object.freeze({
+    changePassword: normalizeBoolean(source.changePassword),
+    setPasswordEnabled: normalizeBoolean(source.setPasswordEnabled),
+    linkProvider: normalizeBoolean(source.linkProvider),
+    unlinkProvider: normalizeBoolean(source.unlinkProvider),
+    signOutOtherSessions: normalizeBoolean(source.signOutOtherSessions)
+  });
+}
+
+function normalizeAuthSecurityStatus(value = {}) {
+  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const authMethods = (Array.isArray(source.authMethods) ? source.authMethods : [])
+    .map((entry) => normalizeAuthMethodStatus(entry))
+    .filter(Boolean);
+  const policySource =
+    source.policy && typeof source.policy === "object"
+      ? source.policy
+      : source.authPolicy && typeof source.authPolicy === "object"
+        ? source.authPolicy
+        : {};
+  const minimumEnabledMethods = Number.isInteger(Number(policySource.minimumEnabledMethods))
+    ? Math.max(1, Number(policySource.minimumEnabledMethods))
+    : AUTH_METHOD_MINIMUM_ENABLED;
+  const enabledMethodsCount = Number.isInteger(Number(policySource.enabledMethodsCount))
+    ? Math.max(0, Number(policySource.enabledMethodsCount))
+    : countEnabledMethods(authMethods);
+  const policy = Object.freeze({
+    minimumEnabledMethods,
+    enabledMethodsCount
+  });
+  const actions = normalizeSecurityActions(source.actions);
+
+  return Object.freeze({
+    mfa: source.mfa && typeof source.mfa === "object"
+      ? Object.freeze({
+          status: String(source.mfa.status || "not_enabled"),
+          enrolled: normalizeBoolean(source.mfa.enrolled),
+          methods: Object.freeze(Array.isArray(source.mfa.methods) ? [...source.mfa.methods] : [])
+        })
+      : Object.freeze({
+          status: "not_enabled",
+          enrolled: false,
+          methods: Object.freeze([])
+        }),
+    policy,
+    authPolicy: policy,
+    actions,
+    authMethods: Object.freeze(authMethods)
+  });
+}
+
+function buildSecurityStatusFromAuthMethodsStatus(authMethodsStatus, { actions = {} } = {}) {
+  const source = authMethodsStatus && typeof authMethodsStatus === "object" ? authMethodsStatus : {};
+  return normalizeAuthSecurityStatus({
+    authMethods: Array.isArray(source.methods) ? source.methods : [],
+    policy: {
+      minimumEnabledMethods: source.minimumEnabledMethods,
+      enabledMethodsCount: source.enabledMethodsCount
+    },
+    actions
+  });
+}
+
+export {
+  normalizeAuthSecurityStatus,
+  buildSecurityStatusFromAuthMethodsStatus
+};

package/src/shared/commands/authCommandValidators.js

@@ -17,6 +17,7 @@ import {
   AUTH_REFRESH_TOKEN_MAX_LENGTH
 } from "../authConstraints.js";
 import { AUTH_METHOD_IDS, AUTH_METHOD_KINDS } from "../authMethods.js";
+import { AUTH_PASSWORD_RECOVERY_DELIVERIES } from "../authCapabilities.js";
 import { OAUTH_PROVIDER_ID_PATTERN } from "../oauthProviders.js";
 
 const oauthProviderFieldDefinition = deepFreeze({
@@ -230,6 +231,109 @@ const authDeniedOutputSchema = createSchema({
   }
 });
 
+const authCapabilityProviderOutputSchema = createSchema({
+  id: {
+    type: "string",
+    required: true,
+    minLength: 2,
+    maxLength: 64,
+    pattern: "^[a-z][a-z0-9_-]{1,63}$"
+  },
+  label: {
+    type: "string",
+    required: true,
+    minLength: 1,
+    maxLength: 120
+  }
+});
+
+const authPasswordCapabilitiesOutputSchema = createSchema({
+  login: { type: "boolean", required: true },
+  register: { type: "boolean", required: true },
+  change: { type: "boolean", required: true },
+  methodToggle: { type: "boolean", required: true }
+});
+
+const authPasswordRecoveryCapabilitiesOutputSchema = createSchema({
+  request: { type: "boolean", required: true },
+  complete: { type: "boolean", required: true },
+  delivery: {
+    type: "string",
+    required: true,
+    enum: AUTH_PASSWORD_RECOVERY_DELIVERIES
+  }
+});
+
+const authOtpCapabilitiesOutputSchema = createSchema({
+  login: { type: "boolean", required: true }
+});
+
+const authOAuthLoginCapabilitiesOutputSchema = createSchema({
+  enabled: { type: "boolean", required: true },
+  providers: {
+    type: "array",
+    required: true,
+    items: oauthProviderCatalogEntrySchema
+  },
+  defaultProvider: {
+    ...oauthProviderFieldDefinition,
+    required: true,
+    nullable: true
+  }
+});
+
+const authProviderLinkingCapabilitiesOutputSchema = createSchema({
+  start: { type: "boolean", required: true },
+  unlink: { type: "boolean", required: true }
+});
+
+const authCapabilitiesFeaturesOutputSchema = createSchema({
+  password: {
+    type: "object",
+    required: true,
+    schema: authPasswordCapabilitiesOutputSchema
+  },
+  passwordRecovery: {
+    type: "object",
+    required: true,
+    schema: authPasswordRecoveryCapabilitiesOutputSchema
+  },
+  otp: {
+    type: "object",
+    required: true,
+    schema: authOtpCapabilitiesOutputSchema
+  },
+  oauthLogin: {
+    type: "object",
+    required: true,
+    schema: authOAuthLoginCapabilitiesOutputSchema
+  },
+  emailConfirmation: { type: "boolean", required: true },
+  profileUpdate: { type: "boolean", required: true },
+  providerLinking: {
+    type: "object",
+    required: true,
+    schema: authProviderLinkingCapabilitiesOutputSchema
+  },
+  securityStatus: { type: "boolean", required: true },
+  signOutOtherSessions: { type: "boolean", required: true },
+  appProfileProjection: { type: "boolean", required: true },
+  devLoginAs: { type: "boolean", required: true }
+});
+
+const authCapabilitiesOutputSchema = createSchema({
+  provider: {
+    type: "object",
+    required: true,
+    schema: authCapabilityProviderOutputSchema
+  },
+  features: {
+    type: "object",
+    required: true,
+    schema: authCapabilitiesFeaturesOutputSchema
+  }
+});
+
 const sessionOutputSchema = createSchema({
   authenticated: { type: "boolean", required: true },
   username: { type: "string", required: false, minLength: 1, maxLength: 120 },
@@ -248,6 +352,11 @@ const sessionOutputSchema = createSchema({
     required: false,
     schema: authDeniedOutputSchema
   },
+  authCapabilities: {
+    type: "object",
+    required: true,
+    schema: authCapabilitiesOutputSchema
+  },
   csrfToken: { type: "string", required: true, minLength: 1 },
   oauthProviders: {
     type: "array",
@@ -269,6 +378,11 @@ const sessionOutputValidator = deepFreeze({
 const sessionUnavailableOutputSchema = createSchema({
   error: { type: "string", required: true, minLength: 1 },
   csrfToken: { type: "string", required: true, minLength: 1 },
+  authCapabilities: {
+    type: "object",
+    required: true,
+    schema: authCapabilitiesOutputSchema
+  },
   oauthProviders: {
     type: "array",
     required: true,
@@ -333,6 +447,7 @@ export {
   logoutOutputValidator,
   oauthProviderCatalogEntryOutputValidator,
   authDeniedOutputSchema,
+  authCapabilitiesOutputSchema,
   sessionOutputValidator,
   sessionUnavailableOutputValidator,
   createCommandMessages

package/src/shared/index.js

@@ -8,3 +8,15 @@ export {
   resolveAuthDeniedLoginMessage
 } from "./authDenied.js";
 export { AUTH_PATHS, buildAuthOauthStartPath } from "./authPaths.js";
+export {
+  AUTH_PASSWORD_RECOVERY_DELIVERIES,
+  AUTH_OPTIONAL_OPERATION_FEATURES,
+  normalizeAuthProviderId,
+  normalizeAuthCapabilities,
+  getCapabilityFeature,
+  isAuthOperationSupported
+} from "./authCapabilities.js";
+export {
+  normalizeAuthSecurityStatus,
+  buildSecurityStatusFromAuthMethodsStatus
+} from "./authSecurityStatus.js";

package/test/authActions.test.js

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createApplication } from "@jskit-ai/kernel/_testable";
+import { ActionRuntimeServiceProvider } from "@jskit-ai/kernel/server/actions";
+import { AuthActionsServiceProvider } from "../src/server/providers/AuthActionsServiceProvider.js";
+import { buildAuthActions } from "../src/server/actions/auth.contributor.js";
+
+function createAppConfigFixture() {
+  return {
+    surfaceModeAll: "all",
+    surfaceDefaultId: "home",
+    surfaceDefinitions: {
+      home: { id: "home", pagesRoot: "", enabled: true, requiresAuth: false, requiresWorkspace: false },
+      console: {
+        id: "console",
+        pagesRoot: "console",
+        enabled: true,
+        requiresAuth: true,
+        requiresWorkspace: false
+      }
+    }
+  };
+}
+
+test("auth logout action delegates to selected auth provider and notifies session changes", async () => {
+  const action = buildAuthActions().find((definition) => definition.id === "auth.logout");
+  const request = {
+    id: "request-1"
+  };
+  const calls = [];
+
+  const result = await action.execute(
+    {},
+    {
+      requestMeta: {
+        request
+      }
+    },
+    {
+      authService: {
+        async logout(receivedRequest) {
+          calls.push({
+            type: "logout",
+            request: receivedRequest
+          });
+          return {
+            ok: true,
+            clearSession: true
+          };
+        }
+      },
+      authSessionEventsService: {
+        async notifySessionChanged(payload) {
+          calls.push({
+            type: "notify",
+            context: payload.context
+          });
+        }
+      }
+    }
+  );
+
+  assert.deepEqual(result, {
+    ok: true,
+    clearSession: true
+  });
+  assert.deepEqual(calls, [
+    {
+      type: "logout",
+      request
+    },
+    {
+      type: "notify",
+      context: {
+        requestMeta: {
+          request
+        }
+      }
+    }
+  ]);
+});
+
+test("AuthActionsServiceProvider registers shared auth actions against auth.provider", async () => {
+  const app = createApplication();
+  const logoutCalls = [];
+  const published = [];
+  class SelectedAuthProvider {
+    static id = "auth.provider";
+
+    register(targetApp) {
+      targetApp.singleton("authService", () => ({
+        async logout(request) {
+          logoutCalls.push(request);
+          return {
+            ok: true,
+            clearSession: true
+          };
+        },
+        async authenticateRequest() {
+          return {
+            authenticated: false,
+            actor: null,
+            transientFailure: false
+          };
+        }
+      }));
+    }
+  }
+
+  app.instance("appConfig", createAppConfigFixture());
+  app.instance("domainEvents", {
+    async publish(payload) {
+      published.push(payload);
+    }
+  });
+
+  await app.start({
+    providers: [ActionRuntimeServiceProvider, SelectedAuthProvider, AuthActionsServiceProvider]
+  });
+
+  const actionExecutor = app.make("actionExecutor");
+  const definitions = actionExecutor.listDefinitions();
+  assert.equal(definitions.some((definition) => definition.id === "auth.login.password"), true);
+  assert.equal(definitions.some((definition) => definition.id === "auth.register"), true);
+  assert.equal(definitions.some((definition) => definition.id === "auth.dev.loginAs"), false);
+  assert.deepEqual(definitions.find((definition) => definition.id === "auth.session.read")?.surfaces, [
+    "home",
+    "console"
+  ]);
+
+  const request = { id: "request-2" };
+  const result = await actionExecutor.execute({
+    actionId: "auth.logout",
+    input: {},
+    context: {
+      channel: "internal",
+      surface: "home",
+      requestMeta: { request },
+      actor: { id: 42 }
+    }
+  });
+
+  assert.deepEqual(result, {
+    ok: true,
+    clearSession: true
+  });
+  assert.deepEqual(logoutCalls, [request]);
+  assert.equal(published.length, 2);
+  assert.deepEqual(
+    published.map((event) => ({
+      source: event.source,
+      entity: event.entity,
+      operation: event.operation,
+      entityId: event.entityId,
+      realtimeEvent: event.meta?.realtime?.event
+    })),
+    [
+      {
+        source: "auth",
+        entity: "session",
+        operation: "updated",
+        entityId: "42",
+        realtimeEvent: "auth.session.changed"
+      },
+      {
+        source: "users",
+        entity: "bootstrap",
+        operation: "updated",
+        entityId: "42",
+        realtimeEvent: "users.bootstrap.changed"
+      }
+    ]
+  );
+});