@jskit-ai/auth-core 0.1.4

package/src/server/lib/tokens.js

@@ -0,0 +1,3 @@
+const AUTH_POLICY_CONTEXT_RESOLVER_TOKEN = "auth.policy.contextResolver";
+
+export { AUTH_POLICY_CONTEXT_RESOLVER_TOKEN };

package/src/server/membershipAccess.js

@@ -0,0 +1,67 @@
+function resolveMembershipRoleId(membershipLike) {
+  return String(membershipLike?.roleId || "").trim();
+}
+
+function resolveMembershipStatus(membershipLike) {
+  return String(membershipLike?.status || membershipLike?.membershipStatus || "active").trim() || "active";
+}
+
+function normalizeMembershipForAccess(membershipLike) {
+  const roleId = resolveMembershipRoleId(membershipLike);
+  if (!roleId) {
+    return null;
+  }
+
+  const status = resolveMembershipStatus(membershipLike);
+  if (status !== "active") {
+    return null;
+  }
+
+  return {
+    roleId,
+    status
+  };
+}
+
+function mapMembershipSummary(membershipLike) {
+  return normalizeMembershipForAccess(membershipLike);
+}
+
+function normalizePermissions(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return Array.from(new Set(value.map((permission) => String(permission || "").trim()).filter(Boolean)));
+}
+
+function createMembershipIndexes(memberships) {
+  const byId = new Map();
+  const bySlug = new Map();
+
+  for (const membership of memberships) {
+    const workspaceId = Number(membership?.id);
+    const workspaceSlug = String(membership?.slug || "").trim();
+
+    if (Number.isInteger(workspaceId) && workspaceId > 0) {
+      byId.set(workspaceId, membership);
+    }
+    if (workspaceSlug) {
+      bySlug.set(workspaceSlug, membership);
+    }
+  }
+
+  return {
+    byId,
+    bySlug
+  };
+}
+
+export {
+  resolveMembershipRoleId,
+  resolveMembershipStatus,
+  normalizeMembershipForAccess,
+  mapMembershipSummary,
+  normalizePermissions,
+  createMembershipIndexes
+};

package/src/server/providers/AccessCoreServiceProvider.js

@@ -0,0 +1,35 @@
+import * as authConstraints from "../../shared/authConstraints.js";
+import * as authMethods from "../../shared/authMethods.js";
+import * as oauthProviders from "../../shared/oauthProviders.js";
+import * as oauthCallbackParams from "../../shared/oauthCallbackParams.js";
+import * as membershipAccess from "../membershipAccess.js";
+import * as inviteTokens from "../inviteTokens.js";
+import * as utils from "../utils.js";
+import * as validators from "../validators.js";
+
+const ACCESS_CORE_API = Object.freeze({
+  authConstraints,
+  authMethods,
+  oauthProviders,
+  oauthCallbackParams,
+  membershipAccess,
+  inviteTokens,
+  utils,
+  validators
+});
+
+class AccessCoreServiceProvider {
+  static id = "auth.access";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("AccessCoreServiceProvider requires application singleton().");
+    }
+
+    app.singleton("auth.access", () => ACCESS_CORE_API);
+  }
+
+  boot() {}
+}
+
+export { AccessCoreServiceProvider };

package/src/server/providers/FastifyAuthPolicyServiceProvider.js

@@ -0,0 +1,124 @@
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { registerActionContextContributor } from "@jskit-ai/kernel/server/actions";
+import { registerRouteVisibilityResolver } from "@jskit-ai/kernel/server/http";
+import { authPolicyPlugin } from "../lib/plugin.js";
+import { AUTH_POLICY_CONTEXT_RESOLVER_TOKEN } from "../lib/tokens.js";
+import { createAuthActionContextContributor } from "../lib/actionContextContributor.js";
+import { createAuthRouteVisibilityResolver } from "../lib/routeVisibilityResolver.js";
+
+const AUTH_ACTION_CONTEXT_CONTRIBUTOR_TOKEN = "auth.policy.actionContextContributor";
+const AUTH_ROUTE_VISIBILITY_RESOLVER_TOKEN = "auth.policy.routeVisibilityResolver";
+
+function parseBoolean(value, fallback = false) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw) {
+    return fallback;
+  }
+  if (["1", "true", "yes", "on"].includes(raw)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(raw)) {
+    return false;
+  }
+  return fallback;
+}
+
+function parseList(value) {
+  return String(value || "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function defaultHasPermission({ permission, permissions = [] } = {}) {
+  if (!permission) {
+    return true;
+  }
+  return Array.isArray(permissions) ? permissions.includes(permission) : false;
+}
+
+class FastifyAuthPolicyServiceProvider {
+  static id = "auth.policy.fastify";
+
+  static dependsOn = ["auth.provider"];
+
+  register(app) {
+    if (!app || typeof app.has !== "function") {
+      throw new Error("FastifyAuthPolicyServiceProvider requires application has().");
+    }
+
+    if (
+      !app.has(AUTH_ACTION_CONTEXT_CONTRIBUTOR_TOKEN) &&
+      typeof app.singleton === "function" &&
+      typeof app.tag === "function"
+    ) {
+      registerActionContextContributor(app, AUTH_ACTION_CONTEXT_CONTRIBUTOR_TOKEN, () =>
+        createAuthActionContextContributor()
+      );
+    }
+
+    if (
+      !app.has(AUTH_ROUTE_VISIBILITY_RESOLVER_TOKEN) &&
+      typeof app.singleton === "function" &&
+      typeof app.tag === "function"
+    ) {
+      registerRouteVisibilityResolver(app, AUTH_ROUTE_VISIBILITY_RESOLVER_TOKEN, () =>
+        createAuthRouteVisibilityResolver()
+      );
+    }
+  }
+
+  async boot(app) {
+    if (!app || typeof app.make !== "function" || typeof app.has !== "function") {
+      throw new Error("FastifyAuthPolicyServiceProvider requires application make()/has().");
+    }
+    if (!app.has("authService")) {
+      throw new Error("FastifyAuthPolicyServiceProvider requires authService binding.");
+    }
+
+    const env = app.has(KERNEL_TOKENS.Env) ? app.make(KERNEL_TOKENS.Env) : {};
+    const fastify = app.make(KERNEL_TOKENS.Fastify);
+    const authService = app.make("authService");
+    const resolveContext =
+      typeof app.has === "function" && app.has(AUTH_POLICY_CONTEXT_RESOLVER_TOKEN)
+        ? app.make(AUTH_POLICY_CONTEXT_RESOLVER_TOKEN)
+        : null;
+
+    if (resolveContext != null && typeof resolveContext !== "function") {
+      throw new Error(
+        `FastifyAuthPolicyServiceProvider requires ${AUTH_POLICY_CONTEXT_RESOLVER_TOKEN} to be a function when provided.`
+      );
+    }
+
+    const pluginDeps = {
+      resolveActor: async (request) => {
+        if (authService && typeof authService.authenticateRequest === "function") {
+          return authService.authenticateRequest(request);
+        }
+        return {
+          authenticated: false,
+          actor: null,
+          transientFailure: false
+        };
+      },
+      hasPermission: defaultHasPermission,
+      ...(typeof resolveContext === "function" ? { resolveContext } : {})
+    };
+
+    const plugin = authPolicyPlugin(
+      pluginDeps,
+      {
+        nodeEnv: String(env.NODE_ENV || "development").trim() || "development",
+        apiPrefix: String(env.AUTH_API_PREFIX || "/api/").trim() || "/api/",
+        unsafeMethods: parseList(env.AUTH_CSRF_UNSAFE_METHODS),
+        csrfCookieOpts: {
+          secure: parseBoolean(env.AUTH_CSRF_COOKIE_SECURE, false)
+        }
+      }
+    );
+
+    await plugin(fastify);
+  }
+}
+
+export { FastifyAuthPolicyServiceProvider };

package/src/server/utils.js

@@ -0,0 +1,26 @@
+import { normalizeReturnToPath as normalizeSharedReturnToPath } from "@jskit-ai/kernel/shared/support";
+
+export function normalizeEmail(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase();
+}
+
+export function normalizeOAuthIntent(value, { fallback = "login" } = {}) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+
+  if (normalized === "login" || normalized === "link") {
+    return normalized;
+  }
+
+  return fallback;
+}
+
+export function normalizeReturnToPath(value, { fallback = "/", allowedOrigins = [] } = {}) {
+  return normalizeSharedReturnToPath(value, {
+    fallback,
+    allowedOrigins
+  });
+}

package/src/server/validators.js

@@ -0,0 +1,183 @@
+import {
+  AUTH_EMAIL_MAX_LENGTH,
+  AUTH_EMAIL_REGEX,
+  AUTH_LOGIN_PASSWORD_MAX_LENGTH,
+  AUTH_PASSWORD_MAX_LENGTH,
+  AUTH_PASSWORD_MIN_LENGTH
+} from "../shared/authConstraints.js";
+import { normalizeEmail } from "./utils.js";
+
+function validateEmail(rawEmail) {
+  const email = normalizeEmail(rawEmail);
+
+  if (!email) {
+    return {
+      email,
+      error: "Email is required."
+    };
+  }
+
+  if (email.length > AUTH_EMAIL_MAX_LENGTH || !AUTH_EMAIL_REGEX.test(email)) {
+    return {
+      email,
+      error: "Provide a valid email address."
+    };
+  }
+
+  return {
+    email,
+    error: ""
+  };
+}
+
+function registerPassword(rawPassword) {
+  const password = String(rawPassword || "");
+  if (!password) {
+    return {
+      password,
+      error: "Password is required."
+    };
+  }
+
+  if (password.length < AUTH_PASSWORD_MIN_LENGTH || password.length > AUTH_PASSWORD_MAX_LENGTH) {
+    return {
+      password,
+      error: "Password must be between 8 and 128 characters."
+    };
+  }
+
+  return {
+    password,
+    error: ""
+  };
+}
+
+function loginPassword(rawPassword) {
+  const password = String(rawPassword || "");
+  if (!password) {
+    return {
+      password,
+      error: "Password is required."
+    };
+  }
+
+  if (password.length > AUTH_LOGIN_PASSWORD_MAX_LENGTH) {
+    return {
+      password,
+      error: `Password must be at most ${AUTH_LOGIN_PASSWORD_MAX_LENGTH} characters.`
+    };
+  }
+
+  return {
+    password,
+    error: ""
+  };
+}
+
+function confirmPassword(rawPassword, rawConfirmPassword) {
+  const password = String(rawPassword || "");
+  const confirmPassword = String(rawConfirmPassword || "");
+
+  if (!confirmPassword) {
+    return "Confirm your password.";
+  }
+
+  if (password !== confirmPassword) {
+    return "Passwords do not match.";
+  }
+
+  return "";
+}
+
+function resetPassword(rawPassword) {
+  return registerPassword(rawPassword);
+}
+
+function registerInput(payload = {}) {
+  const emailCheck = validateEmail(payload.email);
+  const passwordCheck = registerPassword(payload.password);
+  const fieldErrors = {};
+
+  if (emailCheck.error) {
+    fieldErrors.email = emailCheck.error;
+  }
+  if (passwordCheck.error) {
+    fieldErrors.password = passwordCheck.error;
+  }
+
+  return {
+    email: emailCheck.email,
+    password: passwordCheck.password,
+    fieldErrors
+  };
+}
+
+function loginInput(payload = {}) {
+  const emailCheck = validateEmail(payload.email);
+  const passwordCheck = loginPassword(payload.password);
+  const fieldErrors = {};
+
+  if (emailCheck.error) {
+    fieldErrors.email = emailCheck.error;
+  }
+  if (passwordCheck.error) {
+    fieldErrors.password = passwordCheck.error;
+  }
+
+  return {
+    email: emailCheck.email,
+    password: passwordCheck.password,
+    fieldErrors
+  };
+}
+
+function forgotPasswordInput(payload = {}) {
+  const emailCheck = validateEmail(payload.email);
+  const fieldErrors = {};
+
+  if (emailCheck.error) {
+    fieldErrors.email = emailCheck.error;
+  }
+
+  return {
+    email: emailCheck.email,
+    fieldErrors
+  };
+}
+
+function resetPasswordInput(payload = {}) {
+  const passwordCheck = resetPassword(payload.password);
+  const fieldErrors = {};
+
+  if (passwordCheck.error) {
+    fieldErrors.password = passwordCheck.error;
+  }
+
+  return {
+    password: passwordCheck.password,
+    fieldErrors
+  };
+}
+
+export const validators = {
+  email: (rawEmail) => validateEmail(rawEmail).error,
+  registerPassword: (rawPassword) => registerPassword(rawPassword).error,
+  loginPassword: (rawPassword) => loginPassword(rawPassword).error,
+  resetPassword: (rawPassword) => resetPassword(rawPassword).error,
+  confirmPassword: ({ password, confirmPassword: confirmPasswordValue }) => confirmPassword(password, confirmPasswordValue),
+  registerInput,
+  loginInput,
+  forgotPasswordInput,
+  resetPasswordInput
+};
+
+export {
+  confirmPassword,
+  forgotPasswordInput,
+  loginInput,
+  loginPassword,
+  registerInput,
+  registerPassword,
+  resetPassword,
+  resetPasswordInput
+};

package/src/shared/authApi.js

@@ -0,0 +1,50 @@
+import { AUTH_PATHS, buildAuthOauthStartPath } from "./authPaths.js";
+
+function createApi({ request }) {
+  return {
+    session() {
+      return request(AUTH_PATHS.SESSION);
+    },
+    register(payload) {
+      return request(AUTH_PATHS.REGISTER, { method: "POST", body: payload });
+    },
+    login(payload) {
+      return request(AUTH_PATHS.LOGIN, { method: "POST", body: payload });
+    },
+    requestOtp(payload) {
+      return request(AUTH_PATHS.LOGIN_OTP_REQUEST, { method: "POST", body: payload });
+    },
+    verifyOtp(payload) {
+      return request(AUTH_PATHS.LOGIN_OTP_VERIFY, { method: "POST", body: payload });
+    },
+    oauthStartUrl(provider, options = {}) {
+      const oauthStartPath = buildAuthOauthStartPath(provider);
+      const returnTo = String(options.returnTo || "").trim();
+      if (!returnTo) {
+        return oauthStartPath;
+      }
+
+      const params = new URLSearchParams({
+        returnTo
+      });
+      return `${oauthStartPath}?${params.toString()}`;
+    },
+    oauthComplete(payload) {
+      return request(AUTH_PATHS.OAUTH_COMPLETE, { method: "POST", body: payload });
+    },
+    requestPasswordReset(payload) {
+      return request(AUTH_PATHS.PASSWORD_FORGOT, { method: "POST", body: payload });
+    },
+    completePasswordRecovery(payload) {
+      return request(AUTH_PATHS.PASSWORD_RECOVERY, { method: "POST", body: payload });
+    },
+    resetPassword(payload) {
+      return request(AUTH_PATHS.PASSWORD_RESET, { method: "POST", body: payload });
+    },
+    logout() {
+      return request(AUTH_PATHS.LOGOUT, { method: "POST" });
+    }
+  };
+}
+
+export { createApi };

package/src/shared/authConstraints.js

@@ -0,0 +1,13 @@
+export const AUTH_EMAIL_PATTERN = "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$";
+export const AUTH_EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export const AUTH_EMAIL_MIN_LENGTH = 3;
+export const AUTH_EMAIL_MAX_LENGTH = 320;
+
+export const AUTH_PASSWORD_MIN_LENGTH = 8;
+export const AUTH_PASSWORD_MAX_LENGTH = 128;
+export const AUTH_LOGIN_PASSWORD_MAX_LENGTH = 1024;
+
+export const AUTH_RECOVERY_TOKEN_MAX_LENGTH = 4096;
+export const AUTH_ACCESS_TOKEN_MAX_LENGTH = 8192;
+export const AUTH_REFRESH_TOKEN_MAX_LENGTH = 8192;

package/src/shared/authMethods.js

@@ -0,0 +1,170 @@
+import { normalizeOAuthProviderId } from "./oauthProviders.js";
+
+const AUTH_METHOD_PASSWORD_ID = "password";
+const AUTH_METHOD_PASSWORD_PROVIDER = "email";
+const AUTH_METHOD_EMAIL_OTP_ID = "email_otp";
+const AUTH_METHOD_EMAIL_OTP_PROVIDER = "email";
+
+const AUTH_METHOD_KIND_PASSWORD = "password";
+const AUTH_METHOD_KIND_OTP = "otp";
+const AUTH_METHOD_KIND_OAUTH = "oauth";
+const AUTH_METHOD_KINDS = Object.freeze([AUTH_METHOD_KIND_PASSWORD, AUTH_METHOD_KIND_OTP, AUTH_METHOD_KIND_OAUTH]);
+
+const AUTH_METHOD_MINIMUM_ENABLED = 1;
+
+const AUTH_METHOD_DEFINITIONS = Object.freeze([
+  Object.freeze({
+    id: AUTH_METHOD_PASSWORD_ID,
+    kind: AUTH_METHOD_KIND_PASSWORD,
+    provider: AUTH_METHOD_PASSWORD_PROVIDER,
+    label: "Password",
+    supportsSecretUpdate: true
+  }),
+  Object.freeze({
+    id: AUTH_METHOD_EMAIL_OTP_ID,
+    kind: AUTH_METHOD_KIND_OTP,
+    provider: AUTH_METHOD_EMAIL_OTP_PROVIDER,
+    label: "Email one-time code",
+    supportsSecretUpdate: false
+  })
+]);
+
+const AUTH_METHOD_IDS = Object.freeze(AUTH_METHOD_DEFINITIONS.map((definition) => definition.id));
+
+function buildOAuthMethodId(providerId) {
+  const normalizedProviderId = normalizeOAuthProviderId(providerId, { fallback: null });
+  if (!normalizedProviderId) {
+    return null;
+  }
+
+  return `oauth:${normalizedProviderId}`;
+}
+
+function parseAuthMethodId(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+
+  if (normalized === AUTH_METHOD_PASSWORD_ID) {
+    return {
+      id: AUTH_METHOD_PASSWORD_ID,
+      kind: AUTH_METHOD_KIND_PASSWORD,
+      provider: AUTH_METHOD_PASSWORD_PROVIDER
+    };
+  }
+
+  if (normalized === AUTH_METHOD_EMAIL_OTP_ID) {
+    return {
+      id: AUTH_METHOD_EMAIL_OTP_ID,
+      kind: AUTH_METHOD_KIND_OTP,
+      provider: AUTH_METHOD_EMAIL_OTP_PROVIDER
+    };
+  }
+
+  if (normalized.startsWith("oauth:")) {
+    const providerId = normalizeOAuthProviderId(normalized.slice("oauth:".length), {
+      fallback: null
+    });
+    if (!providerId) {
+      return null;
+    }
+
+    return {
+      id: buildOAuthMethodId(providerId),
+      kind: AUTH_METHOD_KIND_OAUTH,
+      provider: providerId
+    };
+  }
+
+  return null;
+}
+
+function normalizeOAuthMethodDefinitionInput(entry) {
+  if (typeof entry === "string") {
+    const providerId = normalizeOAuthProviderId(entry, { fallback: null });
+    if (!providerId) {
+      return null;
+    }
+
+    return {
+      id: providerId,
+      label: providerId
+    };
+  }
+
+  if (!entry || typeof entry !== "object") {
+    return null;
+  }
+
+  const providerId = normalizeOAuthProviderId(entry.id, { fallback: null });
+  if (!providerId) {
+    return null;
+  }
+
+  const label = String(entry.label || providerId).trim() || providerId;
+  return {
+    id: providerId,
+    label
+  };
+}
+
+function buildOAuthMethodDefinitions(oauthProviders = []) {
+  const definitions = [];
+
+  for (const rawProvider of Array.isArray(oauthProviders) ? oauthProviders : []) {
+    const normalized = normalizeOAuthMethodDefinitionInput(rawProvider);
+    if (!normalized || definitions.some((definition) => definition.provider === normalized.id)) {
+      continue;
+    }
+
+    definitions.push(
+      Object.freeze({
+        id: buildOAuthMethodId(normalized.id),
+        kind: AUTH_METHOD_KIND_OAUTH,
+        provider: normalized.id,
+        label: normalized.label,
+        supportsSecretUpdate: false
+      })
+    );
+  }
+
+  return Object.freeze(definitions);
+}
+
+function buildAuthMethodDefinitions({ oauthProviders = [] } = {}) {
+  return Object.freeze([...AUTH_METHOD_DEFINITIONS, ...buildOAuthMethodDefinitions(oauthProviders)]);
+}
+
+function buildAuthMethodIds(options = {}) {
+  return Object.freeze(buildAuthMethodDefinitions(options).map((definition) => definition.id));
+}
+
+function findAuthMethodDefinition(methodId, options = {}) {
+  const normalized = parseAuthMethodId(methodId);
+  if (!normalized) {
+    return null;
+  }
+
+  const found = buildAuthMethodDefinitions(options).find((definition) => definition.id === normalized.id);
+  return found || null;
+}
+
+export {
+  AUTH_METHOD_PASSWORD_ID,
+  AUTH_METHOD_PASSWORD_PROVIDER,
+  AUTH_METHOD_EMAIL_OTP_ID,
+  AUTH_METHOD_EMAIL_OTP_PROVIDER,
+  AUTH_METHOD_KIND_PASSWORD,
+  AUTH_METHOD_KIND_OTP,
+  AUTH_METHOD_KIND_OAUTH,
+  AUTH_METHOD_KINDS,
+  AUTH_METHOD_MINIMUM_ENABLED,
+  AUTH_METHOD_DEFINITIONS,
+  AUTH_METHOD_IDS,
+  buildOAuthMethodId,
+  parseAuthMethodId,
+  buildOAuthMethodDefinitions,
+  buildAuthMethodDefinitions,
+  buildAuthMethodIds,
+  findAuthMethodDefinition
+};

package/src/shared/authPaths.js

@@ -0,0 +1,24 @@
+const AUTH_PATHS = Object.freeze({
+  REGISTER: "/api/register",
+  LOGIN: "/api/login",
+  LOGIN_OTP_REQUEST: "/api/login/otp/request",
+  LOGIN_OTP_VERIFY: "/api/login/otp/verify",
+  OAUTH_START_TEMPLATE: "/api/oauth/:provider/start",
+  OAUTH_COMPLETE: "/api/oauth/complete",
+  PASSWORD_FORGOT: "/api/password/forgot",
+  PASSWORD_RECOVERY: "/api/password/recovery",
+  PASSWORD_RESET: "/api/password/reset",
+  LOGOUT: "/api/logout",
+  SESSION: "/api/session"
+});
+
+function buildAuthOauthStartPath(provider) {
+  const providerId = encodeURIComponent(
+    String(provider || "")
+      .trim()
+      .toLowerCase()
+  );
+  return AUTH_PATHS.OAUTH_START_TEMPLATE.replace(":provider", providerId);
+}
+
+export { AUTH_PATHS, buildAuthOauthStartPath };