@pramen/auth 0.0.5 → 0.0.7

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { HandlerContext } from "@pramen/server";
 export declare const authSchema: {
     auth_users: import("@pramen/server").EntityDef<{
         username: {
@@ -46,3 +47,62 @@ export declare const authHandlers: {
     }>;
     me: import("@pramen/server").Handler<unknown, import("@pramen/server").Identity | null>;
 };
+export declare const magicLinkSchema: {
+    auth_magic_links: import("@pramen/server").EntityDef<{
+        tokenHash: {
+            readonly type: "text";
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        email: {
+            readonly type: "text";
+        };
+        expiresAt: {
+            readonly type: "integer";
+        };
+        consumedAt: {
+            readonly type: "integer";
+        };
+        createdAt: {
+            readonly type: "integer";
+        };
+    }, Record<string, never>>;
+};
+export interface MagicLinkOptions {
+    /** Deliver the link to the recipient. Receives the handler ctx and the raw token —
+     * build the URL however your app routes it, e.g. `${ctx.env.APP_URL}/auth?token=${token}`.
+     * On Cloudflare the recommended transport is Cloudflare Email Sending — a
+     * `send_email` binding (no API keys), e.g.
+     * `await (ctx.env.EMAIL as SendEmail).send({ to, from: { email, name }, subject, text, html })`
+     * (see example/app.ts + oblaka.ts). Throwing rolls back the mutation, so a delivery
+     * failure leaves no orphan token and surfaces to the caller to retry. */
+    sendEmail: (ctx: HandlerContext, args: {
+        email: string;
+        token: string;
+    }) => void | Promise<void>;
+    /** How long the emailed link stays valid, in seconds. Default 900 (15 min). */
+    linkTtlSeconds?: number;
+    /** TTL of the session JWT minted on successful login, in seconds. Default 3600 (1h). */
+    sessionTtlSeconds?: number;
+    /** Roles assigned when a magic-link login first creates the user. Default `["user"]`. */
+    defaultRoles?: string[];
+}
+/** Build the `requestMagicLink` / `loginWithMagicLink` handler pair. Spread the
+ * result into your handler map (and `magicLinkSchema` into your schema). Both are
+ * anonymous — gate nothing; the token is the capability. */
+export declare function createMagicLinkAuth(opts: MagicLinkOptions): {
+    requestMagicLink: import("@pramen/server").Handler<{
+        email: string;
+    }, {
+        ok: boolean;
+    }>;
+    loginWithMagicLink: import("@pramen/server").Handler<{
+        token: string;
+    }, {
+        token: string;
+        user: {
+            username: string;
+            roles: string[];
+        };
+    }>;
+};

package/dist/index.js

@@ -11,6 +11,10 @@
 // signup/login store users in the `auth_users` table and return a bearer token
 // (sub = username, roles). Passwords are PBKDF2-hashed (WebCrypto, no deps).
 // Requires AUTH_SECRET in the environment (ctx.env). JWKS setups don't use this.
+//
+// Passwordless magic-link login is also available via createMagicLinkAuth (spread
+// magicLinkSchema too). It is transport-agnostic: you supply sendEmail; pramen owns
+// the token lifecycle. See createMagicLinkAuth below.
 import { Entity, mutation, query, BadRequest, Unauthorized } from "@pramen/server";
 // --- schema fragment: spread into your defineSchema so the table is migrated ---
 export const authSchema = {
@@ -114,3 +118,95 @@ export const authHandlers = {
     }, { input: parseCreds }),
     me: query((ctx) => ctx.identity),
 };
+// --- magic link (passwordless) login ---------------------------------------
+//
+// A one-time, single-use, time-boxed link emailed to the user. The flow is two
+// anonymous mutations:
+//   requestMagicLink({ email })  -> mints a token, persists its HASH + expiry, and
+//                                   calls your sendEmail. Always returns { ok: true }
+//                                   (no account enumeration — the response is the
+//                                   same whether or not the email has an account).
+//   loginWithMagicLink({ token }) -> validates the token (unexpired, unconsumed),
+//                                   consumes it, find-or-creates the auth_users row
+//                                   (passwordless: empty passwordHash never verifies),
+//                                   and returns the same { token, user } as login.
+//
+// The emailed user is keyed by email in the `username` column, so a magic-link user
+// and a password user with the same handle are the same row. Tokens are stored only
+// as a SHA-256 hash, so a DB leak never exposes a live link.
+// Spread alongside authSchema so the link table is migrated.
+export const magicLinkSchema = {
+    auth_magic_links: Entity((t) => ({
+        tokenHash: t.textId(), // PK = sha256(token); the raw token only ever leaves via email
+        email: t.text(),
+        expiresAt: t.int(), // epoch ms
+        consumedAt: t.int(), // epoch ms; NULL until redeemed (single-use)
+        createdAt: t.int(),
+    })),
+};
+async function sha256Hex(s) {
+    const digest = await crypto.subtle.digest("SHA-256", enc(s));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** 256 bits of entropy, url-safe — the raw link token. */
+function mintToken() {
+    return b64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+function parseEmail(raw) {
+    const o = (raw ?? {});
+    const email = typeof o.email === "string" ? o.email.trim().toLowerCase() : "";
+    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email))
+        throw new BadRequest("a valid email is required");
+    return { email };
+}
+function parseLinkToken(raw) {
+    const o = (raw ?? {});
+    if (typeof o.token !== "string" || o.token.length === 0)
+        throw new BadRequest("token is required");
+    return { token: o.token };
+}
+/** Build the `requestMagicLink` / `loginWithMagicLink` handler pair. Spread the
+ * result into your handler map (and `magicLinkSchema` into your schema). Both are
+ * anonymous — gate nothing; the token is the capability. */
+export function createMagicLinkAuth(opts) {
+    const linkTtlMs = (opts.linkTtlSeconds ?? 900) * 1000;
+    const sessionTtl = opts.sessionTtlSeconds ?? TOKEN_TTL_SECONDS;
+    const defaultRoles = opts.defaultRoles ?? DEFAULT_ROLES;
+    return {
+        requestMagicLink: mutation(async (ctx, input) => {
+            const token = mintToken();
+            const tokenHash = await sha256Hex(token);
+            const now = Date.now();
+            // Invalidate any prior pending links for this email — only the latest works.
+            await ctx.db.exec("DELETE FROM auth_magic_links WHERE email = ?", input.email);
+            await ctx.db.exec("INSERT INTO auth_magic_links (tokenHash, email, expiresAt, createdAt) VALUES (?, ?, ?, ?)", tokenHash, input.email, now + linkTtlMs, now);
+            // Inside the mutation transaction: a throw here rolls the token back.
+            await opts.sendEmail(ctx, { email: input.email, token });
+            return { ok: true };
+        }, { input: parseEmail }),
+        loginWithMagicLink: mutation(async (ctx, input) => {
+            const tokenHash = await sha256Hex(input.token);
+            const rows = await ctx.db.exec("SELECT email, expiresAt, consumedAt FROM auth_magic_links WHERE tokenHash = ? LIMIT 1", tokenHash);
+            const link = rows[0];
+            if (!link || link.consumedAt != null || Number(link.expiresAt) < Date.now()) {
+                throw new Unauthorized("invalid or expired link");
+            }
+            // Single-use: consume before issuing the session.
+            await ctx.db.exec("UPDATE auth_magic_links SET consumedAt = ? WHERE tokenHash = ?", Date.now(), tokenHash);
+            const email = String(link.email);
+            const existing = await ctx.db.exec("SELECT roles FROM auth_users WHERE username = ? LIMIT 1", email);
+            let roles;
+            if (existing.length > 0) {
+                roles = JSON.parse(String(existing[0].roles));
+            }
+            else {
+                roles = defaultRoles;
+                await ctx.db.exec(
+                // Empty passwordHash can never verify → the user stays passwordless.
+                "INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)", email, "", JSON.stringify(roles), Date.now());
+            }
+            const token = await signToken({ sub: email, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
+            return { token, user: { username: email, roles } };
+        }, { input: parseLinkToken }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/auth",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Optional credential→JWT login for pramen — signup/login/me + PBKDF2 hashing, issuing HS256 tokens the pramen verifier accepts.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,10 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json"
   },
@@ -31,6 +34,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "workspace:*"
+    "@pramen/server": "0.0.7"
   }
 }

package/src/index.ts

@@ -11,6 +11,10 @@
 // signup/login store users in the `auth_users` table and return a bearer token
 // (sub = username, roles). Passwords are PBKDF2-hashed (WebCrypto, no deps).
 // Requires AUTH_SECRET in the environment (ctx.env). JWKS setups don't use this.
+//
+// Passwordless magic-link login is also available via createMagicLinkAuth (spread
+// magicLinkSchema too). It is transport-agnostic: you supply sendEmail; pramen owns
+// the token lifecycle. See createMagicLinkAuth below.
 
 import { Entity, mutation, query, BadRequest, Unauthorized } from "@pramen/server";
 import type { HandlerContext } from "@pramen/server";
@@ -152,3 +156,139 @@ export const authHandlers = {
 
   me: query((ctx) => ctx.identity),
 };
+
+// --- magic link (passwordless) login ---------------------------------------
+//
+// A one-time, single-use, time-boxed link emailed to the user. The flow is two
+// anonymous mutations:
+//   requestMagicLink({ email })  -> mints a token, persists its HASH + expiry, and
+//                                   calls your sendEmail. Always returns { ok: true }
+//                                   (no account enumeration — the response is the
+//                                   same whether or not the email has an account).
+//   loginWithMagicLink({ token }) -> validates the token (unexpired, unconsumed),
+//                                   consumes it, find-or-creates the auth_users row
+//                                   (passwordless: empty passwordHash never verifies),
+//                                   and returns the same { token, user } as login.
+//
+// The emailed user is keyed by email in the `username` column, so a magic-link user
+// and a password user with the same handle are the same row. Tokens are stored only
+// as a SHA-256 hash, so a DB leak never exposes a live link.
+
+// Spread alongside authSchema so the link table is migrated.
+export const magicLinkSchema = {
+  auth_magic_links: Entity((t) => ({
+    tokenHash: t.textId(), // PK = sha256(token); the raw token only ever leaves via email
+    email: t.text(),
+    expiresAt: t.int(), // epoch ms
+    consumedAt: t.int(), // epoch ms; NULL until redeemed (single-use)
+    createdAt: t.int(),
+  })),
+};
+
+async function sha256Hex(s: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", enc(s));
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** 256 bits of entropy, url-safe — the raw link token. */
+function mintToken(): string {
+  return b64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+function parseEmail(raw: unknown): { email: string } {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  const email = typeof o.email === "string" ? o.email.trim().toLowerCase() : "";
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) throw new BadRequest("a valid email is required");
+  return { email };
+}
+
+function parseLinkToken(raw: unknown): { token: string } {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  if (typeof o.token !== "string" || o.token.length === 0) throw new BadRequest("token is required");
+  return { token: o.token };
+}
+
+export interface MagicLinkOptions {
+  /** Deliver the link to the recipient. Receives the handler ctx and the raw token —
+   * build the URL however your app routes it, e.g. `${ctx.env.APP_URL}/auth?token=${token}`.
+   * On Cloudflare the recommended transport is Cloudflare Email Sending — a
+   * `send_email` binding (no API keys), e.g.
+   * `await (ctx.env.EMAIL as SendEmail).send({ to, from: { email, name }, subject, text, html })`
+   * (see example/app.ts + oblaka.ts). Throwing rolls back the mutation, so a delivery
+   * failure leaves no orphan token and surfaces to the caller to retry. */
+  sendEmail: (ctx: HandlerContext, args: { email: string; token: string }) => void | Promise<void>;
+  /** How long the emailed link stays valid, in seconds. Default 900 (15 min). */
+  linkTtlSeconds?: number;
+  /** TTL of the session JWT minted on successful login, in seconds. Default 3600 (1h). */
+  sessionTtlSeconds?: number;
+  /** Roles assigned when a magic-link login first creates the user. Default `["user"]`. */
+  defaultRoles?: string[];
+}
+
+/** Build the `requestMagicLink` / `loginWithMagicLink` handler pair. Spread the
+ * result into your handler map (and `magicLinkSchema` into your schema). Both are
+ * anonymous — gate nothing; the token is the capability. */
+export function createMagicLinkAuth(opts: MagicLinkOptions) {
+  const linkTtlMs = (opts.linkTtlSeconds ?? 900) * 1000;
+  const sessionTtl = opts.sessionTtlSeconds ?? TOKEN_TTL_SECONDS;
+  const defaultRoles = opts.defaultRoles ?? DEFAULT_ROLES;
+
+  return {
+    requestMagicLink: mutation(
+      async (ctx, input: { email: string }) => {
+        const token = mintToken();
+        const tokenHash = await sha256Hex(token);
+        const now = Date.now();
+        // Invalidate any prior pending links for this email — only the latest works.
+        await ctx.db.exec("DELETE FROM auth_magic_links WHERE email = ?", input.email);
+        await ctx.db.exec(
+          "INSERT INTO auth_magic_links (tokenHash, email, expiresAt, createdAt) VALUES (?, ?, ?, ?)",
+          tokenHash,
+          input.email,
+          now + linkTtlMs,
+          now,
+        );
+        // Inside the mutation transaction: a throw here rolls the token back.
+        await opts.sendEmail(ctx, { email: input.email, token });
+        return { ok: true };
+      },
+      { input: parseEmail },
+    ),
+
+    loginWithMagicLink: mutation(
+      async (ctx, input: { token: string }) => {
+        const tokenHash = await sha256Hex(input.token);
+        const rows = await ctx.db.exec(
+          "SELECT email, expiresAt, consumedAt FROM auth_magic_links WHERE tokenHash = ? LIMIT 1",
+          tokenHash,
+        );
+        const link = rows[0];
+        if (!link || link.consumedAt != null || Number(link.expiresAt) < Date.now()) {
+          throw new Unauthorized("invalid or expired link");
+        }
+        // Single-use: consume before issuing the session.
+        await ctx.db.exec("UPDATE auth_magic_links SET consumedAt = ? WHERE tokenHash = ?", Date.now(), tokenHash);
+
+        const email = String(link.email);
+        const existing = await ctx.db.exec("SELECT roles FROM auth_users WHERE username = ? LIMIT 1", email);
+        let roles: string[];
+        if (existing.length > 0) {
+          roles = JSON.parse(String(existing[0].roles)) as string[];
+        } else {
+          roles = defaultRoles;
+          await ctx.db.exec(
+            // Empty passwordHash can never verify → the user stays passwordless.
+            "INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)",
+            email,
+            "",
+            JSON.stringify(roles),
+            Date.now(),
+          );
+        }
+        const token = await signToken({ sub: email, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
+        return { token, user: { username: email, roles } };
+      },
+      { input: parseLinkToken },
+    ),
+  };
+}