@storyshelf/auth

View as Markdown

@storyshelf/auth is the auth engine: Better Auth owns OIDC/SAML/WebAuthn wire protocols (concepts, hooks, session management) while StoryShelf keeps users, memberships, invites, and UI. Sessions are Better Auth DB rows under the storyshelf_session cookie (seven-day TTL, cookieCache off so revocation bites immediately — see cookie cache); engine identities mirror into the shelf users table with roles preserved.

Install

npm i @storyshelf/auth

pnpm add @storyshelf/auth

yarn add @storyshelf/auth

npm package — install tarballs and version history.
JSR package — TypeScript-first registry page.
Public API reference — generated docs for every export; start here to learn the API. (The same reference is on JSR.)
Source on GitHub — package directory on main.

Exact pins: better-auth@1.7.6, @better-auth/passkey@1.7.6, @better-auth/sso@1.7.6.

Configure

import { createShelfAuth, resolveAuthOptions } from "@storyshelf/auth";

const shelf = createShelfAuth(
  await resolveAuthOptions({
    db: database,
    secret: "{env:SECRET}",
    baseURL: process.env.PUBLIC_BASE_URL!,
    passkeys: {},
  }),
);

const app = createShelfApp({ database, storage, auth: shelf.adapter });

Mounts at /api/auth/* via the Hono integration; the login page renders one widget per configured method (password, oauth, passkey, sso descriptors — see database adapters).

Recipes

Social — githubPreset, gitlabPreset, googlePreset, entraPreset, cognitoPreset (native provider integrations — see social providers).
Enterprise OIDC — keycloakPreset, oktaPreset, auth0Preset (configs via generic OAuth).
Enterprise SSO — ssoKeycloakPreset, ssoOktaPreset, ssoAuth0Preset, ssoGooglePreset, ssoEntraPreset (domain-routed OIDC via IdP discovery) and samlPreset (explicit IdP fields or metadata XML) via the SSO plugin. IdP callback URLs via ssoCallbackUrls(baseURL, providerId).
Invites — issueInvite / verifyInvite / acceptInvite (single-use, 7-day, hashed at rest; re-invite is password recovery). Minimum password length is 12.
Dev bootstrap — ensurePasswordAdmin(database, { email, password }) provisions the env-driven local admin.
Sessions/passkeys inventory — listUserSessions, listUserPasskeys, hasPasswordCredential (drive the /profile Devices and Passkeys sections).

Secrets stay out of code with {env:NAME} refs (resolved from process.env, then your resolveSecrets hook for Vault/AWS/GCP). Precedence: explicit literal > {env} ref > schema default; code recipes > DB rows > plugin defaults.

See the authentication guide and auth concepts for the invite playbook, passkey prerequisites, secrets, and the engine→shelf user mirror.

Plugin contract

Custom Better Auth plugins ride plugins: [...]. Two boot-time guards: login method ids must be unique across providers, and custom endpoints must not shadow shelf-reserved engine paths (/sign-in/*, /sign-up/email, session revocation — see endpoints). Runtime SSO provider management is blocked — providers are code-driven recipes.

The broader auth modes and project roles are covered in the authentication guide and auth concepts. Upstream docs: Better Auth, passkey, SSO, Hono.