@warlock.js/auth 5.11.0 → 5.13.0

package/esm/providers/provider-state-cookie.mjs

@@ -0,0 +1,63 @@
+import { authConfig } from "../services/auth-config.mjs";
+import { safeEqual } from "../utils/safe-equal.mjs";
+import { createHmac, randomBytes } from "node:crypto";
+
+//#region ../auth/src/providers/provider-state-cookie.ts
+/** Cookie carrying a redirect login's state from the start to the callback. */
+const PROVIDER_STATE_COOKIE = "auth_provider_state";
+/** How long a started provider login stays completable. */
+const PROVIDER_STATE_TTL_SECONDS = 600;
+/** 32 random bytes, base64url — used for `state`, `nonce` and the PKCE verifier. */
+function randomUrlSafe() {
+	return randomBytes(32).toString("base64url");
+}
+/**
+* HMAC over the payload with a key DERIVED from the access-token secret, so
+* the state cookie never shares a MAC key with the JWTs themselves.
+*/
+function sign(payload) {
+	return createHmac("sha256", createHmac("sha256", authConfig.accessToken.secret()).update("@warlock.js/auth:provider-state").digest()).update(payload).digest("base64url");
+}
+/**
+* Write the signed, 10-minute state cookie for a provider login. Attribute
+* flags (`HttpOnly`, `SameSite=Lax`, `Secure` outside dev) come from the
+* `response.cookie()` secure defaults; `Lax` still rides the provider's
+* top-level GET redirect back to the app.
+*/
+function writeProviderState(response, provider, state) {
+	const stored = {
+		...state,
+		provider,
+		expiresAt: Date.now() + PROVIDER_STATE_TTL_SECONDS * 1e3
+	};
+	const payload = Buffer.from(JSON.stringify(stored)).toString("base64url");
+	response.cookie(PROVIDER_STATE_COOKIE, `${payload}.${sign(payload)}`, {
+		raw: true,
+		path: "/",
+		maxAge: PROVIDER_STATE_TTL_SECONDS
+	});
+}
+/**
+* Read AND clear the state cookie, so a started login completes at most once.
+* Resolves `undefined` for an absent, forged (bad MAC), malformed or expired
+* cookie.
+*/
+function takeProviderState(request, response) {
+	const raw = request.cookie(PROVIDER_STATE_COOKIE);
+	response.clearCookie(PROVIDER_STATE_COOKIE, { path: "/" });
+	if (typeof raw !== "string") return void 0;
+	const [payload, signature, ...rest] = raw.split(".");
+	if (!payload || !signature || rest.length > 0 || !safeEqual(signature, sign(payload))) return;
+	let stored;
+	try {
+		stored = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+	} catch {
+		return;
+	}
+	if (typeof stored?.state !== "string" || typeof stored.nonce !== "string" || typeof stored.codeVerifier !== "string" || typeof stored.provider !== "string" || typeof stored.expiresAt !== "number" || stored.expiresAt <= Date.now()) return;
+	return stored;
+}
+
+//#endregion
+export { randomUrlSafe, takeProviderState, writeProviderState };
+//# sourceMappingURL=provider-state-cookie.mjs.map

package/esm/providers/provider-state-cookie.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-state-cookie.mjs","names":[],"sources":["../../../../../../../auth/src/providers/provider-state-cookie.ts"],"sourcesContent":["import type { Request, Response } from \"@warlock.js/core\";\nimport { createHmac, randomBytes } from \"node:crypto\";\nimport type { ProviderAuthorizationState } from \"../contracts/providers\";\nimport { authConfig } from \"../services/auth-config\";\nimport { safeEqual } from \"../utils/safe-equal\";\n\n/** Cookie carrying a redirect login's state from the start to the callback. */\nexport const PROVIDER_STATE_COOKIE = \"auth_provider_state\";\n\n/** How long a started provider login stays completable. */\nconst PROVIDER_STATE_TTL_SECONDS = 600;\n\n/** What the signed cookie holds. */\nexport type StoredProviderState = ProviderAuthorizationState & {\n  provider: string;\n  expiresAt: number;\n};\n\n/** 32 random bytes, base64url — used for `state`, `nonce` and the PKCE verifier. */\nexport function randomUrlSafe(): string {\n  return randomBytes(32).toString(\"base64url\");\n}\n\n/**\n * HMAC over the payload with a key DERIVED from the access-token secret, so\n * the state cookie never shares a MAC key with the JWTs themselves.\n */\nfunction sign(payload: string): string {\n  const key = createHmac(\"sha256\", authConfig.accessToken.secret())\n    .update(\"@warlock.js/auth:provider-state\")\n    .digest();\n\n  return createHmac(\"sha256\", key).update(payload).digest(\"base64url\");\n}\n\n/**\n * Write the signed, 10-minute state cookie for a provider login. Attribute\n * flags (`HttpOnly`, `SameSite=Lax`, `Secure` outside dev) come from the\n * `response.cookie()` secure defaults; `Lax` still rides the provider's\n * top-level GET redirect back to the app.\n */\nexport function writeProviderState(\n  response: Response,\n  provider: string,\n  state: ProviderAuthorizationState,\n): void {\n  const stored: StoredProviderState = {\n    ...state,\n    provider,\n    expiresAt: Date.now() + PROVIDER_STATE_TTL_SECONDS * 1000,\n  };\n  const payload = Buffer.from(JSON.stringify(stored)).toString(\"base64url\");\n\n  response.cookie(PROVIDER_STATE_COOKIE, `${payload}.${sign(payload)}`, {\n    raw: true,\n    path: \"/\",\n    maxAge: PROVIDER_STATE_TTL_SECONDS,\n  });\n}\n\n/**\n * Read AND clear the state cookie, so a started login completes at most once.\n * Resolves `undefined` for an absent, forged (bad MAC), malformed or expired\n * cookie.\n */\nexport function takeProviderState(\n  request: Request,\n  response: Response,\n): StoredProviderState | undefined {\n  const raw: unknown = request.cookie(PROVIDER_STATE_COOKIE);\n\n  response.clearCookie(PROVIDER_STATE_COOKIE, { path: \"/\" });\n\n  if (typeof raw !== \"string\") return undefined;\n\n  const [payload, signature, ...rest] = raw.split(\".\");\n\n  if (!payload || !signature || rest.length > 0 || !safeEqual(signature, sign(payload))) {\n    return undefined;\n  }\n\n  let stored: Partial<StoredProviderState> | undefined;\n\n  try {\n    stored = JSON.parse(Buffer.from(payload, \"base64url\").toString(\"utf8\"));\n  } catch {\n    return undefined;\n  }\n\n  if (\n    typeof stored?.state !== \"string\" ||\n    typeof stored.nonce !== \"string\" ||\n    typeof stored.codeVerifier !== \"string\" ||\n    typeof stored.provider !== \"string\" ||\n    typeof stored.expiresAt !== \"number\" ||\n    stored.expiresAt <= Date.now()\n  ) {\n    return undefined;\n  }\n\n  return stored as StoredProviderState;\n}\n"],"mappings":";;;;;;AAOA,MAAa,wBAAwB;;AAGrC,MAAM,6BAA6B;;AASnC,SAAgB,gBAAwB;CACtC,OAAO,YAAY,EAAE,CAAC,CAAC,SAAS,WAAW;AAC7C;;;;;AAMA,SAAS,KAAK,SAAyB;CAKrC,OAAO,WAAW,UAJN,WAAW,UAAU,WAAW,YAAY,OAAO,CAAC,CAAC,CAC9D,OAAO,iCAAiC,CAAC,CACzC,OAE2B,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,OAAO,WAAW;AACrE;;;;;;;AAQA,SAAgB,mBACd,UACA,UACA,OACM;CACN,MAAM,SAA8B;EAClC,GAAG;EACH;EACA,WAAW,KAAK,IAAI,IAAI,6BAA6B;CACvD;CACA,MAAM,UAAU,OAAO,KAAK,KAAK,UAAU,MAAM,CAAC,CAAC,CAAC,SAAS,WAAW;CAExE,SAAS,OAAO,uBAAuB,GAAG,QAAQ,GAAG,KAAK,OAAO,KAAK;EACpE,KAAK;EACL,MAAM;EACN,QAAQ;CACV,CAAC;AACH;;;;;;AAOA,SAAgB,kBACd,SACA,UACiC;CACjC,MAAM,MAAe,QAAQ,OAAO,qBAAqB;CAEzD,SAAS,YAAY,uBAAuB,EAAE,MAAM,IAAI,CAAC;CAEzD,IAAI,OAAO,QAAQ,UAAU,OAAO;CAEpC,MAAM,CAAC,SAAS,WAAW,GAAG,QAAQ,IAAI,MAAM,GAAG;CAEnD,IAAI,CAAC,WAAW,CAAC,aAAa,KAAK,SAAS,KAAK,CAAC,UAAU,WAAW,KAAK,OAAO,CAAC,GAClF;CAGF,IAAI;CAEJ,IAAI;EACF,SAAS,KAAK,MAAM,OAAO,KAAK,SAAS,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC;CACxE,QAAQ;EACN;CACF;CAEA,IACE,OAAO,QAAQ,UAAU,YACzB,OAAO,OAAO,UAAU,YACxB,OAAO,OAAO,iBAAiB,YAC/B,OAAO,OAAO,aAAa,YAC3B,OAAO,OAAO,cAAc,YAC5B,OAAO,aAAa,KAAK,IAAI,GAE7B;CAGF,OAAO;AACT"}

package/esm/providers/resolve-provider-user.mjs

@@ -0,0 +1,45 @@
+import { authConfig } from "../services/auth-config.mjs";
+import { InvalidProviderCallbackError } from "../errors/invalid-provider-callback.error.mjs";
+import { ProviderEmailNotVerifiedError } from "../errors/provider-email-not-verified.error.mjs";
+import { ProviderAccount } from "../models/provider-account/provider-account.model.mjs";
+import "../models/provider-account/index.mjs";
+
+//#region ../auth/src/providers/resolve-provider-user.ts
+/** Default creation for a first provider login: email, name, and the verified stamp. */
+async function createUserFor(Model, profile) {
+	const createUser = authConfig.providers.createUser();
+	if (createUser) return await createUser(profile, Model);
+	return await Model.create({
+		[authConfig.providers.emailField()]: profile.email,
+		...profile.name ? { name: profile.name } : {},
+		[authConfig.verification.field()]: /* @__PURE__ */ new Date()
+	});
+}
+/**
+* Find or create the app user for a provider profile, and link them.
+*
+* 1. An existing `provider_accounts` link wins — the provider's stable id, not
+*    the email, identifies the account from then on.
+* 2. Otherwise the provider email MUST be verified. An unverified (or absent)
+*    email throws {@link ProviderEmailNotVerifiedError} and nothing is linked
+*    or created: linking on it would let anyone who can add an unverified
+*    address at the provider take over the matching account.
+* 3. Verified: the user whose `auth.providers.emailField` matches, else a new
+*    user (`auth.providers.createUser`, or the default) — then the link is stored.
+*/
+async function resolveProviderUser(Model, profile) {
+	const link = await ProviderAccount.findLink(profile.provider, profile.providerUserId);
+	if (link) {
+		const linked = await Model.find(link.userId);
+		if (!linked || linked.userType !== link.userType) throw new InvalidProviderCallbackError("link-points-to-missing-user");
+		return linked;
+	}
+	if (!profile.emailVerified || !profile.email) throw new ProviderEmailNotVerifiedError();
+	const user = await Model.first({ [authConfig.providers.emailField()]: profile.email }) ?? await createUserFor(Model, profile);
+	await ProviderAccount.link(profile.provider, profile.providerUserId, user, profile.email);
+	return user;
+}
+
+//#endregion
+export { resolveProviderUser };
+//# sourceMappingURL=resolve-provider-user.mjs.map

package/esm/providers/resolve-provider-user.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-provider-user.mjs","names":[],"sources":["../../../../../../../auth/src/providers/resolve-provider-user.ts"],"sourcesContent":["import type { ChildModel } from \"@warlock.js/cascade\";\nimport type { ProviderProfile } from \"../contracts/providers\";\nimport { InvalidProviderCallbackError } from \"../errors/invalid-provider-callback.error\";\nimport { ProviderEmailNotVerifiedError } from \"../errors/provider-email-not-verified.error\";\nimport type { Auth } from \"../models/auth.model\";\nimport { ProviderAccount } from \"../models/provider-account\";\nimport { authConfig } from \"../services/auth-config\";\n\n/** Default creation for a first provider login: email, name, and the verified stamp. */\nasync function createUserFor<T extends Auth>(\n  Model: ChildModel<T>,\n  profile: ProviderProfile,\n): Promise<T> {\n  const createUser = authConfig.providers.createUser();\n\n  if (createUser) {\n    return (await createUser(profile, Model as unknown as ChildModel<Auth>)) as T;\n  }\n\n  return (await Model.create({\n    [authConfig.providers.emailField()]: profile.email,\n    ...(profile.name ? { name: profile.name } : {}),\n    // The provider verified this address; record it the way verifyEmail does.\n    [authConfig.verification.field()]: new Date(),\n  } as never)) as T;\n}\n\n/**\n * Find or create the app user for a provider profile, and link them.\n *\n * 1. An existing `provider_accounts` link wins — the provider's stable id, not\n *    the email, identifies the account from then on.\n * 2. Otherwise the provider email MUST be verified. An unverified (or absent)\n *    email throws {@link ProviderEmailNotVerifiedError} and nothing is linked\n *    or created: linking on it would let anyone who can add an unverified\n *    address at the provider take over the matching account.\n * 3. Verified: the user whose `auth.providers.emailField` matches, else a new\n *    user (`auth.providers.createUser`, or the default) — then the link is stored.\n */\nexport async function resolveProviderUser<T extends Auth>(\n  Model: ChildModel<T>,\n  profile: ProviderProfile,\n): Promise<T> {\n  const link = await ProviderAccount.findLink(profile.provider, profile.providerUserId);\n\n  if (link) {\n    const linked = (await Model.find(link.userId)) as T | null;\n\n    if (!linked || linked.userType !== link.userType) {\n      throw new InvalidProviderCallbackError(\"link-points-to-missing-user\");\n    }\n\n    return linked;\n  }\n\n  if (!profile.emailVerified || !profile.email) {\n    throw new ProviderEmailNotVerifiedError();\n  }\n\n  const existing = (await Model.first({\n    [authConfig.providers.emailField()]: profile.email,\n  })) as T | null;\n\n  const user = existing ?? (await createUserFor(Model, profile));\n\n  await ProviderAccount.link(profile.provider, profile.providerUserId, user, profile.email);\n\n  return user;\n}\n"],"mappings":";;;;;;;;AASA,eAAe,cACb,OACA,SACY;CACZ,MAAM,aAAa,WAAW,UAAU,WAAW;CAEnD,IAAI,YACF,OAAQ,MAAM,WAAW,SAAS,KAAoC;CAGxE,OAAQ,MAAM,MAAM,OAAO;GACxB,WAAW,UAAU,WAAW,IAAI,QAAQ;EAC7C,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;GAE5C,WAAW,aAAa,MAAM,oBAAI,IAAI,KAAK;CAC9C,CAAU;AACZ;;;;;;;;;;;;;AAcA,eAAsB,oBACpB,OACA,SACY;CACZ,MAAM,OAAO,MAAM,gBAAgB,SAAS,QAAQ,UAAU,QAAQ,cAAc;CAEpF,IAAI,MAAM;EACR,MAAM,SAAU,MAAM,MAAM,KAAK,KAAK,MAAM;EAE5C,IAAI,CAAC,UAAU,OAAO,aAAa,KAAK,UACtC,MAAM,IAAI,6BAA6B,6BAA6B;EAGtE,OAAO;CACT;CAEA,IAAI,CAAC,QAAQ,iBAAiB,CAAC,QAAQ,OACrC,MAAM,IAAI,8BAA8B;CAO1C,MAAM,OAAO,MAJW,MAAM,MAAM,GACjC,WAAW,UAAU,WAAW,IAAI,QAAQ,MAC/C,CAAC,KAEyB,MAAM,cAAc,OAAO,OAAO;CAE5D,MAAM,gBAAgB,KAAK,QAAQ,UAAU,QAAQ,gBAAgB,MAAM,QAAQ,KAAK;CAExF,OAAO;AACT"}

package/esm/services/auth-config.mjs

@@ -42,6 +42,14 @@ function parseDuration(key, raw) {
 	if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed <= 0) throw new Error(`auth.${key}: ${JSON.stringify(raw)} is not a valid ms duration — use a positive duration string such as "1h", "7d", or NO_EXPIRATION.`);
 	return parsed;
 }
+/** Email-verification token lifetime used when nothing is configured. */
+const DEFAULT_VERIFICATION_EXPIRES_IN = "24h";
+/** Password-reset token lifetime used when nothing is configured. */
+const DEFAULT_PASSWORD_RESET_EXPIRES_IN = "60m";
+/** Passkey challenge lifetime used when nothing is configured. */
+const DEFAULT_PASSKEY_CHALLENGE_EXPIRES_IN = "5m";
+/** OTP lifetime used when nothing is configured. */
+const DEFAULT_OTP_EXPIRES_IN = "5m";
 /** Access-token lifetime used when nothing is configured. */
 const DEFAULT_ACCESS_TOKEN_EXPIRES_IN = "1h";
 /**
@@ -110,6 +118,82 @@ const authConfig = {
 		*/
 		returnUrlParam: () => config.key("auth.pageAuth.returnUrlParam", "returnUrl")
 	},
+	cookie: {
+		/** Cookie name `setAuthCookie`/`clearAuthCookie` use. @default "access_token" */
+		name: () => config.key("auth.cookie.name", "access_token"),
+		/** Cookie `Path` attribute `setAuthCookie`/`clearAuthCookie` use. @default "/" */
+		path: () => config.key("auth.cookie.path", "/")
+	},
+	csrf: { 
+	/**
+	* Extra origins allowed on a cookie-authenticated unsafe-method request,
+	* beyond the request's own origin. @default []
+	*/
+allowedOrigins: () => config.key("auth.csrf.allowedOrigins", []) },
+	verification: {
+		/** Lifetime in ms of an email-verification token; throws naming the key when unusable. @default "24h" */
+		expiresInMs: () => parseDuration("verification.expiresIn", config.key("auth.verification.expiresIn", DEFAULT_VERIFICATION_EXPIRES_IN)),
+		/** User attribute stamped with the verification date. @default "emailVerifiedAt" */
+		field: () => config.key("auth.verification.field", "emailVerifiedAt"),
+		/** App notification replacing the default verification email. */
+		notification: () => config.key("auth.verification.notification"),
+		/** Link builder whose result is handed to the notification as `url`. */
+		url: () => config.key("auth.verification.url")
+	},
+	passwordReset: {
+		/** Lifetime in ms of a password-reset token; throws naming the key when unusable. @default "60m" */
+		expiresInMs: () => parseDuration("passwordReset.expiresIn", config.key("auth.passwordReset.expiresIn", DEFAULT_PASSWORD_RESET_EXPIRES_IN)),
+		/** User attribute `requestPasswordReset` looks the account up by. @default "email" */
+		identifierField: () => config.key("auth.passwordReset.identifierField", "email"),
+		/** App notification replacing the default reset email. */
+		notification: () => config.key("auth.passwordReset.notification"),
+		/** Link builder whose result is handed to the notification as `url`. */
+		url: () => config.key("auth.passwordReset.url"),
+		/** App-owned password writer replacing the default. */
+		setPassword: () => config.key("auth.passwordReset.setPassword")
+	},
+	providers: {
+		/** `auth.providers.google`, when configured. */
+		google: () => config.key("auth.providers.google"),
+		/** An app-registered provider under `auth.providers.custom.<name>`. */
+		custom: (name) => config.key("auth.providers.custom", {})[name],
+		/** User attribute a verified provider email is matched against. @default "email" */
+		emailField: () => config.key("auth.providers.emailField", "email"),
+		/** App-owned user creation for a first provider login. */
+		createUser: () => config.key("auth.providers.createUser")
+	},
+	passkeys: {
+		/** `auth.passkeys`; throws naming the keys when `rpID`, `rpName` or `origin` is missing. */
+		settings: () => {
+			const settings = config.key("auth.passkeys");
+			if (!settings?.rpID || !settings.rpName || !settings.origin) throw new Error("@warlock.js/auth: passkeys need `auth.passkeys.rpID`, `auth.passkeys.rpName` and `auth.passkeys.origin`.");
+			return settings;
+		},
+		/** Allowed ceremony origins, as a list. */
+		origins: () => {
+			const { origin } = authConfig.passkeys.settings();
+			return Array.isArray(origin) ? origin : [origin];
+		},
+		/** Challenge lifetime in ms; throws naming the key when unusable. @default "5m" */
+		challengeExpiresInMs: () => parseDuration("passkeys.challengeExpiresIn", config.key("auth.passkeys.challengeExpiresIn", DEFAULT_PASSKEY_CHALLENGE_EXPIRES_IN))
+	},
+	otp: {
+		/** Notifications channel the code is sent through. @default "sms" */
+		channel: () => config.key("auth.otp.channel", "sms"),
+		/** User attribute holding the phone number. @default "phone" */
+		phoneField: () => config.key("auth.otp.phoneField", "phone"),
+		/** Code lifetime in ms; throws naming the key when unusable. @default "5m" */
+		expiresInMs: () => parseDuration("otp.expiresIn", config.key("auth.otp.expiresIn", DEFAULT_OTP_EXPIRES_IN)),
+		/** Verify attempts before the code is invalidated. @default 5 */
+		maxAttempts: () => config.key("auth.otp.maxAttempts", 5),
+		/** The message text for a code. */
+		message: (code) => {
+			const build = config.key("auth.otp.message");
+			return build ? build(code) : `Your verification code is ${code}`;
+		},
+		/** App-owned delivery replacing the notifications channel send. */
+		send: () => config.key("auth.otp.send")
+	},
 	refreshToken: {
 		/** Separate refresh secret (legacy: `auth.jwt.refresh.secret`); empty ⇒ fall back to the access secret. */
 		secret: () => resolve("refreshToken.secret", "jwt.refresh.secret"),

package/esm/services/auth-config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth-config.mjs","names":[],"sources":["../../../../../../../auth/src/services/auth-config.ts"],"sourcesContent":["import { config } from \"@warlock.js/core\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport ms from \"ms\";\r\nimport type { CanAuthenticate, LogoutWithoutTokenBehavior } from \"../contracts/types\";\r\nimport type { Auth } from \"../models/auth.model\";\r\n\r\nconst warnedLegacyKeys = new Set<string>();\r\n\r\nconst permitAuthentication: CanAuthenticate = (): boolean => true;\r\n\r\n/**\r\n * `ms` accepts anything at runtime and answers `undefined` for a string it\r\n * cannot parse (`\"30dayz\"`), a *formatted string* for a number (`2592000` ⇒\r\n * `\"43m\"`), and throws for `\"\"`. Its published types claim the far narrower\r\n * `(value: ms.StringValue) => number`, which is exactly what let an\r\n * `as ms.StringValue` cast smuggle arbitrary config text past the compiler and\r\n * hand `undefined` to the JWT signer. Declare the honest runtime signature once,\r\n * here, so every caller is forced to deal with the `undefined`.\r\n */\r\nconst parseMs = ms as unknown as (value: unknown) => number | string | undefined;\r\n\r\n/**\r\n * Turn a configured lifetime into a positive number of milliseconds, or throw\r\n * naming the key.\r\n *\r\n * A token lifetime is a security boundary, so an unusable value is a hard error\r\n * rather than a silent fallback: substituting a default would trade one\r\n * unintended lifetime for another, just as quietly — and quiet is the whole\r\n * problem. Every non-positive, non-finite or non-numeric parse is rejected:\r\n *\r\n * - `\"30dayz\"` / `\"thirty days\"` ⇒ `undefined` ⇒ a JWT signed with **no `exp`\r\n *   claim** and an `Invalid Date` written to the token row.\r\n * - `\"0d\"` ⇒ parses cleanly to `0`, which `fast-jwt` treats as falsy and also\r\n *   emits with **no `exp` claim** — it survives any guard that only rejects\r\n *   `undefined`. `\"-1h\"` signs an already-expired token.\r\n * - `2592000` (a bare number) ⇒ `ms` *formats* it as `\"43m\"`, a string, which\r\n *   then turns `Date.now() + expiresIn` into an `Invalid Date`.\r\n */\r\nfunction parseDuration(key: string, raw: unknown): number {\r\n  let parsed: number | string | undefined;\r\n\r\n  try {\r\n    parsed = parseMs(raw);\r\n  } catch {\r\n    // ms throws (rather than returning undefined) for \"\" and non-strings\r\n    parsed = undefined;\r\n  }\r\n\r\n  if (typeof parsed !== \"number\" || !Number.isFinite(parsed) || parsed <= 0) {\r\n    throw new Error(\r\n      `auth.${key}: ${JSON.stringify(raw)} is not a valid ms duration — ` +\r\n        `use a positive duration string such as \"1h\", \"7d\", or NO_EXPIRATION.`,\r\n    );\r\n  }\r\n\r\n  return parsed;\r\n}\r\n\r\n/** Access-token lifetime used when nothing is configured. */\r\nconst DEFAULT_ACCESS_TOKEN_EXPIRES_IN = \"1h\";\r\n\r\n/**\r\n * Resolve an auth setting, preferring the new `auth.accessToken.*` /\r\n * `auth.refreshToken.*` key and falling back to the deprecated `auth.jwt.*`\r\n * shape — warning once per legacy key. Returns `fallback` when neither is set.\r\n *\r\n * This is the backward-compatible shim that lets existing `auth.jwt.*` configs\r\n * keep working after the config split.\r\n */\r\nfunction resolve<T>(newKey: string, legacyKey: string, fallback?: T): T {\r\n  const fromNew = config.key(`auth.${newKey}`);\r\n\r\n  if (fromNew !== undefined && fromNew !== null) {\r\n    return fromNew as T;\r\n  }\r\n\r\n  const fromLegacy = config.key(`auth.${legacyKey}`);\r\n\r\n  if (fromLegacy !== undefined && fromLegacy !== null) {\r\n    if (!warnedLegacyKeys.has(legacyKey)) {\r\n      warnedLegacyKeys.add(legacyKey);\r\n      log.warn(\"auth\", \"config-deprecation\", `auth.${legacyKey} is deprecated — use auth.${newKey}`);\r\n    }\r\n\r\n    return fromLegacy as T;\r\n  }\r\n\r\n  return fallback as T;\r\n}\r\n\r\n/**\r\n * Typed, backward-compatible access to auth configuration. The service and the\r\n * jwt signer read configuration exclusively through here, so the new split\r\n * config and the legacy `auth.jwt.*` shape both resolve the same way.\r\n */\r\nexport const authConfig = {\r\n  canAuthenticate: async (user: Auth): Promise<boolean> => {\r\n    const canAuthenticate = config.key<CanAuthenticate>(\r\n      \"auth.canAuthenticate\",\r\n      permitAuthentication,\r\n    );\r\n\r\n    return canAuthenticate(user);\r\n  },\r\n  accessToken: {\r\n    /** Signing secret (legacy: `auth.jwt.secret`). Throws if neither is set. */\r\n    secret: (): string => {\r\n      const secret = resolve<string | undefined>(\"accessToken.secret\", \"jwt.secret\");\r\n\r\n      if (!secret) {\r\n        throw new Error(\"auth: no JWT secret configured — set `auth.accessToken.secret`.\");\r\n      }\r\n\r\n      return secret;\r\n    },\r\n    /** Signing algorithm (legacy: `auth.jwt.algorithm`). */\r\n    algorithm: (): Algorithm => resolve(\"accessToken.algorithm\", \"jwt.algorithm\", \"HS256\"),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.expiresIn`). */\r\n    expiresIn: (): string | undefined => resolve(\"accessToken.expiresIn\", \"jwt.expiresIn\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Defaults\r\n     * to 1 hour when unset; throws naming the key when the configured value is\r\n     * not a positive `ms` duration. See {@link parseDuration}.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\r\n        \"accessToken.expiresIn\",\r\n        authConfig.accessToken.expiresIn() ?? DEFAULT_ACCESS_TOKEN_EXPIRES_IN,\r\n      ),\r\n  },\r\n  pageAuth: {\r\n    /**\r\n     * Login path a guarded PAGE route redirects a logged-out browser to.\r\n     *\r\n     * Unset (the default) ⇒ page-route auth failures keep the JSON 401 API\r\n     * contract, so existing apps see NO behavior change. Set it (e.g. \"/login\")\r\n     * to opt a browser-facing app into login-redirect UX: a logged-out human\r\n     * navigating to a guarded page lands on the login screen instead of reading\r\n     * a raw JSON error blob. Finding b9ab9804.\r\n     */\r\n    loginPath: (): string | undefined => config.key(\"auth.pageAuth.loginPath\"),\r\n    /**\r\n     * Query parameter the redirect carries the originally-requested path in, so\r\n     * the login flow can send the user back where they were headed. Defaults to\r\n     * `\"returnUrl\"`.\r\n     */\r\n    returnUrlParam: (): string => config.key(\"auth.pageAuth.returnUrlParam\", \"returnUrl\"),\r\n  },\r\n  refreshToken: {\r\n    /** Separate refresh secret (legacy: `auth.jwt.refresh.secret`); empty ⇒ fall back to the access secret. */\r\n    secret: (): string | undefined => resolve(\"refreshToken.secret\", \"jwt.refresh.secret\"),\r\n    /** Whether refresh tokens are enabled (legacy: `auth.jwt.refresh.enabled`). */\r\n    enabled: (): boolean => resolve(\"refreshToken.enabled\", \"jwt.refresh.enabled\", true),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.refresh.expiresIn`). */\r\n    expiresIn: (): string => resolve(\"refreshToken.expiresIn\", \"jwt.refresh.expiresIn\", \"7d\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Throws\r\n     * naming the key when the configured value is not a positive `ms` duration.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\"refreshToken.expiresIn\", authConfig.refreshToken.expiresIn()),\r\n    /** Rotate-on-use (legacy: `auth.jwt.refresh.rotation`). */\r\n    rotation: (): boolean => resolve(\"refreshToken.rotation\", \"jwt.refresh.rotation\", true),\r\n    /** Max active tokens per user (legacy: `auth.jwt.refresh.maxPerUser`). */\r\n    maxPerUser: (): number => resolve(\"refreshToken.maxPerUser\", \"jwt.refresh.maxPerUser\", 5),\r\n    /** Logout-without-token behavior (legacy: `auth.jwt.refresh.logoutWithoutToken`). */\r\n    logoutWithoutToken: (): LogoutWithoutTokenBehavior =>\r\n      resolve(\"refreshToken.logoutWithoutToken\", \"jwt.refresh.logoutWithoutToken\", \"revoke-all\"),\r\n  },\r\n};\r\n"],"mappings":";;;;;AAOA,MAAM,mCAAmB,IAAI,IAAY;AAEzC,MAAM,6BAAuD;;;;;;;;;;AAW7D,MAAM,UAAU;;;;;;;;;;;;;;;;;;AAmBhB,SAAS,cAAc,KAAa,KAAsB;CACxD,IAAI;CAEJ,IAAI;EACF,SAAS,QAAQ,GAAG;CACtB,QAAQ;EAEN,SAAS;CACX;CAEA,IAAI,OAAO,WAAW,YAAY,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,GACtE,MAAM,IAAI,MACR,QAAQ,IAAI,IAAI,KAAK,UAAU,GAAG,EAAE,mGAEtC;CAGF,OAAO;AACT;;AAGA,MAAM,kCAAkC;;;;;;;;;AAUxC,SAAS,QAAW,QAAgB,WAAmB,UAAiB;CACtE,MAAM,UAAU,OAAO,IAAI,QAAQ,QAAQ;CAE3C,IAAI,YAAY,UAAa,YAAY,MACvC,OAAO;CAGT,MAAM,aAAa,OAAO,IAAI,QAAQ,WAAW;CAEjD,IAAI,eAAe,UAAa,eAAe,MAAM;EACnD,IAAI,CAAC,iBAAiB,IAAI,SAAS,GAAG;GACpC,iBAAiB,IAAI,SAAS;GAC9B,IAAI,KAAK,QAAQ,sBAAsB,QAAQ,UAAU,4BAA4B,QAAQ;EAC/F;EAEA,OAAO;CACT;CAEA,OAAO;AACT;;;;;;AAOA,MAAa,aAAa;CACxB,iBAAiB,OAAO,SAAiC;EAMvD,OALwB,OAAO,IAC7B,wBACA,oBAGmB,CAAC,CAAC,IAAI;CAC7B;CACA,aAAa;;EAEX,cAAsB;GACpB,MAAM,SAAS,QAA4B,sBAAsB,YAAY;GAE7E,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,iEAAiE;GAGnF,OAAO;EACT;;EAEA,iBAA4B,QAAQ,yBAAyB,iBAAiB,OAAO;;EAErF,iBAAqC,QAAQ,yBAAyB,eAAe;;;;;;EAMrF,mBACE,cACE,yBACA,WAAW,YAAY,UAAU,KAAK,+BACxC;CACJ;CACA,UAAU;;;;;;;;;;EAUR,iBAAqC,OAAO,IAAI,yBAAyB;;;;;;EAMzE,sBAA8B,OAAO,IAAI,gCAAgC,WAAW;CACtF;CACA,cAAc;;EAEZ,cAAkC,QAAQ,uBAAuB,oBAAoB;;EAErF,eAAwB,QAAQ,wBAAwB,uBAAuB,IAAI;;EAEnF,iBAAyB,QAAQ,0BAA0B,yBAAyB,IAAI;;;;;EAKxF,mBACE,cAAc,0BAA0B,WAAW,aAAa,UAAU,CAAC;;EAE7E,gBAAyB,QAAQ,yBAAyB,wBAAwB,IAAI;;EAEtF,kBAA0B,QAAQ,2BAA2B,0BAA0B,CAAC;;EAExF,0BACE,QAAQ,mCAAmC,kCAAkC,YAAY;CAC7F;AACF"}
+{"version":3,"file":"auth-config.mjs","names":[],"sources":["../../../../../../../auth/src/services/auth-config.ts"],"sourcesContent":["import { config } from \"@warlock.js/core\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport ms from \"ms\";\r\nimport type {\r\n  AuthNotification,\r\n  CanAuthenticate,\r\n  LogoutWithoutTokenBehavior,\r\n  OneTimeTokenUrlBuilder,\r\n  PasswordSetter,\r\n} from \"../contracts/types\";\r\nimport type {\r\n  AuthProvider,\r\n  GoogleProviderConfig,\r\n  OtpSender,\r\n  PasskeysConfig,\r\n  ProviderUserCreator,\r\n} from \"../contracts/providers\";\r\nimport type { Auth } from \"../models/auth.model\";\r\n\r\nconst warnedLegacyKeys = new Set<string>();\r\n\r\nconst permitAuthentication: CanAuthenticate = (): boolean => true;\r\n\r\n/**\r\n * `ms` accepts anything at runtime and answers `undefined` for a string it\r\n * cannot parse (`\"30dayz\"`), a *formatted string* for a number (`2592000` ⇒\r\n * `\"43m\"`), and throws for `\"\"`. Its published types claim the far narrower\r\n * `(value: ms.StringValue) => number`, which is exactly what let an\r\n * `as ms.StringValue` cast smuggle arbitrary config text past the compiler and\r\n * hand `undefined` to the JWT signer. Declare the honest runtime signature once,\r\n * here, so every caller is forced to deal with the `undefined`.\r\n */\r\nconst parseMs = ms as unknown as (value: unknown) => number | string | undefined;\r\n\r\n/**\r\n * Turn a configured lifetime into a positive number of milliseconds, or throw\r\n * naming the key.\r\n *\r\n * A token lifetime is a security boundary, so an unusable value is a hard error\r\n * rather than a silent fallback: substituting a default would trade one\r\n * unintended lifetime for another, just as quietly — and quiet is the whole\r\n * problem. Every non-positive, non-finite or non-numeric parse is rejected:\r\n *\r\n * - `\"30dayz\"` / `\"thirty days\"` ⇒ `undefined` ⇒ a JWT signed with **no `exp`\r\n *   claim** and an `Invalid Date` written to the token row.\r\n * - `\"0d\"` ⇒ parses cleanly to `0`, which `fast-jwt` treats as falsy and also\r\n *   emits with **no `exp` claim** — it survives any guard that only rejects\r\n *   `undefined`. `\"-1h\"` signs an already-expired token.\r\n * - `2592000` (a bare number) ⇒ `ms` *formats* it as `\"43m\"`, a string, which\r\n *   then turns `Date.now() + expiresIn` into an `Invalid Date`.\r\n */\r\nfunction parseDuration(key: string, raw: unknown): number {\r\n  let parsed: number | string | undefined;\r\n\r\n  try {\r\n    parsed = parseMs(raw);\r\n  } catch {\r\n    // ms throws (rather than returning undefined) for \"\" and non-strings\r\n    parsed = undefined;\r\n  }\r\n\r\n  if (typeof parsed !== \"number\" || !Number.isFinite(parsed) || parsed <= 0) {\r\n    throw new Error(\r\n      `auth.${key}: ${JSON.stringify(raw)} is not a valid ms duration — ` +\r\n        `use a positive duration string such as \"1h\", \"7d\", or NO_EXPIRATION.`,\r\n    );\r\n  }\r\n\r\n  return parsed;\r\n}\r\n\r\n/** Email-verification token lifetime used when nothing is configured. */\r\nconst DEFAULT_VERIFICATION_EXPIRES_IN = \"24h\";\r\n\r\n/** Password-reset token lifetime used when nothing is configured. */\r\nconst DEFAULT_PASSWORD_RESET_EXPIRES_IN = \"60m\";\r\n\r\n/** Passkey challenge lifetime used when nothing is configured. */\r\nconst DEFAULT_PASSKEY_CHALLENGE_EXPIRES_IN = \"5m\";\r\n\r\n/** OTP lifetime used when nothing is configured. */\r\nconst DEFAULT_OTP_EXPIRES_IN = \"5m\";\r\n\r\n/** Access-token lifetime used when nothing is configured. */\r\nconst DEFAULT_ACCESS_TOKEN_EXPIRES_IN = \"1h\";\r\n\r\n/**\r\n * Resolve an auth setting, preferring the new `auth.accessToken.*` /\r\n * `auth.refreshToken.*` key and falling back to the deprecated `auth.jwt.*`\r\n * shape — warning once per legacy key. Returns `fallback` when neither is set.\r\n *\r\n * This is the backward-compatible shim that lets existing `auth.jwt.*` configs\r\n * keep working after the config split.\r\n */\r\nfunction resolve<T>(newKey: string, legacyKey: string, fallback?: T): T {\r\n  const fromNew = config.key(`auth.${newKey}`);\r\n\r\n  if (fromNew !== undefined && fromNew !== null) {\r\n    return fromNew as T;\r\n  }\r\n\r\n  const fromLegacy = config.key(`auth.${legacyKey}`);\r\n\r\n  if (fromLegacy !== undefined && fromLegacy !== null) {\r\n    if (!warnedLegacyKeys.has(legacyKey)) {\r\n      warnedLegacyKeys.add(legacyKey);\r\n      log.warn(\r\n        \"auth\",\r\n        \"config-deprecation\",\r\n        `auth.${legacyKey} is deprecated — use auth.${newKey}`,\r\n      );\r\n    }\r\n\r\n    return fromLegacy as T;\r\n  }\r\n\r\n  return fallback as T;\r\n}\r\n\r\n/**\r\n * Typed, backward-compatible access to auth configuration. The service and the\r\n * jwt signer read configuration exclusively through here, so the new split\r\n * config and the legacy `auth.jwt.*` shape both resolve the same way.\r\n */\r\nexport const authConfig = {\r\n  canAuthenticate: async (user: Auth): Promise<boolean> => {\r\n    const canAuthenticate = config.key<CanAuthenticate>(\r\n      \"auth.canAuthenticate\",\r\n      permitAuthentication,\r\n    );\r\n\r\n    return canAuthenticate(user);\r\n  },\r\n  accessToken: {\r\n    /** Signing secret (legacy: `auth.jwt.secret`). Throws if neither is set. */\r\n    secret: (): string => {\r\n      const secret = resolve<string | undefined>(\"accessToken.secret\", \"jwt.secret\");\r\n\r\n      if (!secret) {\r\n        throw new Error(\"auth: no JWT secret configured — set `auth.accessToken.secret`.\");\r\n      }\r\n\r\n      return secret;\r\n    },\r\n    /** Signing algorithm (legacy: `auth.jwt.algorithm`). */\r\n    algorithm: (): Algorithm => resolve(\"accessToken.algorithm\", \"jwt.algorithm\", \"HS256\"),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.expiresIn`). */\r\n    expiresIn: (): string | undefined => resolve(\"accessToken.expiresIn\", \"jwt.expiresIn\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Defaults\r\n     * to 1 hour when unset; throws naming the key when the configured value is\r\n     * not a positive `ms` duration. See {@link parseDuration}.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\r\n        \"accessToken.expiresIn\",\r\n        authConfig.accessToken.expiresIn() ?? DEFAULT_ACCESS_TOKEN_EXPIRES_IN,\r\n      ),\r\n  },\r\n  pageAuth: {\r\n    /**\r\n     * Login path a guarded PAGE route redirects a logged-out browser to.\r\n     *\r\n     * Unset (the default) ⇒ page-route auth failures keep the JSON 401 API\r\n     * contract, so existing apps see NO behavior change. Set it (e.g. \"/login\")\r\n     * to opt a browser-facing app into login-redirect UX: a logged-out human\r\n     * navigating to a guarded page lands on the login screen instead of reading\r\n     * a raw JSON error blob. Finding b9ab9804.\r\n     */\r\n    loginPath: (): string | undefined => config.key(\"auth.pageAuth.loginPath\"),\r\n    /**\r\n     * Query parameter the redirect carries the originally-requested path in, so\r\n     * the login flow can send the user back where they were headed. Defaults to\r\n     * `\"returnUrl\"`.\r\n     */\r\n    returnUrlParam: (): string => config.key(\"auth.pageAuth.returnUrlParam\", \"returnUrl\"),\r\n  },\r\n  cookie: {\r\n    /** Cookie name `setAuthCookie`/`clearAuthCookie` use. @default \"access_token\" */\r\n    name: (): string => config.key(\"auth.cookie.name\", \"access_token\"),\r\n    /** Cookie `Path` attribute `setAuthCookie`/`clearAuthCookie` use. @default \"/\" */\r\n    path: (): string => config.key(\"auth.cookie.path\", \"/\"),\r\n  },\r\n  csrf: {\r\n    /**\r\n     * Extra origins allowed on a cookie-authenticated unsafe-method request,\r\n     * beyond the request's own origin. @default []\r\n     */\r\n    allowedOrigins: (): string[] => config.key(\"auth.csrf.allowedOrigins\", []),\r\n  },\r\n  verification: {\r\n    /** Lifetime in ms of an email-verification token; throws naming the key when unusable. @default \"24h\" */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\r\n        \"verification.expiresIn\",\r\n        config.key(\"auth.verification.expiresIn\", DEFAULT_VERIFICATION_EXPIRES_IN),\r\n      ),\r\n    /** User attribute stamped with the verification date. @default \"emailVerifiedAt\" */\r\n    field: (): string => config.key(\"auth.verification.field\", \"emailVerifiedAt\"),\r\n    /** App notification replacing the default verification email. */\r\n    notification: (): AuthNotification | undefined => config.key(\"auth.verification.notification\"),\r\n    /** Link builder whose result is handed to the notification as `url`. */\r\n    url: (): OneTimeTokenUrlBuilder | undefined => config.key(\"auth.verification.url\"),\r\n  },\r\n  passwordReset: {\r\n    /** Lifetime in ms of a password-reset token; throws naming the key when unusable. @default \"60m\" */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\r\n        \"passwordReset.expiresIn\",\r\n        config.key(\"auth.passwordReset.expiresIn\", DEFAULT_PASSWORD_RESET_EXPIRES_IN),\r\n      ),\r\n    /** User attribute `requestPasswordReset` looks the account up by. @default \"email\" */\r\n    identifierField: (): string => config.key(\"auth.passwordReset.identifierField\", \"email\"),\r\n    /** App notification replacing the default reset email. */\r\n    notification: (): AuthNotification | undefined => config.key(\"auth.passwordReset.notification\"),\r\n    /** Link builder whose result is handed to the notification as `url`. */\r\n    url: (): OneTimeTokenUrlBuilder | undefined => config.key(\"auth.passwordReset.url\"),\r\n    /** App-owned password writer replacing the default. */\r\n    setPassword: (): PasswordSetter | undefined => config.key(\"auth.passwordReset.setPassword\"),\r\n  },\r\n  providers: {\r\n    /** `auth.providers.google`, when configured. */\r\n    google: (): GoogleProviderConfig | undefined => config.key(\"auth.providers.google\"),\r\n    /** An app-registered provider under `auth.providers.custom.<name>`. */\r\n    custom: (name: string): AuthProvider | undefined =>\r\n      config.key<Record<string, AuthProvider>>(\"auth.providers.custom\", {})[name],\r\n    /** User attribute a verified provider email is matched against. @default \"email\" */\r\n    emailField: (): string => config.key(\"auth.providers.emailField\", \"email\"),\r\n    /** App-owned user creation for a first provider login. */\r\n    createUser: (): ProviderUserCreator | undefined => config.key(\"auth.providers.createUser\"),\r\n  },\r\n  passkeys: {\r\n    /** `auth.passkeys`; throws naming the keys when `rpID`, `rpName` or `origin` is missing. */\r\n    settings: (): PasskeysConfig => {\r\n      const settings = config.key<PasskeysConfig | undefined>(\"auth.passkeys\");\r\n\r\n      if (!settings?.rpID || !settings.rpName || !settings.origin) {\r\n        throw new Error(\r\n          \"@warlock.js/auth: passkeys need `auth.passkeys.rpID`, `auth.passkeys.rpName` and `auth.passkeys.origin`.\",\r\n        );\r\n      }\r\n\r\n      return settings;\r\n    },\r\n    /** Allowed ceremony origins, as a list. */\r\n    origins: (): string[] => {\r\n      const { origin } = authConfig.passkeys.settings();\r\n\r\n      return Array.isArray(origin) ? origin : [origin];\r\n    },\r\n    /** Challenge lifetime in ms; throws naming the key when unusable. @default \"5m\" */\r\n    challengeExpiresInMs: (): number =>\r\n      parseDuration(\r\n        \"passkeys.challengeExpiresIn\",\r\n        config.key(\"auth.passkeys.challengeExpiresIn\", DEFAULT_PASSKEY_CHALLENGE_EXPIRES_IN),\r\n      ),\r\n  },\r\n  otp: {\r\n    /** Notifications channel the code is sent through. @default \"sms\" */\r\n    channel: (): string => config.key(\"auth.otp.channel\", \"sms\"),\r\n    /** User attribute holding the phone number. @default \"phone\" */\r\n    phoneField: (): string => config.key(\"auth.otp.phoneField\", \"phone\"),\r\n    /** Code lifetime in ms; throws naming the key when unusable. @default \"5m\" */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\"otp.expiresIn\", config.key(\"auth.otp.expiresIn\", DEFAULT_OTP_EXPIRES_IN)),\r\n    /** Verify attempts before the code is invalidated. @default 5 */\r\n    maxAttempts: (): number => config.key(\"auth.otp.maxAttempts\", 5),\r\n    /** The message text for a code. */\r\n    message: (code: string): string => {\r\n      const build = config.key<((code: string) => string) | undefined>(\"auth.otp.message\");\r\n\r\n      return build ? build(code) : `Your verification code is ${code}`;\r\n    },\r\n    /** App-owned delivery replacing the notifications channel send. */\r\n    send: (): OtpSender | undefined => config.key(\"auth.otp.send\"),\r\n  },\r\n  refreshToken: {\r\n    /** Separate refresh secret (legacy: `auth.jwt.refresh.secret`); empty ⇒ fall back to the access secret. */\r\n    secret: (): string | undefined => resolve(\"refreshToken.secret\", \"jwt.refresh.secret\"),\r\n    /** Whether refresh tokens are enabled (legacy: `auth.jwt.refresh.enabled`). */\r\n    enabled: (): boolean => resolve(\"refreshToken.enabled\", \"jwt.refresh.enabled\", true),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.refresh.expiresIn`). */\r\n    expiresIn: (): string => resolve(\"refreshToken.expiresIn\", \"jwt.refresh.expiresIn\", \"7d\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Throws\r\n     * naming the key when the configured value is not a positive `ms` duration.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\"refreshToken.expiresIn\", authConfig.refreshToken.expiresIn()),\r\n    /** Rotate-on-use (legacy: `auth.jwt.refresh.rotation`). */\r\n    rotation: (): boolean => resolve(\"refreshToken.rotation\", \"jwt.refresh.rotation\", true),\r\n    /** Max active tokens per user (legacy: `auth.jwt.refresh.maxPerUser`). */\r\n    maxPerUser: (): number => resolve(\"refreshToken.maxPerUser\", \"jwt.refresh.maxPerUser\", 5),\r\n    /** Logout-without-token behavior (legacy: `auth.jwt.refresh.logoutWithoutToken`). */\r\n    logoutWithoutToken: (): LogoutWithoutTokenBehavior =>\r\n      resolve(\"refreshToken.logoutWithoutToken\", \"jwt.refresh.logoutWithoutToken\", \"revoke-all\"),\r\n  },\r\n};\r\n"],"mappings":"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"}

package/esm/services/auth.service.d.mts

@@ -1,7 +1,8 @@
 import { Auth } from "../models/auth.model.mjs";
 import { AccessToken } from "../models/access-token/access-token.model.mjs";
-import { AccessTokenOutput, AuthCredentials, DeviceInfo, LoginResult, TokenPair } from "../contracts/types.mjs";
+import { AccessTokenOutput, AuthCredentials, ClearAuthCookieOptions, DeviceInfo, LoginResult, SetAuthCookieOptions, TokenPair } from "../contracts/types.mjs";
 import { RefreshToken } from "../models/refresh-token/refresh-token.model.mjs";
+import { Response } from "@warlock.js/core";
 import { ChildModel } from "@warlock.js/cascade";
 
 //#region ../auth/src/services/auth.service.d.ts
@@ -17,6 +18,10 @@ declare class AuthService {
    * Resolve the active refresh-token model (default or registered override).
    */
   private get refreshTokenModel();
+  /**
+   * Resolve the active one-time-token model (default or registered override).
+   */
+  private get oneTimeTokenModel();
   /**
    * Build the default access-token JWT payload from a user.
    */
@@ -66,6 +71,18 @@ declare class AuthService {
    * the user + token pair on success, `null` on failure.
    */
   login<T extends Auth>(Model: ChildModel<T>, credentials: AuthCredentials, deviceInfo?: DeviceInfo): Promise<LoginResult<T> | null>;
+  /**
+   * Log in a user some OTHER method already authenticated — a provider
+   * callback, a passkey assertion, a one-time code. Applies the
+   * `auth.canAuthenticate` policy (403 on refusal), then produces exactly
+   * what {@link login} produces: the same tokens, rows and events. Pair with
+   * {@link setAuthCookie} for a cookie session, as with password login.
+   *
+   * Never call this for a user you have not authenticated.
+   */
+  completeLogin<T extends Auth>(user: T, deviceInfo?: DeviceInfo): Promise<LoginResult<T>>;
+  /** The one token-issuing tail every login method shares. */
+  private finalizeLogin;
   /**
    * Log a user out.
    *
@@ -100,7 +117,8 @@ declare class AuthService {
    */
   revokeTokenFamily(familyId: string): Promise<void>;
   /**
-   * Delete expired tokens (refresh + access). Emits `token.expired` per refresh
+   * Delete expired tokens (refresh + access) and spent one-time tokens
+   * (expired or consumed verification/reset/OTP/passkey rows). Emits `token.expired` per refresh
    * token and `cleanup.completed` with the refresh count. Drives the
    * `auth.cleanup` CLI command.
    */
@@ -135,6 +153,45 @@ declare class AuthService {
    * Active, unexpired sessions for the user, newest first.
    */
   getActiveSessions(user: Auth): Promise<RefreshToken[]>;
+  /**
+   * `Max-Age` (seconds) `setAuthCookie` should apply, derived from an
+   * `AccessTokenOutput`'s `expiresAt` — or `undefined` for a bare token
+   * string (a session cookie) or an unparseable `expiresAt`.
+   */
+  private cookieMaxAgeFromToken;
+  /**
+   * Write the auth cookie on `response` — the write side of the `cookie:<name>`
+   * token source `authMiddleware([], "cookie:<name>")` already reads. An explicit
+   * app-controller call, never a side effect of {@link login}, so an existing
+   * bearer-only app never starts emitting `Set-Cookie` just by upgrading.
+   *
+   * Attribute flags (`HttpOnly`, `SameSite=Lax`, `Secure` outside dev) come
+   * from `response.cookie()`'s own `secureCookieDefaults()` floor — this
+   * method never overrides them, only `name`/`path`/`maxAge`. `raw: true`
+   * writes the token unquoted, so the same string a `cookie:<name>` source
+   * reads back is exactly what was issued, not a JSON-wrapped copy.
+   *
+   * @param token - the token string, or an `AccessTokenOutput` (e.g. from
+   *   {@link login}) whose `expiresAt` sets `Max-Age` automatically when
+   *   `options.maxAge` is not given. A bare string with no `options.maxAge`
+   *   produces a session cookie.
+   *
+   * @example
+   * const { user, tokens } = await authService.login(User, credentials);
+   * authService.setAuthCookie(response, tokens.accessToken);
+   */
+  setAuthCookie(response: Response, token: string | AccessTokenOutput, options?: SetAuthCookieOptions): void;
+  /**
+   * Clear the auth cookie {@link setAuthCookie} wrote. An explicit
+   * app-controller call — pair it with {@link logout} after the token row is
+   * revoked. `path` must match what the cookie was set with, or the browser
+   * silently ignores the clear (see `response.clearCookie`'s own doc comment).
+   *
+   * @example
+   * await authService.logout(user, accessToken, refreshToken);
+   * authService.clearAuthCookie(response);
+   */
+  clearAuthCookie(response: Response, options?: ClearAuthCookieOptions): void;
 }
 declare const authService: AuthService;
 //#endregion

package/esm/services/auth.service.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.service.d.mts","names":[],"sources":["../../../../../../../auth/src/services/auth.service.ts"],"mappings":";;;;;;;cAiBM,WAAA;;;;AALiD;;;cAYzC,gBAAA;EAcgC;;;EAAA,YAPhC,iBAAA;EAiDA;;;EA1CL,uBAAA,CAAwB,IAAA,EAAM,IAAA,GAAO,MAAA;EAmF7B;EA1EF,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAAA,QAI5B,qBAAA;EAAA,QAMA,gBAAA;EAmGwC;;;;;EA9EzC,mBAAA,CACX,IAAA,EAAM,IAAA,EACN,OAAA,GAAU,MAAA,oBACT,OAAA,CAAQ,iBAAA;EAAA,QAMG,iBAAA;EAoK+B;;;;EApIhC,kBAAA,CACX,IAAA,EAAM,IAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,YAAA;EAAA,QAQG,cAAA;EAoIX;;;EA1GU,eAAA,CAAgB,IAAA,EAAM,IAAA,EAAM,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,SAAA;EA4I5D;;;;;EAjIF,aAAA,CACX,kBAAA,UACA,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,SAAA;EA8JmE;;;EApFjE,cAAA,CAAe,aAAA,UAAuB,cAAA,WAAyB,OAAA;EAwH5B;;;EAjHnC,YAAA,CAAa,QAAA,WAAmB,OAAA;EAiIH;;;;EAzH7B,YAAA,WAAuB,IAAA,EAClC,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,IAAA,EAAM,eAAA,GACL,OAAA,CAAQ,CAAA;EAwK6B;;;;EAxI3B,KAAA,WAAgB,IAAA,EAC3B,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,WAAA,EAAa,eAAA,EACb,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EA0K4B;;;;;;;;;;EA5ItC,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,WAAA,WAAsB,YAAA,YAAwB,OAAA;EAzRpC;;;EAsT7B,iBAAA,CAAkB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EAtRnD;;;EA6RK,qBAAA,CAAsB,IAAA,EAAM,IAAA,GAAO,OAAA;EA3R7C;;;EAkSU,kBAAA,CAAmB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EA3PpD;;;;;EAoQK,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EA1P5B;;;EAyQD,iBAAA,CAAkB,QAAA,WAAmB,OAAA;EA/OI;;;;;EA0PzC,oBAAA,IAAwB,OAAA;EA7OtB;;;;;;;;;;EAqQF,uBAAA,IAA2B,OAAA;IACtC,YAAA,EAAc,WAAA;IACd,aAAA,EAAe,YAAA;EAAA;EA5KR;;;;;;;;EA4LI,wBAAA,IAA4B,OAAA;IACvC,YAAA;IACA,aAAA;EAAA;EA3JA;;;EA6KW,iBAAA,CAAkB,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,YAAA;AAAA;AAAA,cAKzC,WAAA,EAAW,WAAoB"}
+{"version":3,"file":"auth.service.d.mts","names":[],"sources":["../../../../../../../auth/src/services/auth.service.ts"],"mappings":";;;;;;;;cA0BM,WAAA;;;;AALiD;;;cAYzC,gBAAA;EAqBgC;;;EAAA,YAdhC,iBAAA;EAwDA;;;EAAA,YAjDA,iBAAA;EA0FG;;;EAnFR,uBAAA,CAAwB,IAAA,EAAM,IAAA,GAAO,MAAA;EAsHU;EA7GzC,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAAA,QAI5B,qBAAA;EAAA,QAMA,gBAAA;EAiHH;;;;;EA5FE,mBAAA,CACX,IAAA,EAAM,IAAA,EACN,OAAA,GAAU,MAAA,oBACT,OAAA,CAAQ,iBAAA;EAAA,QAMG,iBAAA;EA4KN;;;;EA5IK,kBAAA,CACX,IAAA,EAAM,IAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,YAAA;EAAA,QAQG,cAAA;EAoKC;;;EA1IF,eAAA,CAAgB,IAAA,EAAM,IAAA,EAAM,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,SAAA;EA4IxE;;;;;EAjIU,aAAA,CACX,kBAAA,UACA,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,SAAA;EAoJR;;;EA5EU,cAAA,CAAe,aAAA,UAAuB,cAAA,WAAyB,OAAA;EA2IjB;;;EApI9C,YAAA,CAAa,QAAA,WAAmB,OAAA;EAkJe;;;;EA1I/C,YAAA,WAAuB,IAAA,EAClC,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,IAAA,EAAM,eAAA,GACL,OAAA,CAAQ,CAAA;EAqMK;;;;EArKH,KAAA,WAAgB,IAAA,EAC3B,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,WAAA,EAAa,eAAA,EACb,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EAsM6B;;;;;;;;;EAnLvC,aAAA,WAAwB,IAAA,EACnC,IAAA,EAAM,CAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EAtSX;EAAA,QA6SE,aAAA;EA/RP;;;;;;;;;;EA0TM,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,WAAA,WAAsB,YAAA,YAAwB,OAAA;EAjRtE;;;EA8SK,iBAAA,CAAkB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EA5SxD;;;EAmTU,qBAAA,CAAsB,IAAA,EAAM,IAAA,GAAO,OAAA;EA5QxC;;;EAmRK,kBAAA,CAAmB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EAjRzD;;;;;EA0RU,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAxPY;;;EAuQzC,iBAAA,CAAkB,QAAA,WAAmB,OAAA;EA5PrC;;;;;;EAwQA,oBAAA,IAAwB,OAAA;EA7LT;;;;;;;;;;EAsNf,uBAAA,IAA2B,OAAA;IACtC,YAAA,EAAc,WAAA;IACd,aAAA,EAAe,YAAA;EAAA;EAtMd;;;;;;;;EAsNU,wBAAA,IAA4B,OAAA;IACvC,YAAA;IACA,aAAA;EAAA;EApLC;;;EAsMU,iBAAA,CAAkB,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,YAAA;EAnLzB;;;;;EAAA,QA4LnB,qBAAA;EAzLL;;;;;;;;;;;;;;;;;;;;;EAwNI,aAAA,CACL,QAAA,EAAU,QAAA,EACV,KAAA,WAAgB,iBAAA,EAChB,OAAA,GAAS,oBAAA;EA9IiC;;;;;;;;;;EAsKrC,eAAA,CAAgB,QAAA,EAAU,QAAA,EAAU,OAAA,GAAS,sBAAA;AAAA;AAAA,cAQzC,WAAA,EAAW,WAAoB"}

package/esm/services/auth.service.mjs

@@ -1,5 +1,7 @@
 import { AccessToken } from "../models/access-token/access-token.model.mjs";
 import "../models/access-token/index.mjs";
+import { OneTimeToken } from "../models/one-time-token/one-time-token.model.mjs";
+import "../models/one-time-token/index.mjs";
 import { RefreshToken } from "../models/refresh-token/refresh-token.model.mjs";
 import "../models/refresh-token/index.mjs";
 import { authConfig } from "./auth-config.mjs";
@@ -26,6 +28,12 @@ var AuthService = class {
 		return config.key("auth.refreshToken.model", RefreshToken);
 	}
 	/**
+	* Resolve the active one-time-token model (default or registered override).
+	*/
+	get oneTimeTokenModel() {
+		return config.key("auth.oneTimeToken.model", OneTimeToken);
+	}
+	/**
 	* Build the default access-token JWT payload from a user.
 	*/
 	buildAccessTokenPayload(user) {
@@ -188,6 +196,23 @@ var AuthService = class {
 	async login(Model, credentials, deviceInfo) {
 		const user = await this.attemptLogin(Model, credentials);
 		if (!user) return null;
+		return this.finalizeLogin(user, deviceInfo);
+	}
+	/**
+	* Log in a user some OTHER method already authenticated — a provider
+	* callback, a passkey assertion, a one-time code. Applies the
+	* `auth.canAuthenticate` policy (403 on refusal), then produces exactly
+	* what {@link login} produces: the same tokens, rows and events. Pair with
+	* {@link setAuthCookie} for a cookie session, as with password login.
+	*
+	* Never call this for a user you have not authenticated.
+	*/
+	async completeLogin(user, deviceInfo) {
+		await this.assertCanAuthenticate(user);
+		return this.finalizeLogin(user, deviceInfo);
+	}
+	/** The one token-issuing tail every login method shares. */
+	async finalizeLogin(user, deviceInfo) {
 		if (!authConfig.refreshToken.enabled()) return {
 			user,
 			tokens: { accessToken: await this.issueAccessToken(user, deviceInfo?.payload) }
@@ -261,7 +286,8 @@ var AuthService = class {
 		authEvents.emit("token.familyRevoked", familyId, revokedTokens);
 	}
 	/**
-	* Delete expired tokens (refresh + access). Emits `token.expired` per refresh
+	* Delete expired tokens (refresh + access) and spent one-time tokens
+	* (expired or consumed verification/reset/OTP/passkey rows). Emits `token.expired` per refresh
 	* token and `cleanup.completed` with the refresh count. Drives the
 	* `auth.cleanup` CLI command.
 	*/
@@ -269,6 +295,7 @@ var AuthService = class {
 		const expiredTokens = await this.refreshTokenModel.purgeExpired();
 		for (const token of expiredTokens) authEvents.emit("token.expired", token);
 		await this.accessTokenModel.purgeExpired();
+		await this.oneTimeTokenModel.purgeSpent();
 		authEvents.emit("cleanup.completed", expiredTokens.length);
 		return expiredTokens.length;
 	}
@@ -311,6 +338,64 @@ var AuthService = class {
 	async getActiveSessions(user) {
 		return this.refreshTokenModel.activeFor(user);
 	}
+	/**
+	* `Max-Age` (seconds) `setAuthCookie` should apply, derived from an
+	* `AccessTokenOutput`'s `expiresAt` — or `undefined` for a bare token
+	* string (a session cookie) or an unparseable `expiresAt`.
+	*/
+	cookieMaxAgeFromToken(token) {
+		if (typeof token === "string") return void 0;
+		const expiresAt = new Date(token.expiresAt).getTime();
+		if (Number.isNaN(expiresAt)) return void 0;
+		return Math.max(0, Math.round((expiresAt - Date.now()) / 1e3));
+	}
+	/**
+	* Write the auth cookie on `response` — the write side of the `cookie:<name>`
+	* token source `authMiddleware([], "cookie:<name>")` already reads. An explicit
+	* app-controller call, never a side effect of {@link login}, so an existing
+	* bearer-only app never starts emitting `Set-Cookie` just by upgrading.
+	*
+	* Attribute flags (`HttpOnly`, `SameSite=Lax`, `Secure` outside dev) come
+	* from `response.cookie()`'s own `secureCookieDefaults()` floor — this
+	* method never overrides them, only `name`/`path`/`maxAge`. `raw: true`
+	* writes the token unquoted, so the same string a `cookie:<name>` source
+	* reads back is exactly what was issued, not a JSON-wrapped copy.
+	*
+	* @param token - the token string, or an `AccessTokenOutput` (e.g. from
+	*   {@link login}) whose `expiresAt` sets `Max-Age` automatically when
+	*   `options.maxAge` is not given. A bare string with no `options.maxAge`
+	*   produces a session cookie.
+	*
+	* @example
+	* const { user, tokens } = await authService.login(User, credentials);
+	* authService.setAuthCookie(response, tokens.accessToken);
+	*/
+	setAuthCookie(response, token, options = {}) {
+		const name = options.name ?? authConfig.cookie.name();
+		const path = options.path ?? authConfig.cookie.path();
+		const tokenValue = typeof token === "string" ? token : token.token;
+		const maxAge = options.maxAge ?? this.cookieMaxAgeFromToken(token);
+		response.cookie(name, tokenValue, {
+			raw: true,
+			path,
+			...maxAge !== void 0 ? { maxAge } : {}
+		});
+	}
+	/**
+	* Clear the auth cookie {@link setAuthCookie} wrote. An explicit
+	* app-controller call — pair it with {@link logout} after the token row is
+	* revoked. `path` must match what the cookie was set with, or the browser
+	* silently ignores the clear (see `response.clearCookie`'s own doc comment).
+	*
+	* @example
+	* await authService.logout(user, accessToken, refreshToken);
+	* authService.clearAuthCookie(response);
+	*/
+	clearAuthCookie(response, options = {}) {
+		const name = options.name ?? authConfig.cookie.name();
+		const path = options.path ?? authConfig.cookie.path();
+		response.clearCookie(name, { path });
+	}
 };
 const authService = new AuthService();