@holo-js/auth-workos 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import { AuthUserLike, AuthEstablishedSession, authRuntimeInternals } from '@holo-js/auth';
+import { AuthWorkosProviderConfig } from '@holo-js/config';
+
+interface WorkosIdentityProfile {
+    readonly id: string;
+    readonly email?: string;
+    readonly emailVerified?: boolean;
+    readonly firstName?: string;
+    readonly lastName?: string;
+    readonly name?: string;
+    readonly avatar?: string;
+    readonly organizationId?: string;
+    readonly raw?: unknown;
+}
+interface WorkosVerifiedSession {
+    readonly sessionId: string;
+    readonly identity: WorkosIdentityProfile;
+    readonly accessToken?: string;
+    readonly expiresAt?: Date;
+    readonly raw?: unknown;
+}
+interface WorkosVerifyRequestContext {
+    readonly provider: string;
+    readonly request: Request;
+    readonly config: AuthWorkosProviderConfig;
+}
+interface WorkosVerifySessionContext {
+    readonly provider: string;
+    readonly token: string;
+    readonly config: AuthWorkosProviderConfig;
+}
+interface WorkosProviderRuntime {
+    verifyRequest?(context: WorkosVerifyRequestContext): Promise<WorkosVerifiedSession | null>;
+    verifySession?(context: WorkosVerifySessionContext): Promise<WorkosVerifiedSession | null>;
+}
+type RuntimeAuthProviderAdapter = ReturnType<typeof authRuntimeInternals.getRuntimeBindings>['providers'][string];
+interface HostedIdentityRecord {
+    readonly provider: string;
+    readonly providerUserId: string;
+    readonly guard: string;
+    readonly authProvider: string;
+    readonly userId: string | number;
+    readonly email?: string;
+    readonly emailVerified: boolean;
+    readonly profile: Readonly<Record<string, unknown>>;
+    readonly linkedAt: Date;
+    readonly updatedAt: Date;
+}
+interface HostedIdentityStore {
+    findByProviderUserId(provider: string, providerUserId: string): Promise<HostedIdentityRecord | null>;
+    findByUserId(provider: string, authProvider: string, userId: string | number): Promise<HostedIdentityRecord | null>;
+    save(record: HostedIdentityRecord): Promise<void>;
+}
+type WorkosSyncStatus = 'created' | 'updated' | 'linked' | 'relinked';
+interface WorkosAuthenticationResult {
+    readonly provider: string;
+    readonly guard: string;
+    readonly authProvider: string;
+    readonly status: WorkosSyncStatus;
+    readonly user: AuthUserLike;
+    readonly identity: HostedIdentityRecord;
+    readonly session: WorkosVerifiedSession;
+    readonly authSession?: AuthEstablishedSession;
+}
+interface WorkosAuthBindings {
+    readonly providers: Readonly<Record<string, WorkosProviderRuntime>>;
+    readonly identityStore: HostedIdentityStore;
+}
+interface ConfigureWorkosAuthRuntimeOptions {
+    readonly providers?: Readonly<Record<string, WorkosProviderRuntime>>;
+    readonly identityStore?: HostedIdentityStore;
+}
+interface WorkosAuthFacade {
+    verifyRequest(request: Request, provider?: string): Promise<WorkosVerifiedSession | null>;
+    verifySession(token: string, provider?: string): Promise<WorkosVerifiedSession | null>;
+    syncIdentity(session: WorkosVerifiedSession, provider?: string): Promise<WorkosAuthenticationResult>;
+    authenticate(request: Request, provider?: string): Promise<WorkosAuthenticationResult | null>;
+}
+declare class WorkosAuthConflictError extends Error {
+    readonly code = "workos_identity_conflict";
+    readonly provider: string;
+    readonly workosUserId: string;
+    readonly email?: string;
+    constructor(options: {
+        readonly provider: string;
+        readonly workosUserId: string;
+        readonly email?: string;
+        readonly message: string;
+    });
+}
+declare function getBindings(): WorkosAuthBindings;
+declare function resolveConfiguredProviderName(provider?: string): string;
+declare function getConfiguredProviderConfig(provider?: string): {
+    readonly name: string;
+    readonly clientId?: string;
+    readonly apiKey?: string;
+    readonly cookiePassword?: string;
+    readonly redirectUri?: string;
+    readonly sessionCookie: string;
+    readonly guard?: string;
+    readonly mapToProvider?: string;
+};
+declare function resolveGuardAndProvider(provider?: string): {
+    readonly guard: string;
+    readonly authProvider: string;
+    readonly adapter: RuntimeAuthProviderAdapter;
+};
+declare function resolveDisplayName(profile: WorkosIdentityProfile): string | undefined;
+declare function resolveEmailForCreation(profile: WorkosIdentityProfile): string;
+declare function normalizeHostedProfile(profile: WorkosIdentityProfile): Readonly<Record<string, unknown>>;
+declare function getSessionTokenFromRequest(request: Request, sessionCookie: string): string | null;
+declare function verifySession(token: string, provider?: string): Promise<WorkosVerifiedSession | null>;
+declare function verifyRequest(request: Request, provider?: string): Promise<WorkosVerifiedSession | null>;
+declare function syncIdentity(session: WorkosVerifiedSession, provider?: string): Promise<WorkosAuthenticationResult>;
+declare function authenticate(request: Request, provider?: string): Promise<WorkosAuthenticationResult | null>;
+declare function configureWorkosAuthRuntime(bindings?: ConfigureWorkosAuthRuntimeOptions): void;
+declare function resetWorkosAuthRuntime(): void;
+declare const workosAuth: Readonly<{
+    authenticate: typeof authenticate;
+    syncIdentity: typeof syncIdentity;
+    verifyRequest: typeof verifyRequest;
+    verifySession: typeof verifySession;
+}>;
+declare const workosAuthInternals: {
+    getBindings: typeof getBindings;
+    getConfiguredProviderConfig: typeof getConfiguredProviderConfig;
+    getSessionTokenFromRequest: typeof getSessionTokenFromRequest;
+    normalizeHostedProfile: typeof normalizeHostedProfile;
+    resolveConfiguredProviderName: typeof resolveConfiguredProviderName;
+    resolveDisplayName: typeof resolveDisplayName;
+    resolveEmailForCreation: typeof resolveEmailForCreation;
+    resolveGuardAndProvider: typeof resolveGuardAndProvider;
+};
+
+export { type ConfigureWorkosAuthRuntimeOptions, type HostedIdentityRecord, type HostedIdentityStore, type WorkosAuthBindings, WorkosAuthConflictError, type WorkosAuthFacade, type WorkosAuthenticationResult, type WorkosIdentityProfile, type WorkosProviderRuntime, type WorkosSyncStatus, type WorkosVerifiedSession, type WorkosVerifyRequestContext, type WorkosVerifySessionContext, authenticate, configureWorkosAuthRuntime, resetWorkosAuthRuntime, syncIdentity, verifyRequest, verifySession, workosAuth, workosAuthInternals };

package/dist/index.mjs

@@ -0,0 +1,677 @@
+// src/index.ts
+import { createPublicKey, verify as verifySignature } from "crypto";
+import { authRuntimeInternals } from "@holo-js/auth";
+import { parseCookieHeader } from "@holo-js/session";
+var WorkosAuthConflictError = class extends Error {
+  code = "workos_identity_conflict";
+  provider;
+  workosUserId;
+  email;
+  constructor(options) {
+    super(options.message);
+    this.name = "WorkosAuthConflictError";
+    this.provider = options.provider;
+    this.workosUserId = options.workosUserId;
+    this.email = options.email;
+  }
+};
+var workosBindings;
+var WORKOS_API_BASE_URL = "https://api.workos.com";
+var workosDefaultProviderRuntimeCache = /* @__PURE__ */ new Map();
+var workosJwksCache = /* @__PURE__ */ new Map();
+var AUTH_PROVIDER_MARKER = /* @__PURE__ */ Symbol.for("holo-js.auth.provider");
+function throwUnconfigured() {
+  throw new Error("[@holo-js/auth-workos] WorkOS auth runtime is not configured yet.");
+}
+function getBindings() {
+  if (!workosBindings?.identityStore) {
+    throwUnconfigured();
+  }
+  return {
+    providers: workosBindings.providers ?? {},
+    identityStore: workosBindings.identityStore
+  };
+}
+function decodeJwtSegment(value, label) {
+  try {
+    return JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+  } catch {
+    throw new Error(`[@holo-js/auth-workos] WorkOS token ${label} was not valid JSON.`);
+  }
+}
+function parseJwt(token) {
+  const segments = token.split(".");
+  if (segments.length !== 3 || !segments[0] || !segments[1] || !segments[2]) {
+    throw new Error("[@holo-js/auth-workos] WorkOS token was not a valid JWT.");
+  }
+  return {
+    header: decodeJwtSegment(segments[0], "header"),
+    payload: decodeJwtSegment(segments[1], "payload"),
+    signature: Buffer.from(segments[2], "base64url"),
+    signingInput: Buffer.from(`${segments[0]}.${segments[1]}`, "utf8")
+  };
+}
+function verifyJwtSignatureWithJwk(token, jwk) {
+  const algorithm = typeof token.header.alg === "string" ? token.header.alg : "";
+  const key = createPublicKey({ key: jwk, format: "jwk" });
+  switch (algorithm) {
+    case "RS256":
+      return verifySignature("RSA-SHA256", token.signingInput, key, token.signature);
+    case "RS384":
+      return verifySignature("RSA-SHA384", token.signingInput, key, token.signature);
+    case "RS512":
+      return verifySignature("RSA-SHA512", token.signingInput, key, token.signature);
+    default:
+      throw new Error(`[@holo-js/auth-workos] Unsupported WorkOS JWT algorithm "${algorithm || "unknown"}".`);
+  }
+}
+async function fetchWorkosJwks(clientId, options = {}) {
+  const normalizedClientId = clientId.trim();
+  if (options.refresh) {
+    workosJwksCache.delete(normalizedClientId);
+  }
+  const existing = workosJwksCache.get(normalizedClientId);
+  if (existing) {
+    return existing;
+  }
+  const pending = (async () => {
+    const response = await fetch(`${WORKOS_API_BASE_URL}/sso/jwks/${encodeURIComponent(normalizedClientId)}`, {
+      headers: {
+        accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`[@holo-js/auth-workos] Failed to load WorkOS JWKS for "${normalizedClientId}".`);
+    }
+    const payload = await response.json();
+    return payload.keys ?? [];
+  })();
+  workosJwksCache.set(normalizedClientId, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    workosJwksCache.delete(normalizedClientId);
+    throw error;
+  }
+}
+async function verifyWorkosSessionToken(token, config) {
+  const clientId = config.clientId?.trim();
+  if (!clientId) {
+    throw new Error("[@holo-js/auth-workos] WorkOS verification requires clientId to be configured.");
+  }
+  const parsed = parseJwt(token);
+  const headerKid = typeof parsed.header.kid === "string" ? parsed.header.kid : void 0;
+  const resolveKey = async (refresh = false) => {
+    const keys = await fetchWorkosJwks(clientId, { refresh });
+    return headerKid ? keys.find((candidate) => candidate.kid === headerKid) : keys[0];
+  };
+  let key = await resolveKey();
+  if (!key || !verifyJwtSignatureWithJwk(parsed, key)) {
+    key = await resolveKey(true);
+  }
+  if (!key || !verifyJwtSignatureWithJwk(parsed, key)) {
+    throw new Error("[@holo-js/auth-workos] WorkOS token signature verification failed.");
+  }
+  const exp = typeof parsed.payload.exp === "number" ? parsed.payload.exp : void 0;
+  if (typeof exp === "number" && exp * 1e3 <= Date.now()) {
+    throw new Error("[@holo-js/auth-workos] WorkOS token has expired.");
+  }
+  const nbf = typeof parsed.payload.nbf === "number" ? parsed.payload.nbf : void 0;
+  if (typeof nbf === "number" && nbf * 1e3 > Date.now()) {
+    throw new Error("[@holo-js/auth-workos] WorkOS token is not valid yet.");
+  }
+  return parsed.payload;
+}
+function normalizeWorkosUserProfile(user) {
+  const firstName = typeof user.firstName === "string" ? user.firstName : typeof user.first_name === "string" ? user.first_name : void 0;
+  const lastName = typeof user.lastName === "string" ? user.lastName : typeof user.last_name === "string" ? user.last_name : void 0;
+  const name = typeof user.name === "string" ? user.name : [firstName, lastName].filter(Boolean).join(" ").trim() || void 0;
+  return Object.freeze({
+    id: String(user.id ?? ""),
+    email: typeof user.email === "string" ? user.email : void 0,
+    emailVerified: user.emailVerified === true || user.email_verified === true,
+    firstName,
+    lastName,
+    name,
+    avatar: typeof user.profilePictureUrl === "string" ? user.profilePictureUrl : typeof user.profile_picture_url === "string" ? user.profile_picture_url : void 0,
+    organizationId: typeof user.organizationId === "string" ? user.organizationId : typeof user.organization_id === "string" ? user.organization_id : void 0,
+    raw: user
+  });
+}
+async function fetchWorkosUserProfile(userId, config) {
+  const apiKey = config.apiKey?.trim();
+  if (!apiKey) {
+    throw new Error("[@holo-js/auth-workos] WorkOS verification requires apiKey to be configured.");
+  }
+  const response = await fetch(`${WORKOS_API_BASE_URL}/user_management/users/${encodeURIComponent(userId)}`, {
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${apiKey}`
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`[@holo-js/auth-workos] Failed to load WorkOS user "${userId}".`);
+  }
+  return normalizeWorkosUserProfile(await response.json());
+}
+function createDefaultProviderRuntime(providerName, config) {
+  const cacheKey = JSON.stringify([
+    providerName,
+    config.clientId ?? "",
+    config.apiKey ?? ""
+  ]);
+  const existing = workosDefaultProviderRuntimeCache.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  const runtime = Object.freeze({
+    async verifySession({ token }) {
+      const claims = await verifyWorkosSessionToken(token, config);
+      const userId = typeof claims.sub === "string" ? claims.sub : "";
+      if (!userId) {
+        throw new Error("[@holo-js/auth-workos] WorkOS token did not include a subject.");
+      }
+      const profile = await fetchWorkosUserProfile(userId, config);
+      const sessionId = typeof claims.sid === "string" ? claims.sid : typeof claims.session_id === "string" ? claims.session_id : token;
+      return Object.freeze({
+        sessionId,
+        identity: profile,
+        accessToken: token,
+        expiresAt: typeof claims.exp === "number" ? new Date(claims.exp * 1e3) : void 0,
+        raw: Object.freeze({
+          claims,
+          user: profile.raw
+        })
+      });
+    }
+  });
+  workosDefaultProviderRuntimeCache.set(cacheKey, runtime);
+  return runtime;
+}
+function resolveConfiguredProviderName(provider) {
+  const bindings = authRuntimeInternals.getRuntimeBindings();
+  if (provider?.trim()) {
+    return provider.trim();
+  }
+  const configuredProviders = Object.keys(bindings.config.workos);
+  if (configuredProviders.length === 0) {
+    return "default";
+  }
+  if (configuredProviders.length === 1) {
+    return configuredProviders[0];
+  }
+  if (configuredProviders.includes("default")) {
+    return "default";
+  }
+  throw new Error("[@holo-js/auth-workos] WorkOS provider name is required when multiple auth.workos entries exist.");
+}
+function getConfiguredProviderConfig(provider) {
+  const providerName = resolveConfiguredProviderName(provider);
+  const authBindings = authRuntimeInternals.getRuntimeBindings();
+  const configured = authBindings.config.workos[providerName];
+  if (!configured) {
+    throw new Error(`[@holo-js/auth-workos] WorkOS provider "${providerName}" is not configured in auth.workos.`);
+  }
+  return {
+    name: providerName,
+    clientId: configured.clientId,
+    apiKey: configured.apiKey,
+    cookiePassword: configured.cookiePassword,
+    redirectUri: configured.redirectUri,
+    sessionCookie: configured.sessionCookie,
+    guard: configured.guard,
+    mapToProvider: configured.mapToProvider
+  };
+}
+function getProviderRuntime(provider) {
+  const providerName = resolveConfiguredProviderName(provider);
+  return getBindings().providers[providerName] ?? createDefaultProviderRuntime(providerName, getConfiguredProviderConfig(providerName));
+}
+function resolveGuardAndProvider(provider) {
+  const authBindings = authRuntimeInternals.getRuntimeBindings();
+  const providerConfig = getConfiguredProviderConfig(provider);
+  const guardName = providerConfig.guard ?? authBindings.config.defaults.guard;
+  const guard = authBindings.config.guards[guardName];
+  if (!guard) {
+    throw new Error(`[@holo-js/auth-workos] Guard "${guardName}" is not configured for WorkOS provider "${providerConfig.name}".`);
+  }
+  if (guard.driver !== "session") {
+    throw new Error(`[@holo-js/auth-workos] WorkOS sign-in requires auth guard "${guardName}" to use the session driver.`);
+  }
+  const authProvider = providerConfig.mapToProvider ?? guard.provider;
+  const adapter = authBindings.providers[authProvider];
+  if (!adapter) {
+    throw new Error(`[@holo-js/auth-workos] Auth provider runtime "${authProvider}" is not configured.`);
+  }
+  return {
+    guard: guardName,
+    authProvider,
+    adapter
+  };
+}
+function requireUserId(adapter, user, message) {
+  if (!user || typeof user !== "object") {
+    throw new Error(message);
+  }
+  const userId = adapter.getId(user);
+  if (typeof userId !== "string" && typeof userId !== "number") {
+    throw new Error(message);
+  }
+  return userId;
+}
+function requireUserRecord(user, message) {
+  if (!user || typeof user !== "object") {
+    throw new Error(message);
+  }
+  return user;
+}
+function serializeLocalUser(adapter, user, providerName) {
+  const id = adapter.getId(user);
+  const serialized = adapter.serialize ? adapter.serialize(user) : { ...user };
+  const result = {
+    ...serialized,
+    id
+  };
+  Object.defineProperty(result, AUTH_PROVIDER_MARKER, {
+    value: providerName,
+    enumerable: false,
+    configurable: true
+  });
+  return Object.freeze(result);
+}
+function resolveDisplayName(profile) {
+  if (profile.name?.trim()) {
+    return profile.name.trim();
+  }
+  const fullName = [profile.firstName?.trim(), profile.lastName?.trim()].filter(Boolean).join(" ").trim();
+  return fullName || void 0;
+}
+function resolveEmailForCreation(profile) {
+  const normalized = profile.email?.trim();
+  if (normalized) {
+    return normalized;
+  }
+  return `${profile.id}@workos.hosted.local`;
+}
+function normalizeHostedProfile(profile) {
+  return Object.freeze({
+    id: profile.id,
+    email: profile.email,
+    emailVerified: profile.emailVerified === true,
+    firstName: profile.firstName,
+    lastName: profile.lastName,
+    name: resolveDisplayName(profile),
+    avatar: profile.avatar,
+    organizationId: profile.organizationId,
+    raw: profile.raw
+  });
+}
+async function findUserByEmail(adapter, email) {
+  if (!email?.trim()) {
+    return null;
+  }
+  const user = await adapter.findByCredentials({ email: email.trim() });
+  return user ? requireUserRecord(user, "[@holo-js/auth-workos] Auth provider lookups must return object users.") : null;
+}
+async function updateLocalUser(adapter, user, input) {
+  const nextInput = {
+    name: input.name,
+    email: input.email,
+    avatar: typeof input.avatar === "undefined" ? void 0 : input.avatar,
+    email_verified_at: input.emailVerified === true ? /* @__PURE__ */ new Date() : void 0
+  };
+  const current = user;
+  const changed = typeof nextInput.name !== "undefined" && nextInput.name !== current.name || typeof nextInput.email !== "undefined" && nextInput.email !== current.email || typeof nextInput.avatar !== "undefined" && nextInput.avatar !== (current.avatar ?? void 0) || input.emailVerified === true && !current.email_verified_at;
+  if (!changed) {
+    return { user, changed: false };
+  }
+  if (adapter.update) {
+    return {
+      user: requireUserRecord(
+        await adapter.update(user, nextInput),
+        "[@holo-js/auth-workos] Auth provider updates must return object users."
+      ),
+      changed: true
+    };
+  }
+  throw new Error(
+    "[@holo-js/auth-workos] Auth provider adapters must implement update() to persist profile changes."
+  );
+}
+async function ensureNoUnexpectedEmailCollision(adapter, authProvider, profile, currentUserId) {
+  const email = profile.email?.trim();
+  if (!email) {
+    return;
+  }
+  const matched = await findUserByEmail(adapter, email);
+  if (!matched) {
+    return;
+  }
+  if (requireUserId(
+    adapter,
+    matched,
+    "[@holo-js/auth-workos] Matched local users must expose a serializable id."
+  ) !== currentUserId) {
+    throw new WorkosAuthConflictError({
+      provider: "workos",
+      workosUserId: profile.id,
+      email,
+      message: `[@holo-js/auth-workos] WorkOS email "${email}" collides with a different local user.`
+    });
+  }
+}
+async function assertUserLinkAvailable(providerName, authProvider, adapter, user, workosUserId) {
+  const existing = await getBindings().identityStore.findByUserId(
+    providerName,
+    authProvider,
+    requireUserId(adapter, user, "[@holo-js/auth-workos] Linked users must expose a serializable id.")
+  );
+  if (existing && existing.providerUserId !== workosUserId) {
+    throw new WorkosAuthConflictError({
+      provider: providerName,
+      workosUserId,
+      email: existing.email,
+      message: `[@holo-js/auth-workos] Local user is already linked to WorkOS identity "${existing.providerUserId}".`
+    });
+  }
+}
+function isEmailVerificationRequired() {
+  return authRuntimeInternals.getRuntimeBindings().config.emailVerification.required === true;
+}
+function createIdentityRecord(input) {
+  const now = /* @__PURE__ */ new Date();
+  return Object.freeze({
+    provider: input.provider,
+    providerUserId: input.profile.id,
+    guard: input.guard,
+    authProvider: input.authProvider,
+    userId: input.userId,
+    email: input.profile.email,
+    emailVerified: input.profile.emailVerified === true,
+    profile: normalizeHostedProfile(input.profile),
+    linkedAt: input.previous?.linkedAt ?? now,
+    updatedAt: now
+  });
+}
+function getSessionTokenFromRequest(request, sessionCookie) {
+  const authorization = request.headers.get("authorization")?.trim();
+  if (authorization) {
+    const [scheme, token] = authorization.split(/\s+/, 2);
+    if (scheme?.toLowerCase() === "bearer" && token?.trim()) {
+      return token.trim();
+    }
+  }
+  const cookies = parseCookieHeader(request.headers.get("cookie"));
+  return cookies[sessionCookie] ?? null;
+}
+function getHoloSessionIdFromRequest(request) {
+  const cookieHeader = authRuntimeInternals.getRuntimeBindings().session.sessionCookie("");
+  const separator = cookieHeader.indexOf("=");
+  const cookieName = separator > 0 ? decodeURIComponent(cookieHeader.slice(0, separator)) : "";
+  if (!cookieName) {
+    return null;
+  }
+  const cookies = parseCookieHeader(request.headers.get("cookie"));
+  return cookies[cookieName] ?? null;
+}
+async function reuseExistingHoloSession(request, authenticated) {
+  const bindings = authRuntimeInternals.getRuntimeBindings();
+  const sessionId = getHoloSessionIdFromRequest(request);
+  if (!sessionId) {
+    return null;
+  }
+  bindings.context.setSessionId(authenticated.guard, sessionId);
+  const record = await bindings.session.read(sessionId);
+  const payload = authRuntimeInternals.readSessionPayload(record, authenticated.guard);
+  if (!payload || payload.guard !== authenticated.guard || payload.provider !== authenticated.authProvider || String(payload.userId) !== String(authenticated.user.id)) {
+    return null;
+  }
+  bindings.context.setCachedUser(authenticated.guard, authenticated.user);
+  return Object.freeze({
+    guard: authenticated.guard,
+    user: authenticated.user,
+    sessionId,
+    cookies: Object.freeze([])
+  });
+}
+async function verifySession(token, provider) {
+  const providerConfig = getConfiguredProviderConfig(provider);
+  const runtime = getProviderRuntime(providerConfig.name);
+  if (!runtime.verifySession) {
+    throw new Error(`[@holo-js/auth-workos] WorkOS provider runtime "${providerConfig.name}" does not implement verifySession().`);
+  }
+  return runtime.verifySession({
+    provider: providerConfig.name,
+    token,
+    config: providerConfig
+  });
+}
+async function verifyRequest(request, provider) {
+  const providerConfig = getConfiguredProviderConfig(provider);
+  const runtime = getProviderRuntime(providerConfig.name);
+  if (runtime.verifyRequest) {
+    return runtime.verifyRequest({
+      provider: providerConfig.name,
+      request,
+      config: providerConfig
+    });
+  }
+  const token = getSessionTokenFromRequest(request, providerConfig.sessionCookie);
+  if (!token) {
+    return null;
+  }
+  return verifySession(token, providerConfig.name);
+}
+async function syncIdentity(session, provider) {
+  const providerConfig = getConfiguredProviderConfig(provider);
+  const providerName = providerConfig.name;
+  const profile = session.identity;
+  const { guard, authProvider, adapter } = resolveGuardAndProvider(providerName);
+  const verificationRequired = isEmailVerificationRequired();
+  const verifiedEmail = profile.emailVerified === true && profile.email?.trim() ? profile.email.trim() : void 0;
+  if (verificationRequired && !verifiedEmail) {
+    throw new Error(`[@holo-js/auth-workos] WorkOS identity "${profile.id}" must provide a verified email address.`);
+  }
+  const identityStore = getBindings().identityStore;
+  const existingIdentity = await identityStore.findByProviderUserId(providerName, profile.id);
+  if (existingIdentity) {
+    const existingLinkedUser = await adapter.findById(existingIdentity.userId);
+    let linkedUser = existingLinkedUser ? requireUserRecord(existingLinkedUser, "[@holo-js/auth-workos] Auth provider lookups must return object users.") : null;
+    if (!linkedUser) {
+      linkedUser = verifiedEmail ? await findUserByEmail(adapter, verifiedEmail) : null;
+      if (linkedUser) {
+        await assertUserLinkAvailable(providerName, authProvider, adapter, linkedUser, profile.id);
+      }
+      if (!linkedUser) {
+        linkedUser = requireUserRecord(await adapter.create({
+          name: resolveDisplayName(profile),
+          email: resolveEmailForCreation(profile),
+          password: null,
+          avatar: profile.avatar ?? null,
+          email_verified_at: profile.emailVerified === true ? /* @__PURE__ */ new Date() : null
+        }), "[@holo-js/auth-workos] Auth provider create() must return an object user.");
+      }
+      const relinked = await updateLocalUser(adapter, linkedUser, {
+        name: resolveDisplayName(profile),
+        email: profile.email?.trim(),
+        avatar: profile.avatar,
+        emailVerified: profile.emailVerified === true
+      });
+      const relinkedUser = relinked.user;
+      const identity3 = createIdentityRecord({
+        provider: providerName,
+        guard,
+        authProvider,
+        userId: requireUserId(
+          adapter,
+          relinkedUser,
+          "[@holo-js/auth-workos] Relinked local users must expose a serializable id."
+        ),
+        profile,
+        previous: existingIdentity
+      });
+      await identityStore.save(identity3);
+      return Object.freeze({
+        provider: providerName,
+        guard,
+        authProvider,
+        status: "relinked",
+        user: serializeLocalUser(adapter, relinkedUser, authProvider),
+        identity: identity3,
+        session
+      });
+    }
+    await ensureNoUnexpectedEmailCollision(
+      adapter,
+      authProvider,
+      profile,
+      requireUserId(
+        adapter,
+        linkedUser,
+        "[@holo-js/auth-workos] Linked local users must expose a serializable id."
+      )
+    );
+    const updated = await updateLocalUser(adapter, linkedUser, {
+      name: resolveDisplayName(profile),
+      email: profile.email?.trim(),
+      avatar: profile.avatar,
+      emailVerified: profile.emailVerified === true
+    });
+    const identity2 = createIdentityRecord({
+      provider: providerName,
+      guard,
+      authProvider,
+      userId: requireUserId(
+        adapter,
+        updated.user,
+        "[@holo-js/auth-workos] Updated local users must expose a serializable id."
+      ),
+      profile,
+      previous: existingIdentity
+    });
+    await identityStore.save(identity2);
+    return Object.freeze({
+      provider: providerName,
+      guard,
+      authProvider,
+      status: updated.changed ? "updated" : "linked",
+      user: serializeLocalUser(adapter, updated.user, authProvider),
+      identity: identity2,
+      session
+    });
+  }
+  let localUser = verifiedEmail ? await findUserByEmail(adapter, verifiedEmail) : null;
+  if (localUser) {
+    await assertUserLinkAvailable(providerName, authProvider, adapter, localUser, profile.id);
+    const linked = await updateLocalUser(adapter, localUser, {
+      name: resolveDisplayName(profile),
+      email: profile.email?.trim(),
+      avatar: profile.avatar,
+      emailVerified: profile.emailVerified === true
+    });
+    const identity2 = createIdentityRecord({
+      provider: providerName,
+      guard,
+      authProvider,
+      userId: requireUserId(
+        adapter,
+        linked.user,
+        "[@holo-js/auth-workos] Linked local users must expose a serializable id."
+      ),
+      profile
+    });
+    await identityStore.save(identity2);
+    return Object.freeze({
+      provider: providerName,
+      guard,
+      authProvider,
+      status: "linked",
+      user: serializeLocalUser(adapter, linked.user, authProvider),
+      identity: identity2,
+      session
+    });
+  }
+  localUser = requireUserRecord(await adapter.create({
+    name: resolveDisplayName(profile),
+    email: resolveEmailForCreation(profile),
+    password: null,
+    avatar: profile.avatar ?? null,
+    email_verified_at: profile.emailVerified === true ? /* @__PURE__ */ new Date() : null
+  }), "[@holo-js/auth-workos] Auth provider create() must return an object user.");
+  const identity = createIdentityRecord({
+    provider: providerName,
+    guard,
+    authProvider,
+    userId: requireUserId(
+      adapter,
+      localUser,
+      "[@holo-js/auth-workos] Created local users must expose a serializable id."
+    ),
+    profile
+  });
+  await identityStore.save(identity);
+  return Object.freeze({
+    provider: providerName,
+    guard,
+    authProvider,
+    status: "created",
+    user: serializeLocalUser(adapter, localUser, authProvider),
+    identity,
+    session
+  });
+}
+async function authenticate(request, provider) {
+  const session = await verifyRequest(request, provider);
+  if (!session) {
+    return null;
+  }
+  const authenticated = await syncIdentity(session, provider);
+  const authSession = await reuseExistingHoloSession(request, authenticated) ?? await authRuntimeInternals.establishSessionForUser(authenticated.user, {
+    guard: authenticated.guard,
+    provider: authenticated.authProvider
+  });
+  return Object.freeze({
+    ...authenticated,
+    authSession
+  });
+}
+function configureWorkosAuthRuntime(bindings) {
+  if (!bindings) {
+    workosBindings = void 0;
+    return;
+  }
+  workosBindings = Object.freeze({
+    providers: bindings.providers ?? workosBindings?.providers,
+    identityStore: bindings.identityStore ?? workosBindings?.identityStore
+  });
+}
+function resetWorkosAuthRuntime() {
+  workosBindings = void 0;
+}
+var workosAuth = Object.freeze({
+  authenticate,
+  syncIdentity,
+  verifyRequest,
+  verifySession
+});
+var workosAuthInternals = {
+  getBindings,
+  getConfiguredProviderConfig,
+  getSessionTokenFromRequest,
+  normalizeHostedProfile,
+  resolveConfiguredProviderName,
+  resolveDisplayName,
+  resolveEmailForCreation,
+  resolveGuardAndProvider
+};
+export {
+  WorkosAuthConflictError,
+  authenticate,
+  configureWorkosAuthRuntime,
+  resetWorkosAuthRuntime,
+  syncIdentity,
+  verifyRequest,
+  verifySession,
+  workosAuth,
+  workosAuthInternals
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@holo-js/auth-workos",
+  "version": "0.1.3",
+  "description": "Holo-JS Framework - WorkOS auth integration contracts",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@holo-js/auth": "workspace:*",
+    "@holo-js/config": "workspace:*",
+    "@holo-js/session": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}