@draftlab/auth 0.3.0 → 0.4.1

package/dist/plugin/plugin.js

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

package/dist/provider/magiclink.d.ts

@@ -0,0 +1,89 @@
+import { Provider } from "./provider.js";
+
+//#region src/provider/magiclink.d.ts
+
+/**
+ * Configuration options for the Magic Link authentication provider.
+ *
+ * @template Claims - Type of claims collected during authentication (email, phone, etc.)
+ */
+interface MagicLinkConfig<Claims extends Record<string, string> = Record<string, string>> {
+  /**
+   * Token expiration time in seconds.
+   * After this time, the magic link becomes invalid.
+   *
+   * @default 900 (15 minutes)
+   */
+  readonly expiry?: number;
+  /**
+   * Request handler for rendering the magic link UI.
+   * Handles both the initial claim collection and "check your email" screens.
+   *
+   * @param req - The HTTP request object
+   * @param state - Current authentication state
+   * @param form - Form data from POST requests (if any)
+   * @param error - Authentication error to display (if any)
+   * @returns Promise resolving to the authentication page response
+   */
+  request: (req: Request, state: MagicLinkState, form?: FormData, error?: MagicLinkError) => Promise<Response>;
+  /**
+   * Callback for sending magic links to users.
+   * Should handle delivery via email, SMS, or other communication channels.
+   *
+   * @param claims - User claims containing contact information
+   * @param magicUrl - The magic link URL to send
+   * @returns Promise resolving to undefined on success, or error object on failure
+   */
+  sendLink: (claims: Claims, magicUrl: string) => Promise<MagicLinkError | undefined>;
+}
+/**
+ * Authentication flow states for the magic link provider.
+ * The provider transitions between these states during authentication.
+ */
+type MagicLinkState = {
+  /** Initial state: user enters their claims (email, phone, etc.) */
+  readonly type: "start";
+} | {
+  /** Link sent state: user checks their email/phone */
+  readonly type: "sent";
+  /** Whether this is a resend request */
+  readonly resend?: boolean;
+  /** The secure token for verification */
+  readonly token: string;
+  /** User claims collected during the start phase */
+  readonly claims: Record<string, string>;
+};
+/**
+ * Possible errors during magic link authentication.
+ */
+type MagicLinkError = {
+  /** The magic link is invalid or expired */
+  readonly type: "invalid_link";
+} | {
+  /** A user claim is invalid or missing */
+  readonly type: "invalid_claim";
+  /** The claim field that failed validation */
+  readonly key: string;
+  /** The invalid value or error description */
+  readonly value: string;
+};
+/**
+ * User data returned by successful magic link authentication.
+ *
+ * @template Claims - Type of claims collected during authentication
+ */
+interface MagicLinkUserData<Claims extends Record<string, string> = Record<string, string>> {
+  /** The verified claims collected during authentication */
+  readonly claims: Claims;
+}
+/**
+ * Creates a Magic Link authentication provider.
+ * Implements a flexible claim-based authentication flow with magic link verification.
+ *
+ * @template Claims - Type of claims to collect (email, phone, username, etc.)
+ * @param config - Magic Link provider configuration
+ * @returns Provider instance implementing magic link authentication
+ */
+declare const MagicLinkProvider: <Claims extends Record<string, string> = Record<string, string>>(config: MagicLinkConfig<Claims>) => Provider<MagicLinkUserData<Claims>>;
+//#endregion
+export { MagicLinkConfig, MagicLinkError, MagicLinkProvider, MagicLinkState, MagicLinkUserData };

package/dist/provider/magiclink.js

@@ -0,0 +1,87 @@
+import { generateUnbiasedDigits, timingSafeCompare } from "../random.js";
+
+//#region src/provider/magiclink.ts
+/**
+* Creates a Magic Link authentication provider.
+* Implements a flexible claim-based authentication flow with magic link verification.
+*
+* @template Claims - Type of claims to collect (email, phone, username, etc.)
+* @param config - Magic Link provider configuration
+* @returns Provider instance implementing magic link authentication
+*/
+const MagicLinkProvider = (config) => {
+	/**
+	* Generates a cryptographically secure token.
+	*/
+	const generateToken = () => {
+		return generateUnbiasedDigits(32);
+	};
+	return {
+		type: "magiclink",
+		init(routes, ctx) {
+			/**
+			* Transitions between authentication states and renders the appropriate UI.
+			*/
+			const transition = async (c, nextState, formData, error) => {
+				await ctx.set(c, "provider", 3600 * 24, nextState);
+				const response = await config.request(c.request, nextState, formData, error);
+				return ctx.forward(c, response);
+			};
+			/**
+			* GET /authorize - Display initial claim collection form
+			*/
+			routes.get("/authorize", async (c) => {
+				return transition(c, { type: "start" });
+			});
+			/**
+			* POST /authorize - Handle form submissions and state transitions
+			*/
+			routes.post("/authorize", async (c) => {
+				const formData = await c.formData();
+				const action = formData.get("action")?.toString();
+				if (action === "request" || action === "resend") {
+					const token = generateToken();
+					const formEntries = Object.fromEntries(formData);
+					const { action: _,...claims } = formEntries;
+					const baseUrl = new URL(c.request.url).origin;
+					const magicUrl = new URL(`/auth/${ctx.name}/verify`, baseUrl);
+					magicUrl.searchParams.set("token", token);
+					for (const [key, value] of Object.entries(claims)) if (typeof value === "string") magicUrl.searchParams.set(key, value);
+					const sendError = await config.sendLink(claims, magicUrl.toString());
+					if (sendError) return transition(c, { type: "start" }, formData, sendError);
+					return transition(c, {
+						type: "sent",
+						resend: action === "resend",
+						claims,
+						token
+					}, formData);
+				}
+				return transition(c, { type: "start" });
+			});
+			/**
+			* GET /verify - Handle magic link clicks
+			*/
+			routes.get("/verify", async (c) => {
+				const url = new URL(c.request.url);
+				const token = url.searchParams.get("token");
+				const storedState = await ctx.get(c, "provider");
+				if (!token || !storedState || storedState.type !== "sent") return transition(c, { type: "start" }, void 0, { type: "invalid_link" });
+				if (!timingSafeCompare(storedState.token, token)) return transition(c, { type: "start" }, void 0, { type: "invalid_link" });
+				const urlClaims = {};
+				for (const [key, value] of url.searchParams) if (key !== "token" && value) urlClaims[key] = value;
+				const claimsMatch = Object.keys(storedState.claims).every((key) => {
+					const urlValue = urlClaims[key];
+					const storedValue = storedState.claims[key];
+					if (!urlValue || !storedValue) return false;
+					return timingSafeCompare(storedValue, urlValue);
+				});
+				if (!claimsMatch) return transition(c, { type: "start" }, void 0, { type: "invalid_link" });
+				await ctx.unset(c, "provider");
+				return await ctx.success(c, { claims: storedState.claims });
+			});
+		}
+	};
+};
+
+//#endregion
+export { MagicLinkProvider };

package/dist/types.js

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

package/dist/ui/magiclink.d.ts

@@ -0,0 +1,41 @@
+import { MagicLinkConfig } from "../provider/magiclink.js";
+
+//#region src/ui/magiclink.d.ts
+
+/**
+ * Type for customizable UI copy text
+ */
+interface MagicLinkUICopy {
+  readonly email_placeholder: string;
+  readonly email_invalid: string;
+  readonly button_continue: string;
+  readonly link_info: string;
+  readonly link_sent: string;
+  readonly link_resent: string;
+  readonly link_didnt_get: string;
+  readonly link_resend: string;
+}
+/**
+ * Input mode for the contact field
+ */
+type MagicLinkUIMode = "email" | "phone";
+/**
+ * Configuration options for the MagicLinkUI component
+ */
+interface MagicLinkUIOptions<Claims extends Record<string, string> = Record<string, string>> extends Pick<MagicLinkConfig<Claims>, "sendLink"> {
+  /**
+   * Input mode determining the type of contact information to collect
+   * @default "email"
+   */
+  readonly mode?: MagicLinkUIMode;
+  /**
+   * Custom text copy for UI labels, messages, and errors
+   */
+  readonly copy?: Partial<MagicLinkUICopy>;
+}
+/**
+ * Creates a complete UI configuration for Magic Link authentication
+ */
+declare const MagicLinkUI: <Claims extends Record<string, string> = Record<string, string>>(options: MagicLinkUIOptions<Claims>) => MagicLinkConfig<Claims>;
+//#endregion
+export { MagicLinkUI, MagicLinkUICopy, MagicLinkUIMode, MagicLinkUIOptions };

package/dist/ui/magiclink.js

@@ -0,0 +1,146 @@
+import { Layout, renderToHTML } from "./base.js";
+import { FormAlert } from "./form.js";
+import { jsx, jsxs } from "preact/jsx-runtime";
+
+//#region src/ui/magiclink.tsx
+/**
+* Default text copy for the Magic Link authentication UI
+*/
+const DEFAULT_COPY = {
+	email_placeholder: "Email",
+	email_invalid: "Email address is not valid",
+	button_continue: "Send Magic Link",
+	link_info: "We'll send a secure link to your email.",
+	link_sent: "Magic link sent to ",
+	link_resent: "Magic link resent to ",
+	link_didnt_get: "Didn't get the email?",
+	link_resend: "Resend Magic Link"
+};
+/**
+* Gets the appropriate error message for display
+*/
+const getErrorMessage = (error, copy) => {
+	if (!error?.type) return void 0;
+	switch (error.type) {
+		case "invalid_link": return "This magic link is invalid or expired";
+		case "invalid_claim": return copy.email_invalid;
+	}
+};
+/**
+* Gets the appropriate success message for display
+*/
+const getSuccessMessage = (state, copy, mode) => {
+	if (state.type === "start" || !state.claims) return void 0;
+	const contact = state.claims[mode] || "";
+	const prefix = state.resend ? copy.link_resent : copy.link_sent;
+	return {
+		message: `${prefix}${contact}`,
+		contact
+	};
+};
+/**
+* Creates a complete UI configuration for Magic Link authentication
+*/
+const MagicLinkUI = (options) => {
+	const copy = {
+		...DEFAULT_COPY,
+		...options.copy
+	};
+	const mode = options.mode || "email";
+	/**
+	* Renders the start form for collecting contact information
+	*/
+	const renderStart = (form, error, state) => {
+		const success = getSuccessMessage(state || { type: "start" }, copy, mode);
+		return /* @__PURE__ */ jsx(Layout, { children: /* @__PURE__ */ jsxs("form", {
+			"data-component": "form",
+			method: "post",
+			children: [
+				success ? /* @__PURE__ */ jsx(FormAlert, {
+					message: success.message,
+					color: "success"
+				}) : /* @__PURE__ */ jsx(FormAlert, { message: getErrorMessage(error, copy) }),
+				/* @__PURE__ */ jsx("input", {
+					"data-component": "input",
+					type: mode === "email" ? "email" : "tel",
+					name: mode,
+					placeholder: copy.email_placeholder,
+					value: form?.get(mode)?.toString() || "",
+					autoComplete: mode,
+					required: true
+				}),
+				/* @__PURE__ */ jsx("input", {
+					type: "hidden",
+					name: "action",
+					value: "request"
+				}),
+				/* @__PURE__ */ jsx("button", {
+					"data-component": "button",
+					type: "submit",
+					children: copy.button_continue
+				}),
+				/* @__PURE__ */ jsx("p", {
+					"data-component": "description",
+					children: copy.link_info
+				})
+			]
+		}) });
+	};
+	/**
+	* Renders the "check your email" page after magic link is sent
+	*/
+	const renderSent = (_form, error, state) => {
+		const success = getSuccessMessage(state, copy, mode);
+		const contact = state.type === "sent" ? state.claims?.[mode] || "" : "";
+		return /* @__PURE__ */ jsx(Layout, { children: /* @__PURE__ */ jsxs("form", {
+			"data-component": "form",
+			method: "post",
+			children: [
+				/* @__PURE__ */ jsx("h2", {
+					"data-component": "title",
+					children: "Check your email"
+				}),
+				success ? /* @__PURE__ */ jsx(FormAlert, {
+					message: success.message,
+					color: "success"
+				}) : /* @__PURE__ */ jsx(FormAlert, { message: getErrorMessage(error, copy) }),
+				/* @__PURE__ */ jsx("p", {
+					"data-component": "description",
+					children: "Click the link in your email to sign in."
+				}),
+				/* @__PURE__ */ jsx("input", {
+					name: "action",
+					type: "hidden",
+					value: "resend"
+				}),
+				/* @__PURE__ */ jsx("input", {
+					name: mode,
+					type: "hidden",
+					value: contact
+				}),
+				/* @__PURE__ */ jsx("div", {
+					"data-component": "form-footer",
+					children: /* @__PURE__ */ jsxs("span", { children: [
+						copy.link_didnt_get,
+						" ",
+						/* @__PURE__ */ jsx("button", {
+							type: "submit",
+							"data-component": "link",
+							children: copy.link_resend
+						})
+					] })
+				})
+			]
+		}) });
+	};
+	return {
+		sendLink: options.sendLink,
+		request: async (_req, state, form, error) => {
+			const html = renderToHTML(state.type === "start" ? renderStart(form, error, state) : renderSent(form, error, state));
+			return new Response(html, { headers: { "Content-Type": "text/html" } });
+		}
+	};
+};
+
+//#endregion
+export { MagicLinkUI };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftlab/auth",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Core implementation for @draftlab/auth",
   "author": "Matheus Pergoli",
@@ -37,10 +37,10 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^24.1.0",
+    "@types/node": "^24.3.0",
     "@types/qrcode": "^1.5.5",
-    "tsdown": "^0.13.0",
-    "typescript": "^5.8.3",
+    "tsdown": "^0.14.1",
+    "typescript": "^5.9.2",
     "@draftlab/tsconfig": "0.1.0"
   },
   "peerDependencies": {
@@ -59,11 +59,11 @@
     "@simplewebauthn/server": "^13.1.2",
     "@standard-schema/spec": "^1.0.0",
     "jose": "^6.0.12",
-    "otpauth": "^9.4.0",
-    "preact": "^10.27.0",
+    "otpauth": "^9.4.1",
+    "preact": "^10.27.1",
     "preact-render-to-string": "^6.5.13",
     "qrcode": "^1.5.4",
-    "@draftlab/auth-router": "0.0.5"
+    "@draftlab/auth-router": "0.0.6"
   },
   "engines": {
     "node": ">=18"