@yiminlab/authkit

Authentication toolkit for YiminLab apps: token management, login redirect, callback handling, and React hooks/components.

Cross-app login handoff

Portal callbacks now carry only a short-lived, one-time code plus a validated same-origin return path. VoyageCallbackHandler (and CallbackHandler) redeems that code with AuthKit for a fresh session bound to the receiving app, removes the code from browser history, and writes tokens only after a complete successful response. During the rollout it still accepts the prior token-query callback format for compatibility.

Entrypoints

| Import | Role | | --- | --- | | @yiminlab/authkit / @yiminlab/authkit/react | Headless AuthKit. Session, tokens, redirects. Default UI uses inline fallbacks and does not require Voyage. | | @yiminlab/authkit/voyage | Optional Voyage adapter. Maps AuthKit state onto @yiminlab/voyage 0.15.x components. |

Install Voyage only when you use the adapter:

pnpm add @yiminlab/authkit @yiminlab/voyage

Peer dependency: @yiminlab/voyage ^0.15.0 (optional unless importing /voyage).

Host apps should load Voyage CSS / theme attrs as usual (@yiminlab/voyage/tokens.css, @yiminlab/voyage/voyage.css).

Logout contract

useAuth().logout() exits only the current app session. It first calls POST /api/auth/logout/current with the current access/refresh pair, then clears this origin's tokens and user state; same-origin tabs converge through storage events. Other app/device sessions keep their independent refresh-token families.

const { logout } = useAuth();
await logout(); // ends the current app session only

useAuth().logoutAllSessions() is the explicit account-wide operation. Like the low-level AuthKitClient.logoutAllSessions, it calls POST /api/auth/logout/all, which revokes every refresh token owned by the user. The historical POST /api/auth/logout and AuthKitClient.logout remain global-revoke compatibility aliases for older clients.

1. If the access token is expired but a refresh token remains, the client refreshes first so the revoke request carries a usable identity.
2. If there is no usable credential, local logout still completes immediately.
3. Server revoke failure does not block local logout. HTTP errors (401/5xx), network failures, and request timeouts are logged; local tokens, user state, and cross-tab session (via storage events) are always cleared afterward.

const { logoutAllSessions } = useAuth();
await logoutAllSessions(); // signs out every app/device when server revoke succeeds

Minimal Voyage usage

import {
  VoyageAuthGuard,
  VoyageCallbackHandler,
  VoyageAuthMenu,
} from '@yiminlab/authkit/voyage';
import { VoyageToolbar } from '@yiminlab/voyage/react';

// Guard a page (section state view)
<VoyageAuthGuard fallback="prompt" returnPath="/app">
  <AppPage />
</VoyageAuthGuard>

// OAuth / portal callback page (page state view)
<VoyageCallbackHandler defaultRedirectPath="/" />

// Standard app toolbar with the account menu in Voyage's account slot
// reloginOnLogout: clear this app session then redirect to login (Engram-style)
<VoyageToolbar
  account={<VoyageAuthMenu returnPath="/app" reloginOnLogout />}
/>

VoyageAuthMenu can also be rendered on its own when a host does not use VoyageToolbar. It displays display_name → username → email, email as secondary text, and avatar_url when available.

Headless equivalents remain available from the root / /react entry (AuthGuard, CallbackHandler, useAuth) for apps that bring their own UI.