@selei/auth 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @selei/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sign in or sign up with a Seleimend account using OpenID Connect authorization code flow and S256 PKCE. ESM, TypeScript declarations, modern browsers, and Node 20.19+.
+
+```sh
+pnpm add @selei/auth
+```
+
+Register an application in the Seleimend administrator console first. Register every callback and logout URL exactly, and the browser application's origin separately. The default issuer is `https://signin.seleimend.com`.
+
+## Browser
+
+```ts
+import { createBrowserClient, createSignInButton } from '@selei/auth/browser';
+
+const auth = await createBrowserClient({
+  clientId: 'YOUR_PUBLIC_CLIENT_ID',
+  redirectUri: 'https://your-product.example/callback',
+  postLogoutRedirectUri: 'https://your-product.example/',
+});
+
+if (location.pathname === '/callback') {
+  const user = await auth.handleCallback();
+  document.querySelector('#name')!.textContent = user.name ?? user.sub;
+}
+
+document.querySelector('#signin')!.append(createSignInButton({
+  onSignIn: async () => { location.assign(await auth.beginSignIn()); },
+  onError: () => { document.querySelector('#error')!.textContent = 'Please try again.'; },
+}));
+// Registration: location.assign(await auth.beginSignUp());
+// Profile: await auth.getUserInfo();
+// Logout: location.assign(await auth.logout());
+```
+
+Use a **public** client without a secret. The adapter keeps access tokens in memory; reloading starts a new sign-in. Only short-lived PKCE transactions live in sessionStorage, are bound to the tab, and are consumed once. Never put secrets or tokens in localStorage. Browser clients cannot request `offline_access` or refresh tokens. Render profile values as text, never HTML. The consented `picture` URL is temporary; fetch new user information to renew it.
+
+## Node
+
+```ts
+import { createNodeClient } from '@selei/auth/node';
+
+const auth = await createNodeClient({
+  clientId: process.env.SELEIMEND_CLIENT_ID!,
+  clientSecret: process.env.SELEIMEND_CLIENT_SECRET!,
+  redirectUri: 'https://your-product.example/callback',
+  postLogoutRedirectUri: 'https://your-product.example/',
+  scopes: ['openid', 'profile', 'email', 'offline_access'],
+}, {
+  put: async (state, transaction) => sessionTransactions.put(state, transaction),
+  take: async state => sessionTransactions.take(state),
+});
+// Redirect: await auth.beginSignIn() / auth.beginSignUp()
+// Callback: const tokens = await auth.handleCallback(requestAbsoluteUrl)
+// Profile: const user = await auth.getUserInfo(tokens)
+// Refresh: tokens = await auth.refresh(tokens)
+// Revoke: await auth.revoke(tokens.refresh_token ?? tokens.access_token)
+// Logout: redirect(await auth.logout(tokens))
+```
+
+Provide your own transaction store **scoped to the requesting browser session**. `take` must atomically delete and return a transaction. Store tokens only on the server behind a Secure, HttpOnly, SameSite cookie, protect application mutations from CSRF, and persist rotated refresh tokens atomically. Serialize concurrent refreshes: refresh-token reuse revokes the token family. Offline access must be enabled for the confidential client and consented by the user. The absolute refresh lifetime is 30 days.
+
+Callbacks validate state, nonce, issuer, audience, signature, expiry, and PKCE. Do not treat decoded JWT data as authorization. Use the stable `sub` identifier for account associations; email addresses can change. Signing out revokes tokens and navigates to the provider's explicit logout confirmation. Other product sessions must check userinfo/introspection or short-lived tokens to observe revocation; there is no back-channel logout endpoint.
+
+## Development examples
+
+In this repository:
+
+```sh
+cd packages/seleimend-auth
+pnpm install --frozen-lockfile
+# Public client callback http://localhost:3001/callback, origin http://localhost:3001
+VITE_SELEIMEND_CLIENT_ID=... pnpm example:browser
+# Confidential callback http://localhost:3000/callback
+SELEIMEND_CLIENT_ID=... SELEIMEND_CLIENT_SECRET=... pnpm example:node
+```
+
+See the example source for issuer and port overrides. Local HTTP requires `allowInsecureLocalhost: true`; production requires HTTPS. The Node example uses an in-memory session store for demonstration. Replace it with your durable per-session storage before deployment.
+
+## Build and release
+
+```sh
+pnpm install --frozen-lockfile
+pnpm test
+pnpm pack
+pnpm publish --access public
+```
+
+The registry package is `@selei/auth` and `publishConfig.access` is `public`. pnpm uses existing npm registry credentials; authentication tokens must never enter this package or source control. Only compiled code, declarations, and this README are included. A package archive can be installed locally before its first registry publication.

package/dist/browser.d.ts

@@ -0,0 +1,15 @@
+import { type ClientConfig } from './index.js';
+export type { ClientConfig, TokenSet, UserInfo } from './index.js';
+export declare function createBrowserClient(config: ClientConfig): Promise<{
+    beginSignIn: () => Promise<URL>;
+    beginSignUp: () => Promise<URL>;
+    handleCallback(url?: URL | string): Promise<import("openid-client").UserInfoResponse>;
+    getUserInfo(): Promise<import("openid-client").UserInfoResponse>;
+    logout(): Promise<URL>;
+    revoke(): Promise<void>;
+}>;
+export declare function createSignInButton(options: {
+    onSignIn: () => void | Promise<void>;
+    label?: string;
+    onError?: (error: unknown) => void;
+}): HTMLButtonElement;

package/dist/browser.js

@@ -0,0 +1,84 @@
+import { createClient } from './index.js';
+export async function createBrowserClient(config) {
+    if ('clientSecret' in config)
+        throw new Error('Never include a client secret in browser code.');
+    const prefix = 'seleimend:' + config.clientId + ':';
+    const store = {
+        async put(state, transaction) {
+            for (let i = sessionStorage.length - 1; i >= 0; i--) {
+                const key = sessionStorage.key(i);
+                if (!key?.startsWith(prefix))
+                    continue;
+                try {
+                    if (JSON.parse(sessionStorage.getItem(key)).expiresAt <= Date.now())
+                        sessionStorage.removeItem(key);
+                }
+                catch {
+                    sessionStorage.removeItem(key);
+                }
+            }
+            sessionStorage.setItem(prefix + state, JSON.stringify(transaction));
+        },
+        async take(state) {
+            const data = sessionStorage.getItem(prefix + state);
+            sessionStorage.removeItem(prefix + state);
+            return data ? JSON.parse(data) : undefined;
+        },
+    };
+    const client = await createClient(config, store);
+    let tokens;
+    return {
+        beginSignIn: client.beginSignIn,
+        beginSignUp: client.beginSignUp,
+        async handleCallback(url = window.location.href) {
+            try {
+                tokens = await client.handleCallback(url);
+            }
+            finally {
+                window.history.replaceState(null, '', new URL(config.redirectUri).pathname);
+            }
+            return client.getUserInfo(tokens);
+        },
+        async getUserInfo() {
+            if (!tokens)
+                throw new Error('Sign in first.');
+            return client.getUserInfo(tokens);
+        },
+        async logout() {
+            try {
+                return await client.logout(tokens);
+            }
+            finally {
+                tokens = undefined;
+            }
+        },
+        async revoke() {
+            try {
+                if (tokens)
+                    await client.revoke(tokens.access_token);
+            }
+            finally {
+                tokens = undefined;
+            }
+        },
+    };
+}
+export function createSignInButton(options) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'seleimend-signin-button';
+    button.textContent = options.label ?? 'Sign in with a Seleimend account';
+    button.addEventListener('click', async () => {
+        button.disabled = true;
+        try {
+            await options.onSignIn();
+        }
+        catch (error) {
+            options.onError?.(error);
+        }
+        finally {
+            button.disabled = false;
+        }
+    });
+    return button;
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import * as oidc from 'openid-client';
+export interface ClientConfig {
+    issuer?: string;
+    clientId: string;
+    redirectUri: string;
+    postLogoutRedirectUri?: string;
+    scopes?: string[];
+    /** Explicit opt-in, only for loopback/localhost URLs. */
+    allowInsecureLocalhost?: boolean;
+}
+export interface Transaction {
+    verifier: string;
+    nonce: string;
+    expiresAt: number;
+}
+/** Each store belongs to one browser session. take must consume atomically. */
+export interface TransactionStore {
+    put(state: string, transaction: Transaction): Promise<void>;
+    take(state: string): Promise<Transaction | undefined>;
+}
+export type TokenSet = Awaited<ReturnType<typeof oidc.authorizationCodeGrant>>;
+export type UserInfo = Awaited<ReturnType<typeof oidc.fetchUserInfo>>;
+export declare function createClient(config: ClientConfig, store: TransactionStore, clientSecret?: string): Promise<{
+    beginSignIn: () => Promise<URL>;
+    beginSignUp: () => Promise<URL>;
+    handleCallback: (value: URL | string) => Promise<TokenSet>;
+    getUserInfo: (tokens: TokenSet) => Promise<UserInfo>;
+    refresh: (tokens: TokenSet) => Promise<TokenSet>;
+    revoke: (token: string) => Promise<void>;
+    logout: (tokens?: TokenSet) => Promise<URL>;
+}>;

package/dist/index.js

@@ -0,0 +1,76 @@
+import * as oidc from 'openid-client';
+function safeUrl(value, local) {
+    const url = new URL(value);
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.hostname.endsWith('.localhost');
+    if (url.username || url.password || url.hash || (url.protocol !== 'https:' && !(local && loopback && url.protocol === 'http:'))) {
+        throw new Error('Use HTTPS URLs, or explicitly enable localhost HTTP for development.');
+    }
+    return url;
+}
+export async function createClient(config, store, clientSecret) {
+    const local = config.allowInsecureLocalhost === true;
+    const issuer = safeUrl(config.issuer ?? 'https://signin.seleimend.com', local);
+    const callback = safeUrl(config.redirectUri, local);
+    if (config.postLogoutRedirectUri)
+        safeUrl(config.postLogoutRedirectUri, local);
+    const scopes = config.scopes ?? ['openid', 'profile', 'email'];
+    if (!scopes.includes('openid'))
+        throw new Error('The openid scope is required.');
+    if (!clientSecret && scopes.includes('offline_access'))
+        throw new Error('Browser clients cannot request offline access.');
+    const configuration = await oidc.discovery(issuer, config.clientId, {}, clientSecret ? oidc.ClientSecretBasic(clientSecret) : oidc.None(), local && issuer.protocol === 'http:' ? { execute: [oidc.allowInsecureRequests] } : undefined);
+    oidc.enableNonRepudiationChecks(configuration);
+    async function begin(intent = 'signin') {
+        const state = oidc.randomState();
+        const nonce = oidc.randomNonce();
+        const verifier = oidc.randomPKCECodeVerifier();
+        await store.put(state, { verifier, nonce, expiresAt: Date.now() + 10 * 60_000 });
+        return oidc.buildAuthorizationUrl(configuration, {
+            redirect_uri: callback.href, scope: scopes.join(' '), response_type: 'code',
+            state, nonce, code_challenge: await oidc.calculatePKCECodeChallenge(verifier),
+            code_challenge_method: 'S256', ...(intent === 'signup' ? { prompt: 'create' } : {}),
+        });
+    }
+    async function handleCallback(value) {
+        const url = new URL(value);
+        if (url.origin !== callback.origin || url.pathname !== callback.pathname)
+            throw new Error('Unexpected callback URL.');
+        const states = url.searchParams.getAll('state');
+        if (states.length !== 1 || !states[0])
+            throw new Error('Missing or ambiguous callback state.');
+        const transaction = await store.take(states[0]);
+        if (!transaction || transaction.expiresAt <= Date.now())
+            throw new Error('Sign-in expired or already completed.');
+        return oidc.authorizationCodeGrant(configuration, url, {
+            expectedState: states[0], expectedNonce: transaction.nonce,
+            pkceCodeVerifier: transaction.verifier, idTokenExpected: true,
+        });
+    }
+    return {
+        beginSignIn: () => begin('signin'),
+        beginSignUp: () => begin('signup'),
+        handleCallback,
+        getUserInfo: (tokens) => {
+            const subject = tokens.claims()?.sub;
+            if (!subject)
+                throw new Error('An authenticated subject is required.');
+            return oidc.fetchUserInfo(configuration, tokens.access_token, subject);
+        },
+        refresh: async (tokens) => {
+            if (!clientSecret || !tokens.refresh_token)
+                throw new Error('A server refresh token is required.');
+            return oidc.refreshTokenGrant(configuration, tokens.refresh_token);
+        },
+        revoke: (token) => oidc.tokenRevocation(configuration, token),
+        logout: async (tokens) => {
+            if (tokens)
+                await oidc.tokenRevocation(configuration, tokens.refresh_token ?? tokens.access_token);
+            return oidc.buildEndSessionUrl(configuration, {
+                client_id: config.clientId,
+                // Revocation may remove the provider's ID-token record. Client ID plus an
+                // exact registered return URL starts the provider's explicit confirmation.
+                ...(config.postLogoutRedirectUri ? { post_logout_redirect_uri: config.postLogoutRedirectUri } : {}),
+            });
+        },
+    };
+}

package/dist/node.d.ts

@@ -0,0 +1,13 @@
+import { type ClientConfig, type TransactionStore } from './index.js';
+export type { ClientConfig, TransactionStore, Transaction, TokenSet, UserInfo } from './index.js';
+export declare function createNodeClient(config: ClientConfig & {
+    clientSecret: string;
+}, store: TransactionStore): Promise<{
+    beginSignIn: () => Promise<URL>;
+    beginSignUp: () => Promise<URL>;
+    handleCallback: (value: URL | string) => Promise<import("./index.js").TokenSet>;
+    getUserInfo: (tokens: import("./index.js").TokenSet) => Promise<import("./index.js").UserInfo>;
+    refresh: (tokens: import("./index.js").TokenSet) => Promise<import("./index.js").TokenSet>;
+    revoke: (token: string) => Promise<void>;
+    logout: (tokens?: import("./index.js").TokenSet) => Promise<URL>;
+}>;

package/dist/node.js

@@ -0,0 +1,6 @@
+import { createClient } from './index.js';
+export function createNodeClient(config, store) {
+    if (!config.clientSecret)
+        throw new Error('A server client secret is required.');
+    return createClient(config, store, config.clientSecret);
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@selei/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Sign in and sign up with a Seleimend account using OpenID Connect.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "dependencies": {
+    "openid-client": "6.8.8"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vite": "8.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/victorseleimend293/account-manager.git",
+    "directory": "packages/seleimend-auth"
+  },
+  "homepage": "https://github.com/victorseleimend293/account-manager/tree/main/packages/seleimend-auth",
+  "scripts": {
+    "build": "tsc",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "example:node": "pnpm build && node examples/node.mjs",
+    "example:browser": "pnpm build && vite examples/browser --host 127.0.0.1 --port 3001"
+  }
 }