slauthjs 0.0.0-stage → 1.0.0

package/src/core.js

@@ -0,0 +1,311 @@
+import { createAccess } from './access.js'
+import { createEmailCodes } from './email-code.js'
+import { consoleEmail } from './email/console.js'
+import { createLock } from './lock.js'
+import { PasskeyError, readChallenge, verifyAuthentication, verifyRegistration } from './passkey/webauthn.js'
+import { createSessions } from './session.js'
+import { createUsers, normalizeEmail, validEmail } from './users.js'
+import { base64Url, json } from './util.js'
+
+const CHALLENGE_SECONDS = 5 * 60
+const UNSAFE = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
+let warned = false
+
+/**
+ * slauth: sign-in for side projects.
+ *
+ *   const auth = slauth({ secret, store })
+ *   if (url.pathname.startsWith('/auth/')) return auth.handle(request)
+ *   const user = await auth.user(request)
+ *
+ * @param {import('./index.js').SlauthConfig} config
+ */
+export function slauth(config) {
+  const {
+    secret,
+    store,
+    appName = 'your app',
+    basePath = '/auth',
+    cookie = 'slauth_session',
+    sessionDays = 30,
+    allow,
+    passkeys = {},
+    origins,
+  } = config ?? {}
+
+  if (!store || typeof store.get !== 'function') {
+    throw new Error("slauth: pass a store, e.g. store: memory() from 'slauthjs/stores/memory'.")
+  }
+  if (typeof secret !== 'string' || secret.length < 16) {
+    throw new Error('slauth: `secret` must be a random string of at least 16 characters. Make one with: openssl rand -base64 32')
+  }
+
+  const sender = config.email ?? consoleEmail()
+  if (!config.email && !warned) {
+    warned = true
+    console.warn('slauth: no `email` sender set, so sign-in codes are printed to the console.')
+  }
+
+  const users = createUsers(store, allow)
+  const sessions = createSessions({ store, cookie, days: sessionDays })
+  const codes = createEmailCodes({ store, secret, sender, appName })
+  const access = config.access ? createAccess({ teamDomain: config.access.team, audience: config.access.aud, devUser: config.access.devUser, fetch: config.access.fetch }) : null
+  const lock = config.lock
+    ? createLock(
+        { get: (userId) => store.get(`lock:${userId}`), put: (userId, doc) => store.put(`lock:${userId}`, doc) },
+        { cookie: config.lock === true ? 'slauth_lock' : (config.lock.cookie ?? 'slauth_lock'), defaultPolicy: config.lock === true ? 'never' : (config.lock.default ?? 'never') },
+      )
+    : null
+
+  const prefix = basePath.replace(/\/+$/, '')
+
+  /** The signed-in person, or null. Doesn't look at the app lock; see requireUser. */
+  async function user(request) {
+    const session = await sessions.read(request)
+    if (session) {
+      const found = await users.byId(session.userId)
+      // Taking someone off the allow list signs them out everywhere.
+      if (found && (await users.allowed(found.email))) return publicUser(found)
+    }
+    if (access) {
+      const fromAccess = await access.getUser(request)
+      if (fromAccess) {
+        const found = await users.signIn(fromAccess.email)
+        if (found) return publicUser(found)
+      }
+    }
+    return null
+  }
+
+  /**
+   * The signed-in, unlocked person, or a 401 Response to send back as it is:
+   *
+   *   const user = await auth.requireUser(request)
+   *   if (user instanceof Response) return user
+   */
+  async function requireUser(request) {
+    const found = await user(request)
+    if (!found) return json({ error: 'Please sign in.', code: 'signed-out' }, 401)
+    if (lock && !(await lock.isUnlocked(lockUser(found), request.headers.get('cookie')))) {
+      return json({ error: 'Please enter your PIN.', code: 'locked' }, 401)
+    }
+    return found
+  }
+
+  /** Every route under basePath. Returns a 404 for anything else, so it's safe to call for any request. */
+  async function handle(request) {
+    const url = new URL(request.url)
+    if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) return json({ error: 'Not found.', code: 'not-found' }, 404)
+    const route = url.pathname.slice(prefix.length + 1)
+    const method = request.method
+
+    if (UNSAFE.has(method)) {
+      const refused = checkSameSite(request, url, origins)
+      if (refused) return refused
+    }
+
+    try {
+      return await routeRequest(route, method, request, url)
+    } catch (error) {
+      if (error instanceof PasskeyError) return json({ error: error.message, code: 'passkey-failed' }, 400)
+      console.error('slauth:', error)
+      return json({ error: 'Something went wrong.', code: 'server-error' }, 500)
+    }
+  }
+
+  async function routeRequest(route, method, request, url) {
+    const body = async () => {
+      try {
+        return (await request.json()) ?? {}
+      } catch {
+        return {}
+      }
+    }
+
+    if (route === 'session' && method === 'GET') {
+      const session = await sessions.read(request)
+      const found = await user(request)
+      const headers = {}
+      if (session && found) {
+        const refreshed = await sessions.refresh(session, request)
+        if (refreshed) headers['Set-Cookie'] = refreshed
+      }
+      const out = { user: found }
+      if (lock && found) out.lock = (await lock.handle('session', 'GET', body, lockUser(found), request.headers.get('cookie'), url.protocol === 'https:')).body
+      return json(out, 200, headers)
+    }
+
+    if (route === 'email/start' && method === 'POST') {
+      const email = normalizeEmail((await body()).email)
+      if (!validEmail(email)) return json({ error: "That doesn't look like an email address.", code: 'bad-email' }, 400)
+      if (!(await users.allowed(email))) return json({ error: "That email isn't on the list for this app.", code: 'not-allowed' }, 403)
+      const sent = await codes.start(email)
+      if (!sent.ok) return json({ error: `Please wait ${sent.retryAfter}s before asking for another code.`, code: sent.code, retryAfter: sent.retryAfter }, 429)
+      return json({ ok: true })
+    }
+
+    if (route === 'email/verify' && method === 'POST') {
+      const input = await body()
+      const email = normalizeEmail(input.email)
+      if (!validEmail(email)) return json({ error: "That doesn't look like an email address.", code: 'bad-email' }, 400)
+      const result = await codes.verify(email, input.code)
+      if (!result.ok) {
+        const messages = { expired: 'That code has expired. Ask for a new one.', 'too-many-tries': 'Too many tries. Ask for a new code.', 'bad-code': 'That code is wrong.' }
+        return json({ error: messages[result.code], code: result.code, triesLeft: result.triesLeft }, result.code === 'bad-code' ? 400 : 410)
+      }
+      const found = await users.signIn(email)
+      if (!found) return json({ error: "That email isn't on the list for this app.", code: 'not-allowed' }, 403)
+      return json({ user: publicUser(found) }, 200, { 'Set-Cookie': await sessions.create(found.id, request) })
+    }
+
+    if (route === 'signout' && method === 'POST') {
+      return json({ ok: true }, 200, { 'Set-Cookie': await sessions.destroy(request) })
+    }
+
+    if (route.startsWith('passkey') || route === 'passkeys') {
+      if (passkeys === false) return json({ error: 'Passkeys are turned off.', code: 'not-found' }, 404)
+      return passkeyRoute(route, method, request, url, body)
+    }
+
+    if (route.startsWith('lock/') && lock) {
+      const found = await user(request)
+      if (!found) return json({ error: 'Please sign in.', code: 'signed-out' }, 401)
+      const reply = await lock.handle(route.slice(5), method, body, lockUser(found), request.headers.get('cookie'), url.protocol === 'https:')
+      if (reply) return json(reply.body, reply.status, reply.cookie ? { 'Set-Cookie': reply.cookie } : {})
+    }
+
+    return json({ error: 'Not found.', code: 'not-found' }, 404)
+  }
+
+  /* ---------- passkeys ---------- */
+
+  const expect = (url, challenge) => ({
+    rpId: passkeys.rpId ?? url.hostname,
+    origin: passkeys.origin ?? origins ?? url.origin,
+    challenge,
+    requireUserVerification: passkeys.userVerification === 'required',
+  })
+
+  async function takeChallenge(clientDataJSON, type) {
+    const challenge = readChallenge(clientDataJSON)
+    if (!challenge) throw new PasskeyError('The response has no challenge.')
+    const stored = await store.get(`challenge:${challenge}`)
+    // Single use, whatever happens next.
+    await store.delete(`challenge:${challenge}`)
+    if (!stored || stored.type !== type) throw new PasskeyError('That passkey request expired. Try again.')
+    return { challenge, stored }
+  }
+
+  async function newChallenge(value) {
+    const challenge = base64Url(crypto.getRandomValues(new Uint8Array(32)))
+    await store.put(`challenge:${challenge}`, value, { ttl: CHALLENGE_SECONDS })
+    return challenge
+  }
+
+  async function passkeyRoute(route, method, request, url, body) {
+    if (route === 'passkey/login/options' && method === 'POST') {
+      const challenge = await newChallenge({ type: 'login' })
+      return json({
+        challenge,
+        rpId: passkeys.rpId ?? url.hostname,
+        timeout: CHALLENGE_SECONDS * 1000,
+        userVerification: passkeys.userVerification ?? 'preferred',
+        allowCredentials: [],
+      })
+    }
+
+    if (route === 'passkey/login/verify' && method === 'POST') {
+      const { credential } = await body()
+      await takeChallenge(credential?.response?.clientDataJSON, 'login')
+      const stored = typeof credential?.id === 'string' ? await store.get(`passkey:${credential.id}`) : null
+      if (!stored) return json({ error: "This passkey isn't registered here.", code: 'passkey-unknown' }, 400)
+      if (credential.response.userHandle && credential.response.userHandle !== base64Url(new TextEncoder().encode(stored.userId))) {
+        throw new PasskeyError('This passkey belongs to someone else.')
+      }
+      const { counter } = await verifyAuthentication(credential, stored, expect(url, readChallenge(credential.response.clientDataJSON)))
+      await store.put(`passkey:${stored.id}`, { ...stored, counter, lastUsedAt: Date.now() })
+      const found = await users.byId(stored.userId)
+      if (!found || !(await users.allowed(found.email))) return json({ error: "You're not on the list for this app.", code: 'not-allowed' }, 403)
+      return json({ user: publicUser(found) }, 200, { 'Set-Cookie': await sessions.create(found.id, request) })
+    }
+
+    // Everything below is for someone already signed in.
+    const found = await user(request)
+    if (!found) return json({ error: 'Please sign in.', code: 'signed-out' }, 401)
+    const ids = (await store.get(`passkeys:${found.id}`)) ?? []
+
+    if (route === 'passkey/register/options' && method === 'POST') {
+      const challenge = await newChallenge({ type: 'register', userId: found.id })
+      return json({
+        challenge,
+        rp: { id: passkeys.rpId ?? url.hostname, name: passkeys.rpName ?? appName },
+        user: { id: base64Url(new TextEncoder().encode(found.id)), name: found.email, displayName: found.email },
+        pubKeyCredParams: [
+          { type: 'public-key', alg: -7 },
+          { type: 'public-key', alg: -257 },
+        ],
+        timeout: CHALLENGE_SECONDS * 1000,
+        attestation: 'none',
+        authenticatorSelection: { residentKey: 'required', requireResidentKey: true, userVerification: passkeys.userVerification ?? 'preferred' },
+        excludeCredentials: ids.map((id) => ({ type: 'public-key', id })),
+      })
+    }
+
+    if (route === 'passkey/register/verify' && method === 'POST') {
+      const { credential, name } = await body()
+      const { challenge, stored } = await takeChallenge(credential?.response?.clientDataJSON, 'register')
+      if (stored.userId !== found.id) throw new PasskeyError('That passkey request was for someone else.')
+      const verified = await verifyRegistration(credential, expect(url, challenge))
+      if (await store.get(`passkey:${verified.id}`)) return json({ error: 'That passkey is already registered.', code: 'passkey-exists' }, 409)
+      const label = typeof name === 'string' && name.trim() ? name.trim().slice(0, 60) : `Passkey added ${new Date().toISOString().slice(0, 10)}`
+      await store.put(`passkey:${verified.id}`, { ...verified, userId: found.id, name: label, createdAt: Date.now(), lastUsedAt: null })
+      await store.put(`passkeys:${found.id}`, [...ids, verified.id])
+      return json({ ok: true, passkey: { id: verified.id, name: label } })
+    }
+
+    if (route === 'passkeys' && method === 'GET') {
+      const list = []
+      for (const id of ids) {
+        const pk = await store.get(`passkey:${id}`)
+        if (pk) list.push({ id: pk.id, name: pk.name, createdAt: pk.createdAt, lastUsedAt: pk.lastUsedAt })
+      }
+      return json({ passkeys: list })
+    }
+
+    if (route === 'passkey/delete' && method === 'POST') {
+      const { id } = await body()
+      if (!ids.includes(id)) return json({ error: 'No such passkey.', code: 'passkey-unknown' }, 404)
+      await store.delete(`passkey:${id}`)
+      await store.put(`passkeys:${found.id}`, ids.filter((x) => x !== id))
+      return json({ ok: true })
+    }
+
+    return json({ error: 'Not found.', code: 'not-found' }, 404)
+  }
+
+  return { handle, user, requireUser, store }
+}
+
+function publicUser(user) {
+  return { id: user.id, email: user.email, createdAt: user.createdAt }
+}
+
+/** createLock works with { email, userId }. */
+function lockUser(user) {
+  return { email: user.email, userId: user.id }
+}
+
+/**
+ * Stops other websites using a visitor's cookies to post here (CSRF): writes must be JSON
+ * (which a plain HTML form can't send) and, when the browser says where they came from,
+ * come from this site.
+ */
+function checkSameSite(request, url, origins) {
+  const type = request.headers.get('content-type') ?? ''
+  if (!type.startsWith('application/json')) return json({ error: 'Expected JSON.', code: 'bad-request' }, 415)
+  const origin = request.headers.get('origin')
+  const allowed = [origins ?? url.origin].flat()
+  if (origin && !allowed.includes(origin)) return json({ error: 'Cross-site request refused.', code: 'cross-site' }, 403)
+  if (!origin && request.headers.get('sec-fetch-site') === 'cross-site') return json({ error: 'Cross-site request refused.', code: 'cross-site' }, 403)
+  return null
+}

package/src/element.d.ts

@@ -0,0 +1,6 @@
+export {}
+declare global {
+  interface HTMLElementTagNameMap {
+    'slauth-sign-in': HTMLElement
+  }
+}

package/src/element.js

@@ -0,0 +1,151 @@
+import { createClient } from './client.js'
+
+/**
+ * <slauth-sign-in>: a drop-in sign-in box. Email → 6-digit code → signed in, with
+ * "Sign in with a passkey" and an offer to add one afterwards. Works in any framework
+ * (it's a plain custom element) and is themed with CSS variables:
+ *
+ *   slauth-sign-in {
+ *     --slauth-accent: #f59e0b;  --slauth-ink: #2b2118;  --slauth-bg: #fff;
+ *     --slauth-radius: 14px;     --slauth-font: inherit;
+ *   }
+ *
+ * Attributes: base-path (default /auth), app-name, redirect (where to go once signed in),
+ * no-passkeys (email codes only).
+ * Fires `slauth:signed-in` with `{ detail: { user } }`.
+ *
+ *   import 'slauthjs/element'
+ *   <slauth-sign-in app-name="Planda" redirect="/"></slauth-sign-in>
+ */
+
+const STYLE = `
+:host { display: block; font-family: var(--slauth-font, inherit); color: var(--slauth-ink, #2b2118); max-width: 360px; }
+.card { background: var(--slauth-bg, #fff); border: 2px solid var(--slauth-ink, #2b2118); border-radius: var(--slauth-radius, 14px); padding: 22px; box-shadow: 4px 4px 0 var(--slauth-ink, #2b2118); }
+h2 { margin: 0 0 4px; font-size: 20px; line-height: 1.2; }
+p { margin: 0 0 14px; font-size: 14px; opacity: .8; }
+label { display: block; font-size: 13px; font-weight: 600; margin-bottom: 6px; }
+input { box-sizing: border-box; width: 100%; font: inherit; font-size: 16px; padding: 10px 12px; border: 2px solid var(--slauth-ink, #2b2118); border-radius: calc(var(--slauth-radius, 14px) - 6px); background: transparent; color: inherit; }
+input.code { letter-spacing: .4em; text-align: center; font-size: 22px; font-weight: 700; }
+input:focus { outline: 3px solid var(--slauth-accent, #f59e0b); outline-offset: 1px; }
+button { font: inherit; font-weight: 700; font-size: 15px; cursor: pointer; border-radius: calc(var(--slauth-radius, 14px) - 6px); padding: 10px 14px; width: 100%; margin-top: 12px; }
+.primary { background: var(--slauth-accent, #f59e0b); color: var(--slauth-ink, #2b2118); border: 2px solid var(--slauth-ink, #2b2118); }
+.primary:active { transform: translate(1px, 1px); }
+.ghost { background: transparent; color: inherit; border: 2px dashed currentColor; opacity: .85; }
+.link { background: none; border: 0; padding: 4px; width: auto; font-weight: 600; text-decoration: underline; opacity: .75; }
+button:disabled { opacity: .5; cursor: default; }
+.error { color: #c2410c; font-size: 13px; font-weight: 600; min-height: 18px; margin: 8px 0 0; }
+.row { display: flex; justify-content: space-between; margin-top: 8px; }
+`
+
+class SlauthSignIn extends HTMLElement {
+  connectedCallback() {
+    this.auth = createClient({ basePath: this.getAttribute('base-path') ?? '/auth' })
+    this.appName = this.getAttribute('app-name') ?? ''
+    this.state = { step: 'email', email: '', error: '', busy: false }
+    this.attachShadow({ mode: 'open' })
+    this.render()
+  }
+
+  set(patch) {
+    this.state = { ...this.state, ...patch }
+    this.render()
+  }
+
+  async run(action) {
+    this.set({ busy: true, error: '' })
+    try {
+      await action()
+    } catch (error) {
+      this.set({ error: error.message ?? 'Something went wrong.' })
+    } finally {
+      if (this.isConnected) this.set({ busy: false })
+    }
+  }
+
+  done(user) {
+    // Back to the start, ready for the next time it's shown (e.g. after signing out).
+    this.state = { step: 'email', email: '', error: '', busy: false }
+    this.render()
+    this.dispatchEvent(new CustomEvent('slauth:signed-in', { detail: { user }, bubbles: true, composed: true }))
+    const to = this.getAttribute('redirect')
+    if (to) window.location.assign(to)
+  }
+
+  render() {
+    const { step, email, error, busy } = this.state
+    const passkeys = !this.hasAttribute('no-passkeys') && this.auth.passkey.supported()
+    const name = this.appName ? ` to ${escape(this.appName)}` : ''
+    const views = {
+      email: `
+        <h2>Sign in${name}</h2>
+        <p>We'll email you a 6-digit code. No password needed.</p>
+        <form data-on="email">
+          <label for="email">Email</label>
+          <input id="email" type="email" autocomplete="email webauthn" required value="${escape(email)}" />
+          <button class="primary" ${busy ? 'disabled' : ''}>Email me a code</button>
+        </form>
+        ${passkeys ? `<button class="ghost" data-on="passkey" ${busy ? 'disabled' : ''}>Sign in with a passkey</button>` : ''}`,
+      code: `
+        <h2>Check your email</h2>
+        <p>We sent a code to <strong>${escape(email)}</strong>.</p>
+        <form data-on="code">
+          <label for="code">Code</label>
+          <input id="code" class="code" inputmode="numeric" autocomplete="one-time-code" maxlength="6" required />
+          <button class="primary" ${busy ? 'disabled' : ''}>Sign in</button>
+        </form>
+        <div class="row"><button class="link" data-on="back">Use another email</button><button class="link" data-on="resend">Send again</button></div>`,
+      offer: `
+        <h2>You're in 🦥</h2>
+        <p>Add a passkey and next time it's just Face ID, Touch ID or your PIN.</p>
+        <button class="primary" data-on="add" ${busy ? 'disabled' : ''}>Add a passkey</button>
+        <button class="link" data-on="skip">Not now</button>`,
+    }
+    this.shadowRoot.innerHTML = `<style>${STYLE}</style><div class="card" part="card">${views[step]}<p class="error" role="alert">${escape(error)}</p></div>`
+
+    const on = (key, handler) => {
+      const el = this.shadowRoot.querySelector(`[data-on="${key}"]`)
+      el?.addEventListener(el.tagName === 'FORM' ? 'submit' : 'click', (event) => {
+        event.preventDefault()
+        handler()
+      })
+    }
+    // Read inputs before run(): it re-renders the form, which would empty them.
+    on('email', () => {
+      const value = this.shadowRoot.getElementById('email').value.trim()
+      this.set({ email: value })
+      return this.run(async () => {
+        await this.auth.email.start(value)
+        this.set({ step: 'code' })
+        this.shadowRoot.getElementById('code')?.focus()
+      })
+    })
+    on('code', () => {
+      const code = this.shadowRoot.getElementById('code').value
+      return this.run(async () => {
+        const { user } = await this.auth.email.verify(email, code)
+        this.user = user
+        if (passkeys) this.set({ step: 'offer' })
+        else this.done(user)
+      })
+    })
+    on('passkey', () => this.run(async () => this.done((await this.auth.passkey.signIn()).user)))
+    on('back', () => this.set({ step: 'email', error: '' }))
+    on('resend', () => this.run(() => this.auth.email.start(email)))
+    on('add', () =>
+      this.run(async () => {
+        await this.auth.passkey.register()
+        this.done(this.user)
+      }),
+    )
+    on('skip', () => this.done(this.user))
+    this.shadowRoot.querySelector('input')?.focus({ preventScroll: true })
+  }
+}
+
+function escape(text) {
+  return String(text).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('slauth-sign-in')) {
+  customElements.define('slauth-sign-in', SlauthSignIn)
+}

package/src/email/cloudflare.d.ts

@@ -0,0 +1 @@
+export { cloudflareEmail } from './index.js'

package/src/email/cloudflare.js

@@ -0,0 +1,19 @@
+/**
+ * Sends codes with Cloudflare Email Service, through a `send_email` binding in your
+ * wrangler config:
+ *
+ *   "send_email": [{ "name": "EMAIL" }]
+ *
+ * @param {{ send(message: { to: string, from: string, subject: string, text: string, html: string }): Promise<unknown> }} binding  e.g. env.EMAIL
+ * @param {{ from: string }} options  a sender on a domain set up for Email Service
+ * @returns {import('../index.js').EmailSender}
+ */
+export function cloudflareEmail(binding, { from }) {
+  if (!binding?.send) throw new Error('slauth: cloudflareEmail() needs a send_email binding, e.g. env.EMAIL.')
+  if (!from) throw new Error('slauth: cloudflareEmail() needs a from address.')
+  return {
+    async send({ to, subject, text, html }) {
+      await binding.send({ to, from, subject, text, html })
+    },
+  }
+}

package/src/email/console.d.ts

@@ -0,0 +1 @@
+export { consoleEmail } from './index.js'

package/src/email/console.js

@@ -0,0 +1,13 @@
+/**
+ * Prints sign-in codes to the console instead of emailing them. The default while
+ * you build, so there's nothing to set up to try slauth.
+ *
+ * @returns {import('../index.js').EmailSender}
+ */
+export function consoleEmail() {
+  return {
+    async send({ to, code, appName }) {
+      console.log(`\n  🦥 slauth: ${appName} sign-in code for ${to} is ${code}\n`)
+    },
+  }
+}

package/src/email/index.d.ts

@@ -0,0 +1,4 @@
+import type { EmailSender } from '../index.js'
+export function consoleEmail(): EmailSender
+export function resend(options: { apiKey: string; from: string; fetch?: typeof fetch }): EmailSender
+export function cloudflareEmail(binding: { send(message: { to: string; from: string; subject: string; text: string; html: string }): Promise<unknown> }, options: { from: string }): EmailSender

package/src/email/message.js

@@ -0,0 +1,16 @@
+/** The sign-in email every sender uses, unless you pass your own `message`. */
+export function codeMessage({ code, appName, minutes }) {
+  const subject = `${code} is your ${appName} sign-in code`
+  const text = `Your ${appName} sign-in code is ${code}\n\nIt works for ${minutes} minutes. If you didn't ask for it, you can ignore this email.`
+  const html = `<!doctype html><html><body style="margin:0;padding:32px 16px;background:#fdf6ec;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:#2b2118">
+<div style="max-width:420px;margin:0 auto;background:#fff;border:2px solid #2b2118;border-radius:16px;padding:28px">
+<p style="margin:0 0 8px;font-size:15px">Your <strong>${escapeHtml(appName)}</strong> sign-in code:</p>
+<p style="margin:0 0 16px;font-size:34px;font-weight:800;letter-spacing:6px">${code}</p>
+<p style="margin:0;font-size:13px;color:#6b5d50">It works for ${minutes} minutes. If you didn't ask for it, you can ignore this email.</p>
+</div></body></html>`
+  return { subject, text, html }
+}
+
+function escapeHtml(text) {
+  return String(text).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+}

package/src/email/resend.d.ts

@@ -0,0 +1 @@
+export { resend } from './index.js'

package/src/email/resend.js

@@ -0,0 +1,21 @@
+/**
+ * Sends codes with Resend (resend.com; the free tier is plenty for a side project).
+ *
+ * @param {{ apiKey: string, from: string, fetch?: typeof fetch }} options
+ *   from  a sender on a domain you verified in Resend, e.g. "My App <hi@myapp.dev>"
+ * @returns {import('../index.js').EmailSender}
+ */
+export function resend({ apiKey, from, fetch: doFetch = (...args) => fetch(...args) }) {
+  if (!apiKey) throw new Error('slauth: resend() needs an apiKey.')
+  if (!from) throw new Error('slauth: resend() needs a from address on a domain you verified in Resend.')
+  return {
+    async send({ to, subject, text, html }) {
+      const res = await doFetch('https://api.resend.com/emails', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ from, to: [to], subject, text, html }),
+      })
+      if (!res.ok) throw new Error(`slauth: Resend said ${res.status}: ${(await res.text()).slice(0, 200)}`)
+    },
+  }
+}

package/src/email-code.js

@@ -0,0 +1,61 @@
+import { codeMessage } from './email/message.js'
+import { hmac, safeEqual } from './util.js'
+
+const CODE_MINUTES = 10
+const MAX_TRIES = 5
+const RESEND_SECONDS = 60
+
+/**
+ * Sign in with a 6-digit code sent by email.
+ *
+ *   code:<email>  { hash, expiresAt, tries, sentAt }  (lives 10 minutes)
+ *
+ * Only an HMAC of the code is stored. Each code allows 5 tries, and a new code can be
+ * asked for once a minute per address.
+ *
+ * @param {{ store: import('./index.js').Store, secret: string, sender: import('./index.js').EmailSender, appName: string }} options
+ */
+export function createEmailCodes({ store, secret, sender, appName }) {
+  const hashOf = (email, code) => hmac(secret, `code:${email}:${code}`)
+
+  return {
+    /** @returns {Promise<{ ok: true } | { ok: false, code: 'slow-down', retryAfter: number }>} */
+    async start(email) {
+      const existing = await store.get(`code:${email}`)
+      const wait = existing ? Math.ceil((existing.sentAt + RESEND_SECONDS * 1000 - Date.now()) / 1000) : 0
+      if (wait > 0) return { ok: false, code: 'slow-down', retryAfter: wait }
+
+      const code = randomCode()
+      const now = Date.now()
+      await store.put(`code:${email}`, { hash: await hashOf(email, code), expiresAt: now + CODE_MINUTES * 60_000, tries: 0, sentAt: now }, { ttl: CODE_MINUTES * 60 })
+      await sender.send({ to: email, code, appName, ...codeMessage({ code, appName, minutes: CODE_MINUTES }) })
+      return { ok: true }
+    },
+
+    /** @returns {Promise<{ ok: true } | { ok: false, code: 'expired' | 'too-many-tries' | 'bad-code', triesLeft?: number }>} */
+    async verify(email, code) {
+      const entry = await store.get(`code:${email}`)
+      if (!entry || entry.expiresAt <= Date.now()) return { ok: false, code: 'expired' }
+      if (entry.tries >= MAX_TRIES) return { ok: false, code: 'too-many-tries' }
+
+      const guess = String(code ?? '').replace(/\D/g, '')
+      if (guess.length === 6 && safeEqual(await hashOf(email, guess), entry.hash)) {
+        await store.delete(`code:${email}`)
+        return { ok: true }
+      }
+      const tries = entry.tries + 1
+      const ttl = Math.max(1, Math.ceil((entry.expiresAt - Date.now()) / 1000))
+      await store.put(`code:${email}`, { ...entry, tries }, { ttl })
+      return tries >= MAX_TRIES ? { ok: false, code: 'too-many-tries' } : { ok: false, code: 'bad-code', triesLeft: MAX_TRIES - tries }
+    },
+  }
+}
+
+/** Six uniformly random digits (rejection sampling, so no digit is likelier than another). */
+function randomCode() {
+  const buf = new Uint32Array(1)
+  for (;;) {
+    crypto.getRandomValues(buf)
+    if (buf[0] < 4_294_000_000) return String(buf[0] % 1_000_000).padStart(6, '0')
+  }
+}