@biowiki/auth-sdk

Browser OAuth 2.0 Authorization Code + PKCE (S256) client for BioWiki Web applications. It keeps only the short-lived access token in sessionStorage; the refresh token remains an Identity-managed HttpOnly Cookie. It also maintains a stable per-application browser device ID in localStorage and sends it when exchanging or refreshing tokens.

Install

The package is published only to the company private npm Registry. Configure the scope registry in the consuming project's .npmrc:

@biowiki:registry=https://npm.company.example/repository/npm-private/

Then install a pinned version:

npm install @biowiki/[email protected]

Use

import { BioWikiAuthClient } from '@biowiki/auth-sdk';

export const auth = new BioWikiAuthClient({
  authUrl: import.meta.env.VITE_AUTH_URL,
  clientId: import.meta.env.VITE_SSO_CLIENT_ID,
  redirectUri: `${window.location.origin}/auth/callback`
});

export async function login() {
  await auth.login(window.location.pathname + window.location.search);
}

export async function completeLogin() {
  const { returnTo } = await auth.completeLogin();
  window.location.replace(returnTo.startsWith('/') ? returnTo : '/');
}

In the callback route, call completeLogin() exactly once. For protected pages, use getSession() or requireAuth().

Logout

First revoke the application's current API session through its same-origin BFF, then call logout(). The SDK clears its local access token and navigates to the Identity Service logout endpoint to clear the SSO session before returning to the registered application origin.

try {
  await fetch('/api/bff/auth/logout', { method: 'POST' });
} finally {
  await auth.logout();
}

Registration

The SDK also provides browser registration helpers:

await auth.requestRegistrationCode({
  email: '[email protected]',
  botToken: '<turnstile-token>'
});

await auth.register({
  email: '[email protected]',
  password: 'StrongPassword',
  verificationCode: '381624'
});

Publish

Package maintainers publish from packages/auth-sdk:

npm ci
npm run typecheck
npm run build
npm pack --dry-run
npm publish --registry="$NPM_REGISTRY"

Set NPM_REGISTRY and NPM_TOKEN in CI secrets. Copy .npmrc.example to a user-level or CI-generated .npmrc, replacing the Registry URL. Never commit an npm token.

prepublishOnly rebuilds and typechecks the package before publication. Only dist/, README.md, and LICENSE are included in the published tarball.

Security

• Do not place app_secret, service tokens, JWT signing keys, or npm tokens in frontend environment variables.
• Register the exact callback URL for each environment in Platform Console.
• Configure Identity Service CORS_ORIGIN to include the application Origin.
• The SDK does not create Tenants, Applications, OAuth Clients, or API credentials. Use getSession(), isAuthenticated(), and requireAuth() for browser session checks.