@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/dist/{component/server/implementation → server}/sessions.js

@@ -1,10 +1,11 @@
-import { LOG_LEVELS, TOKEN_SUB_CLAIM_DIVIDER, logWithLevel, maybeRedact, stringToNumber } from "./utils.js";
-import { generateToken } from "./tokens.js";
+import { LOG_LEVELS, REFRESH_TOKEN_DIVIDER, TOKEN_SUB_CLAIM_DIVIDER, logWithLevel, maybeRedact } from "./utils.js";
 import { authDb } from "./db.js";
-import { createRefreshToken, deleteAllRefreshTokens, formatRefreshToken } from "./refresh.js";
+import { createRefreshToken } from "./refresh.js";
+import { generateToken } from "./tokens.js";
 
-//#region src/server/implementation/sessions.ts
+//#region src/server/sessions.ts
 const DEFAULT_SESSION_TOTAL_DURATION_MS = 1e3 * 60 * 60 * 24 * 30;
+/** @internal */
 async function maybeGenerateTokensForSession(ctx, config, userId, sessionId, generateTokens) {
 	return {
 		userId,
@@ -17,6 +18,7 @@ async function maybeGenerateTokensForSession(ctx, config, userId, sessionId, gen
 		}) : null
 	};
 }
+/** @internal */
 async function createNewAndDeleteExistingSession(ctx, config, userId) {
 	const db = authDb(ctx, config);
 	const existingSessionId = await getAuthSessionId(ctx);
@@ -26,6 +28,7 @@ async function createNewAndDeleteExistingSession(ctx, config, userId) {
 	}
 	return await createSession(ctx, userId, config);
 }
+/** @internal */
 async function generateTokensForSession(ctx, config, args) {
 	const ids = {
 		userId: args.userId,
@@ -34,25 +37,28 @@ async function generateTokensForSession(ctx, config, args) {
 	const refreshTokenId = args.issuedRefreshTokenId ?? await createRefreshToken(ctx, config, args.sessionId, args.parentRefreshTokenId);
 	const result = {
 		token: await generateToken(ids, config),
-		refreshToken: formatRefreshToken(refreshTokenId, args.sessionId)
+		refreshToken: `${refreshTokenId}${REFRESH_TOKEN_DIVIDER}${args.sessionId}`
 	};
 	logWithLevel(LOG_LEVELS.DEBUG, `Generated token ${maybeRedact(result.token)} and refresh token ${maybeRedact(refreshTokenId)} for session ${maybeRedact(args.sessionId)}`);
 	return result;
 }
 async function createSession(ctx, userId, config) {
 	const db = authDb(ctx, config);
-	const expirationTime = Date.now() + (config.session?.totalDurationMs ?? stringToNumber(process.env.AUTH_SESSION_TOTAL_DURATION_MS) ?? DEFAULT_SESSION_TOTAL_DURATION_MS);
+	const expirationTime = Date.now() + (config.session?.totalDurationMs ?? (process.env.AUTH_SESSION_TOTAL_DURATION_MS !== void 0 ? Number(process.env.AUTH_SESSION_TOTAL_DURATION_MS) : void 0) ?? DEFAULT_SESSION_TOTAL_DURATION_MS);
 	return await db.sessions.create(userId, expirationTime);
 }
+/** @internal */
 async function deleteSession(ctx, session, config) {
-	await authDb(ctx, config).sessions.delete(session._id);
-	await deleteAllRefreshTokens(ctx, session._id, config);
+	const db = authDb(ctx, config);
+	await db.sessions.delete(session._id);
+	await db.refreshTokens.deleteAll(session._id);
 }
 /**
 * Return the current session ID from the auth identity subject.
 *
 * Internal helper used by auth runtime internals and `auth.session.current`.
 */
+/** @internal */
 async function getAuthSessionId(ctx) {
 	const identity = await ctx.auth.getUserIdentity();
 	if (identity === null) return null;

package/dist/server/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","names":[],"sources":["../../src/server/sessions.ts"],"sourcesContent":["import { Auth } from \"convex/server\";\nimport { GenericId } from \"convex/values\";\n\nimport { authDb } from \"./db\";\nimport { createRefreshToken } from \"./refresh\";\nimport { generateToken } from \"./tokens\";\nimport { Doc, MutationCtx, SessionInfo } from \"./types\";\nimport { ConvexAuthConfig } from \"./types\";\nimport {\n  LOG_LEVELS,\n  TOKEN_SUB_CLAIM_DIVIDER,\n  REFRESH_TOKEN_DIVIDER,\n  logWithLevel,\n  maybeRedact,\n} from \"./utils\";\n\nconst DEFAULT_SESSION_TOTAL_DURATION_MS = 1000 * 60 * 60 * 24 * 30; // 30 days\n\n/** @internal */\nexport async function maybeGenerateTokensForSession(\n  ctx: MutationCtx,\n  config: ConvexAuthConfig,\n  userId: GenericId<\"User\">,\n  sessionId: GenericId<\"Session\">,\n  generateTokens: boolean,\n): Promise<SessionInfo> {\n  return {\n    userId,\n    sessionId,\n    tokens: generateTokens\n      ? await generateTokensForSession(ctx, config, {\n          userId,\n          sessionId,\n          issuedRefreshTokenId: null,\n          parentRefreshTokenId: null,\n        })\n      : null,\n  };\n}\n\n/** @internal */\nexport async function createNewAndDeleteExistingSession(\n  ctx: MutationCtx,\n  config: ConvexAuthConfig,\n  userId: GenericId<\"User\">,\n) {\n  const db = authDb(ctx, config);\n  const existingSessionId = await getAuthSessionId(ctx);\n  if (existingSessionId !== null) {\n    const existingSession = await db.sessions.getById(existingSessionId);\n    if (existingSession !== null) {\n      await deleteSession(ctx, existingSession, config);\n    }\n  }\n  return await createSession(ctx, userId, config);\n}\n\n/** @internal */\nexport async function generateTokensForSession(\n  ctx: MutationCtx,\n  config: ConvexAuthConfig,\n  args: {\n    userId: GenericId<\"User\">;\n    sessionId: GenericId<\"Session\">;\n    issuedRefreshTokenId: GenericId<\"RefreshToken\"> | null;\n    parentRefreshTokenId: GenericId<\"RefreshToken\"> | null;\n  },\n) {\n  const ids = { userId: args.userId, sessionId: args.sessionId };\n  const refreshTokenId =\n    args.issuedRefreshTokenId ??\n    (await createRefreshToken(\n      ctx,\n      config,\n      args.sessionId,\n      args.parentRefreshTokenId,\n    ));\n  const result = {\n    token: await generateToken(ids, config),\n    refreshToken: `${refreshTokenId}${REFRESH_TOKEN_DIVIDER}${args.sessionId}`,\n  };\n  logWithLevel(\n    LOG_LEVELS.DEBUG,\n    `Generated token ${maybeRedact(result.token)} and refresh token ${maybeRedact(refreshTokenId)} for session ${maybeRedact(args.sessionId)}`,\n  );\n  return result;\n}\n\nasync function createSession(\n  ctx: MutationCtx,\n  userId: GenericId<\"User\">,\n  config: ConvexAuthConfig,\n) {\n  const db = authDb(ctx, config);\n  const expirationTime =\n    Date.now() +\n    (config.session?.totalDurationMs ??\n      (process.env.AUTH_SESSION_TOTAL_DURATION_MS !== undefined\n        ? Number(process.env.AUTH_SESSION_TOTAL_DURATION_MS)\n        : undefined) ??\n      DEFAULT_SESSION_TOTAL_DURATION_MS);\n  return (await db.sessions.create(\n    userId,\n    expirationTime,\n  )) as GenericId<\"Session\">;\n}\n\n/** @internal */\nexport async function deleteSession(\n  ctx: MutationCtx,\n  session: Doc<\"Session\">,\n  config: ConvexAuthConfig,\n) {\n  const db = authDb(ctx, config);\n  await db.sessions.delete(session._id);\n  await db.refreshTokens.deleteAll(session._id);\n}\n\n/**\n * Return the current session ID from the auth identity subject.\n *\n * Internal helper used by auth runtime internals and `auth.session.current`.\n */\n/** @internal */\nexport async function getAuthSessionId(ctx: { auth: Auth }) {\n  const identity = await ctx.auth.getUserIdentity();\n  if (identity === null) {\n    return null;\n  }\n  const [, sessionId] = identity.subject.split(TOKEN_SUB_CLAIM_DIVIDER);\n  return sessionId as GenericId<\"Session\">;\n}\n"],"mappings":";;;;;;AAgBA,MAAM,oCAAoC,MAAO,KAAK,KAAK,KAAK;;AAGhE,eAAsB,8BACpB,KACA,QACA,QACA,WACA,gBACsB;AACtB,QAAO;EACL;EACA;EACA,QAAQ,iBACJ,MAAM,yBAAyB,KAAK,QAAQ;GAC1C;GACA;GACA,sBAAsB;GACtB,sBAAsB;GACvB,CAAC,GACF;EACL;;;AAIH,eAAsB,kCACpB,KACA,QACA,QACA;CACA,MAAM,KAAK,OAAO,KAAK,OAAO;CAC9B,MAAM,oBAAoB,MAAM,iBAAiB,IAAI;AACrD,KAAI,sBAAsB,MAAM;EAC9B,MAAM,kBAAkB,MAAM,GAAG,SAAS,QAAQ,kBAAkB;AACpE,MAAI,oBAAoB,KACtB,OAAM,cAAc,KAAK,iBAAiB,OAAO;;AAGrD,QAAO,MAAM,cAAc,KAAK,QAAQ,OAAO;;;AAIjD,eAAsB,yBACpB,KACA,QACA,MAMA;CACA,MAAM,MAAM;EAAE,QAAQ,KAAK;EAAQ,WAAW,KAAK;EAAW;CAC9D,MAAM,iBACJ,KAAK,wBACJ,MAAM,mBACL,KACA,QACA,KAAK,WACL,KAAK,qBACN;CACH,MAAM,SAAS;EACb,OAAO,MAAM,cAAc,KAAK,OAAO;EACvC,cAAc,GAAG,iBAAiB,wBAAwB,KAAK;EAChE;AACD,cACE,WAAW,OACX,mBAAmB,YAAY,OAAO,MAAM,CAAC,qBAAqB,YAAY,eAAe,CAAC,eAAe,YAAY,KAAK,UAAU,GACzI;AACD,QAAO;;AAGT,eAAe,cACb,KACA,QACA,QACA;CACA,MAAM,KAAK,OAAO,KAAK,OAAO;CAC9B,MAAM,iBACJ,KAAK,KAAK,IACT,OAAO,SAAS,oBACd,QAAQ,IAAI,mCAAmC,SAC5C,OAAO,QAAQ,IAAI,+BAA+B,GAClD,WACJ;AACJ,QAAQ,MAAM,GAAG,SAAS,OACxB,QACA,eACD;;;AAIH,eAAsB,cACpB,KACA,SACA,QACA;CACA,MAAM,KAAK,OAAO,KAAK,OAAO;AAC9B,OAAM,GAAG,SAAS,OAAO,QAAQ,IAAI;AACrC,OAAM,GAAG,cAAc,UAAU,QAAQ,IAAI;;;;;;;;AAS/C,eAAsB,iBAAiB,KAAqB;CAC1D,MAAM,WAAW,MAAM,IAAI,KAAK,iBAAiB;AACjD,KAAI,aAAa,KACf,QAAO;CAET,MAAM,GAAG,aAAa,SAAS,QAAQ,MAAM,wBAAwB;AACrE,QAAO"}

package/dist/server/signin.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/server/signin.js

@@ -0,0 +1,201 @@
+import { AuthError } from "./authError.js";
+import { generateRandomString, requireEnv } from "./utils.js";
+import { callCreateVerificationCode } from "./mutations/code.js";
+import { callRefreshSession } from "./mutations/refresh.js";
+import { callVerifierSignature } from "./mutations/signature.js";
+import { callSignIn } from "./mutations/signin.js";
+import { callVerifier } from "./mutations/verifier.js";
+import { callVerifyCodeAndSignIn } from "./mutations/verify.js";
+import { queryTotpVerifiedByUserId } from "./types.js";
+import { handleDevice } from "./device.js";
+import { handlePasskeyFx } from "./passkey.js";
+import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects.js";
+import { handleTotp } from "./totp.js";
+import { Fx } from "@robelest/fx";
+
+//#region src/server/signin.ts
+const DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 3600 * 24;
+/** @internal */
+async function signInImpl(ctx, provider, args, options) {
+	const fx = signInFx(ctx, provider, args, options);
+	return Fx.run(fx.pipe(Fx.recover((e) => Fx.fatal(e.toConvexError()))));
+}
+/**
+* Core sign-in pipeline as an Fx generator.
+*
+* Handles: refresh tokens, verification codes, then dispatches by
+* provider type using a dispatch map (no if-chain).
+*/
+function signInFx(ctx, provider, args, options) {
+	return Fx.gen(function* () {
+		if (provider === null && args.refreshToken) {
+			const tokens = yield* Fx.promise(() => callRefreshSession(ctx, { refreshToken: args.refreshToken }));
+			if (tokens === null) return {
+				kind: "signedIn",
+				signedIn: null
+			};
+			return {
+				kind: "refreshTokens",
+				signedIn: { tokens }
+			};
+		}
+		if (provider === null && args.params?.code !== void 0) return {
+			kind: "signedIn",
+			signedIn: yield* Fx.promise(() => callVerifyCodeAndSignIn(ctx, {
+				params: args.params,
+				verifier: args.verifier,
+				generateTokens: true,
+				allowExtraProviders: options.allowExtraProviders
+			}))
+		};
+		const resolvedProvider = yield* provider != null ? Fx.succeed(provider) : Fx.fail(new AuthError("SIGN_IN_MISSING_PARAMS"));
+		return yield* Fx.match(resolvedProvider).on("type", {
+			email: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),
+			phone: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),
+			credentials: (p) => handleCredentialsFx(ctx, p, args, options),
+			oauth: (p) => handleOAuthProviderFx(ctx, p, args, options),
+			passkey: (p) => handlePasskeyFx(ctx, p, args),
+			totp: (p) => handleTotp(ctx, p, args),
+			device: (p) => handleDevice(ctx, p, args),
+			sso: (_p) => handleSsoProviderFx(ctx, args)
+		});
+	});
+}
+function handleEmailAndPhoneProviderFx(ctx, provider, args, options) {
+	return Fx.gen(function* () {
+		if (args.params?.code !== void 0) {
+			const result = yield* Fx.promise(() => callVerifyCodeAndSignIn(ctx, {
+				params: args.params,
+				provider: provider.id,
+				generateTokens: options.generateTokens,
+				allowExtraProviders: options.allowExtraProviders
+			}));
+			return {
+				kind: "signedIn",
+				signedIn: yield* result != null ? Fx.succeed(result) : Fx.fail(new AuthError("INVALID_VERIFICATION_CODE"))
+			};
+		}
+		const code = provider.generateVerificationToken ? yield* Fx.from({
+			ok: async () => provider.generateVerificationToken(),
+			err: () => new AuthError("INTERNAL_ERROR", "Failed to generate verification token")
+		}) : generateRandomString(32, "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz");
+		const expirationTime = Date.now() + (provider.maxAge ?? DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S) * 1e3;
+		const verificationArgs = {
+			identifier: yield* Fx.promise(() => callCreateVerificationCode(ctx, {
+				provider: provider.id,
+				accountId: args.accountId,
+				email: args.params?.email,
+				phone: args.params?.phone,
+				code,
+				expirationTime,
+				allowExtraProviders: options.allowExtraProviders
+			})),
+			url: setURLSearchParam(yield* Fx.promise(() => redirectAbsoluteUrl(ctx.auth.config, args.params ?? {})), "code", code),
+			token: code,
+			expires: new Date(expirationTime)
+		};
+		yield* Fx.match(provider).on("type", {
+			email: (p) => Fx.from({
+				ok: async () => p.sendVerificationRequest({
+					...verificationArgs,
+					provider: p,
+					request: new Request("http://localhost")
+				}, ctx),
+				err: () => new AuthError("INTERNAL_ERROR", "Failed to send email code")
+			}),
+			phone: (p) => Fx.from({
+				ok: async () => p.sendVerificationRequest({
+					...verificationArgs,
+					provider: p
+				}, ctx),
+				err: () => new AuthError("INTERNAL_ERROR", "Failed to send phone code")
+			})
+		});
+		return {
+			kind: "started",
+			started: true
+		};
+	});
+}
+function handleCredentialsFx(ctx, provider, args, options) {
+	return Fx.gen(function* () {
+		const result = yield* Fx.promise(() => provider.authorize(args.params ?? {}, ctx));
+		if (result === null) return {
+			kind: "signedIn",
+			signedIn: null
+		};
+		if (yield* Fx.promise(async () => {
+			return await queryTotpVerifiedByUserId(ctx, result.userId) !== null;
+		})) {
+			yield* Fx.promise(() => callSignIn(ctx, {
+				userId: result.userId,
+				sessionId: result.sessionId,
+				generateTokens: false
+			}));
+			const verifier = yield* Fx.promise(() => callVerifier(ctx));
+			yield* Fx.promise(() => callVerifierSignature(ctx, {
+				verifier,
+				signature: JSON.stringify({ userId: result.userId })
+			}));
+			return {
+				kind: "totpRequired",
+				verifier
+			};
+		}
+		return {
+			kind: "signedIn",
+			signedIn: yield* Fx.promise(() => callSignIn(ctx, {
+				userId: result.userId,
+				sessionId: result.sessionId,
+				generateTokens: options.generateTokens
+			}))
+		};
+	});
+}
+function handleOAuthProviderFx(ctx, provider, args, options) {
+	return Fx.gen(function* () {
+		if (args.params?.code !== void 0) return {
+			kind: "signedIn",
+			signedIn: yield* Fx.promise(() => callVerifyCodeAndSignIn(ctx, {
+				params: args.params,
+				verifier: args.verifier,
+				generateTokens: true,
+				allowExtraProviders: options.allowExtraProviders
+			}))
+		};
+		const redirect = new URL((process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv("CONVEX_SITE_URL")) + `/api/auth/signin/${provider.id}`);
+		const verifier = yield* Fx.promise(() => callVerifier(ctx));
+		redirect.searchParams.set("code", verifier);
+		if (args.params?.redirectTo !== void 0) {
+			yield* Fx.guard(typeof args.params.redirectTo !== "string", Fx.fail(new AuthError("INVALID_REDIRECT", `Expected \`redirectTo\` to be a string, got ${args.params.redirectTo}`)));
+			redirect.searchParams.set("redirectTo", args.params.redirectTo);
+		}
+		return {
+			kind: "redirect",
+			redirect: redirect.toString(),
+			verifier
+		};
+	});
+}
+function handleSsoProviderFx(ctx, args) {
+	return Fx.gen(function* () {
+		const enterpriseId = args.params?.enterpriseId;
+		if (!enterpriseId || typeof enterpriseId !== "string") return yield* Fx.fail(new AuthError("SIGN_IN_MISSING_PARAMS", "enterpriseId is required for SSO sign-in."));
+		const protocol = args.params?.protocol ?? "oidc";
+		if (protocol !== "oidc" && protocol !== "saml") return yield* Fx.fail(new AuthError("SIGN_IN_MISSING_PARAMS", `Invalid SSO protocol: ${protocol}. Expected "oidc" or "saml".`));
+		const verifier = yield* Fx.promise(() => callVerifier(ctx));
+		const siteUrl = process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv("CONVEX_SITE_URL");
+		const redirect = new URL(`${siteUrl}/api/auth/sso/${enterpriseId}/${protocol}/signin`);
+		redirect.searchParams.set("code", verifier);
+		if (typeof args.params?.redirectTo === "string") redirect.searchParams.set("redirectTo", args.params.redirectTo);
+		return {
+			kind: "redirect",
+			redirect: redirect.toString(),
+			verifier
+		};
+	});
+}
+
+//#endregion
+export { signInImpl };
+//# sourceMappingURL=signin.js.map

package/dist/server/signin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signin.js","names":[],"sources":["../../src/server/signin.ts"],"sourcesContent":["import type { Fx as FxType } from \"@robelest/fx\";\nimport { GenericId } from \"convex/values\";\n\nimport { handleDevice } from \"./device\";\nimport { Fx } from \"@robelest/fx\";\n\nimport { AuthError } from \"./authError\";\nimport {\n  callCreateVerificationCode,\n  callRefreshSession,\n  callSignIn,\n  callVerifier,\n  callVerifierSignature,\n  callVerifyCodeAndSignIn,\n} from \"./mutations/index\";\nimport { handlePasskeyFx } from \"./passkey\";\nimport { redirectAbsoluteUrl, setURLSearchParam } from \"./redirects\";\nimport { handleTotp } from \"./totp\";\nimport {\n  AuthProviderMaterializedConfig,\n  ConvexCredentialsConfig,\n  EmailConfig,\n  GenericActionCtxWithAuthConfig,\n  PhoneConfig,\n} from \"./types\";\nimport {\n  AuthDataModel,\n  SessionInfo,\n  SessionInfoWithTokens,\n  Tokens,\n  queryTotpVerifiedByUserId,\n} from \"./types\";\nimport type { OAuthMaterializedConfig } from \"./types\";\nimport { generateRandomString } from \"./utils\";\nimport { requireEnv } from \"./utils\";\n\nconst DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 60 * 60 * 24; // 24 hours\n\ntype EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;\n\ntype SignInResult =\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | { kind: \"refreshTokens\"; signedIn: { tokens: Tokens } }\n  | { kind: \"started\"; started: true }\n  | { kind: \"redirect\"; redirect: string; verifier: string }\n  | { kind: \"passkeyOptions\"; options: Record<string, any>; verifier: string }\n  | { kind: \"totpRequired\"; verifier: string }\n  | {\n      kind: \"totpSetup\";\n      uri: string;\n      secret: string;\n      verifier: string;\n      totpId: string;\n    }\n  | {\n      kind: \"deviceCode\";\n      deviceCode: string;\n      userCode: string;\n      verificationUri: string;\n      verificationUriComplete: string;\n      expiresIn: number;\n      interval: number;\n    };\n\n/** @internal */\nexport async function signInImpl(\n  ctx: EnrichedActionCtx,\n  provider: AuthProviderMaterializedConfig | null,\n  args: {\n    accountId?: GenericId<\"Account\">;\n    params?: Record<string, any>;\n    verifier?: string;\n    refreshToken?: string;\n    calledBy?: string;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): Promise<SignInResult> {\n  const fx = signInFx(ctx, provider, args, options);\n  return Fx.run(\n    fx.pipe(Fx.recover((e) => Fx.fatal((e as AuthError).toConvexError()))),\n  );\n}\n\n/**\n * Core sign-in pipeline as an Fx generator.\n *\n * Handles: refresh tokens, verification codes, then dispatches by\n * provider type using a dispatch map (no if-chain).\n */\nfunction signInFx(\n  ctx: EnrichedActionCtx,\n  provider: AuthProviderMaterializedConfig | null,\n  args: {\n    accountId?: GenericId<\"Account\">;\n    params?: Record<string, any>;\n    verifier?: string;\n    refreshToken?: string;\n    calledBy?: string;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): FxType<SignInResult, AuthError> {\n  return Fx.gen(function* () {\n    // --- Refresh token (no provider) ---\n    if (provider === null && args.refreshToken) {\n      const tokens = yield* Fx.promise(() =>\n        callRefreshSession(ctx, { refreshToken: args.refreshToken! }),\n      );\n      if (tokens === null) {\n        return { kind: \"signedIn\" as const, signedIn: null };\n      }\n      return { kind: \"refreshTokens\" as const, signedIn: { tokens } };\n    }\n\n    // --- Verify code (no provider, code present) ---\n    if (provider === null && args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          verifier: args.verifier,\n          generateTokens: true,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      return { kind: \"signedIn\" as const, signedIn: result };\n    }\n\n    // --- Provider is required past this point ---\n    const resolvedProvider = yield* provider != null\n      ? Fx.succeed(provider)\n      : Fx.fail(new AuthError(\"SIGN_IN_MISSING_PARAMS\"));\n\n    // --- Dispatch by provider type ---\n    return yield* Fx.match(resolvedProvider).on(\"type\", {\n      email: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),\n      phone: (p) => handleEmailAndPhoneProviderFx(ctx, p, args, options),\n      credentials: (p) => handleCredentialsFx(ctx, p, args, options),\n      oauth: (p) => handleOAuthProviderFx(ctx, p, args, options),\n      passkey: (p) => handlePasskeyFx(ctx, p, args),\n      totp: (p) => handleTotp(ctx, p, args),\n      device: (p) => handleDevice(ctx, p, args),\n      sso: (_p) => handleSsoProviderFx(ctx, args),\n    });\n  });\n}\n\n// ============================================================================\n// Email / Phone\n// ============================================================================\n\nfunction handleEmailAndPhoneProviderFx(\n  ctx: EnrichedActionCtx,\n  provider: EmailConfig | PhoneConfig,\n  args: {\n    params?: Record<string, any>;\n    accountId?: GenericId<\"Account\">;\n  },\n  options: {\n    generateTokens: boolean;\n    allowExtraProviders: boolean;\n  },\n): FxType<\n  | { kind: \"started\"; started: true }\n  | { kind: \"signedIn\"; signedIn: SessionInfoWithTokens },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    // --- Code verification path ---\n    if (args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          provider: provider.id,\n          generateTokens: options.generateTokens,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      const verified = yield* result != null\n        ? Fx.succeed(result)\n        : Fx.fail(new AuthError(\"INVALID_VERIFICATION_CODE\"));\n      return {\n        kind: \"signedIn\" as const,\n        signedIn: verified as SessionInfoWithTokens,\n      };\n    }\n\n    // --- Send verification code path ---\n    const alphabet =\n      \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\";\n    const code = provider.generateVerificationToken\n      ? yield* Fx.from({\n          ok: async () => provider.generateVerificationToken!(),\n          err: () =>\n            new AuthError(\n              \"INTERNAL_ERROR\",\n              \"Failed to generate verification token\",\n            ),\n        })\n      : generateRandomString(32, alphabet);\n    const expirationTime =\n      Date.now() +\n      (provider.maxAge ?? DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S) * 1000;\n\n    const identifier = yield* Fx.promise(() =>\n      callCreateVerificationCode(ctx, {\n        provider: provider.id,\n        accountId: args.accountId,\n        email: args.params?.email,\n        phone: args.params?.phone,\n        code,\n        expirationTime,\n        allowExtraProviders: options.allowExtraProviders,\n      }),\n    );\n    const destination = yield* Fx.promise(() =>\n      redirectAbsoluteUrl(\n        ctx.auth.config,\n        (args.params ?? {}) as { redirectTo: unknown },\n      ),\n    );\n    const verificationArgs = {\n      identifier,\n      url: setURLSearchParam(destination, \"code\", code),\n      token: code,\n      expires: new Date(expirationTime),\n    };\n    yield* Fx.match(provider).on(\"type\", {\n      email: (p) =>\n        Fx.from({\n          ok: async () =>\n            p.sendVerificationRequest(\n              {\n                ...verificationArgs,\n                provider: p,\n                request: new Request(\"http://localhost\"),\n              },\n              ctx,\n            ),\n          err: () =>\n            new AuthError(\"INTERNAL_ERROR\", \"Failed to send email code\"),\n        }),\n      phone: (p) =>\n        Fx.from({\n          ok: async () =>\n            p.sendVerificationRequest(\n              { ...verificationArgs, provider: p },\n              ctx,\n            ),\n          err: () =>\n            new AuthError(\"INTERNAL_ERROR\", \"Failed to send phone code\"),\n        }),\n    });\n    return { kind: \"started\" as const, started: true as const };\n  });\n}\n\n// ============================================================================\n// Credentials\n// ============================================================================\n\nfunction handleCredentialsFx(\n  ctx: EnrichedActionCtx,\n  provider: ConvexCredentialsConfig,\n  args: {\n    params?: Record<string, any>;\n  },\n  options: {\n    generateTokens: boolean;\n  },\n): FxType<\n  | { kind: \"signedIn\"; signedIn: SessionInfo | null }\n  | { kind: \"totpRequired\"; verifier: string },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    const result = yield* Fx.promise(() =>\n      provider.authorize(args.params ?? {}, ctx),\n    );\n    if (result === null) {\n      return { kind: \"signedIn\" as const, signedIn: null };\n    }\n\n    // Check if user has TOTP 2FA enrolled before issuing tokens\n    const hasTotpEnrolled = yield* Fx.promise(async () => {\n      const totpDoc = await queryTotpVerifiedByUserId(ctx, result.userId);\n      return totpDoc !== null;\n    });\n    if (hasTotpEnrolled) {\n      // Create session but withhold tokens — TOTP verification needed\n      yield* Fx.promise(() =>\n        callSignIn(ctx, {\n          userId: result.userId,\n          sessionId: result.sessionId,\n          generateTokens: false,\n        }),\n      );\n      // Store userId in verifier so the TOTP verify flow can complete sign-in\n      const verifier = yield* Fx.promise(() => callVerifier(ctx));\n      yield* Fx.promise(() =>\n        callVerifierSignature(ctx, {\n          verifier,\n          signature: JSON.stringify({ userId: result.userId }),\n        }),\n      );\n      return { kind: \"totpRequired\" as const, verifier };\n    }\n\n    const idsAndTokens = yield* Fx.promise(() =>\n      callSignIn(ctx, {\n        userId: result.userId,\n        sessionId: result.sessionId,\n        generateTokens: options.generateTokens,\n      }),\n    );\n    return { kind: \"signedIn\" as const, signedIn: idsAndTokens };\n  });\n}\n\n// ============================================================================\n// OAuth\n// ============================================================================\n\nfunction handleOAuthProviderFx(\n  ctx: EnrichedActionCtx,\n  provider: OAuthMaterializedConfig,\n  args: {\n    params?: Record<string, any>;\n    verifier?: string;\n  },\n  options: {\n    allowExtraProviders: boolean;\n  },\n): FxType<\n  | { kind: \"signedIn\"; signedIn: SessionInfoWithTokens | null }\n  | { kind: \"redirect\"; redirect: string; verifier: string },\n  AuthError\n> {\n  return Fx.gen(function* () {\n    // --- Code verification path ---\n    if (args.params?.code !== undefined) {\n      const result = yield* Fx.promise(() =>\n        callVerifyCodeAndSignIn(ctx, {\n          params: args.params,\n          verifier: args.verifier,\n          generateTokens: true,\n          allowExtraProviders: options.allowExtraProviders,\n        }),\n      );\n      return {\n        kind: \"signedIn\" as const,\n        signedIn: result as SessionInfoWithTokens | null,\n      };\n    }\n\n    // --- Build redirect URL ---\n    const redirect = new URL(\n      (process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv(\"CONVEX_SITE_URL\")) +\n        `/api/auth/signin/${provider.id}`,\n    );\n    const verifier = yield* Fx.promise(() => callVerifier(ctx));\n    redirect.searchParams.set(\"code\", verifier);\n\n    if (args.params?.redirectTo !== undefined) {\n      yield* Fx.guard(\n        typeof args.params.redirectTo !== \"string\",\n        Fx.fail(\n          new AuthError(\n            \"INVALID_REDIRECT\",\n            `Expected \\`redirectTo\\` to be a string, got ${args.params.redirectTo}`,\n          ),\n        ),\n      );\n      redirect.searchParams.set(\"redirectTo\", args.params.redirectTo);\n    }\n\n    return {\n      kind: \"redirect\" as const,\n      redirect: redirect.toString(),\n      verifier,\n    };\n  });\n}\n\n// ============================================================================\n// SSO (Enterprise OIDC / SAML)\n// ============================================================================\n\nfunction handleSsoProviderFx(\n  ctx: EnrichedActionCtx,\n  args: {\n    params?: Record<string, any>;\n  },\n): FxType<{ kind: \"redirect\"; redirect: string; verifier: string }, AuthError> {\n  return Fx.gen(function* () {\n    const enterpriseId = args.params?.enterpriseId;\n    if (!enterpriseId || typeof enterpriseId !== \"string\") {\n      return yield* Fx.fail(\n        new AuthError(\n          \"SIGN_IN_MISSING_PARAMS\",\n          \"enterpriseId is required for SSO sign-in.\",\n        ),\n      );\n    }\n\n    const protocol: \"oidc\" | \"saml\" = args.params?.protocol ?? \"oidc\";\n    if (protocol !== \"oidc\" && protocol !== \"saml\") {\n      return yield* Fx.fail(\n        new AuthError(\n          \"SIGN_IN_MISSING_PARAMS\",\n          `Invalid SSO protocol: ${protocol as string}. Expected \"oidc\" or \"saml\".`,\n        ),\n      );\n    }\n\n    const verifier = yield* Fx.promise(() => callVerifier(ctx));\n    const siteUrl =\n      process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv(\"CONVEX_SITE_URL\");\n    const redirect = new URL(\n      `${siteUrl}/api/auth/sso/${enterpriseId}/${protocol}/signin`,\n    );\n    redirect.searchParams.set(\"code\", verifier);\n\n    if (typeof args.params?.redirectTo === \"string\") {\n      redirect.searchParams.set(\"redirectTo\", args.params.redirectTo);\n    }\n\n    return {\n      kind: \"redirect\" as const,\n      redirect: redirect.toString(),\n      verifier,\n    };\n  });\n}\n"],"mappings":"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"}

package/dist/server/ssr.d.ts

@@ -0,0 +1,226 @@
+//#region src/server/ssr.d.ts
+/** Cookie lifetime configuration for auth tokens. */
+type AuthCookieConfig = {
+  /** Maximum age in seconds, or `null` for session cookies. */maxAge: number | null;
+};
+/** Raw cookie values extracted from a request. */
+type AuthCookies = {
+  /** The JWT access token, or `null` when absent. */token: string | null; /** The refresh token, or `null` when absent. */
+  refreshToken: string | null; /** The OAuth PKCE verifier, or `null` when absent. */
+  verifier: string | null;
+};
+/** A structured cookie ready to be set via any framework's cookie API. */
+type AuthCookie = {
+  name: string;
+  value: string;
+  options: {
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    maxAge?: number;
+    expires?: Date;
+  };
+};
+/**
+ * Options for the SSR auth helper returned by {@link server}.
+ */
+type ServerOptions = {
+  /** Convex deployment API URL (e.g. `https://your-app.convex.cloud`). */url: string;
+  /**
+   * Accepted JWT issuers for `refresh()` and `verify()`.
+   *
+   * By default, this is derived from `url`. If `url` ends with
+   * `.convex.cloud`, the matching `.convex.site` issuer is also accepted.
+   */
+  acceptedIssuers?: string[];
+  /**
+   * Path the client POSTs auth actions to. Defaults to `"/api/auth"`.
+   * Must match the `proxyPath` option on the client.
+   *
+   * @defaultValue "/api/auth"
+   */
+  apiRoute?: string; /** Cookie `maxAge` in seconds, or `null` for session cookies. */
+  cookieMaxAge?: number | null; /** Enable verbose debug logging for token refresh and cookie operations. */
+  verbose?: boolean;
+  /**
+   * Optional namespace for auth cookie names.
+   *
+   * Use this to isolate auth cookies between multiple local apps on the same host.
+   * If omitted, a deterministic deployment-scoped namespace is derived from `url`.
+   */
+  cookieNamespace?: string;
+  /**
+   * Control whether `refresh()` handles OAuth `?code=` query parameters.
+   *
+   * - `true` (default): always exchange the code on GET requests with `text/html` accept.
+   * - `false`: never exchange — useful when only the client handles codes.
+   * - A function: called with the `Request` for per-request decisions.
+   *
+   * @defaultValue true
+   */
+  shouldHandleCode?: ((request: Request) => boolean | Promise<boolean>) | boolean;
+};
+/**
+ * Result returned from `server().refresh()`.
+ *
+ * Covers both normal SSR refreshes and OAuth code-exchange redirects.
+ */
+type RefreshResult = {
+  /** Code exchange occurred — return the pre-built redirect `Response`. */redirect: true; /** 302 redirect with Set-Cookie headers already serialized. */
+  response: Response;
+} | {
+  /** No redirect — apply cookies and read the token. */redirect: false; /** Structured cookies to set on the response. */
+  cookies: AuthCookie[]; /** JWT for SSR hydration, or `null` if not authenticated. */
+  token: string | null;
+};
+/**
+ * Derive the cookie names used for auth tokens.
+ *
+ * On localhost the names are unprefixed; on production hosts they
+ * use the `__Host-` prefix for tighter security.
+ *
+ * @param host - The `Host` header value. Omit to use unprefixed names.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns An object with `token`, `refreshToken`, and `verifier` cookie names.
+ */
+declare function authCookieNames(host?: string, cookieNamespace?: string | null): {
+  token: string;
+  refreshToken: string;
+  verifier: string;
+};
+/**
+ * Parse auth cookie values from a raw `Cookie` header string.
+ *
+ * @param cookieHeader - The raw `Cookie` header, or `null`/`undefined`.
+ * @param host - The `Host` header, used to determine cookie name prefixes.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns Parsed {@link AuthCookies} with `token`, `refreshToken`, and `verifier`.
+ */
+declare function parseAuthCookies(cookieHeader: string | null | undefined, host?: string, cookieNamespace?: string | null): AuthCookies;
+/**
+ * Serialize auth cookies into `Set-Cookie` header strings.
+ *
+ * Nulled-out values produce deletion cookies (maxAge 0, expired date).
+ *
+ * @param cookies - The auth cookie values to serialize.
+ * @param host - The `Host` header, used for cookie name prefixes and `Secure` flag.
+ * @param config - Cookie lifetime config. Defaults to session cookies.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns An array of three `Set-Cookie` header strings.
+ */
+declare function serializeAuthCookies(cookies: AuthCookies, host?: string, config?: AuthCookieConfig, cookieNamespace?: string | null): string[];
+/**
+ * Build structured cookie objects for any SSR framework.
+ *
+ * Use with SvelteKit's `event.cookies.set()`, TanStack Start's `setCookie()`,
+ * Next.js's `cookies().set()`, or any other framework cookie API.
+ *
+ * @param cookies - The auth cookie values to convert.
+ * @param host - The `Host` header, used for cookie name prefixes and `Secure`.
+ * @param config - Cookie lifetime config. Defaults to session cookies.
+ * @param cookieNamespace - Optional namespace suffix for cookie isolation.
+ * @returns Structured cookie descriptors ready for framework cookie APIs.
+ */
+declare function structuredAuthCookies(cookies: AuthCookies, host?: string, config?: AuthCookieConfig, cookieNamespace?: string | null): AuthCookie[];
+/**
+ * Check whether a request pathname matches the auth proxy route.
+ *
+ * Handles trailing-slash ambiguity: both `/api/auth` and `/api/auth/`
+ * match regardless of how `apiRoute` is configured.
+ *
+ * @param pathname - The request URL pathname.
+ * @param apiRoute - The configured proxy route (e.g. `"/api/auth"`).
+ * @returns `true` when the pathname matches the proxy route.
+ *
+ * @see {@link server}
+ */
+declare function shouldProxyAuthAction(pathname: string, apiRoute: string): boolean;
+/**
+ * Create an SSR auth helper for server-side frameworks.
+ *
+ * Handles cookie-based token management, OAuth code exchange,
+ * and automatic JWT refresh on page loads. Works with any
+ * framework that gives you a `Request` object — SvelteKit,
+ * TanStack Start, Remix, Next.js, etc.
+ *
+ * @param options - SSR configuration (Convex API URL, issuer rules, proxy route, cookie lifetime).
+ * @returns An object with `token`, `verify`, `proxy`, and `refresh` methods.
+ *
+ * @example SvelteKit hooks
+ * ```ts
+ * // src/hooks.server.ts
+ * import { server } from '@robelest/convex-auth/server';
+ *
+ * const auth = server({ url: CONVEX_URL });
+ *
+ * export const handle = async ({ event, resolve }) => {
+ *   const { cookies, token } = await auth.refresh(event.request);
+ *   for (const c of cookies) event.cookies.set(c.name, c.value, c.options);
+ *   event.locals.token = token;
+ *   return resolve(event);
+ * };
+ * ```
+ *
+ * @example Generic proxy endpoint
+ * ```ts
+ * if (shouldProxyAuthAction(url.pathname, '/api/auth')) {
+ *   return auth.proxy(request);
+ * }
+ * ```
+ *
+ * @param options - Server-side auth configuration including Convex URL,
+ *   accepted issuers, proxy route, and cookie behavior.
+ * @returns SSR helpers for reading tokens, refreshing cookies, and proxying
+ *   auth actions through an httpOnly-cookie layer.
+ *
+ * @see {@link shouldProxyAuthAction}
+ */
+declare function server(options: ServerOptions): {
+  /**
+   * Read the JWT from the request cookies without any validation.
+   *
+   * @param request - The incoming HTTP request.
+   * @returns The raw JWT string, or `null` when no token cookie exists.
+   */
+  token(request: Request): string | null;
+  /**
+   * Check whether the request carries a non-expired JWT.
+   *
+   * Performs local expiration checking only (no network call).
+   * Use for lightweight auth guards in middleware.
+   *
+   * @param request - The incoming HTTP request.
+   * @returns `true` when a valid, non-expired JWT exists in the cookies.
+   */
+  verify(request: Request): Promise<boolean>;
+  /**
+   * Handle a proxied `signIn` or `signOut` POST from the client.
+   *
+   * Validates the route, method, and origin, then forwards the
+   * action to Convex and returns a `Response` with updated
+   * `Set-Cookie` headers. The client never sees the real
+   * refresh token — it stays in httpOnly cookies.
+   *
+   * @param request - The incoming POST request from the client.
+   * @returns A JSON `Response` with auth result and cookie headers.
+   */
+  proxy(request: Request): Promise<Response>;
+  /**
+   * Refresh auth tokens on page load.
+   *
+   * Call this in your server hooks/middleware on every request.
+   * It handles three scenarios:
+   *
+   * 1. **OAuth code exchange** — exchanges a `?code=` query param for tokens and returns a redirect URL.
+   * 2. **Token refresh** — refreshes the JWT if it's close to expiry.
+   * 3. **No-op** — returns the existing token when no refresh is needed.
+   *
+   * @param request - The incoming HTTP request.
+   * @returns Structured cookies to set on the response, an optional redirect URL, and the current JWT.
+   */
+  refresh(request: Request): Promise<RefreshResult>;
+};
+//#endregion
+export { AuthCookie, AuthCookieConfig, AuthCookies, RefreshResult, ServerOptions, authCookieNames, parseAuthCookies, serializeAuthCookies, server, shouldProxyAuthAction, structuredAuthCookies };
+//# sourceMappingURL=ssr.d.ts.map

package/dist/server/ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.d.ts","names":[],"sources":["../../src/server/ssr.ts"],"mappings":";;KAkBY,gBAAA;EAAgB,6DAE1B,MAAA;AAAA;;KAIU,WAAA;EAAW,mDAErB,KAAA,iBAFqB;EAIrB,YAAA;EAEA,QAAA;AAAA;;KAIU,UAAA;EACV,IAAA;EACA,KAAA;EACA,OAAA;IACE,IAAA;IACA,QAAA;IACA,MAAA;IACA,QAAA;IACA,MAAA;IACA,OAAA,GAAU,IAAA;EAAA;AAAA;;;;KAOF,aAAA;EAAA,wEAEV,GAAA;;;;;;;EAOA,eAAA;EAkBA;;;;;;EAXA,QAAA,WA+BU;EA7BV,YAAA;EAEA,OAAA;EA8BI;;;;;;EAvBJ,eAAA;EAiCS;;AAkBX;;;;;;;EAzCE,gBAAA,KACM,OAAA,EAAS,OAAA,eAAsB,OAAA;AAAA;;;AA8DvC;;;KArDY,aAAA;EAsDV,yEAnDI,QAAA,QAqDJ;EAnDI,QAAA,EAAU,QAAA;AAAA;EAoDF,sDAhDR,QAAA,SAqE8B;EAnE9B,OAAA,EAAS,UAAA,IAsE8B;EApEvC,KAAA;AAAA;;;;;;;AAgHN;;;;iBA9FgB,eAAA,CACd,IAAA,WACA,eAAA;;;;;;;;;;;;;iBAoBc,gBAAA,CACd,YAAA,6BACA,IAAA,WACA,eAAA,mBACC,WAAA;;;;;AA0QH;;;;;;;iBArPgB,oBAAA,CACd,OAAA,EAAS,WAAA,EACT,IAAA,WACA,MAAA,GAAQ,gBAAA,EACR,eAAA;;;;;;;;;;;;;iBA2Cc,qBAAA,CACd,OAAA,EAAS,WAAA,EACT,IAAA,WACA,MAAA,GAAQ,gBAAA,EACR,eAAA,mBACC,UAAA;;;;;;;;;;;;;iBAuDa,qBAAA,CAAsB,QAAA,UAAkB,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0IxC,MAAA,CAAO,OAAA,EAAS,aAAA;;;;;;;iBAqBb,OAAA;;;;;;;;;;kBAiBO,OAAA,GAAU,OAAA;;;;;;;;;;;;iBAoCX,OAAA,GAAU,OAAA,CAAQ,QAAA;;;;;;;;;;;;;;mBA+iBhB,OAAA,GAAU,OAAA,CAAQ,aAAA;AAAA"}