slauthjs 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 silicondaydream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# slauth 🦥
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Auth for side projects.** Email codes and passkeys in five minutes, in your own database,
+on whatever you deploy to. Zero dependencies, about 29 kB.
+
+Sturdier than a password in an env var, and a lot less fuss than a hosted auth company.
+
+```js
+import { slauth } from 'slauthjs'
+import { d1 } from 'slauthjs/stores/d1'
+import { resend } from 'slauthjs/email/resend'
+
+const auth = slauth({
+  secret: env.SLAUTH_SECRET,
+  store: d1(env.DB),
+  email: resend({ apiKey: env.RESEND_API_KEY, from: 'My App <hi@myapp.dev>' }),
+})
+
+if (url.pathname.startsWith('/auth/')) return auth.handle(request)
+const user = await auth.user(request) // { id, email, createdAt } or null
+```
+
+```html
+<script type="module">import 'slauthjs/element'</script>
+<slauth-sign-in app-name="My App" redirect="/"></slauth-sign-in>
+```
+
+- **Email codes**: 6 digits, 10 minutes, 5 tries, stored as an HMAC.
+- **Passkeys**: WebAuthn (ES256 + RS256) checked with Web Crypto, no libraries.
+- **Your database**: D1, SQLite (bun:sqlite, node:sqlite, better-sqlite3), Workers KV, memory, or any `get`/`put`/`delete`.
+- **Runs anywhere** with `Request`/`Response`: Cloudflare Workers, Bun, Deno, Node, Next.js, Astro, Hono.
+- **Extras**: an allow list (`['me@example.com', '@family.com']`), an optional PIN app lock, and Cloudflare Access support.
+
+📖 **Docs: [slauth.dev/docs](https://slauth.dev/docs/)**: [quickstart](https://slauth.dev/docs/quickstart/), [frameworks](https://slauth.dev/docs/frameworks/cloudflare-workers/), [security](https://slauth.dev/docs/concepts/security/).
+
+## Examples
+
+- [`examples/workers-d1`](examples/workers-d1): Cloudflare Workers + D1, with the sign-in box
+- [`examples/bun-sqlite`](examples/bun-sqlite): Bun + bun:sqlite
+- [`examples/node-express`](examples/node-express): Express + node:sqlite
+
+## Not for
+
+Enterprise SSO/SAML, orgs and roles, or dozens of OAuth providers. For those, see
+[the comparison](https://slauth.dev/compare).
+
+## Repository
+
+| | |
+|---|---|
+| `src/` | the library (plain ESM + `.d.ts`) |
+| `test/` | test helpers, a simulated passkey authenticator, type checks, a browser test |
+| `examples/` | runnable apps |
+| `site/` | slauth.dev: Astro marketing pages + Starlight docs |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "slauthjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Auth for side projects: email codes and passkeys, your own database, zero dependencies. Runs on Workers, Bun, Deno and Node.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./client": {
+      "types": "./src/client.d.ts",
+      "default": "./src/client.js"
+    },
+    "./element": {
+      "types": "./src/element.d.ts",
+      "default": "./src/element.js"
+    },
+    "./node": {
+      "types": "./src/node.d.ts",
+      "default": "./src/node.js"
+    },
+    "./stores/memory": {
+      "types": "./src/stores/memory.d.ts",
+      "default": "./src/stores/memory.js"
+    },
+    "./stores/d1": {
+      "types": "./src/stores/d1.d.ts",
+      "default": "./src/stores/d1.js"
+    },
+    "./stores/kv": {
+      "types": "./src/stores/kv.d.ts",
+      "default": "./src/stores/kv.js"
+    },
+    "./stores/sqlite": {
+      "types": "./src/stores/sqlite.d.ts",
+      "default": "./src/stores/sqlite.js"
+    },
+    "./email/console": {
+      "types": "./src/email/console.d.ts",
+      "default": "./src/email/console.js"
+    },
+    "./email/resend": {
+      "types": "./src/email/resend.d.ts",
+      "default": "./src/email/resend.js"
+    },
+    "./email/cloudflare": {
+      "types": "./src/email/cloudflare.d.ts",
+      "default": "./src/email/cloudflare.js"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js"
+  ],
+  "sideEffects": [
+    "./src/element.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "vitest run && tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "passkeys",
+    "webauthn",
+    "magic-code",
+    "cloudflare-workers",
+    "d1",
+    "bun",
+    "deno",
+    "side-project"
+  ],
+  "homepage": "https://slauth.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/silicondaydream/slauth.git"
+  }
+}

package/src/access.js

@@ -0,0 +1,143 @@
+/**
+ * Who is this? Cloudflare Access answers that before a request ever reaches the app:
+ * it signs people in (email code or Google) and passes each request through with a
+ * signed JWT in the Cf-Access-Jwt-Assertion header. This checks that JWT.
+ *
+ * Never trust the plain Cf-Access-Authenticated-User-Email header on its own: anyone who
+ * reaches the Worker without going through Access (a stray route, a workers.dev URL
+ * left open) can set it. The JWT can only be signed by your Access team.
+ *
+ * Web Crypto only, so it runs on Workers, Node 20+ and in tests alike.
+ */
+
+import { base64Url, readCookie } from './util.js'
+
+const JWKS_TTL_MS = 60 * 60 * 1000
+const CLOCK_SKEW_S = 60
+
+/**
+ * @typedef {{ email: string, userId: string }} User
+ * @typedef {{
+ *   teamDomain: string,
+ *   audience: string | string[],
+ *   allowedEmails?: string[],
+ *   aliases?: Record<string, string>,
+ *   devUser?: string,
+ *   fetch?: typeof fetch,
+ * }} AccessOptions
+ */
+
+/**
+ * @param {AccessOptions} options
+ *   teamDomain     "yourteam" or "yourteam.cloudflareaccess.com"
+ *   audience       the Application Audience (AUD) tag from the Access application
+ *   allowedEmails  optional second check after the Access policy
+ *   aliases        email -> userId, to keep someone's data when their email changes
+ *   devUser        local development only: treat every request as this email
+ */
+export function createAccess(options) {
+  const team = normalizeTeam(options.teamDomain)
+  const issuer = `https://${team}`
+  const audiences = [options.audience].flat().filter(Boolean)
+  const allowed = options.allowedEmails?.map((e) => e.trim().toLowerCase())
+  const doFetch = options.fetch ?? ((...args) => fetch(...args))
+
+  if (!options.devUser && audiences.length === 0) throw new Error('slauth: Access audience (AUD tag) is required.')
+
+  /** @type {{ keys: Map<string, CryptoKey>, at: number } | null} */
+  let jwks = null
+
+  async function keyFor(kid, force = false) {
+    if (force || !jwks || Date.now() - jwks.at > JWKS_TTL_MS) {
+      const res = await doFetch(`${issuer}/cdn-cgi/access/certs`)
+      if (!res.ok) throw new Error(`slauth: could not load Access keys (${res.status}).`)
+      const { keys = [] } = await res.json()
+      const map = new Map()
+      for (const jwk of keys) {
+        if (jwk.kty !== 'RSA' || !jwk.kid) continue
+        map.set(jwk.kid, await crypto.subtle.importKey('jwk', jwk, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']))
+      }
+      jwks = { keys: map, at: Date.now() }
+    }
+    return jwks.keys.get(kid)
+  }
+
+  /**
+   * The signed-in person, or null when the request didn't come through Access, the
+   * token is bad or expired, or the email isn't on the list.
+   * @param {Request} request
+   * @returns {Promise<User | null>}
+   */
+  async function getUser(request) {
+    if (options.devUser) return toUser(options.devUser)
+
+    const token = request.headers.get('cf-access-jwt-assertion') ?? readCookie(request.headers.get('cookie'), 'CF_Authorization')
+    if (!token) return null
+    const claims = await verify(token)
+    if (!claims || typeof claims.email !== 'string') return null
+    return toUser(claims.email)
+  }
+
+  async function verify(token) {
+    const parts = token.split('.')
+    if (parts.length !== 3) return null
+    let header, claims
+    try {
+      header = JSON.parse(decodeText(parts[0]))
+      claims = JSON.parse(decodeText(parts[1]))
+    } catch {
+      return null
+    }
+    if (header.alg !== 'RS256' || typeof header.kid !== 'string') return null
+
+    // Access rotates its keys; an unknown kid means it's time to look again.
+    const key = (await keyFor(header.kid)) ?? (await keyFor(header.kid, true))
+    if (!key) return null
+
+    const signed = new TextEncoder().encode(`${parts[0]}.${parts[1]}`)
+    const ok = await crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, decodeBytes(parts[2]), signed)
+    if (!ok) return null
+
+    const now = Math.floor(Date.now() / 1000)
+    if (claims.iss !== issuer) return null
+    if (![claims.aud].flat().some((a) => audiences.includes(a))) return null
+    if (typeof claims.exp !== 'number' || claims.exp + CLOCK_SKEW_S < now) return null
+    if (typeof claims.nbf === 'number' && claims.nbf - CLOCK_SKEW_S > now) return null
+    return claims
+  }
+
+  async function toUser(rawEmail) {
+    const email = rawEmail.trim().toLowerCase()
+    if (allowed && !allowed.includes(email)) return null
+    return { email, userId: options.aliases?.[email] ?? (await userIdFor(email)) }
+  }
+
+  return { getUser }
+}
+
+/**
+ * A stable, opaque id for an email: the same in every app, so the suite agrees on who
+ * is who without sharing a database. It never contains the email itself.
+ * @param {string} email
+ */
+export async function userIdFor(email) {
+  const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`slauth:${email.trim().toLowerCase()}`))
+  return `u_${base64Url(bytes).slice(0, 22)}`
+}
+
+function normalizeTeam(domain) {
+  const bare = String(domain ?? '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '')
+  return bare.includes('.') ? bare : `${bare}.cloudflareaccess.com`
+}
+
+
+function decodeBytes(segment) {
+  const base64 = segment.replace(/-/g, '+').replace(/_/g, '/')
+  const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4))
+  return Uint8Array.from(binary, (c) => c.charCodeAt(0))
+}
+
+function decodeText(segment) {
+  return new TextDecoder().decode(decodeBytes(segment))
+}
+

package/src/client.d.ts

@@ -0,0 +1,34 @@
+import type { Policy, SlauthUser } from './index.js'
+
+export class SlauthError extends Error {
+  /** e.g. "bad-code", "expired", "not-allowed", "slow-down", "signed-out", "offline". */
+  code: string
+  status: number
+  [detail: string]: unknown
+}
+
+export interface SlauthClient {
+  session(): Promise<{ user: SlauthUser | null; lock?: { policy: Policy; required: boolean; pinSet: boolean; unlocked: boolean } }>
+  email: {
+    start(email: string): Promise<{ ok: true }>
+    verify(email: string, code: string): Promise<{ user: SlauthUser }>
+  }
+  passkey: {
+    supported(): boolean
+    register(name?: string): Promise<{ ok: true; passkey: { id: string; name: string } }>
+    signIn(): Promise<{ user: SlauthUser }>
+    list(): Promise<{ passkeys: { id: string; name: string; createdAt: number; lastUsedAt: number | null }[] }>
+    remove(id: string): Promise<{ ok: true }>
+  }
+  signOut(): Promise<{ ok: true }>
+  lock: {
+    unlock(pin: string): Promise<{ ok: true }>
+    setup(pin: string, policy?: Policy): Promise<{ ok: true }>
+    skip(): Promise<{ ok: true }>
+    changePin(current: string, next: string): Promise<{ ok: true }>
+    setPolicy(policy: Policy, pin?: string): Promise<{ ok: true; policy: Policy }>
+    lockNow(): Promise<{ ok: true }>
+  }
+}
+
+export function createClient(options?: { basePath?: string; fetch?: typeof fetch }): SlauthClient

package/src/client.js

@@ -0,0 +1,118 @@
+/**
+ * The browser side: tiny helpers around the /auth routes, including the WebAuthn
+ * plumbing passkeys need.
+ *
+ *   import { createClient } from 'slauthjs/client'
+ *   const auth = createClient()                 // or createClient({ basePath: '/api/auth' })
+ *   await auth.email.start('me@example.com')
+ *   const { user } = await auth.email.verify('me@example.com', '123456')
+ */
+
+/** Thrown for any answer that isn't a success; `code` says which (see the docs' error list). */
+export class SlauthError extends Error {
+  constructor(message, code, status, details = {}) {
+    super(message)
+    this.code = code
+    this.status = status
+    Object.assign(this, details)
+  }
+}
+
+export function createClient({ basePath = '/auth', fetch: doFetch = (...args) => fetch(...args) } = {}) {
+  const base = basePath.replace(/\/+$/, '')
+
+  async function call(path, body) {
+    const init = body === undefined ? { credentials: 'same-origin' } : { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }
+    let res
+    try {
+      res = await doFetch(`${base}/${path}`, init)
+    } catch {
+      throw new SlauthError("Couldn't reach the server.", 'offline', 0)
+    }
+    const data = await res.json().catch(() => ({}))
+    if (!res.ok) {
+      const { error, code, ...rest } = data
+      throw new SlauthError(error ?? `HTTP ${res.status}`, code ?? 'server-error', res.status, rest)
+    }
+    return data
+  }
+
+  const passkey = {
+    /** True when this browser can use passkeys. */
+    supported: () => typeof window !== 'undefined' && typeof window.PublicKeyCredential === 'function',
+
+    /** Adds a passkey for the signed-in person. */
+    async register(name) {
+      const options = await call('passkey/register/options', {})
+      const credential = await navigator.credentials.create({
+        publicKey: {
+          ...options,
+          challenge: bytes(options.challenge),
+          user: { ...options.user, id: bytes(options.user.id) },
+          excludeCredentials: options.excludeCredentials.map((c) => ({ ...c, id: bytes(c.id) })),
+        },
+      })
+      return call('passkey/register/verify', { credential: serialize(credential), name })
+    },
+
+    /** Signs in with a passkey; the browser lets the person pick one. */
+    async signIn() {
+      const options = await call('passkey/login/options', {})
+      const credential = await navigator.credentials.get({
+        publicKey: { ...options, challenge: bytes(options.challenge), allowCredentials: [] },
+      })
+      return call('passkey/login/verify', { credential: serialize(credential) })
+    },
+
+    list: () => call('passkeys'),
+    remove: (id) => call('passkey/delete', { id }),
+  }
+
+  return {
+    /** `{ user }` (null when signed out), plus `lock` when the app lock is on. */
+    session: () => call('session'),
+    email: {
+      start: (email) => call('email/start', { email }),
+      verify: (email, code) => call('email/verify', { email, code }),
+    },
+    passkey,
+    signOut: () => call('signout', {}),
+    lock: {
+      unlock: (pin) => call('lock/login', { pin }),
+      setup: (pin, policy) => call('lock/setup', { pin, policy }),
+      skip: () => call('lock/setup', { policy: 'never' }),
+      changePin: (current, next) => call('lock/pin', { current, next }),
+      setPolicy: (policy, pin) => call('lock/policy', { policy, pin }),
+      lockNow: () => call('lock/logout', {}),
+    },
+  }
+}
+
+function bytes(base64url) {
+  const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/')
+  const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4))
+  return Uint8Array.from(binary, (c) => c.charCodeAt(0))
+}
+
+function text(buffer) {
+  let binary = ''
+  for (const byte of new Uint8Array(buffer)) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/** A PublicKeyCredential as JSON with base64url fields, the shape the server reads. */
+function serialize(credential) {
+  if (typeof credential.toJSON === 'function') return credential.toJSON()
+  const r = credential.response
+  const response = { clientDataJSON: text(r.clientDataJSON) }
+  if (r.attestationObject) {
+    response.attestationObject = text(r.attestationObject)
+    response.transports = r.getTransports?.() ?? []
+  }
+  if (r.authenticatorData) {
+    response.authenticatorData = text(r.authenticatorData)
+    response.signature = text(r.signature)
+    response.userHandle = r.userHandle ? text(r.userHandle) : null
+  }
+  return { id: credential.id, rawId: text(credential.rawId), type: credential.type, response }
+}