@webtwizz/cloud 0.3.0 → 0.4.0

package/AI_GUIDE.md

@@ -70,6 +70,21 @@ Sign-ins are email and password only. Sign-in emails (reset codes, confirmations
 
 Sites built before this package import sign-ins from another package in `src/lib/auth/`. When you work on their sign-ins, move `server.ts`, `client.ts` and the auth route to the files above (same sign-ins, same users) and remove the old package.
 
+### Sending sign-in emails yourself
+
+Only when the owner picked "Your site" under Cloud > Users > Emails. Add `src/app/api/sign-in-emails/route.ts`; the site's sign-in service calls it with every code, and the package checks the call really comes from it:
+
+```ts
+import { handleSignInEmails, signInEmailCopy } from '@webtwizz/cloud/emails';
+
+export const POST = handleSignInEmails(async (email) => {
+  const { subject, text } = signInEmailCopy(email, 'Site name');
+  // send `subject` and `text` to `email.to` with the site's email connector, e.g. Resend
+});
+```
+
+`email` has `to`, `kind` ('code' or 'link'), `purpose` ('email-verification', 'forget-password' or 'sign-in'), and `code` or `link`. Throw if sending fails: the visitor sees the sign-in fail instead of waiting for an email that never comes. It starts working once the site is published; until then WebTwizz sends them.
+
 ## Database
 
 One shared client, server-side only (route handlers, server components, server actions):

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @webtwizz/cloud
 
+## 0.4.0
+
+### Minor Changes
+
+- 87e84b1: Sites can send their own sign-in emails: `@webtwizz/cloud/emails` adds `handleSignInEmails()`, which checks each call comes from the site's sign-in service and hands over the address and code, and `signInEmailCopy()` with WebTwizz's wording.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -14,9 +14,10 @@ WebTwizz puts every setting in the site's environment, so each module works with
 | `@webtwizz/cloud/server` | `createAuth()` with `.handler()`, `.middleware()`, `.getSession()` and the server sign-in methods |
 | `@webtwizz/cloud/client` | `createAuthClient()` for client components |
 | `@webtwizz/cloud/db` | `createDb()`, a `postgres` client with pooler-safe settings |
+| `@webtwizz/cloud/emails` | `handleSignInEmails()` for sites that send their own sign-in emails, `signInEmailCopy()` for the wording |
 | `@webtwizz/cloud/files` | `createFiles()` with `uploadUrl`, `publicUrl`, `privateUrl`, `remove` |
 
-`server`, `db` and `files` are server-only. [AI_GUIDE.md](AI_GUIDE.md) has the full walkthrough and ships with each version.
+`server`, `db`, `files` and `emails` are server-only. [AI_GUIDE.md](AI_GUIDE.md) has the full walkthrough and ships with each version.
 
 ## Environment
 

package/dist/emails.d.ts

@@ -0,0 +1,23 @@
+type SignInEmail = {
+    to: string;
+    kind: 'code' | 'link';
+    purpose: 'sign-in' | 'email-verification' | 'forget-password' | (string & {});
+    code?: string;
+    link?: string;
+    expiresAt?: string;
+};
+type SignInEmailOptions = {
+    /** The sign-in address the site's settings point at; defaults to WEBTWIZZ_AUTH_URL. */
+    authUrl?: string;
+};
+/** True when the request really comes from the site's sign-in service. */
+declare function verifySignInEmail(request: Request, body: string, options?: SignInEmailOptions): Promise<boolean>;
+/** Route handler for the sign-in emails a site sends itself: `export const POST = handleSignInEmails(async (email) => { ... })`. */
+declare function handleSignInEmails(send: (email: SignInEmail) => Promise<void>, options?: SignInEmailOptions): (request: Request) => Promise<Response>;
+/** WebTwizz's own subject and wording for a sign-in email, for sites that send their own. */
+declare function signInEmailCopy(email: SignInEmail, site: string): {
+    subject: string;
+    text: string;
+};
+
+export { type SignInEmail, type SignInEmailOptions, handleSignInEmails, signInEmailCopy, verifySignInEmail };

package/dist/emails.js

@@ -0,0 +1,83 @@
+import {
+  env
+} from "./chunk-ESAV545E.js";
+
+// src/emails.ts
+import "server-only";
+var MAX_AGE_MS = 5 * 60 * 1e3;
+var keys = /* @__PURE__ */ new Map();
+var fromBase64Url = (value) => Uint8Array.from(atob(value.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+var toBase64Url = (value) => btoa(String.fromCharCode(...new TextEncoder().encode(value))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+async function signingKey(authUrl, kid) {
+  const find = (list) => list.find((k) => k.kid === kid && k.crv === "Ed25519" && k.x);
+  const cached = keys.get(authUrl);
+  let match = cached ? find(cached.keys) : void 0;
+  if (!match && (!cached || Date.now() - cached.at > 6e4)) {
+    const response = await fetch(`${authUrl.replace(/\/+$/, "")}/.well-known/jwks.json`).catch(() => null);
+    const list = (await response?.json().catch(() => null))?.keys ?? [];
+    keys.set(authUrl, { at: Date.now(), keys: list });
+    match = find(list);
+  }
+  if (!match) return null;
+  return crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: match.x }, { name: "Ed25519" }, false, ["verify"]);
+}
+async function verifySignInEmail(request, body, options = {}) {
+  const signature = request.headers.get("x-neon-signature");
+  const kid = request.headers.get("x-neon-signature-kid");
+  const timestamp = request.headers.get("x-neon-timestamp");
+  if (!signature || !kid || !timestamp || !/^\d+$/.test(timestamp) || Math.abs(Date.now() - Number(timestamp)) > MAX_AGE_MS) return false;
+  const [header, middle, sig] = signature.split(".");
+  if (!header || middle !== "" || !sig) return false;
+  const key = await signingKey(options.authUrl ?? env("WEBTWIZZ_AUTH_URL"), kid);
+  if (!key) return false;
+  const input = new TextEncoder().encode(`${header}.${toBase64Url(`${timestamp}.${toBase64Url(body)}`)}`);
+  return crypto.subtle.verify({ name: "Ed25519" }, key, fromBase64Url(sig), input).catch(() => false);
+}
+function handleSignInEmails(send, options = {}) {
+  return async (request) => {
+    const body = await request.text();
+    if (!await verifySignInEmail(request, body, options)) return Response.json({ error: "signature" }, { status: 401 });
+    const event = (() => {
+      try {
+        return JSON.parse(body);
+      } catch {
+        return null;
+      }
+    })();
+    const type = event?.event_type;
+    const data = event?.event_data ?? {};
+    const to = String(event?.user?.email ?? data.email ?? "").trim().toLowerCase();
+    if ((data.delivery_preference ?? "email") === "sms") return Response.json({ error: "text messages are not sent" }, { status: 422 });
+    if (type !== "send.otp" && type !== "send.magic_link" || !to) return Response.json({ ok: true, skipped: true });
+    const email = {
+      to,
+      kind: type === "send.otp" ? "code" : "link",
+      purpose: String((type === "send.otp" ? data.otp_type : data.link_type) ?? "sign-in"),
+      ...data.otp_code ? { code: String(data.otp_code) } : {},
+      ...data.link_url ? { link: String(data.link_url) } : {},
+      ...data.expires_at ? { expiresAt: String(data.expires_at) } : {}
+    };
+    try {
+      await send(email);
+    } catch (error) {
+      console.error("[webtwizz-auth] The site could not send a sign-in email", error);
+      return Response.json({ error: "send" }, { status: 502 });
+    }
+    return Response.json({ ok: true });
+  };
+}
+function signInEmailCopy(email, site) {
+  const code = email.kind === "code";
+  const copy = email.purpose === "email-verification" ? { subject: `Confirm your email for ${site}`, lead: code ? `Enter this code on ${site} to confirm your email address.` : `Open this link to confirm your email address for ${site}.`, label: "Confirmation code", note: `If you didn't sign up for ${site}, ignore this email.` } : email.purpose === "forget-password" ? { subject: `Reset your ${site} password`, lead: code ? `Enter this code on ${site} to choose a new password.` : `Open this link to choose a new password for ${site}.`, label: "Reset code", note: "If you didn't ask to reset your password, ignore this email. Your password stays the same." } : { subject: code ? `Your ${site} sign-in code` : `Sign in to ${site}`, lead: code ? `Enter this code on ${site} to sign in.` : `Open this link to sign in to ${site}.`, label: "Sign-in code", note: `If you didn't try to sign in to ${site}, ignore this email.` };
+  const value = code ? `${copy.label}: ${email.code}` : email.link;
+  return { subject: copy.subject, text: `${copy.lead}
+
+${value}
+
+${copy.note}` };
+}
+export {
+  handleSignInEmails,
+  signInEmailCopy,
+  verifySignInEmail
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webtwizz/cloud",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Sign-ins, database and file storage for sites built on WebTwizz Cloud",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,10 @@
       "types": "./dist/files.d.ts",
       "default": "./dist/files.js"
     },
+    "./emails": {
+      "types": "./dist/emails.d.ts",
+      "default": "./dist/emails.js"
+    },
     "./AI_GUIDE.md": "./AI_GUIDE.md",
     "./package.json": "./package.json"
   },