slauthjs 0.0.0-stage → 2.0.0

package/src/element.js

@@ -0,0 +1,253 @@
+import { createClient } from './client.js'
+import { MESSAGES, STYLE, escape } from './ui.js'
+
+/**
+ * <slauth-sign-in>: a drop-in sign-in box. It asks the server what's turned on and
+ * offers it: "Continue with GitHub/Google/…", email → 6-digit code, a password, a
+ * passkey, then the two-factor code for people who set one up, and an offer to add a
+ * passkey 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;
+ *     --slauth-accent-ink: #2b2118;  (text on the accent; for dark themes)
+ *     --slauth-error: #c2410c;
+ *   }
+ *
+ * Attributes: base-path (default /auth), app-name, redirect (where to go once signed in),
+ * mode ("sign-up" to start on the password sign-up form), no-passkeys (no passkey
+ * button or offer).
+ * Fires `slauth:signed-in` with `{ detail: { user } }`.
+ *
+ *   import 'slauthjs/element'
+ *   <slauth-sign-in app-name="Planda" redirect="/"></slauth-sign-in>
+ */
+
+class SlauthSignIn extends HTMLElement {
+  connectedCallback() {
+    this.auth = createClient({ basePath: this.getAttribute('base-path') ?? '/auth' })
+    this.appName = this.getAttribute('app-name') ?? ''
+    this.config = { providers: [], passwords: false, passkeys: true }
+    this.state = { step: 'email', mode: this.getAttribute('mode') === 'sign-up' ? 'sign-up' : 'code', email: '', error: '', busy: false, recovery: false }
+    this.attachShadow({ mode: 'open' })
+    this.readUrl()
+    this.render()
+    this.load()
+  }
+
+  /** Errors and the two-factor step can arrive in the URL, after a provider sends people back. */
+  readUrl() {
+    const params = new URLSearchParams(window.location.search)
+    const error = params.get('slauth_error')
+    if (error) this.state.error = MESSAGES[error] ?? 'Something went wrong. Please try again.'
+    if (params.get('slauth_step') === 'two-factor') this.state.step = 'two-factor'
+    this.afterRedirect = params.get('redirect')
+    this.invite = params.get('slauth_invite')
+    if (error || params.has('slauth_step')) {
+      for (const key of ['slauth_error', 'slauth_step']) params.delete(key)
+      const query = params.toString()
+      window.history.replaceState(window.history.state, '', window.location.pathname + (query ? `?${query}` : '') + window.location.hash)
+    }
+  }
+
+  async load() {
+    try {
+      const [config, session] = await Promise.all([this.auth.config(), this.auth.session()])
+      this.config = config
+      if (session.twoFactor === 'pending') this.state.step = 'two-factor'
+      if (this.state.mode === 'sign-up' && !config.passwords) this.state.mode = 'code'
+      this.render()
+    } catch {
+      // The box still works with email codes.
+    }
+  }
+
+  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: MESSAGES[error.code] ?? error.message ?? 'Something went wrong.' })
+    } finally {
+      if (this.isConnected) this.set({ busy: false })
+    }
+  }
+
+  /** After the first step: the two-factor code, the passkey offer, or done. */
+  async signedIn(result, { offer = true } = {}) {
+    if (result.twoFactor) return this.set({ step: 'two-factor', recovery: false })
+    this.user = result.user
+    if (offer && this.passkeys()) return this.set({ step: 'offer' })
+    return this.done(result.user)
+  }
+
+  async done(user) {
+    if (this.invite && this.config.organizations) await this.auth.orgs.accept(this.invite).catch(() => {})
+    // Back to the start, ready for the next time it's shown (e.g. after signing out).
+    this.state = { step: 'email', mode: 'code', email: '', error: '', busy: false, recovery: false }
+    this.render()
+    this.dispatchEvent(new CustomEvent('slauth:signed-in', { detail: { user }, bubbles: true, composed: true }))
+    const to = this.getAttribute('redirect') ?? this.afterRedirect
+    if (to) window.location.assign(to)
+  }
+
+  passkeys() {
+    return !this.hasAttribute('no-passkeys') && this.config.passkeys !== false && this.auth.passkey.supported()
+  }
+
+  render() {
+    const { step, mode, email, error, busy, recovery } = this.state
+    const { providers = [], passwords } = this.config
+    const app = this.appName || (this.config.appName !== 'your app' ? (this.config.appName ?? '') : '')
+    const name = app ? ` to ${escape(app)}` : ''
+    const off = busy ? 'disabled' : ''
+    const redirect = this.getAttribute('redirect') ?? window.location.pathname + window.location.search
+    const providerButtons = providers.length
+      ? `<div class="providers">${providers.map((p) => `<a class="button" part="provider" href="${escape(this.auth.oauth.url(p.id, { redirect }))}">Continue with ${escape(p.name)}</a>`).join('')}</div><div class="or">or</div>`
+      : ''
+
+    const emailViews = {
+      code: `
+        <h2>Sign in${name}</h2>
+        ${providerButtons}
+        <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" ${off}>Email me a code</button>
+        </form>
+        ${this.passkeys() ? `<button class="ghost dashed" data-on="passkey" ${off}>Sign in with a passkey</button>` : ''}
+        ${passwords ? `<div class="row"><button class="link" data-on="mode-password">Use a password</button><button class="link" data-on="mode-sign-up">Create an account</button></div>` : ''}`,
+      password: `
+        <h2>Sign in${name}</h2>
+        ${providerButtons}
+        <form data-on="password">
+          <label for="email">Email</label>
+          <input id="email" type="email" autocomplete="username webauthn" required value="${escape(email)}" />
+          <label for="password">Password</label>
+          <input id="password" type="password" autocomplete="current-password" required />
+          <button class="primary" ${off}>Sign in</button>
+        </form>
+        <div class="row"><button class="link" data-on="mode-code">Email me a code instead</button><button class="link" data-on="mode-code">Forgot password?</button></div>`,
+      'sign-up': `
+        <h2>Create an account${name}</h2>
+        ${providerButtons}
+        <form data-on="sign-up">
+          <label for="email">Email</label>
+          <input id="email" type="email" autocomplete="email" required value="${escape(email)}" />
+          <label for="password">Password</label>
+          <input id="password" type="password" autocomplete="new-password" minlength="8" required />
+          <button class="primary" ${off}>Create account</button>
+        </form>
+        <div class="row"><button class="link" data-on="mode-password">I have an account</button></div>`,
+    }
+
+    const views = {
+      email: emailViews[mode] ?? emailViews.code,
+      code: `
+        <h2>Check your email</h2>
+        <p>We sent a code to <strong>${escape(email)}</strong>${this.config.magicLinks ? ', with a link you can tap instead' : ''}.</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" ${off}>${mode === 'sign-up' ? 'Create account' : '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>`,
+      'two-factor': recovery
+        ? `
+        <h2>Use a recovery code</h2>
+        <p>One of the codes you saved when you turned on two-factor sign-in. Each works once.</p>
+        <form data-on="two-factor">
+          <label for="code">Recovery code</label>
+          <input id="code" autocomplete="off" autocapitalize="off" spellcheck="false" required />
+          <button class="primary" ${off}>Continue</button>
+        </form>
+        <div class="row"><button class="link" data-on="use-app">Use the app instead</button></div>`
+        : `
+        <h2>Two-factor sign-in</h2>
+        <p>Enter the 6-digit code from your authenticator app.</p>
+        <form data-on="two-factor">
+          <label for="code">Code</label>
+          <input id="code" class="code" inputmode="numeric" autocomplete="one-time-code" maxlength="6" required />
+          <button class="primary" ${off}>Continue</button>
+        </form>
+        <div class="row"><button class="link" data-on="use-recovery">Lost your phone?</button><button class="link" data-on="back">Start over</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" ${off}>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) => {
+      for (const el of this.shadowRoot.querySelectorAll(`[data-on="${key}"]`)) {
+        el.addEventListener(el.tagName === 'FORM' ? 'submit' : 'click', (event) => {
+          event.preventDefault()
+          handler()
+        })
+      }
+    }
+    const value = (id) => this.shadowRoot.getElementById(id)?.value ?? ''
+    // Read inputs before run(): it re-renders the form, which would empty them.
+    on('email', () => {
+      const typed = value('email').trim()
+      this.set({ email: typed })
+      return this.run(async () => {
+        await this.auth.email.start(typed, { redirect: this.getAttribute('redirect') ?? undefined })
+        this.set({ step: 'code' })
+        this.shadowRoot.getElementById('code')?.focus()
+      })
+    })
+    on('password', () => {
+      const typed = value('email').trim()
+      const password = value('password')
+      this.set({ email: typed })
+      return this.run(async () => this.signedIn(await this.auth.password.signIn(typed, password)))
+    })
+    on('sign-up', () => {
+      const typed = value('email').trim()
+      const password = value('password')
+      this.set({ email: typed })
+      return this.run(async () => {
+        await this.auth.password.signUp(typed, password)
+        this.set({ step: 'code' })
+      })
+    })
+    on('code', () => {
+      const code = value('code')
+      return this.run(async () => this.signedIn(await this.auth.email.verify(email, code)))
+    })
+    on('two-factor', () => {
+      const code = value('code')
+      return this.run(async () => this.signedIn(await this.auth.twoFactor.verify(recovery ? { recoveryCode: code } : { code }), { offer: false }))
+    })
+    on('passkey', () => this.run(async () => this.signedIn(await this.auth.passkey.signIn(), { offer: false })))
+    on('mode-code', () => this.set({ mode: 'code', error: '' }))
+    on('mode-password', () => this.set({ mode: 'password', error: '' }))
+    on('mode-sign-up', () => this.set({ mode: 'sign-up', error: '' }))
+    on('use-recovery', () => this.set({ recovery: true, error: '' }))
+    on('use-app', () => this.set({ recovery: false, error: '' }))
+    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()
+        await this.done(this.user)
+      }),
+    )
+    on('skip', () => this.done(this.user))
+    const first = this.shadowRoot.querySelector(step === 'email' && email ? '#password, input' : 'input')
+    first?.focus({ preventScroll: true })
+  }
+}
+
+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,14 @@
+/**
+ * Prints sign-in codes (and links) 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, link, appName, kind = 'sign-in', subject }) {
+      if (kind === 'sign-in') console.log(`\n  🦥 slauth: ${appName} sign-in code for ${to} is ${code}${link ? `\n     or open ${link}` : ''}\n`)
+      else console.log(`\n  🦥 slauth: email to ${to}: ${subject}${code ? `\n     code: ${code}` : ''}${link ? `\n     link: ${link}` : ''}\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,56 @@
+import { escapeHtml } from '../util.js'
+
+/**
+ * The emails slauth sends, unless you pass your own `emails` function in the config.
+ *
+ *   sign-in       a 6-digit code (and a link, with magicLinks on)
+ *   email-change  a code to confirm a new address
+ *   invite        an invitation to join an organization
+ */
+export function defaultMessage(kind, { code, link, appName, minutes, orgName, inviter }) {
+  if (kind === 'email-change') {
+    return box({
+      subject: `${code} is your code to confirm this email for ${appName}`,
+      lines: [`Enter this code in ${escapeHtml(appName)} to use this address from now on:`],
+      textLines: [`Enter this code in ${appName} to use this address from now on:`],
+      code,
+      footer: `It works for ${minutes} minutes. If you didn't ask for it, you can ignore this email.`,
+    })
+  }
+  if (kind === 'invite') {
+    return box({
+      subject: `${inviter ? `${inviter} invited you` : "You're invited"} to join ${orgName} on ${appName}`,
+      lines: [`${inviter ? `${escapeHtml(inviter)} invited you` : "You're invited"} to join <strong>${escapeHtml(orgName)}</strong> on ${escapeHtml(appName)}.`],
+      textLines: [`${inviter ? `${inviter} invited you` : "You're invited"} to join ${orgName} on ${appName}.`],
+      link,
+      linkLabel: 'Accept the invitation',
+      footer: `Sign in with this email address to accept. The invitation lasts 7 days.`,
+    })
+  }
+  return box({
+    subject: `${code} is your ${appName} sign-in code`,
+    lines: [`Your <strong>${escapeHtml(appName)}</strong> sign-in code:`],
+    textLines: [`Your ${appName} sign-in code is ${code}`],
+    code,
+    link,
+    linkLabel: `Sign in to ${appName}`,
+    footer: `It works for ${minutes} minutes. If you didn't ask for it, you can ignore this email.`,
+  })
+}
+
+/** The sign-in email, as slauth 1.0 exported it. */
+export function codeMessage({ code, appName, minutes }) {
+  return defaultMessage('sign-in', { code, appName, minutes })
+}
+
+function box({ subject, lines, textLines = lines, code, link, linkLabel, footer }) {
+  const text = [...textLines, code ? `\n${code}` : '', link ? `\n${linkLabel}: ${link}` : '', `\n${footer}`].filter(Boolean).join('\n')
+  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">
+${lines.map((l) => `<p style="margin:0 0 8px;font-size:15px">${l}</p>`).join('\n')}
+${code ? `<p style="margin:0 0 16px;font-size:34px;font-weight:800;letter-spacing:6px">${escapeHtml(code)}</p>` : ''}
+${link ? `<p style="margin:8px 0 16px"><a href="${escapeHtml(link)}" style="display:inline-block;background:#f59e0b;color:#2b2118;border:2px solid #2b2118;border-radius:10px;padding:10px 16px;font-weight:700;text-decoration:none">${escapeHtml(linkLabel)}</a></p>` : ''}
+<p style="margin:0;font-size:13px;color:#6b5d50">${escapeHtml(footer)}</p>
+</div></body></html>`
+  return { subject, text, html }
+}

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,75 @@
+import { defaultMessage } from './email/message.js'
+import { hmac, safeEqual } from './util.js'
+
+export const CODE_MINUTES = 10
+const MAX_TRIES = 5
+const RESEND_SECONDS = 60
+
+/**
+ * 6-digit codes sent by email: for signing in, and for confirming a new address.
+ *
+ *   code:<email>              { hash, expiresAt, tries, sentAt, ... }  (lives 10 minutes)
+ *   code-change:<userId>      the same, for a new email address
+ *
+ * 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, message?: import('./index.js').SlauthConfig['emails'] }} options
+ */
+export function createEmailCodes({ store, secret, sender, appName, message }) {
+  const hashOf = (email, code) => hmac(secret, `code:${email}:${code}`)
+
+  return {
+    /**
+     * @param {string} email
+     * @param {{ key?: string, kind?: 'sign-in' | 'email-change', link?: string, data?: object }} [options]
+     * @returns {Promise<{ ok: true } | { ok: false, code: 'slow-down', retryAfter: number }>}
+     */
+    async start(email, { key = `code:${email}`, kind = 'sign-in', link, data = {} } = {}) {
+      const existing = await store.get(key)
+      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(key, { ...data, email, hash: await hashOf(email, code), expiresAt: now + CODE_MINUTES * 60_000, tries: 0, sentAt: now }, { ttl: CODE_MINUTES * 60 })
+      await send({ kind, to: email, code, link, minutes: CODE_MINUTES })
+      return { ok: true }
+    },
+
+    /** @returns {Promise<{ ok: true, entry: object } | { ok: false, code: 'expired' | 'too-many-tries' | 'bad-code', triesLeft?: number }>} */
+    async verify(email, code, { key = `code:${email}` } = {}) {
+      const entry = await store.get(key)
+      if (!entry || entry.expiresAt <= Date.now() || (entry.email && entry.email !== email)) 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(key)
+        return { ok: true, entry }
+      }
+      const tries = entry.tries + 1
+      const ttl = Math.max(1, Math.ceil((entry.expiresAt - Date.now()) / 1000))
+      await store.put(key, { ...entry, tries }, { ttl })
+      return tries >= MAX_TRIES ? { ok: false, code: 'too-many-tries' } : { ok: false, code: 'bad-code', triesLeft: MAX_TRIES - tries }
+    },
+
+    send,
+  }
+
+  /** Builds an email (yours, if you passed `emails`) and hands it to the sender. */
+  async function send({ kind, to, code, link, ...details }) {
+    const data = { code, link, appName, ...details }
+    const built = (message && (await message(kind, data))) || defaultMessage(kind, data)
+    await sender.send({ to, code, link, appName, kind, ...built })
+  }
+}
+
+/** 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')
+  }
+}