slauthjs 0.0.0-stage → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## 2.0.0
+
+slauth keeps its five-minute start and now goes as deep as a project needs. Everything
+new is opt-in and still dependency-free.
+
+### New
+
+- **Sign in with providers** (`providers`): `github()`, `google()`, `discord()`, `gitlab()`,
+  `microsoft()`, any OpenID Connect issuer with `oidc()`, or your own with `oauth2()`, from
+  `slauthjs/providers`. PKCE, browser-bound state, account linking and unlinking, and
+  sign-in by email only when the provider says it's verified.
+- **Magic links** (`magicLinks`): a one-tap link in the code email, behind a click so mail
+  scanners don't use it up.
+- **Passwords** (`passwords`): PBKDF2-SHA256, email-verified sign-up, per-email lockout.
+- **Two-factor** (`twoFactor`): TOTP with one-time recovery codes.
+- **Tokens** (`tokens`): ES256 JWTs at `GET /auth/token`, public keys at `/auth/jwks.json`,
+  `auth.createToken` / `auth.verifyToken`; `auth.user()` accepts them as bearer tokens.
+- **Organizations** (`organizations`): owners, admins and custom roles, email invitations,
+  `auth.orgs.require()`.
+- **Users**: `name`, `image`, `roles`, `metadata` (public) and `privateMetadata`;
+  `requireUser(request, { role })`; email change with a code; self-service deletion.
+- **Admin API**: `auth.users.get/byEmail/list/create/update/delete/ban/unban`,
+  `auth.sessions.list/revoke/revokeAll/create` (with `impersonatorId`), `auth.accounts.list`,
+  `auth.session(request)`.
+- **Sessions**: list your devices, sign one or all others out. Bearer session tokens for
+  apps without cookies (`X-Slauth-Transport: bearer`, `createClient({ token })`).
+- **Events** (`on`): `signUp`, `signIn`, `signOut`, `userUpdated`, `userDeleted`.
+- **Custom emails** (`emails`), and senders now get `kind` and `link`.
+- **Per-IP rate limits** (`rateLimit`) on code, password and two-factor routes.
+- `allow(email, context)` now gets the sign-in method, provider and profile.
+- `GET /auth/config` tells sign-in screens what's turned on.
+- `<slauth-sign-in>` offers providers, passwords, sign-up (`mode="sign-up"`) and the
+  two-factor step, and shows provider errors.
+- `<slauth-account>` (`slauthjs/account`): profile, email, passkeys, password, providers,
+  two-factor, devices, invitations, sign out and delete.
+- `Store.list()` (optional) on every built-in store, for `auth.users.list()`.
+- `baseUrl`, `signInPage`, `freshMinutes`, `allowDeletion` options.
+
+### Changed
+
+- **Adding a passkey now needs a recent sign-in** (15 minutes by default, `freshMinutes`),
+  like setting a password, changing email, turning on two-factor, linking a provider and
+  deleting the account. The sign-in box's passkey offer comes straight after sign-in, so
+  it's unaffected; a settings-page "Add passkey" button may now get `reauth-required`.
+  Set `freshMinutes: false` for the 1.x behaviour.
+- Users carry more fields. Users stored by 1.x are read with defaults; nothing to migrate.
+- `<slauth-sign-in>` without a bundler needs `ui.js` next to `element.js` and `client.js`.
+
+### Upgrading from 1.x
+
+No data migration: users and sessions saved by 1.x keep working (old sessions join the
+new per-user index the first time they're used). Check these:
+
+1. **A settings-page "Add passkey" button** may now answer `reauth-required` for people
+   who signed in over 15 minutes ago. Ask them to sign in again, or set `freshMinutes`.
+2. **Serving the element without a bundler?** Copy `ui.js` next to `element.js` and
+   `client.js`, or the element won't load.
+3. **Per-IP rate limits are on** where the host sets `CF-Connecting-IP`, `Fly-Client-IP`
+   or `X-Real-IP`: 10 code requests per IP per 10 minutes. Many people behind one office
+   IP could hit it; raise it with `rateLimit.limits` or set `rateLimit: false`.
+4. **A few more store writes**: each sign-in also updates the person's session list, and
+   rate limiting keeps counters. Fine for D1 and SQLite; on Workers KV's free tier
+   (1,000 writes a day), consider `rateLimit: false`.
+5. `auth.user()` returns more fields (`name`, `image`, `roles`, `metadata`). Code that
+   compared the whole object, or stored it, sees the new keys.
+
+## 1.0.0
+
+Email codes, passkeys, sessions, stores (D1, SQLite, KV, memory), Resend and Cloudflare
+Email senders, the client, `<slauth-sign-in>`, Cloudflare Access support and the PIN app lock.

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,93 @@
-# 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.
+**Open-source auth you own.** Email codes and passkeys in five minutes, in your own database,
+on whatever you deploy to. Then, when the side project grows up: "Sign in with GitHub",
+passwords, two-factor, organizations, an admin API and JWTs, one config key at a time.
+Zero dependencies.
+
+Like Auth.js meets a free Clerk, with the simplicity turned all the way up.
+
+```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, name, image, roles, metadata, createdAt } or null
+```
+
+```html
+<script type="module">import 'slauthjs/element'</script>
+<slauth-sign-in app-name="My App" redirect="/"></slauth-sign-in>
+```
+
+## Out of the box
+
+- **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.
+- **Sessions** that people can see and revoke, per-IP rate limits, CSRF protection.
+
+## When you need more
+
+Every one of these is off until you turn it on:
+
+```js
+import { github, google, oidc } from 'slauthjs/providers'
+
+slauth({
+  ...,
+  providers: [github({ clientId, clientSecret }), google({ clientId, clientSecret }), oidc({ id: 'okta', name: 'Okta', issuer, clientId })],
+  magicLinks: true,     // a one-tap link in the code email
+  passwords: true,      // optional, and only after proving the email
+  twoFactor: true,      // authenticator apps + recovery codes
+  organizations: true,  // teams, roles, email invitations
+  tokens: true,         // ES256 JWTs + /auth/jwks.json for your other services
+  on: { signUp: ({ user }) => createProfile(user.id) },
+})
+```
+
+| | |
+|---|---|
+| **Providers** | GitHub, Google, Discord, GitLab, Microsoft, any OpenID Connect issuer, or a custom `oauth2()`. PKCE, account linking, verified emails only. |
+| **Passwords** | PBKDF2 via Web Crypto. "Forgot password" is just an email code. |
+| **Two-factor** | TOTP (RFC 6238) with one-time recovery codes. Passkeys skip it. |
+| **Users** | Names, pictures, roles, public and private metadata, email change, self-service deletion. `requireUser(request, { role: 'admin' })`. |
+| **Admin API** | `auth.users.list/create/update/delete/ban`, `auth.sessions.revokeAll`, impersonation. |
+| **Organizations** | Owners, admins and your own roles; invitations by email; `auth.orgs.require(request, orgId)`. |
+| **Apps without cookies** | Bearer session tokens for mobile apps and CLIs. |
+| **UI** | `<slauth-sign-in>` offers whatever's on; `<slauth-account>` is a whole account page in one tag. |
+
+📖 **Docs: [slauth.dev/docs](https://slauth.dev/docs/)**: [quickstart](https://slauth.dev/docs/quickstart/), [providers](https://slauth.dev/docs/sign-in/providers/), [frameworks](https://slauth.dev/docs/frameworks/cloudflare-workers/), [security](https://slauth.dev/docs/concepts/security/). What changed: [CHANGELOG.md](CHANGELOG.md).
+
+## 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
+
+SAML, SCIM, per-organization SSO, or a hosted dashboard you didn't build. 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 |
+
+The site and docs (slauth.dev) live in a separate repository. Spotted a docs mistake?
+[Open an issue](https://github.com/silicondaydream/slauth/issues) here.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_POLICY.md](CODE_POLICY.md). Security
+reports: [SECURITY.md](SECURITY.md). MIT licensed.

package/package.json

@@ -1,6 +1,116 @@
 {
   "name": "slauthjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Open-source auth you own: email codes, passkeys, \"Sign in with GitHub/Google\", passwords, two-factor, sessions, organizations and JWTs. Your 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"
+    },
+    "./providers": {
+      "types": "./src/providers.d.ts",
+      "default": "./src/providers.js"
+    },
+    "./element": {
+      "types": "./src/element.d.ts",
+      "default": "./src/element.js"
+    },
+    "./account": {
+      "types": "./src/account-element.d.ts",
+      "default": "./src/account-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",
+    "CHANGELOG.md",
+    "!src/**/*.test.js"
+  ],
+  "sideEffects": [
+    "./src/element.js",
+    "./src/account-element.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "vitest run && tsc -p tsconfig.json",
+    "smoke": "node test/smoke.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "oauth",
+    "oidc",
+    "sign-in-with-github",
+    "passkeys",
+    "webauthn",
+    "two-factor",
+    "totp",
+    "magic-link",
+    "sessions",
+    "organizations",
+    "jwt",
+    "nextauth-alternative",
+    "clerk-alternative",
+    "cloudflare-workers",
+    "d1",
+    "bun",
+    "deno"
+  ],
+  "homepage": "https://slauth.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/silicondaydream/slauth.git"
+  },
+  "packageManager": "pnpm@10.28.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

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/account-element.d.ts

@@ -0,0 +1,8 @@
+/** Importing this registers <slauth-account>. */
+export {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'slauth-account': HTMLElement
+  }
+}