@goobits/auth

Pluggable authentication for SvelteKit with a class-first API and durable adapters for sessions, users, credentials, OAuth tokens, MFA, and WebAuthn.

Start Here

pnpm add @goobits/auth

• docs/quickstart.md owns the complete SvelteKit setup.
• docs/public-api.md is the exported API reference.
• docs/integration.md covers custom storage adapters.
• docs/security-contract.md defines application and library security responsibilities.

A normal SvelteKit integration creates one GoobitsAuth instance, wires auth.handle() into hooks.server.ts, and mounts auth.handlers at src/routes/auth/[...auth]/+server.ts. Use drizzleAdapter(db, { schema }) for Drizzle or provide the documented adapter capabilities for another store.

Entrypoints

The main @goobits/auth entrypoint, route handlers, cookie adapters, and UI helpers are SvelteKit-first. Framework-neutral primitives are available through focused subpaths:

• @goobits/auth/security
• @goobits/auth/verification
• @goobits/auth/password
• @goobits/auth/mfa
• @goobits/auth/adapters/pg
• @goobits/auth/testing

Generic HTTP credentials, CSRF, cryptography, logging, redaction, and rate-limit counters remain owned by their @goobits/security/* entrypoints.

Stability And Distribution

Documented exports are stable for the 0.3.x line. WebAuthn and MFA may receive additive options as browser and authenticator behavior evolves.

• First-party TypeScript workspaces consume checked-out src/ entrypoints so application checks cannot use stale generated output.
• Registry installations consume compiled JavaScript and declarations from dist; raw TypeScript and release tooling are excluded.
• pnpm run build rebuilds the compiled package when a workspace needs dist.

Runtime Targets

• Cloudflare Workers and Pages use the Worker build and WASM-backed password hashing. WebAuthn handlers return 501 and must not be enabled there.
• Node 22+ selects native Argon2 and Node WebAuthn support. @goobits/auth/node and @goobits/auth/adapters/pg are Node-only.

Core Contract

• GoobitsAuth owns the SvelteKit handle, managed handlers, named route factories, session lookup, route-role guards, and security-event pipeline.
• The secure profile requires CSRF, shared production rate limiting, and an awaited audit emitter. An application-wide origin guard is valid only through the executable validateExternalSecurityBoundary callback.
• requireAuthRole() gates website/session roles; product permissions remain an application concern.
• drizzleAdapter() returns the required session, user, and password-credential capabilities plus optional token, magic-link, MFA, and WebAuthn capabilities when their tables are configured.
• Password hashes are available only through PasswordCredentialAdapter, never through general user-profile methods.
• Password-reset completion and token consumption require application-owned atomic operations; unsafe find-then-delete compatibility paths are not kept.
• Session stores persist verifier hashes rather than bearer cookie values, and managed-session APIs use separate opaque identifiers.
• OAuth token storage requires a rotation-ready keyring or application-owned codec and a unique (userId, provider) constraint.

See the public API and migration guide for the complete capability contracts.

Production Expectations

• Use one durable rate-limit store across production instances.
• Bridge Auth events into an awaited @goobits/security/audit logger with createAuthEventAuditEmitter().
• Configure secure cookies, trusted proxy headers, alert delivery, encryption keys, and required database migrations before deployment.
• Require fresh application authorization for MFA and passkey changes.
• Keep route-level product authorization, TLS, headers, secrets, and key rotation in the host application or edge.

Documentation

• docs/quickstart.md — SvelteKit setup.
• docs/public-api.md — exported API and capability reference.
• docs/integration.md — custom adapter contract.
• docs/security-contract.md — profiles, defaults, and production responsibilities.
• docs/schema.md — schema requirements.
• docs/testing.md — test helpers and expectations.
• docs/migrations/0.3-breaking.md — migration from pre-0.3 integrations.
• examples/sveltekit-quickstart/ — minimal application wiring.