@webtwizz/cloud 0.3.0 → 0.4.1

package/AI_GUIDE.md

@@ -41,7 +41,7 @@ if (error) setMessage(authMessage(error));
 
 For wording that fits the site, pass overrides: `authMessage(error, { USER_ALREADY_EXISTS: 'You already have a booking account.' })`.
 
-When the owner turns on Confirm email, sign-up returns no session and the 6-digit code is emailed automatically. Show a code step: `authClient.emailOtp.verifyEmail({ email, otp })`, then sign them in, with a "Send a new code" button that calls `authClient.emailOtp.sendVerificationOtp({ email, type: 'email-verification' })`. Never send the first code yourself.
+Confirm email is off unless the owner turns it on in Settings > Cloud > Users, so sign-up signs people straight in and an unconfirmed email never stops a sign-in. When the owner turns on Confirm email, sign-up returns no session and the 6-digit code is emailed automatically. Show a code step: `authClient.emailOtp.verifyEmail({ email, otp })`, then sign them in, with a "Send a new code" button that calls `authClient.emailOtp.sendVerificationOtp({ email, type: 'email-verification' })`. Never send the first code yourself.
 
 5. Protect pages in `src/proxy.ts`, listing only the protected routes in the matcher (a matcher over every path blocks the sign-in page's own scripts):
 
@@ -66,10 +66,34 @@ Never destructure `{ user }` from the top level.
 
 8. Every sign-in page gets a "Forgot password?" link to `/reset-password`, a client page in two steps: their email, then `authClient.forgetPassword.emailOtp({ email })`, which emails a 6-digit code; then the code and a new password, then `authClient.emailOtp.resetPassword({ email, otp, password })`, then send them to sign in. Leave `/reset-password` out of the proxy matcher. The owner can also send a reset code from the Data panel, and it lands on this page.
 
+9. Admins are accounts whose role is `'admin'`. Admin pages and admin writes check it on the server, the same way as step 6:
+
+```ts
+const { data: session } = await auth.getSession();
+if (session?.user?.role !== 'admin') return Response.json({ error: 'Admins only' }, { status: 403 });
+```
+
+The first admin is the owner's own account on the site: they sign up like any visitor (their WebTwizz account is separate), then make that account an admin under Users in the Data panel, or ask you to do it. A new role reaches their session within a few minutes, or right away when they sign in again.
+
 Sign-ins are email and password only. Sign-in emails (reset codes, confirmations) are sent for the site automatically; never build email sending or add an email service for them. If the user asks for another way to sign in, say WebTwizz Cloud sign-ins are email and password for now and build that.
 
 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):
@@ -87,6 +111,17 @@ The database can pause or fill up on the owner's plan. Wrap reads and saves in t
 
 Pages that only show data set `export const revalidate = 60`, and the server action that saves calls `revalidatePath` for them. Pages for a signed-in user stay dynamic.
 
+The database runs while pages read or save data and stops after 5 quiet minutes; its running time comes out of the owner's monthly allowance. So a page that refreshes data on a timer (a feed, a chat, a dashboard) refreshes only while the tab is visible, and again when the visitor comes back:
+
+```ts
+useEffect(() => {
+  const refresh = () => { if (document.visibilityState === 'visible') load(); };
+  const timer = setInterval(refresh, 60_000);
+  document.addEventListener('visibilitychange', refresh);
+  return () => { clearInterval(timer); document.removeEventListener('visibilitychange', refresh); };
+}, []);
+```
+
 ## Files
 
 Two buckets: `public` (anyone can view, for images shown on the site) and `private` (documents, opened through short-lived links). Images you place on pages yourself keep using the usual image tools; this is for what visitors or the site's features upload.
@@ -117,4 +152,4 @@ Show files with `createFiles().publicUrl(key)` in a plain `<img>` or link, or `a
 
 ## Owner tools
 
-The owner manages users under Users in the Data panel (password reset, block, delete with their rows, export), sets who can sign up and the sign-in emails in Settings > Cloud > Users, and downloads everything from Settings > Cloud > Database. Point them there when they ask.
+The owner manages users under Users in the Data panel (make admin, password reset, block, delete with their rows, export), sets who can sign up and the sign-in emails in Settings > Cloud > Users, and downloads everything from Settings > Cloud > Database. Point them there when they ask.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @webtwizz/cloud
 
+## 0.4.1
+
+### Patch Changes
+
+- 67343d5: Signed-in visitors can sign out, and `authClient` can read their session: since 0.2.0 the sign-in route answered both with a server error inside Next, because it copied a request Next hands over as a Proxy. Visitors who pressed Sign out stayed signed in.
+
+## 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
 
@@ -39,6 +40,8 @@ npm run build
 
 `test/fixture` is a small Next app that CI builds against the packed tarball.
 
+To try a change in the local WebTwizz preview site without publishing: `npm run preview` builds the package, puts it in the preview container's `node_modules` under a unique dev version, and restarts its dev server (about 10 seconds). `npm run dev` does the same on every save.
+
 ## Releases
 
 - Add a changeset (`npx changeset`) to any PR that changes what sites get.

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/dist/server.js

@@ -1435,7 +1435,8 @@ function forLibrary(request, make) {
   if (translated === cookie) return request;
   const headers2 = new Headers(request.headers);
   headers2.set("cookie", translated);
-  return make(request, headers2);
+  const body = request.method === "GET" || request.method === "HEAD" ? void 0 : request.body;
+  return make(request.url, { method: request.method, headers: headers2, body, signal: request.signal, ...body ? { duplex: "half" } : {} });
 }
 function forBrowser(response) {
   const provider = [...response.headers.keys()].filter((name) => PROVIDER_HEADER.test(name));
@@ -1481,7 +1482,7 @@ function createAuth(options = {}) {
   const middleware = auth.middleware.bind(auth);
   auth.handler = () => {
     const methods = handler();
-    const wrap = (method) => async (request, context) => forBrowser(await method(forLibrary(request, (original, headers2) => new Request(original, { headers: headers2 })), context));
+    const wrap = (method) => async (request, context) => forBrowser(await method(forLibrary(request, (url, init) => new Request(url, init)), context));
     const post = wrap(methods.POST);
     const signUp = async (request, context) => {
       const response = await post(request, context);
@@ -1493,7 +1494,7 @@ function createAuth(options = {}) {
   };
   auth.middleware = (config) => {
     const run = middleware(config);
-    return async (request) => forBrowser(await run(forLibrary(request, (original, headers2) => new NextRequest2(original, { headers: headers2 }))));
+    return async (request) => forBrowser(await run(forLibrary(request, (url, init) => new NextRequest2(url, init))));
   };
   return auth;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webtwizz/cloud",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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"
   },
@@ -51,7 +55,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:integration": "npm run build && vitest run --config vitest.integration.config.ts",
-    "prepublishOnly": "npm run build && npm run typecheck && npm test"
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
+    "preview": "tsup && node scripts/preview.mjs",
+    "dev": "tsup --watch --onSuccess \"node scripts/preview.mjs\""
   },
   "engines": {
     "node": ">=20"