@holo-js/auth-clerk 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import { AuthUserLike, AuthEstablishedSession, authRuntimeInternals } from '@holo-js/auth';
+import { AuthClerkProviderConfig } from '@holo-js/config';
+
+interface ClerkEmailAddress {
+    readonly id?: string;
+    readonly emailAddress: string;
+    readonly verificationStatus?: 'verified' | 'unverified' | 'pending';
+}
+interface ClerkUserProfile {
+    readonly id: string;
+    readonly email?: string;
+    readonly emailVerified?: boolean;
+    readonly firstName?: string;
+    readonly lastName?: string;
+    readonly name?: string;
+    readonly imageUrl?: string;
+    readonly primaryEmailAddressId?: string;
+    readonly emailAddresses?: readonly ClerkEmailAddress[];
+    readonly raw?: unknown;
+}
+interface ClerkVerifiedSession {
+    readonly sessionId: string;
+    readonly user: ClerkUserProfile;
+    readonly accessToken?: string;
+    readonly actor?: {
+        readonly id?: string;
+        readonly type?: string;
+    };
+    readonly raw?: unknown;
+}
+interface ClerkVerifyRequestContext {
+    readonly provider: string;
+    readonly request: Request;
+    readonly config: AuthClerkProviderConfig;
+}
+interface ClerkVerifySessionContext {
+    readonly provider: string;
+    readonly token: string;
+    readonly config: AuthClerkProviderConfig;
+}
+interface ClerkProviderRuntime {
+    verifyRequest?(context: ClerkVerifyRequestContext): Promise<ClerkVerifiedSession | null>;
+    verifySession?(context: ClerkVerifySessionContext): Promise<ClerkVerifiedSession | 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 ClerkSyncStatus = 'created' | 'updated' | 'linked' | 'relinked';
+interface ClerkAuthenticationResult {
+    readonly provider: string;
+    readonly guard: string;
+    readonly authProvider: string;
+    readonly status: ClerkSyncStatus;
+    readonly user: AuthUserLike;
+    readonly identity: HostedIdentityRecord;
+    readonly session: ClerkVerifiedSession;
+    readonly authSession?: AuthEstablishedSession;
+}
+interface ClerkAuthBindings {
+    readonly providers: Readonly<Record<string, ClerkProviderRuntime>>;
+    readonly identityStore: HostedIdentityStore;
+}
+interface ConfigureClerkAuthRuntimeOptions {
+    readonly providers?: Readonly<Record<string, ClerkProviderRuntime>>;
+    readonly identityStore?: HostedIdentityStore;
+}
+interface ClerkAuthFacade {
+    verifyRequest(request: Request, provider?: string): Promise<ClerkVerifiedSession | null>;
+    verifySession(token: string, provider?: string): Promise<ClerkVerifiedSession | null>;
+    syncIdentity(session: ClerkVerifiedSession, provider?: string): Promise<ClerkAuthenticationResult>;
+    authenticate(request: Request, provider?: string): Promise<ClerkAuthenticationResult | null>;
+}
+declare class ClerkAuthConflictError extends Error {
+    readonly code = "clerk_identity_conflict";
+    readonly provider: string;
+    readonly clerkUserId: string;
+    readonly email?: string;
+    constructor(options: {
+        readonly provider: string;
+        readonly clerkUserId: string;
+        readonly email?: string;
+        readonly message: string;
+    });
+}
+declare function getBindings(): ClerkAuthBindings;
+declare function resolveConfiguredProviderName(provider?: string): string;
+declare function getConfiguredProviderConfig(provider?: string): {
+    readonly name: string;
+    readonly publishableKey?: string;
+    readonly secretKey?: string;
+    readonly jwtKey?: string;
+    readonly apiUrl?: string;
+    readonly frontendApi?: string;
+    readonly sessionCookie: string;
+    readonly authorizedParties: readonly string[];
+    readonly guard?: string;
+    readonly mapToProvider?: string;
+};
+declare function resolveGuardAndProvider(provider?: string): {
+    readonly guard: string;
+    readonly authProvider: string;
+    readonly adapter: RuntimeAuthProviderAdapter;
+};
+declare function resolvePrimaryEmail(profile: ClerkUserProfile): {
+    email?: string;
+    emailVerified: boolean;
+};
+declare function resolveDisplayName(profile: ClerkUserProfile): string | undefined;
+declare function resolveEmailForCreation(profile: ClerkUserProfile): string;
+declare function normalizeHostedProfile(profile: ClerkUserProfile): Readonly<Record<string, unknown>>;
+declare function getSessionTokenFromRequest(request: Request, sessionCookie: string): string | null;
+declare function verifySession(token: string, provider?: string): Promise<ClerkVerifiedSession | null>;
+declare function verifyRequest(request: Request, provider?: string): Promise<ClerkVerifiedSession | null>;
+declare function syncIdentity(session: ClerkVerifiedSession, provider?: string): Promise<ClerkAuthenticationResult>;
+declare function authenticate(request: Request, provider?: string): Promise<ClerkAuthenticationResult | null>;
+declare function configureClerkAuthRuntime(bindings?: ConfigureClerkAuthRuntimeOptions): void;
+declare function resetClerkAuthRuntime(): void;
+declare const clerkAuth: Readonly<{
+    authenticate: typeof authenticate;
+    syncIdentity: typeof syncIdentity;
+    verifyRequest: typeof verifyRequest;
+    verifySession: typeof verifySession;
+}>;
+declare const clerkAuthInternals: {
+    getBindings: typeof getBindings;
+    getConfiguredProviderConfig: typeof getConfiguredProviderConfig;
+    getSessionTokenFromRequest: typeof getSessionTokenFromRequest;
+    normalizeHostedProfile: typeof normalizeHostedProfile;
+    resolveConfiguredProviderName: typeof resolveConfiguredProviderName;
+    resolveDisplayName: typeof resolveDisplayName;
+    resolveEmailForCreation: typeof resolveEmailForCreation;
+    resolveGuardAndProvider: typeof resolveGuardAndProvider;
+    resolvePrimaryEmail: typeof resolvePrimaryEmail;
+};
+
+export { type ClerkAuthBindings, ClerkAuthConflictError, type ClerkAuthFacade, type ClerkAuthenticationResult, type ClerkEmailAddress, type ClerkProviderRuntime, type ClerkSyncStatus, type ClerkUserProfile, type ClerkVerifiedSession, type ClerkVerifyRequestContext, type ClerkVerifySessionContext, type ConfigureClerkAuthRuntimeOptions, type HostedIdentityRecord, type HostedIdentityStore, authenticate, clerkAuth, clerkAuthInternals, configureClerkAuthRuntime, resetClerkAuthRuntime, syncIdentity, verifyRequest, verifySession };

package/dist/index.mjs

@@ -0,0 +1,785 @@
+// src/index.ts
+import { createPublicKey, verify as verifySignature } from "crypto";
+import { authRuntimeInternals } from "@holo-js/auth";
+import { parseCookieHeader } from "@holo-js/session";
+var ClerkAuthConflictError = class extends Error {
+  code = "clerk_identity_conflict";
+  provider;
+  clerkUserId;
+  email;
+  constructor(options) {
+    super(options.message);
+    this.name = "ClerkAuthConflictError";
+    this.provider = options.provider;
+    this.clerkUserId = options.clerkUserId;
+    this.email = options.email;
+  }
+};
+var clerkBindings;
+var CLERK_API_BASE_URL = "https://api.clerk.com";
+var clerkDefaultProviderRuntimeCache = /* @__PURE__ */ new Map();
+var clerkJwksCache = /* @__PURE__ */ new Map();
+var AUTH_PROVIDER_MARKER = /* @__PURE__ */ Symbol.for("holo-js.auth.provider");
+function throwUnconfigured() {
+  throw new Error("[@holo-js/auth-clerk] Clerk auth runtime is not configured yet.");
+}
+function getBindings() {
+  if (!clerkBindings?.identityStore) {
+    throwUnconfigured();
+  }
+  return {
+    providers: clerkBindings.providers ?? {},
+    identityStore: clerkBindings.identityStore
+  };
+}
+function decodeJwtSegment(value, label) {
+  try {
+    return JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+  } catch {
+    throw new Error(`[@holo-js/auth-clerk] Clerk 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-clerk] Clerk 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-clerk] Unsupported Clerk JWT algorithm "${algorithm || "unknown"}".`);
+  }
+}
+function verifyJwtSignatureWithPem(token, pem) {
+  const algorithm = typeof token.header.alg === "string" ? token.header.alg : "";
+  const key = createPublicKey(pem.replace(/\\n/g, "\n"));
+  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-clerk] Unsupported Clerk JWT algorithm "${algorithm || "unknown"}".`);
+  }
+}
+function resolveClerkJwksUrl(config) {
+  const frontendApi = config.frontendApi?.trim();
+  if (frontendApi) {
+    return `${frontendApi.replace(/\/$/, "")}/.well-known/jwks.json`;
+  }
+  const apiUrl = config.apiUrl?.trim() || CLERK_API_BASE_URL;
+  return `${apiUrl.replace(/\/$/, "")}/v1/jwks`;
+}
+async function fetchClerkJwks(jwksUrl, options = {}) {
+  if (options.refresh) {
+    clerkJwksCache.delete(jwksUrl);
+  }
+  const existing = clerkJwksCache.get(jwksUrl);
+  if (existing) {
+    return existing;
+  }
+  const pending = (async () => {
+    const response = await fetch(jwksUrl, {
+      headers: {
+        accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`[@holo-js/auth-clerk] Failed to load Clerk JWKS from "${jwksUrl}".`);
+    }
+    const payload = await response.json();
+    return payload.keys ?? [];
+  })();
+  clerkJwksCache.set(jwksUrl, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    clerkJwksCache.delete(jwksUrl);
+    throw error;
+  }
+}
+async function verifyClerkSessionToken(token, config, authorizedParties = []) {
+  const parsed = parseJwt(token);
+  const verified = (() => {
+    const pem = config.jwtKey?.trim();
+    if (pem) {
+      return verifyJwtSignatureWithPem(parsed, pem);
+    }
+    return void 0;
+  })();
+  if (verified === false) {
+    throw new Error("[@holo-js/auth-clerk] Clerk token signature verification failed.");
+  }
+  if (typeof verified === "undefined") {
+    const headerKid = typeof parsed.header.kid === "string" ? parsed.header.kid : void 0;
+    const jwksUrl = resolveClerkJwksUrl(config);
+    const resolveKey = async (refresh = false) => {
+      const keys = await fetchClerkJwks(jwksUrl, { 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-clerk] Clerk 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-clerk] Clerk 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-clerk] Clerk token is not valid yet.");
+  }
+  const azp = typeof parsed.payload.azp === "string" ? parsed.payload.azp.trim() : "";
+  if (azp) {
+    const allowedAuthorizedParties = authorizedParties.map((value) => value.trim()).filter(Boolean);
+    if (allowedAuthorizedParties.length > 0 && !allowedAuthorizedParties.includes(azp)) {
+      throw new Error(`[@holo-js/auth-clerk] Clerk token authorized party "${azp}" is not allowed.`);
+    }
+  }
+  return parsed.payload;
+}
+function normalizeClerkEmailAddress(value) {
+  const verification = value.verification && typeof value.verification === "object" ? value.verification : void 0;
+  return Object.freeze({
+    id: typeof value.id === "string" ? value.id : void 0,
+    emailAddress: typeof value.emailAddress === "string" ? value.emailAddress : typeof value.email_address === "string" ? value.email_address : "",
+    verificationStatus: typeof value.verificationStatus === "string" ? value.verificationStatus : typeof verification?.status === "string" ? verification.status : void 0
+  });
+}
+function normalizeClerkUserProfile(user) {
+  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: typeof user.firstName === "string" ? user.firstName : typeof user.first_name === "string" ? user.first_name : void 0,
+    lastName: typeof user.lastName === "string" ? user.lastName : typeof user.last_name === "string" ? user.last_name : void 0,
+    name: typeof user.name === "string" ? user.name : void 0,
+    imageUrl: typeof user.imageUrl === "string" ? user.imageUrl : typeof user.image_url === "string" ? user.image_url : void 0,
+    primaryEmailAddressId: typeof user.primaryEmailAddressId === "string" ? user.primaryEmailAddressId : typeof user.primary_email_address_id === "string" ? user.primary_email_address_id : void 0,
+    emailAddresses: Array.isArray(user.emailAddresses) ? user.emailAddresses.map((entry) => normalizeClerkEmailAddress(entry)) : Array.isArray(user.email_addresses) ? user.email_addresses.map((entry) => normalizeClerkEmailAddress(entry)) : void 0,
+    raw: user
+  });
+}
+async function fetchClerkUserProfile(userId, config) {
+  const secretKey = config.secretKey?.trim();
+  if (!secretKey) {
+    throw new Error("[@holo-js/auth-clerk] Clerk verification requires secretKey to be configured.");
+  }
+  const apiBase = config.apiUrl?.trim() || CLERK_API_BASE_URL;
+  const response = await fetch(`${apiBase.replace(/\/$/, "")}/v1/users/${encodeURIComponent(userId)}`, {
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${secretKey}`
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`[@holo-js/auth-clerk] Failed to load Clerk user "${userId}".`);
+  }
+  return normalizeClerkUserProfile(await response.json());
+}
+function createDefaultProviderRuntime(providerName, config) {
+  const cacheKey = JSON.stringify([
+    providerName,
+    config.apiUrl ?? "",
+    config.frontendApi ?? "",
+    config.jwtKey ?? "",
+    config.secretKey ?? "",
+    [...config.authorizedParties ?? []].sort()
+  ]);
+  const existing = clerkDefaultProviderRuntimeCache.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  const runtime = Object.freeze({
+    async verifySession({ token }) {
+      const claims = await verifyClerkSessionToken(token, config, config.authorizedParties);
+      const userId = typeof claims.sub === "string" ? claims.sub : "";
+      if (!userId) {
+        throw new Error("[@holo-js/auth-clerk] Clerk token did not include a subject.");
+      }
+      const profile = await fetchClerkUserProfile(userId, config);
+      const sessionId = typeof claims.sid === "string" ? claims.sid : typeof claims.session_id === "string" ? claims.session_id : token;
+      return Object.freeze({
+        sessionId,
+        user: profile,
+        accessToken: token,
+        raw: Object.freeze({
+          claims,
+          user: profile.raw
+        })
+      });
+    }
+  });
+  clerkDefaultProviderRuntimeCache.set(cacheKey, runtime);
+  return runtime;
+}
+function resolveConfiguredProviderName(provider) {
+  const bindings = authRuntimeInternals.getRuntimeBindings();
+  if (provider?.trim()) {
+    return provider.trim();
+  }
+  const configuredProviders = Object.keys(bindings.config.clerk);
+  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-clerk] Clerk provider name is required when multiple auth.clerk entries exist.");
+}
+function getConfiguredProviderConfig(provider) {
+  const providerName = resolveConfiguredProviderName(provider);
+  const authBindings = authRuntimeInternals.getRuntimeBindings();
+  const configured = authBindings.config.clerk[providerName];
+  if (!configured) {
+    throw new Error(`[@holo-js/auth-clerk] Clerk provider "${providerName}" is not configured in auth.clerk.`);
+  }
+  return {
+    name: providerName,
+    publishableKey: configured.publishableKey,
+    secretKey: configured.secretKey,
+    jwtKey: configured.jwtKey,
+    apiUrl: configured.apiUrl,
+    frontendApi: configured.frontendApi,
+    sessionCookie: configured.sessionCookie,
+    authorizedParties: configured.authorizedParties ?? [],
+    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-clerk] Guard "${guardName}" is not configured for Clerk provider "${providerConfig.name}".`);
+  }
+  if (guard.driver !== "session") {
+    throw new Error(`[@holo-js/auth-clerk] Clerk 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-clerk] 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 resolvePrimaryEmail(profile) {
+  if (profile.email?.trim()) {
+    return {
+      email: profile.email.trim(),
+      emailVerified: profile.emailVerified === true
+    };
+  }
+  const primary = profile.emailAddresses?.find((entry) => entry.id === profile.primaryEmailAddressId) ?? profile.emailAddresses?.[0];
+  if (!primary?.emailAddress?.trim()) {
+    return {
+      email: void 0,
+      emailVerified: false
+    };
+  }
+  return {
+    email: primary.emailAddress.trim(),
+    emailVerified: primary.verificationStatus === "verified"
+  };
+}
+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 primary = resolvePrimaryEmail(profile).email;
+  if (primary) {
+    return primary;
+  }
+  return `${profile.id}@clerk.hosted.local`;
+}
+function normalizeHostedProfile(profile) {
+  const resolvedEmail = resolvePrimaryEmail(profile);
+  return Object.freeze({
+    id: profile.id,
+    email: resolvedEmail.email,
+    emailVerified: resolvedEmail.emailVerified,
+    firstName: profile.firstName,
+    lastName: profile.lastName,
+    name: resolveDisplayName(profile),
+    imageUrl: profile.imageUrl,
+    primaryEmailAddressId: profile.primaryEmailAddressId,
+    emailAddresses: profile.emailAddresses ? [...profile.emailAddresses] : void 0,
+    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-clerk] 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-clerk] Auth provider updates must return object users."
+      ),
+      changed: true
+    };
+  }
+  throw new Error(
+    "[@holo-js/auth-clerk] Auth provider adapters must implement update() to persist profile changes."
+  );
+}
+async function ensureNoUnexpectedEmailCollision(adapter, authProvider, profile, currentUserId) {
+  const resolvedEmail = resolvePrimaryEmail(profile).email;
+  if (!resolvedEmail) {
+    return;
+  }
+  const matched = await findUserByEmail(adapter, resolvedEmail);
+  if (!matched) {
+    return;
+  }
+  if (requireUserId(
+    adapter,
+    matched,
+    "[@holo-js/auth-clerk] Matched local users must expose a serializable id."
+  ) !== currentUserId) {
+    throw new ClerkAuthConflictError({
+      provider: "clerk",
+      clerkUserId: profile.id,
+      email: resolvedEmail,
+      message: `[@holo-js/auth-clerk] Clerk email "${resolvedEmail}" collides with a different local user.`
+    });
+  }
+}
+async function assertUserLinkAvailable(providerName, authProvider, adapter, user, clerkUserId) {
+  const existing = await getBindings().identityStore.findByUserId(
+    providerName,
+    authProvider,
+    requireUserId(adapter, user, "[@holo-js/auth-clerk] Linked users must expose a serializable id.")
+  );
+  if (existing && existing.providerUserId !== clerkUserId) {
+    throw new ClerkAuthConflictError({
+      provider: providerName,
+      clerkUserId,
+      email: existing.email,
+      message: `[@holo-js/auth-clerk] Local user is already linked to Clerk identity "${existing.providerUserId}".`
+    });
+  }
+}
+function isEmailVerificationRequired() {
+  return authRuntimeInternals.getRuntimeBindings().config.emailVerification.required === true;
+}
+function createIdentityRecord(input) {
+  const now = /* @__PURE__ */ new Date();
+  const resolvedEmail = resolvePrimaryEmail(input.profile);
+  return Object.freeze({
+    provider: input.provider,
+    providerUserId: input.profile.id,
+    guard: input.guard,
+    authProvider: input.authProvider,
+    userId: input.userId,
+    email: resolvedEmail.email,
+    emailVerified: resolvedEmail.emailVerified,
+    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-clerk] Clerk 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 configuredRuntime = getBindings().providers[providerConfig.name];
+  const runtime = configuredRuntime ?? 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;
+  }
+  if (configuredRuntime) {
+    if (!configuredRuntime.verifySession) {
+      throw new Error(`[@holo-js/auth-clerk] Clerk provider runtime "${providerConfig.name}" does not implement verifySession().`);
+    }
+    return configuredRuntime.verifySession({
+      provider: providerConfig.name,
+      token,
+      config: providerConfig
+    });
+  }
+  const requestOrigin = new URL(request.url).origin;
+  const defaultRuntime = createDefaultProviderRuntime(providerConfig.name, {
+    ...providerConfig,
+    authorizedParties: Object.freeze([
+      .../* @__PURE__ */ new Set([
+        ...providerConfig.authorizedParties ?? [],
+        requestOrigin
+      ])
+    ])
+  });
+  if (!defaultRuntime.verifySession) {
+    throw new Error(`[@holo-js/auth-clerk] Clerk provider runtime "${providerConfig.name}" does not implement verifySession().`);
+  }
+  return defaultRuntime.verifySession({
+    provider: providerConfig.name,
+    token,
+    config: {
+      ...providerConfig,
+      authorizedParties: Object.freeze([
+        .../* @__PURE__ */ new Set([
+          ...providerConfig.authorizedParties ?? [],
+          requestOrigin
+        ])
+      ])
+    }
+  });
+}
+async function syncIdentity(session, provider) {
+  const providerConfig = getConfiguredProviderConfig(provider);
+  const providerName = providerConfig.name;
+  const profile = session.user;
+  const { guard, authProvider, adapter } = resolveGuardAndProvider(providerName);
+  const verificationRequired = isEmailVerificationRequired();
+  const resolvedEmail = resolvePrimaryEmail(profile);
+  const verifiedEmail = resolvedEmail.emailVerified ? resolvedEmail.email : void 0;
+  if (verificationRequired && !verifiedEmail) {
+    throw new Error(`[@holo-js/auth-clerk] Clerk 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-clerk] 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.imageUrl ?? null,
+          email_verified_at: resolvedEmail.emailVerified ? /* @__PURE__ */ new Date() : null
+        }), "[@holo-js/auth-clerk] Auth provider create() must return an object user.");
+      }
+      const relinked = await updateLocalUser(adapter, linkedUser, {
+        name: resolveDisplayName(profile),
+        email: resolvedEmail.email,
+        avatar: profile.imageUrl,
+        emailVerified: resolvedEmail.emailVerified
+      });
+      const relinkedUser = relinked.user;
+      const identity3 = createIdentityRecord({
+        provider: providerName,
+        guard,
+        authProvider,
+        userId: requireUserId(
+          adapter,
+          relinkedUser,
+          "[@holo-js/auth-clerk] 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-clerk] Linked local users must expose a serializable id."
+      )
+    );
+    const updated = await updateLocalUser(adapter, linkedUser, {
+      name: resolveDisplayName(profile),
+      email: resolvedEmail.email,
+      avatar: profile.imageUrl,
+      emailVerified: resolvedEmail.emailVerified
+    });
+    const identity2 = createIdentityRecord({
+      provider: providerName,
+      guard,
+      authProvider,
+      userId: requireUserId(
+        adapter,
+        updated.user,
+        "[@holo-js/auth-clerk] 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: resolvedEmail.email,
+      avatar: profile.imageUrl,
+      emailVerified: resolvedEmail.emailVerified
+    });
+    const identity2 = createIdentityRecord({
+      provider: providerName,
+      guard,
+      authProvider,
+      userId: requireUserId(
+        adapter,
+        linked.user,
+        "[@holo-js/auth-clerk] 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.imageUrl ?? null,
+    email_verified_at: resolvedEmail.emailVerified ? /* @__PURE__ */ new Date() : null
+  }), "[@holo-js/auth-clerk] Auth provider create() must return an object user.");
+  const identity = createIdentityRecord({
+    provider: providerName,
+    guard,
+    authProvider,
+    userId: requireUserId(
+      adapter,
+      localUser,
+      "[@holo-js/auth-clerk] 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 configureClerkAuthRuntime(bindings) {
+  if (!bindings) {
+    clerkBindings = void 0;
+    return;
+  }
+  clerkBindings = Object.freeze({
+    providers: bindings.providers ?? clerkBindings?.providers,
+    identityStore: bindings.identityStore ?? clerkBindings?.identityStore
+  });
+}
+function resetClerkAuthRuntime() {
+  clerkBindings = void 0;
+}
+var clerkAuth = Object.freeze({
+  authenticate,
+  syncIdentity,
+  verifyRequest,
+  verifySession
+});
+var clerkAuthInternals = {
+  getBindings,
+  getConfiguredProviderConfig,
+  getSessionTokenFromRequest,
+  normalizeHostedProfile,
+  resolveConfiguredProviderName,
+  resolveDisplayName,
+  resolveEmailForCreation,
+  resolveGuardAndProvider,
+  resolvePrimaryEmail
+};
+export {
+  ClerkAuthConflictError,
+  authenticate,
+  clerkAuth,
+  clerkAuthInternals,
+  configureClerkAuthRuntime,
+  resetClerkAuthRuntime,
+  syncIdentity,
+  verifyRequest,
+  verifySession
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@holo-js/auth-clerk",
+  "version": "0.1.3",
+  "description": "Holo-JS Framework - Clerk 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"
+  }
+}