@goobits/auth

Pluggable authentication for SvelteKit with a class-first API and durable adapters for sessions, users, credentials, OAuth identities and 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.6.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 request-origin verification, shared production rate limiting, and an awaited audit emitter. Signed CSRF tokens additionally require security.csrf.secret; secure deployments may explicitly disable the token layer only while origin verification remains required. strict requires both boundaries.
• requireAuthRole() gates website/session roles; product permissions remain an application concern.
• drizzleAdapter() returns the required session, user, and password-credential capabilities plus optional OAuth identity/token, magic-link, MFA, and WebAuthn storage capabilities when their tables are configured. Enabling passkey registration additionally requires an application-owned atomic createCredentialWithinLimit() capability.
• 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.
• OAuth ownership uses a provider's stable subject through the dedicated OAuthIdentityAdapter; mutable email claims never link accounts implicitly.
• OAuth sign-in, provider linking, reauthentication, and unlinking are separate flows. Identity changes require application-owned fresh authorization.
• Applications must refuse an unlink that would remove the account's last usable sign-in method.
• credentialMutations lets applications put assurance, cross-store recovery checks, credential persistence, session revocation, and audit state behind one serialized transaction boundary.

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, passkey, and OAuth identity changes.
• Offer conditional passkey autofill only after supportsConditionalPasskeys() confirms browser support.
• Rotate a current session through rotateSessionAssurance() after a trusted primary- or second-factor verification instead of rewriting session metadata in application code.
• 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.6-breaking.md — session-bound CSRF, request-origin, and secret-safe provider migration.
• docs/migrations/0.5-breaking.md — atomic passkey-registration adapter migration from 0.4.
• docs/migrations/0.4-breaking.md — OAuth identity and authentication-lifecycle migration from 0.3.
• docs/migrations/0.3-breaking.md — earlier migration from pre-0.3 integrations.
• examples/sveltekit-quickstart/ — minimal application wiring.

License

Licensed under the Functional Source License, Version 1.1, ALv2 Future License. Each released version becomes available under Apache License 2.0 two years after that version is made available. See LICENSE.