@elench/testkit 0.1.81 → 0.1.83

package/lib/config-api/auth-fixtures.mjs

@@ -0,0 +1,767 @@
+import { runtimeHttp, runtimeJson } from "./runtime.mjs";
+
+const DEFAULT_PASSWORD = "TestkitPass2026";
+const SUPPORTED_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+
+export function jsonSessionContract(options = {}) {
+  const normalized = normalizePlainObject(options, "auth.contracts.jsonSession(...)");
+  const authCookie = normalizeOptionalString(normalized.authCookie);
+  const refreshCookie = normalizeOptionalString(normalized.refreshCookie);
+  const organizationIdPath = normalizeOptionalString(normalized.organizationIdPath);
+  const sessionCookies = normalizeStringMap(normalized.sessionCookies);
+  const sessionFields = normalizeStringMap(normalized.sessionFields);
+
+  return {
+    kind: "json-session",
+    contentTypeJson: normalized.contentTypeJson !== false,
+    forwardedFor: normalized.forwardedFor ?? "deterministic",
+    login: {
+      expect: normalized.loginExpect ?? 200,
+      path: normalizeOptionalString(normalized.loginPath) || "/api/v1/auth/login",
+    },
+    organization: normalizeOrganizationHeaderConfig(normalized),
+    session: {
+      auth: normalizeAuthCaptureConfig({
+        authCookie,
+        authHeader: normalized.authHeader,
+        authPrefix: normalized.authPrefix,
+        authSourceKey: normalized.authSourceKey,
+      }),
+      cookies: {
+        ...(authCookie ? { [(normalizeOptionalString(normalized.authSourceKey) || "jwt")]: authCookie } : {}),
+        ...(refreshCookie ? { refreshToken: refreshCookie } : {}),
+        ...sessionCookies,
+      },
+      fields: {
+        ...(organizationIdPath ? { organizationId: organizationIdPath } : {}),
+        ...sessionFields,
+      },
+    },
+    signup: normalized.signup === false
+      ? { enabled: false, expect: [], path: null }
+      : {
+          enabled: normalized.signup !== false,
+          expect: normalized.signupExpect ?? [201, 409],
+          path: normalizeOptionalString(normalized.signupPath) || "/api/v1/auth/signup",
+        },
+  };
+}
+
+export function singleOrgTopology(options = {}) {
+  const normalized = normalizePlainObject(options, "auth.topologies.singleOrg(...)");
+  const namespace = normalizeRequiredString(normalized.namespace, "auth.topologies.singleOrg(...).namespace");
+  const defaultOrgKey = normalizeOptionalString(normalized.org) || "primary";
+  const actorEntries = normalizeTopologyActors(normalized.actors, defaultOrgKey);
+
+  return {
+    kind: "auth-topology",
+    namespace,
+    defaultPassword: normalizeOptionalString(normalized.password) || DEFAULT_PASSWORD,
+    actors: finalizeActorEntries({
+      namespace,
+      actorEntries,
+      orgs: normalizeTopologyOrgs(normalized.orgs, [defaultOrgKey]),
+      defaultOrgKey,
+      defaultPassword: normalizeOptionalString(normalized.password) || DEFAULT_PASSWORD,
+      label: "auth.topologies.singleOrg(...)",
+    }),
+  };
+}
+
+export function crossOrgTopology(options = {}) {
+  const normalized = normalizePlainObject(options, "auth.topologies.crossOrg(...)");
+  const namespace = normalizeRequiredString(normalized.namespace, "auth.topologies.crossOrg(...).namespace");
+  const actorEntries = normalizeTopologyActors(normalized.actors, null);
+  if (actorEntries.length === 0) {
+    throw new Error("auth.topologies.crossOrg(...) requires at least one actor");
+  }
+  const orgKeys = [...new Set(actorEntries.map((entry) => entry.orgKey))];
+
+  return {
+    kind: "auth-topology",
+    namespace,
+    defaultPassword: normalizeOptionalString(normalized.password) || DEFAULT_PASSWORD,
+    actors: finalizeActorEntries({
+      namespace,
+      actorEntries,
+      orgs: normalizeTopologyOrgs(normalized.orgs, orgKeys),
+      defaultOrgKey: actorEntries[0].orgKey,
+      defaultPassword: normalizeOptionalString(normalized.password) || DEFAULT_PASSWORD,
+      label: "auth.topologies.crossOrg(...)",
+    }),
+  };
+}
+
+export function authFixture(options = {}) {
+  const normalized = normalizePlainObject(options, "auth.fixture(...)");
+  const contract = normalizeContract(normalized.contract);
+  const topology = normalizeTopology(normalized.topology);
+
+  return {
+    contract,
+    topology,
+    profiles(profileDefinitions = {}) {
+      if (!profileDefinitions || typeof profileDefinitions !== "object" || Array.isArray(profileDefinitions)) {
+        throw new Error("auth.fixture(...).profiles(...) requires an object");
+      }
+
+      const resolved = {};
+      for (const [profileName, descriptor] of Object.entries(profileDefinitions)) {
+        resolved[profileName] = buildFixtureProfile({
+          contract,
+          topology,
+          descriptor,
+          label: `auth.fixture(...).profiles().${profileName}`,
+        });
+      }
+      return resolved;
+    },
+  };
+}
+
+export function actorProfile(actorName, options = {}) {
+  return {
+    kind: "actor",
+    actor: normalizeRequiredString(actorName, "auth.profile.actor(..., ... ) actor"),
+    env: options.env,
+    headers: normalizeHeaderOptions(options.headers),
+    options: options.options,
+  };
+}
+
+export function actorsProfile(options = {}) {
+  const normalized = normalizePlainObject(options, "auth.profile.actors(...)");
+  const actors = normalizeActorNameList(normalized.actors);
+  if (actors.length === 0) {
+    throw new Error("auth.profile.actors(...) requires at least one actor");
+  }
+
+  const primaryActor = normalizeOptionalString(normalized.primaryActor) || actors[0];
+  if (!actors.includes(primaryActor)) {
+    throw new Error(`auth.profile.actors(...) primaryActor "${primaryActor}" is not included in actors`);
+  }
+
+  return {
+    kind: "actors",
+    actors,
+    primaryActor,
+    env: normalized.env,
+    headers: normalizeHeaderOptions(normalized.headers),
+    options: normalized.options,
+  };
+}
+
+export function rawAuthProfile(options = {}) {
+  const normalized = normalizePlainObject(options, "auth.profile.raw(...)");
+  return {
+    kind: "raw",
+    env: normalized.env,
+    headers: normalizeHeaderOptions(normalized.headers),
+    options: normalized.options,
+  };
+}
+
+function buildFixtureProfile({ contract, topology, descriptor, label }) {
+  const normalizedDescriptor = normalizeProfileDescriptor(descriptor, label, topology);
+  const actorNames = normalizedDescriptor.kind === "raw"
+    ? []
+    : normalizedDescriptor.kind === "actor"
+      ? [normalizedDescriptor.actor]
+      : normalizedDescriptor.actors;
+  const primaryActor = normalizedDescriptor.kind === "raw"
+    ? null
+    : normalizedDescriptor.kind === "actor"
+      ? normalizedDescriptor.actor
+      : normalizedDescriptor.primaryActor;
+
+  const headerBuilder = createCompositeHeaderBuilder({
+    defaultActor: primaryActor,
+    headers: mergeHeaderOptions(buildContractHeaderOptions(contract), normalizedDescriptor.headers),
+    resolveActorRecord(bundle, actorName) {
+      return resolveActorRecord(bundle, actorName);
+    },
+  });
+
+  return {
+    env: normalizedDescriptor.env,
+    options: normalizedDescriptor.options,
+    auth: normalizedDescriptor.kind === "raw"
+      ? null
+      : {
+          setup({ env }) {
+            return buildSessionBundle({
+              actorNames,
+              contract,
+              env,
+              primaryActor,
+              topology,
+            });
+          },
+          headers(sessionBundle, context = {}) {
+            const actorName = context.actor || primaryActor;
+            return buildAuthHeaders({
+              actorRecord: resolveActorRecord(sessionBundle, actorName),
+              auth: contract.session.auth,
+            });
+          },
+        },
+    headers(sessionBundle, context = {}) {
+      return headerBuilder(sessionBundle, context.env, context.actor || primaryActor);
+    },
+    rawHeaders(sessionBundle, context = {}) {
+      return headerBuilder(sessionBundle, context.env, context.actor || null);
+    },
+    __testkitAuthProfile: {
+      actorNames,
+      kind: normalizedDescriptor.kind,
+      primaryActor,
+    },
+  };
+}
+
+function buildSessionBundle({ actorNames, contract, env, primaryActor, topology }) {
+  const actors = {};
+
+  actorNames.forEach((actorName, actorIndex) => {
+    const actorDefinition = topology.actors[actorName];
+    if (!actorDefinition) {
+      throw new Error(`Unknown actor "${actorName}" in auth fixture topology`);
+    }
+    const actorRecord = resolveActorSession({
+      actorDefinition,
+      actorIndex,
+      contract,
+      env,
+    });
+    actors[actorName] = actorRecord;
+  });
+
+  return {
+    actors,
+    primaryActor,
+  };
+}
+
+function resolveActorSession({ actorDefinition, actorIndex, contract, env }) {
+  const context = {
+    actor: actorDefinition.actorName,
+    actorIndex,
+    env,
+  };
+
+  if (contract.signup.enabled) {
+    try {
+      runProfileRequest({
+        requestConfig: {
+          body: () => buildSignupBody(actorDefinition),
+          expect: contract.signup.expect,
+          method: "POST",
+          path: contract.signup.path,
+        },
+        context: { ...context, phase: "signup" },
+        label: `auth.fixture signup for actor "${actorDefinition.actorName}"`,
+      });
+    } catch {
+      // Provisioning is best-effort. Some apps report duplicate-account races as 500s
+      // instead of a clean 409, and a successful login is the authoritative signal.
+    }
+  }
+
+  const response = runProfileRequest({
+    requestConfig: {
+      body: () => buildLoginBody(actorDefinition),
+      expect: contract.login.expect,
+      method: "POST",
+      path: contract.login.path,
+    },
+    context: { ...context, phase: "login" },
+    label: `auth.fixture login for actor "${actorDefinition.actorName}"`,
+  });
+  const session = extractSessionData(response, contract.session);
+
+  return {
+    actorIndex,
+    actorName: actorDefinition.actorName,
+    email: actorDefinition.email,
+    name: actorDefinition.name,
+    organizationKey: actorDefinition.organizationKey,
+    organizationName: actorDefinition.organizationName,
+    session,
+    ...session,
+  };
+}
+
+function buildSignupBody(actorDefinition) {
+  return {
+    email: actorDefinition.email,
+    password: actorDefinition.password,
+    name: actorDefinition.name,
+    organizationName: actorDefinition.organizationName,
+    ...normalizePlainObject(actorDefinition.signupBody, "actor signupBody"),
+  };
+}
+
+function buildLoginBody(actorDefinition) {
+  return {
+    email: actorDefinition.email,
+    password: actorDefinition.password,
+    ...normalizePlainObject(actorDefinition.loginBody, "actor loginBody"),
+  };
+}
+
+function normalizeContract(contract) {
+  if (!contract || contract.kind !== "json-session") {
+    throw new Error("auth.fixture(...).contract must come from auth.contracts.jsonSession(...)");
+  }
+  return contract;
+}
+
+function normalizeTopology(topology) {
+  if (!topology || topology.kind !== "auth-topology" || !topology.actors) {
+    throw new Error("auth.fixture(...).topology must come from auth.topologies.*(...)");
+  }
+  return topology;
+}
+
+function normalizeProfileDescriptor(descriptor, label, topology) {
+  if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
+    throw new Error(`${label} must be built with auth.profile.*(...)`);
+  }
+
+  if (descriptor.kind === "raw") {
+    return descriptor;
+  }
+
+  if (descriptor.kind === "actor") {
+    if (!topology.actors[descriptor.actor]) {
+      throw new Error(`${label} references unknown actor "${descriptor.actor}"`);
+    }
+    return descriptor;
+  }
+
+  if (descriptor.kind === "actors") {
+    descriptor.actors.forEach((actorName) => {
+      if (!topology.actors[actorName]) {
+        throw new Error(`${label} references unknown actor "${actorName}"`);
+      }
+    });
+    return descriptor;
+  }
+
+  throw new Error(`${label} must be built with auth.profile.*(...)`);
+}
+
+function normalizeTopologyActors(value, defaultOrgKey) {
+  if (value == null) {
+    if (!defaultOrgKey) {
+      return [];
+    }
+    return [{ actorName: "primary", orgKey: defaultOrgKey, config: {} }];
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((actorName) => ({
+      actorName: normalizeRequiredString(actorName, "actor name"),
+      orgKey: defaultOrgKey || "primary",
+      config: {},
+    }));
+  }
+
+  if (typeof value !== "object") {
+    throw new Error("topology actors must be an array or object");
+  }
+
+  return Object.entries(value).map(([actorName, actorConfig]) => {
+    if (typeof actorConfig === "string") {
+      return {
+        actorName: normalizeRequiredString(actorName, "actor name"),
+        orgKey: normalizeRequiredString(actorConfig, `topology actor "${actorName}" org`),
+        config: {},
+      };
+    }
+
+    const normalizedConfig = normalizePlainObject(actorConfig, `topology actor "${actorName}"`);
+    const orgKey = normalizeOptionalString(normalizedConfig.org) || defaultOrgKey;
+    if (!orgKey) {
+      throw new Error(`topology actor "${actorName}" requires an org`);
+    }
+    return {
+      actorName: normalizeRequiredString(actorName, "actor name"),
+      orgKey,
+      config: normalizedConfig,
+    };
+  });
+}
+
+function normalizeTopologyOrgs(value, fallbackOrgKeys) {
+  const orgs = {};
+  const input = value == null ? {} : normalizePlainObject(value, "topology orgs");
+
+  fallbackOrgKeys.forEach((orgKey) => {
+    orgs[orgKey] = normalizePlainObject(input[orgKey], `topology org "${orgKey}"`);
+  });
+
+  for (const [orgKey, orgConfig] of Object.entries(input)) {
+    orgs[orgKey] = normalizePlainObject(orgConfig, `topology org "${orgKey}"`);
+  }
+
+  return orgs;
+}
+
+function finalizeActorEntries({ namespace, actorEntries, orgs, defaultOrgKey, defaultPassword, label }) {
+  const actors = {};
+  actorEntries.forEach(({ actorName, orgKey, config }) => {
+    const resolvedOrgKey = orgKey || defaultOrgKey;
+    if (!resolvedOrgKey) {
+      throw new Error(`${label} actor "${actorName}" requires an org`);
+    }
+    const orgConfig = orgs[resolvedOrgKey] || {};
+    actors[actorName] = {
+      actorName,
+      email:
+        normalizeOptionalString(config.email) ||
+        buildGeneratedEmail(namespace, actorName),
+      loginBody: normalizePlainObject(config.loginBody, `${label} actor "${actorName}" loginBody`),
+      name:
+        normalizeOptionalString(config.name) ||
+        `Testkit ${humanizeToken(namespace)} ${humanizeToken(actorName)}`,
+      organizationKey: resolvedOrgKey,
+      organizationName:
+        normalizeOptionalString(config.organizationName) ||
+        normalizeOptionalString(orgConfig.name) ||
+        `Testkit ${humanizeToken(namespace)} ${humanizeToken(resolvedOrgKey)} Org`,
+      password: normalizeOptionalString(config.password) || defaultPassword,
+      signupBody: normalizePlainObject(config.signupBody, `${label} actor "${actorName}" signupBody`),
+    };
+  });
+  return actors;
+}
+
+function buildGeneratedEmail(namespace, actorName) {
+  return `testkit+${slugifyToken(namespace)}.${slugifyToken(actorName)}@example.test`;
+}
+
+function normalizeAuthCaptureConfig(options) {
+  const authSourceKey = normalizeOptionalString(options.authSourceKey) || "jwt";
+  const authCookie = normalizeOptionalString(options.authCookie);
+  if (!authCookie) return null;
+
+  return {
+    cookie: authCookie,
+    header: normalizeOptionalString(options.authHeader) || "Authorization",
+    prefix: options.authPrefix === undefined ? "Bearer " : String(options.authPrefix),
+    source: {
+      key: authSourceKey,
+    },
+  };
+}
+
+function normalizeOrganizationHeaderConfig(options) {
+  const organizationHeader = options.organizationHeader;
+  if (organizationHeader === false) return false;
+  if (organizationHeader == null) return "X-Organization-Id";
+  if (typeof organizationHeader === "string") return organizationHeader;
+  throw new Error("auth.contracts.jsonSession(...).organizationHeader must be a string or false");
+}
+
+function buildContractHeaderOptions(contract) {
+  const fromSession = [];
+  if (contract.organization !== false) {
+    fromSession.push({
+      field: "organizationId",
+      header: contract.organization,
+    });
+  }
+
+  return {
+    contentTypeJson: contract.contentTypeJson,
+    forwardedFor: contract.forwardedFor,
+    fromSession,
+    values: undefined,
+  };
+}
+
+function normalizeHeaderOptions(options) {
+  if (options == null) return {};
+  const normalized = normalizePlainObject(options, "auth profile headers");
+  return {
+    contentTypeJson: normalized.contentTypeJson,
+    forwardedFor: normalized.forwardedFor,
+    fromSession: Array.isArray(normalized.fromSession)
+      ? normalized.fromSession.map((entry, index) => normalizeFromSessionEntry(entry, index))
+      : [],
+    values: normalized.values,
+  };
+}
+
+function mergeHeaderOptions(baseOptions, overrideOptions) {
+  const base = normalizeHeaderOptions(baseOptions);
+  const override = normalizeHeaderOptions(overrideOptions);
+  return {
+    contentTypeJson:
+      override.contentTypeJson !== undefined ? override.contentTypeJson : base.contentTypeJson,
+    forwardedFor: override.forwardedFor !== undefined ? override.forwardedFor : base.forwardedFor,
+    fromSession: override.fromSession.length > 0 ? override.fromSession : base.fromSession,
+    values: override.values !== undefined ? override.values : base.values,
+  };
+}
+
+function normalizeFromSessionEntry(entry, index) {
+  const normalized = normalizePlainObject(entry, `headers.fromSession[${index}]`);
+  return {
+    actor: normalizeOptionalString(normalized.actor) || null,
+    field: normalizeRequiredString(normalized.field, `headers.fromSession[${index}].field`),
+    header: normalizeRequiredString(normalized.header, `headers.fromSession[${index}].header`),
+  };
+}
+
+function normalizeActorNameList(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) {
+    return value.map((entry, index) => normalizeRequiredString(entry, `actors[${index}]`));
+  }
+  throw new Error("auth.profile.actors(...).actors must be an array");
+}
+
+function normalizePlainObject(value, label) {
+  if (value == null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return { ...value };
+}
+
+function normalizeStringMap(value) {
+  const normalized = {};
+  if (!value) return normalized;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Expected a string map");
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    normalized[key] = normalizeRequiredString(entry, `string map entry "${key}"`);
+  }
+  return normalized;
+}
+
+function normalizeRequiredString(value, label) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalString(value) {
+  if (value == null) return "";
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : "";
+}
+
+function humanizeToken(value) {
+  return String(value || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function slugifyToken(value) {
+  return String(value || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function resolveActorRecord(sessionBundle, actorName) {
+  if (!sessionBundle?.actors || !actorName) return null;
+  return sessionBundle.actors[actorName] || null;
+}
+
+function buildAuthHeaders({ actorRecord, auth }) {
+  if (!auth || !actorRecord) return {};
+  const source = auth.source || {};
+  const value = actorRecord[source.key];
+  if (!value) return {};
+
+  const header = auth.header || "Authorization";
+  const prefix = auth.prefix === undefined ? "Bearer " : String(auth.prefix);
+  return {
+    [header]: `${prefix}${value}`,
+  };
+}
+
+function createCompositeHeaderBuilder({ defaultActor, headers, resolveActorRecord }) {
+  const normalized = normalizeHeaderOptions(headers);
+
+  return function buildHeaders(sessionBundle, env, actorOverride = null) {
+    const actorName = actorOverride || defaultActor || null;
+    const actorRecord = resolveActorRecord(sessionBundle, actorName);
+    const staticValues = resolveFactoryValue(normalized.values, {
+      actor: actorName,
+      env,
+      session: actorRecord,
+    }) || {};
+    const builtHeaders = {
+      ...(normalized.contentTypeJson ? { "Content-Type": "application/json" } : {}),
+      ...staticValues,
+    };
+
+    const forwardedFor = buildForwardedForHeader(normalized.forwardedFor, env, actorName);
+    if (forwardedFor) {
+      builtHeaders[forwardedFor.header] = forwardedFor.value;
+    }
+
+    for (const entry of normalized.fromSession || []) {
+      const record = resolveActorRecord(sessionBundle, entry.actor || actorName);
+      const value = record ? readValueAtPath(record, entry.field) : null;
+      if (value != null && value !== "") {
+        builtHeaders[entry.header] = String(value);
+      }
+    }
+
+    return builtHeaders;
+  };
+}
+
+function buildForwardedForHeader(config, env, actorName) {
+  if (!config) return null;
+  const header = typeof config === "object" && config.header ? config.header : "X-Forwarded-For";
+  const seed =
+    typeof config === "object" && config.seed
+      ? config.seed
+      : `${env?.BASE || "testkit"}:${actorName || "raw"}`;
+  return {
+    header,
+    value: deriveDeterministicIp(seed),
+  };
+}
+
+function deriveDeterministicIp(seed) {
+  const text = String(seed || "testkit");
+  const octets = [0, 0, 0, 0];
+  for (let index = 0; index < text.length; index += 1) {
+    octets[index % 4] = (octets[index % 4] * 31 + text.charCodeAt(index)) % 250;
+  }
+  return `10.${octets[0] + 1}.${octets[1] + 1}.${octets[2] + 1}`;
+}
+
+function runProfileRequest({ requestConfig, context, label }) {
+  const method = normalizeMethod(requestConfig.method);
+  const path = normalizeRequiredString(requestConfig.path, `${label} path`);
+  const bodyValue = resolveFactoryValue(requestConfig.body, context);
+  const headersValue = resolveFactoryValue(requestConfig.headers, context) || {};
+  const headers = {
+    ...(requestConfig.contentTypeJson === false ? {} : { "Content-Type": "application/json" }),
+    ...(context.env?.routeParams || {}),
+    ...headersValue,
+  };
+  const expectedStatuses = normalizeExpectedStatuses(requestConfig.expect);
+  const url = `${context.env.BASE}${path}`;
+  const response = dispatchProfileRequest(method, url, bodyValue, headers);
+
+  if (!expectedStatuses.includes(Number(response?.status))) {
+    throw new Error(
+      `${label} failed (${response?.status ?? "unknown"}): ${response?.body ?? "no response body"}`
+    );
+  }
+
+  return response;
+}
+
+function dispatchProfileRequest(method, url, body, headers) {
+  if (method === "GET") return runtimeHttp.get(url, { headers });
+  if (method === "DELETE") return runtimeHttp.del(url, body == null ? null : JSON.stringify(body), { headers });
+  if (method === "PUT") return runtimeHttp.put(url, JSON.stringify(body ?? null), { headers });
+  if (method === "PATCH") return runtimeHttp.patch(url, JSON.stringify(body ?? null), { headers });
+  return runtimeHttp.post(url, JSON.stringify(body ?? null), { headers });
+}
+
+function normalizeMethod(value) {
+  const method = String(value || "POST").trim().toUpperCase();
+  if (!SUPPORTED_METHODS.has(method)) {
+    throw new Error(`Unsupported auth request method "${method}"`);
+  }
+  return method;
+}
+
+function normalizeExpectedStatuses(value) {
+  if (value == null) return [200];
+  return Array.isArray(value) ? value.map((entry) => Number(entry)) : [Number(value)];
+}
+
+function resolveFactoryValue(value, context) {
+  if (typeof value === "function") {
+    return value(context);
+  }
+  return value;
+}
+
+function extractSessionData(response, sessionConfig) {
+  const data = {};
+  const body = safeRuntimeJson(response);
+
+  const cookies = {
+    ...(sessionConfig.auth ? { [sessionConfig.auth.source.key]: sessionConfig.auth.cookie } : {}),
+    ...sessionConfig.cookies,
+  };
+  for (const [fieldName, cookieName] of Object.entries(cookies)) {
+    data[fieldName] = extractCookieValue(response, cookieName);
+  }
+
+  for (const [fieldName, fieldPath] of Object.entries(sessionConfig.fields || {})) {
+    data[fieldName] = readValueAtPath(body, fieldPath);
+  }
+
+  return data;
+}
+
+function extractCookieValue(response, cookieName) {
+  const cookies = response?.cookies?.[cookieName];
+  if (Array.isArray(cookies) && cookies[0]?.value) {
+    return cookies[0].value;
+  }
+
+  const headerValues = [];
+  for (const [headerName, headerValue] of Object.entries(response?.headers || {})) {
+    if (String(headerName).toLowerCase() !== "set-cookie") continue;
+    if (Array.isArray(headerValue)) headerValues.push(...headerValue);
+    else if (headerValue) headerValues.push(headerValue);
+  }
+
+  const pattern = new RegExp(`(?:^|,\\s*)${cookieName}=([^;,]+)`);
+  for (const value of headerValues) {
+    const match = pattern.exec(String(value));
+    if (match?.[1]) return match[1];
+  }
+
+  return null;
+}
+
+function safeRuntimeJson(response) {
+  try {
+    return runtimeJson(response);
+  } catch {
+    return null;
+  }
+}
+
+function readValueAtPath(value, path) {
+  if (value == null || typeof path !== "string" || path.trim().length === 0) {
+    return null;
+  }
+  const parts = String(path)
+    .replace(/\[(\d+)\]/g, ".$1")
+    .split(".")
+    .filter(Boolean);
+
+  let current = value;
+  for (const part of parts) {
+    if (current == null) return null;
+    current = current[part];
+  }
+  return current ?? null;
+}