@jskit-ai/auth-core 0.1.4

package/src/shared/commands/authPasswordResetCommand.js

@@ -0,0 +1,49 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "../inputNormalization.js";
+import {
+  authPasswordValidator,
+  createCommandMessages,
+  okMessageResponseValidator
+} from "./authCommandValidators.js";
+
+const AUTH_PASSWORD_RESET_MESSAGES = createCommandMessages({
+  fields: {
+    password: {
+      required: "Password is required.",
+      minLength: "Password must be at least 8 characters.",
+      default: "Password must be at least 8 characters."
+    }
+  }
+});
+
+const authPasswordResetBodyValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      password: authPasswordValidator.schema
+    },
+    {
+      additionalProperties: false
+    }
+  ),
+  normalize: normalizeObjectInput,
+  messages: AUTH_PASSWORD_RESET_MESSAGES
+});
+
+const authPasswordResetCommand = Object.freeze({
+  command: "auth.password.reset",
+  operation: Object.freeze({
+    method: "POST",
+    bodyValidator: authPasswordResetBodyValidator,
+    responseValidator: okMessageResponseValidator,
+    messages: AUTH_PASSWORD_RESET_MESSAGES,
+    idempotent: false,
+    invalidates: Object.freeze(["auth.session.read"])
+  })
+});
+
+export {
+  authPasswordResetBodyValidator,
+  okMessageResponseValidator,
+  AUTH_PASSWORD_RESET_MESSAGES,
+  authPasswordResetCommand
+};

package/src/shared/commands/authPasswordResetRequestCommand.js

@@ -0,0 +1,50 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "../inputNormalization.js";
+import {
+  authEmailValidator,
+  createCommandMessages,
+  okMessageResponseValidator
+} from "./authCommandValidators.js";
+
+const AUTH_PASSWORD_RESET_REQUEST_MESSAGES = createCommandMessages({
+  fields: {
+    email: {
+      required: "Email is required.",
+      minLength: "Email is required.",
+      pattern: "Enter a valid email address.",
+      default: "Enter a valid email address."
+    }
+  }
+});
+
+const authPasswordResetRequestBodyValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      email: authEmailValidator.schema
+    },
+    {
+      additionalProperties: false
+    }
+  ),
+  normalize: normalizeObjectInput,
+  messages: AUTH_PASSWORD_RESET_REQUEST_MESSAGES
+});
+
+const authPasswordResetRequestCommand = Object.freeze({
+  command: "auth.password.reset.request",
+  operation: Object.freeze({
+    method: "POST",
+    bodyValidator: authPasswordResetRequestBodyValidator,
+    responseValidator: okMessageResponseValidator,
+    messages: AUTH_PASSWORD_RESET_REQUEST_MESSAGES,
+    idempotent: false,
+    invalidates: Object.freeze([])
+  })
+});
+
+export {
+  authPasswordResetRequestBodyValidator,
+  okMessageResponseValidator,
+  AUTH_PASSWORD_RESET_REQUEST_MESSAGES,
+  authPasswordResetRequestCommand
+};

package/src/shared/commands/authRegisterCommand.js

@@ -0,0 +1,57 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "../inputNormalization.js";
+import {
+  authEmailValidator,
+  authPasswordValidator,
+  createCommandMessages,
+  registerResponseValidator
+} from "./authCommandValidators.js";
+
+const AUTH_REGISTER_MESSAGES = createCommandMessages({
+  fields: {
+    email: {
+      required: "Email is required.",
+      minLength: "Email is required.",
+      pattern: "Enter a valid email address.",
+      default: "Enter a valid email address."
+    },
+    password: {
+      required: "Password is required.",
+      minLength: "Password must be at least 8 characters.",
+      default: "Password must be at least 8 characters."
+    }
+  }
+});
+
+const authRegisterBodyValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      email: authEmailValidator.schema,
+      password: authPasswordValidator.schema
+    },
+    {
+      additionalProperties: false
+    }
+  ),
+  normalize: normalizeObjectInput,
+  messages: AUTH_REGISTER_MESSAGES
+});
+
+const authRegisterCommand = Object.freeze({
+  command: "auth.register",
+  operation: Object.freeze({
+    method: "POST",
+    bodyValidator: authRegisterBodyValidator,
+    responseValidator: registerResponseValidator,
+    messages: AUTH_REGISTER_MESSAGES,
+    idempotent: false,
+    invalidates: Object.freeze(["auth.session.read"])
+  })
+});
+
+export {
+  authRegisterBodyValidator,
+  registerResponseValidator,
+  AUTH_REGISTER_MESSAGES,
+  authRegisterCommand
+};

package/src/shared/commands/authSessionReadCommand.js

@@ -0,0 +1,26 @@
+import {
+  createCommandMessages,
+  sessionResponseValidator,
+  sessionUnavailableResponseValidator
+} from "./authCommandValidators.js";
+
+const AUTH_SESSION_READ_MESSAGES = createCommandMessages();
+
+const authSessionReadCommand = Object.freeze({
+  command: "auth.session.read",
+  operation: Object.freeze({
+    method: "GET",
+    responseValidator: sessionResponseValidator,
+    unavailableResponseValidator: sessionUnavailableResponseValidator,
+    messages: AUTH_SESSION_READ_MESSAGES,
+    idempotent: true,
+    invalidates: Object.freeze([])
+  })
+});
+
+export {
+  sessionResponseValidator,
+  sessionUnavailableResponseValidator,
+  AUTH_SESSION_READ_MESSAGES,
+  authSessionReadCommand
+};

package/src/shared/index.js

@@ -0,0 +1,3 @@
+export { createApi } from "./authApi.js";
+export { runAuthSignOutFlow } from "./signOutFlow.js";
+export { AUTH_PATHS, buildAuthOauthStartPath } from "./authPaths.js";

package/src/shared/inputNormalization.js

@@ -0,0 +1 @@
+export { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";

package/src/shared/inviteTokens.js

@@ -0,0 +1,38 @@
+const OPAQUE_INVITE_TOKEN_HASH_PREFIX = "inviteh_";
+
+function normalizeInviteToken(token) {
+  return String(token || "").trim();
+}
+
+function isSha256Hex(value) {
+  return /^[a-f0-9]{64}$/i.test(String(value || "").trim());
+}
+
+function encodeInviteTokenHash(tokenHash) {
+  const normalizedTokenHash = String(tokenHash || "")
+    .trim()
+    .toLowerCase();
+  if (!isSha256Hex(normalizedTokenHash)) {
+    return "";
+  }
+
+  return `${OPAQUE_INVITE_TOKEN_HASH_PREFIX}${normalizedTokenHash}`;
+}
+
+function decodeInviteTokenHash(inviteToken) {
+  const normalizedToken = normalizeInviteToken(inviteToken);
+  if (!normalizedToken.startsWith(OPAQUE_INVITE_TOKEN_HASH_PREFIX)) {
+    return "";
+  }
+
+  const tokenHash = normalizedToken.slice(OPAQUE_INVITE_TOKEN_HASH_PREFIX.length).trim().toLowerCase();
+  return isSha256Hex(tokenHash) ? tokenHash : "";
+}
+
+export {
+  OPAQUE_INVITE_TOKEN_HASH_PREFIX,
+  normalizeInviteToken,
+  isSha256Hex,
+  encodeInviteTokenHash,
+  decodeInviteTokenHash
+};

package/src/shared/oauthCallbackParams.js

@@ -0,0 +1,5 @@
+const OAUTH_QUERY_PARAM_PROVIDER = "oauthProvider";
+const OAUTH_QUERY_PARAM_INTENT = "oauthIntent";
+const OAUTH_QUERY_PARAM_RETURN_TO = "oauthReturnTo";
+
+export { OAUTH_QUERY_PARAM_PROVIDER, OAUTH_QUERY_PARAM_INTENT, OAUTH_QUERY_PARAM_RETURN_TO };

package/src/shared/oauthProviders.js

@@ -0,0 +1,66 @@
+const OAUTH_PROVIDER_ID_PATTERN = "^[a-z0-9][a-z0-9_-]{1,31}$";
+const OAUTH_PROVIDER_ID_REGEX = new RegExp(OAUTH_PROVIDER_ID_PATTERN);
+
+function normalizeOAuthProviderId(value, { fallback = null } = {}) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+
+  if (OAUTH_PROVIDER_ID_REGEX.test(normalized)) {
+    return normalized;
+  }
+
+  const fallbackNormalized = String(fallback || "")
+    .trim()
+    .toLowerCase();
+  if (OAUTH_PROVIDER_ID_REGEX.test(fallbackNormalized)) {
+    return fallbackNormalized;
+  }
+
+  return null;
+}
+
+function isValidOAuthProviderId(value) {
+  return Boolean(normalizeOAuthProviderId(value, { fallback: null }));
+}
+
+function normalizeOAuthProviderList(value, { fallback = [] } = {}) {
+  const source = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? value.split(",")
+      : value == null
+        ? []
+        : [value];
+
+  const normalized = [];
+  for (const entry of source) {
+    const providerId = normalizeOAuthProviderId(entry, { fallback: null });
+    if (!providerId || normalized.includes(providerId)) {
+      continue;
+    }
+    normalized.push(providerId);
+  }
+
+  if (normalized.length > 0) {
+    return normalized;
+  }
+
+  if (!Array.isArray(fallback)) {
+    return [];
+  }
+
+  if (fallback.length < 1) {
+    return [];
+  }
+
+  return normalizeOAuthProviderList(fallback, { fallback: [] });
+}
+
+export {
+  OAUTH_PROVIDER_ID_PATTERN,
+  OAUTH_PROVIDER_ID_REGEX,
+  normalizeOAuthProviderId,
+  isValidOAuthProviderId,
+  normalizeOAuthProviderList
+};

package/src/shared/signOutFlow.js

@@ -0,0 +1,28 @@
+function normalizeAuthApi(authApi) {
+  if (!authApi || typeof authApi !== "object") {
+    throw new TypeError("runAuthSignOutFlow requires authApi.");
+  }
+  if (typeof authApi.logout !== "function") {
+    throw new TypeError("runAuthSignOutFlow requires authApi.logout().");
+  }
+  return authApi;
+}
+
+async function runAuthSignOutFlow({ authApi, clearCsrfTokenCache = null, afterSignOut = null } = {}) {
+  const normalizedAuthApi = normalizeAuthApi(authApi);
+  const clearFn = typeof clearCsrfTokenCache === "function" ? clearCsrfTokenCache : null;
+  const afterFn = typeof afterSignOut === "function" ? afterSignOut : null;
+
+  try {
+    await normalizedAuthApi.logout();
+  } finally {
+    if (clearFn) {
+      clearFn();
+    }
+    if (afterFn) {
+      await afterFn();
+    }
+  }
+}
+
+export { runAuthSignOutFlow };

package/test/actionContextContributor.test.js

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createAuthActionContextContributor } from "../src/server/lib/actionContextContributor.js";
+
+test("auth action context contributor skips empty placeholder values", () => {
+  const contributor = createAuthActionContextContributor();
+
+  const contribution = contributor.contribute({
+    request: {
+      user: null,
+      workspace: null,
+      membership: null,
+      permissions: []
+    }
+  });
+
+  assert.deepEqual(contribution, {});
+});
+
+test("auth action context contributor contributes real request context values", () => {
+  const contributor = createAuthActionContextContributor();
+
+  const request = {
+    user: {
+      id: 7
+    },
+    workspace: {
+      id: 11
+    },
+    membership: {
+      roleId: "owner"
+    },
+    permissions: ["workspace.settings.update", "", "  "]
+  };
+
+  const contribution = contributor.contribute({ request });
+
+  assert.deepEqual(contribution, {
+    actor: request.user,
+    workspace: request.workspace,
+    membership: request.membership,
+    permissions: ["workspace.settings.update"]
+  });
+});

package/test/authApi.test.js

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createApi } from "../src/client/authApi.js";
+
+test("authApi exposes the expected methods and request routes", async () => {
+  const calls = [];
+  const api = createApi({
+    request: async (url, options = {}) => {
+      calls.push({ url, options });
+      return { ok: true };
+    }
+  });
+
+  assert.deepEqual(Object.keys(api), [
+    "session",
+    "register",
+    "login",
+    "requestOtp",
+    "verifyOtp",
+    "oauthStartUrl",
+    "oauthComplete",
+    "requestPasswordReset",
+    "completePasswordRecovery",
+    "resetPassword",
+    "logout"
+  ]);
+
+  await api.session();
+  await api.login({ email: "x@example.com" });
+  await api.logout();
+
+  assert.equal(calls[0].url, "/api/session");
+  assert.equal(calls[1].url, "/api/login");
+  assert.equal(calls[1].options.method, "POST");
+  assert.equal(calls[2].url, "/api/logout");
+  assert.equal(calls[2].options.method, "POST");
+});
+
+test("authApi oauthStartUrl builds provider path with optional returnTo", () => {
+  const api = createApi({
+    request: async () => ({})
+  });
+
+  assert.equal(api.oauthStartUrl("GitHub"), "/api/oauth/github/start");
+  assert.equal(api.oauthStartUrl("github", { returnTo: "/console" }), "/api/oauth/github/start?returnTo=%2Fconsole");
+});

package/test/authMethods.test.js

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  AUTH_METHOD_IDS,
+  AUTH_METHOD_KINDS,
+  buildAuthMethodDefinitions,
+  buildAuthMethodIds,
+  buildOAuthMethodDefinitions,
+  buildOAuthMethodId,
+  findAuthMethodDefinition,
+  parseAuthMethodId
+} from "../src/shared/authMethods.js";
+import {
+  isValidOAuthProviderId,
+  normalizeOAuthProviderId,
+  normalizeOAuthProviderList
+} from "../src/shared/oauthProviders.js";
+
+test("oauth provider helpers normalize ids and lists", () => {
+  assert.equal(normalizeOAuthProviderId(" Google "), "google");
+  assert.equal(normalizeOAuthProviderId(""), null);
+  assert.equal(normalizeOAuthProviderId("x"), null);
+  assert.equal(normalizeOAuthProviderId("", { fallback: "github" }), "github");
+
+  assert.equal(isValidOAuthProviderId("github"), true);
+  assert.equal(isValidOAuthProviderId("bad provider"), false);
+
+  assert.deepEqual(normalizeOAuthProviderList([" google ", "github", "google", "bad provider"]), [
+    "google",
+    "github"
+  ]);
+  assert.deepEqual(normalizeOAuthProviderList("google, github, invalid provider"), ["google", "github"]);
+  assert.deepEqual(normalizeOAuthProviderList("", { fallback: ["google"] }), ["google"]);
+});
+
+test("auth method builders build provider-aware oauth method definitions", () => {
+  const oauthMethods = buildOAuthMethodDefinitions([
+    { id: "google", label: "Google" },
+    { id: "github", label: "GitHub" },
+    { id: "google", label: "Duplicate" },
+    { id: "bad provider", label: "Invalid" }
+  ]);
+
+  assert.deepEqual(
+    oauthMethods.map((method) => method.id),
+    ["oauth:google", "oauth:github"]
+  );
+
+  const methods = buildAuthMethodDefinitions({
+    oauthProviders: [
+      { id: "google", label: "Google" },
+      { id: "github", label: "GitHub" }
+    ]
+  });
+  assert.deepEqual(methods.map((method) => method.id), ["password", "email_otp", "oauth:google", "oauth:github"]);
+
+  const ids = buildAuthMethodIds({
+    oauthProviders: [
+      { id: "google", label: "Google" },
+      { id: "github", label: "GitHub" }
+    ]
+  });
+  assert.deepEqual(ids, ["password", "email_otp", "oauth:google", "oauth:github"]);
+});
+
+test("auth method helpers parse generic oauth ids while definition lookup remains catalog-based", () => {
+  assert.deepEqual(parseAuthMethodId("password"), {
+    id: "password",
+    kind: "password",
+    provider: "email"
+  });
+
+  assert.deepEqual(parseAuthMethodId("oauth:github"), {
+    id: "oauth:github",
+    kind: "oauth",
+    provider: "github"
+  });
+
+  assert.equal(parseAuthMethodId("oauth:bad provider"), null);
+  assert.equal(parseAuthMethodId("unknown"), null);
+
+  assert.equal(findAuthMethodDefinition("oauth:github"), null);
+  assert.equal(
+    findAuthMethodDefinition("oauth:github", {
+      oauthProviders: [{ id: "github", label: "GitHub" }]
+    })?.label,
+    "GitHub"
+  );
+
+  assert.deepEqual(AUTH_METHOD_IDS, ["password", "email_otp"]);
+  assert.deepEqual(AUTH_METHOD_KINDS, ["password", "otp", "oauth"]);
+  assert.equal(buildOAuthMethodId("google"), "oauth:google");
+  assert.equal(buildOAuthMethodId("x"), null);
+});

package/test/authPaths.test.js

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { AUTH_PATHS, buildAuthOauthStartPath } from "../src/shared/authPaths.js";
+
+test("AUTH_PATHS defines canonical auth endpoint paths", () => {
+  assert.equal(Object.isFrozen(AUTH_PATHS), true);
+  assert.equal(AUTH_PATHS.LOGIN, "/api/login");
+  assert.equal(AUTH_PATHS.LOGOUT, "/api/logout");
+  assert.equal(AUTH_PATHS.SESSION, "/api/session");
+  assert.equal(AUTH_PATHS.OAUTH_START_TEMPLATE, "/api/oauth/:provider/start");
+});
+
+test("buildAuthOauthStartPath normalizes and encodes provider id", () => {
+  assert.equal(buildAuthOauthStartPath("GitHub"), "/api/oauth/github/start");
+  assert.equal(buildAuthOauthStartPath("Git Hub"), "/api/oauth/git%20hub/start");
+});

package/test/commandValidators.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { authRegisterCommand } from "../src/shared/commands/authRegisterCommand.js";
+import { authLoginPasswordCommand } from "../src/shared/commands/authLoginPasswordCommand.js";
+import { authLoginOtpRequestCommand } from "../src/shared/commands/authLoginOtpRequestCommand.js";
+import { authLoginOtpVerifyCommand } from "../src/shared/commands/authLoginOtpVerifyCommand.js";
+import { authLoginOAuthStartCommand } from "../src/shared/commands/authLoginOAuthStartCommand.js";
+import { authLoginOAuthCompleteCommand } from "../src/shared/commands/authLoginOAuthCompleteCommand.js";
+import { authPasswordResetRequestCommand } from "../src/shared/commands/authPasswordResetRequestCommand.js";
+import { authPasswordRecoveryCompleteCommand } from "../src/shared/commands/authPasswordRecoveryCompleteCommand.js";
+import { authPasswordResetCommand } from "../src/shared/commands/authPasswordResetCommand.js";
+import { authLogoutCommand } from "../src/shared/commands/authLogoutCommand.js";
+import { authSessionReadCommand } from "../src/shared/commands/authSessionReadCommand.js";
+
+test("auth commands expose canonical operation validator messages", () => {
+  const commands = {
+    authRegisterCommand,
+    authLoginPasswordCommand,
+    authLoginOtpRequestCommand,
+    authLoginOtpVerifyCommand,
+    authLoginOAuthStartCommand,
+    authLoginOAuthCompleteCommand,
+    authPasswordResetRequestCommand,
+    authPasswordRecoveryCompleteCommand,
+    authPasswordResetCommand,
+    authLogoutCommand,
+    authSessionReadCommand
+  };
+
+  for (const [label, command] of Object.entries(commands)) {
+    assert.equal(typeof command.operation?.messages, "object", `${label}.operation.messages must be an object.`);
+  }
+});