typeferry 0.6.0

package/README.md

@@ -0,0 +1,88 @@
+# typeferry
+
+The TypeScript implementation of TypeFerry provides the reference Node.js server, browser/Node client, React hooks, authentication helpers, EJSON, and an optional MongoDB extension.
+
+Install the public TypeScript package with `npm install typeferry`. Repository contributors can use the local [`template/`](../template/) workflow described in the [quickstart](../docs/getting-started.md).
+
+## Runtime requirements
+
+- Node.js `24.19.0`
+- npm `11.17.0`
+- Node.js for the server runtime
+- A browser or WebSocket-capable JavaScript runtime for clients
+
+## Public entry points
+
+| Import | Purpose |
+|---|---|
+| `typeferry/server` | Server, methods, events, channels, and runtime types |
+| `typeferry/server/decorators` | Namespace and method decorators |
+| `typeferry/server/transports` | Node HTTP, WebSocket, and Redis transports |
+| `typeferry/client` | Core client and connection APIs |
+| `typeferry/react` | React provider and hooks |
+| `typeferry/auth` | Shared auth, token, session, and cookie helpers |
+| `typeferry/auth/server/oauth` | Server OAuth providers |
+| `typeferry/auth/client/oauth` | Client OAuth helpers |
+| `typeferry/ejson` | Extended JSON namespace |
+| `typeferry/mongodb` | Native-driver MongoDB extension |
+| `typeferry/mongodb/decorators` | MongoDB collection decorators |
+
+Applications should import these compiled package exports. Do not alias or import TypeFerry source files from application code.
+
+## Define and serve a typed method
+
+```ts
+import { Server } from 'typeferry/server'
+import type { ClientNode } from 'typeferry/server'
+import {
+  type InferNamespace,
+  Method,
+  Namespace,
+  registerNamespace,
+  Schema,
+} from 'typeferry/server/decorators'
+import { z } from 'zod'
+
+const greetingSchema = z.object({
+  name: z.string().trim().min(1),
+})
+
+type GreetingInput = z.infer<typeof greetingSchema>
+
+@Namespace('greeting')
+export class GreetingMethods {
+  @Method()
+  @Schema(greetingSchema)
+  async hello(
+    _client: ClientNode,
+    input: GreetingInput,
+  ): Promise<string> {
+    return `Hello, ${input.name}!`
+  }
+}
+
+export type GreetingApi = InferNamespace<GreetingMethods, 'greeting'>
+
+const server = new Server({ host: '127.0.0.1', port: 8002 })
+registerNamespace(GreetingMethods)
+await server.isReady()
+```
+
+Clients can call the method as `client.m.greeting.hello({ name: 'Ada' })` when parameterized with `GreetingApi`. The decorators turn the class method into an HTTP and WebSocket RPC endpoint, while `@Schema()` validates network input at runtime. The `Server` constructor installs both transports; call `server.close()` during graceful shutdown.
+
+## Development
+
+Run commands from `typeferry-ts/`:
+
+```sh
+npm ci
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## Guides
+
+Start at the [documentation home](../docs/README.md) or jump to [server and RPC](../docs/typescript/server-rpc.md), [client](../docs/typescript/client.md), [React](../docs/typescript/react.md), [authentication](../docs/typescript/authentication.md), [events and channels](../docs/typescript/events-and-channels.md), [MongoDB](../docs/typescript/mongodb.md), [EJSON](../docs/typescript/ejson.md), or [deployment](../docs/typescript/deployment.md).

package/dist/auth/client/cross-tab-sync.d.ts

@@ -0,0 +1,21 @@
+import type { Client } from '../../client/index.js';
+import type { CrossTabSyncConfig } from '../types.js';
+/**
+ * Set up cross-tab token synchronization using BroadcastChannel.
+ * When one tab refreshes the token, all other tabs receive the update.
+ *
+ * @param client - TypeFerry client instance
+ * @param config - Sync configuration
+ * @returns Cleanup function
+ */
+export declare function setupCrossTabSync(client: Client, config: CrossTabSyncConfig): () => void;
+/**
+ * Broadcast a token refresh to all other tabs.
+ * Call this after successfully refreshing the token.
+ *
+ * @param channelName - BroadcastChannel name
+ * @param token - New access token
+ * @param exp - Token expiration (Unix timestamp in seconds)
+ * @param iat - Token issued-at time (Unix timestamp in seconds) for clock-skew compensation
+ */
+export declare function broadcastTokenRefresh(channelName: string, token: string, exp: number, iat?: number): void;

package/dist/auth/client/cross-tab-sync.js

@@ -0,0 +1,56 @@
+const TOKEN_REFRESHED = 'TOKEN_REFRESHED';
+/**
+ * Set up cross-tab token synchronization using BroadcastChannel.
+ * When one tab refreshes the token, all other tabs receive the update.
+ *
+ * @param client - TypeFerry client instance
+ * @param config - Sync configuration
+ * @returns Cleanup function
+ */
+export function setupCrossTabSync(client, config) {
+    // BroadcastChannel not available in SSR or older browsers
+    if (typeof BroadcastChannel === 'undefined') {
+        return () => { };
+    }
+    const channel = new BroadcastChannel(config.channelName);
+    const handleMessage = (event) => {
+        // Validate message structure before trusting data from other tabs
+        if (event.data?.type === TOKEN_REFRESHED &&
+            typeof event.data.token === 'string' &&
+            typeof event.data.exp === 'number') {
+            const { token, exp, iat } = event.data;
+            const context = { token, exp };
+            if (typeof iat === 'number') {
+                context.iat = iat;
+                context._tokenReceivedAt = Date.now();
+            }
+            client.updateContext(context);
+            if (config.tokenRefreshedEvent) {
+                client.emit(config.tokenRefreshedEvent, { token, exp });
+            }
+        }
+    };
+    channel.addEventListener('message', handleMessage);
+    return () => {
+        channel.removeEventListener('message', handleMessage);
+        channel.close();
+    };
+}
+/**
+ * Broadcast a token refresh to all other tabs.
+ * Call this after successfully refreshing the token.
+ *
+ * @param channelName - BroadcastChannel name
+ * @param token - New access token
+ * @param exp - Token expiration (Unix timestamp in seconds)
+ * @param iat - Token issued-at time (Unix timestamp in seconds) for clock-skew compensation
+ */
+export function broadcastTokenRefresh(channelName, token, exp, iat) {
+    if (typeof BroadcastChannel === 'undefined') {
+        return;
+    }
+    const channel = new BroadcastChannel(channelName);
+    channel.postMessage({ type: TOKEN_REFRESHED, token, exp, iat });
+    channel.close();
+}
+//# sourceMappingURL=cross-tab-sync.js.map

package/dist/auth/client/cross-tab-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-tab-sync.js","sourceRoot":"","sources":["../../../src/auth/client/cross-tab-sync.ts"],"names":[],"mappings":"AAGA,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAA0B;IAE1B,0DAA0D;IAC1D,IAAI,OAAO,gBAAgB,KAAK,WAAW,EAAE,CAAC;QAC5C,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IAExD,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAE,EAAE;QAC5C,kEAAkE;QAClE,IACE,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,eAAe;YACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ;YACpC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,QAAQ,EAClC,CAAC;YACD,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,CAAA;YAEtC,MAAM,OAAO,GAA4B,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;YACvD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,CAAC,GAAG,GAAG,GAAG,CAAA;gBACjB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACvC,CAAC;YAED,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAE7B,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;gBAC/B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;YACzD,CAAC;QACH,CAAC;IACH,CAAC,CAAA;IAED,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;IAElD,OAAO,GAAG,EAAE;QACV,OAAO,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;QACrD,OAAO,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmB,EACnB,KAAa,EACb,GAAW,EACX,GAAY;IAEZ,IAAI,OAAO,gBAAgB,KAAK,WAAW,EAAE,CAAC;QAC5C,OAAM;IACR,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,WAAW,CAAC,CAAA;IACjD,OAAO,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAA;IAC/D,OAAO,CAAC,KAAK,EAAE,CAAA;AACjB,CAAC"}

package/dist/auth/client/index.d.ts

@@ -0,0 +1,2 @@
+export { broadcastTokenRefresh, setupCrossTabSync } from './cross-tab-sync.js';
+export { refreshAccessToken, setupTokenRefreshOnExpiry } from './token-refresh.js';

package/dist/auth/client/index.js

@@ -0,0 +1,3 @@
+export { broadcastTokenRefresh, setupCrossTabSync } from './cross-tab-sync.js';
+export { refreshAccessToken, setupTokenRefreshOnExpiry } from './token-refresh.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/auth/client/oauth/google-provider.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+export interface GoogleOAuthProviderProps {
+    clientId: string;
+    children: ReactNode;
+}
+/**
+ * Wraps the application tree with Google OAuth context.
+ * Thin re-export of `@react-oauth/google`'s provider for
+ * consistency with the typeferry auth module surface.
+ */
+export declare function GoogleOAuthProvider({ clientId, children, }: GoogleOAuthProviderProps): ReactNode;

package/dist/auth/client/oauth/google-provider.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { GoogleOAuthProvider as ReactGoogleOAuthProvider } from '@react-oauth/google';
+/**
+ * Wraps the application tree with Google OAuth context.
+ * Thin re-export of `@react-oauth/google`'s provider for
+ * consistency with the typeferry auth module surface.
+ */
+export function GoogleOAuthProvider({ clientId, children, }) {
+    return (_jsx(ReactGoogleOAuthProvider, { clientId: clientId, children: children }));
+}
+//# sourceMappingURL=google-provider.js.map

package/dist/auth/client/oauth/google-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-provider.js","sourceRoot":"","sources":["../../../../src/auth/client/oauth/google-provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,mBAAmB,IAAI,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAQrF;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,QAAQ,EACR,QAAQ,GACiB;IACzB,OAAO,CACL,KAAC,wBAAwB,IAAC,QAAQ,EAAE,QAAQ,YACzC,QAAQ,GACgB,CAC5B,CAAA;AACH,CAAC"}

package/dist/auth/client/oauth/index.d.ts

@@ -0,0 +1,4 @@
+export type { GoogleOAuthProviderProps } from './google-provider.js';
+export { GoogleOAuthProvider } from './google-provider.js';
+export type { UseGoogleLoginOptions } from './use-google-login.js';
+export { useTypeFerryGoogleLogin } from './use-google-login.js';

package/dist/auth/client/oauth/index.js

@@ -0,0 +1,3 @@
+export { GoogleOAuthProvider } from './google-provider.js';
+export { useTypeFerryGoogleLogin } from './use-google-login.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/client/oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/auth/client/oauth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAEvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/auth/client/oauth/use-google-login.d.ts

@@ -0,0 +1,39 @@
+export interface UseGoogleLoginOptions {
+    /**
+     * Server method to call with the authorization code.
+     * @default 'auth.google'
+     */
+    method?: string;
+    /**
+     * Async hook that runs after Google returns the auth code but
+     * before the server call. Return additional params to merge
+     * with `{ code }`, or return `false` to abort the flow.
+     *
+     * Useful for reCAPTCHA, analytics, or pre-flight checks.
+     */
+    beforeServerCall?: (code: string) => Promise<Record<string, unknown> | false>;
+    /** Called after successful authentication and context update. */
+    onSuccess?: () => void;
+    /** Called when any step of the flow fails. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Hook that returns a trigger function for the Google OAuth popup flow.
+ *
+ * On user consent it exchanges the authorization code with the server,
+ * updates the typeferry client context, and reconnects the socket with
+ * the new credentials.
+ *
+ * @example
+ * ```tsx
+ * const login = useTypeFerryGoogleLogin({
+ *   beforeServerCall: async () => {
+ *     const token = await executeRecaptcha('google_signup')
+ *     return token ? { recaptchaToken: token } : false
+ *   },
+ * })
+ *
+ * <button onClick={() => login()}>Sign in with Google</button>
+ * ```
+ */
+export declare function useTypeFerryGoogleLogin(options?: UseGoogleLoginOptions): () => void;

package/dist/auth/client/oauth/use-google-login.js

@@ -0,0 +1,55 @@
+import { useGoogleLogin } from '@react-oauth/google';
+import { useCallback } from 'react';
+import { useClient } from '../../../react/hooks/use-client.js';
+/**
+ * Hook that returns a trigger function for the Google OAuth popup flow.
+ *
+ * On user consent it exchanges the authorization code with the server,
+ * updates the typeferry client context, and reconnects the socket with
+ * the new credentials.
+ *
+ * @example
+ * ```tsx
+ * const login = useTypeFerryGoogleLogin({
+ *   beforeServerCall: async () => {
+ *     const token = await executeRecaptcha('google_signup')
+ *     return token ? { recaptchaToken: token } : false
+ *   },
+ * })
+ *
+ * <button onClick={() => login()}>Sign in with Google</button>
+ * ```
+ */
+export function useTypeFerryGoogleLogin(options = {}) {
+    const { method = 'auth.google', beforeServerCall, onSuccess, onError, } = options;
+    const client = useClient();
+    const login = useGoogleLogin({
+        onSuccess: async ({ code }) => {
+            try {
+                let extraParams = {};
+                if (beforeServerCall) {
+                    const result = await beforeServerCall(code);
+                    if (result === false)
+                        return;
+                    extraParams = result;
+                }
+                const { token, exp, iat } = await client.call(method, { code, ...extraParams }, { http: true });
+                await client.setContextAndReInit({
+                    isGoogleAuth: true,
+                    token,
+                    exp,
+                    iat,
+                    _tokenReceivedAt: Date.now(),
+                });
+                onSuccess?.();
+            }
+            catch (error) {
+                onError?.(error);
+            }
+        },
+        flow: 'auth-code',
+        select_account: true,
+    });
+    return useCallback(() => login(), [login]);
+}
+//# sourceMappingURL=use-google-login.js.map

package/dist/auth/client/oauth/use-google-login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-google-login.js","sourceRoot":"","sources":["../../../../src/auth/client/oauth/use-google-login.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAEnC,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAA;AA2B3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAiC,EAAE;IAEnC,MAAM,EACJ,MAAM,GAAG,aAAa,EACtB,gBAAgB,EAChB,SAAS,EACT,OAAO,GACR,GAAG,OAAO,CAAA;IAEX,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAE1B,MAAM,KAAK,GAAG,cAAc,CAAC;QAC3B,SAAS,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;YAC5B,IAAI,CAAC;gBACH,IAAI,WAAW,GAA4B,EAAE,CAAA;gBAE7C,IAAI,gBAAgB,EAAE,CAAC;oBACrB,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAA;oBAC3C,IAAI,MAAM,KAAK,KAAK;wBAAE,OAAM;oBAC5B,WAAW,GAAG,MAAM,CAAA;gBACtB,CAAC;gBAED,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAC3C,MAAM,EACN,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,EACxB,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAA;gBAED,MAAM,MAAM,CAAC,mBAAmB,CAAC;oBAC/B,YAAY,EAAE,IAAI;oBAClB,KAAK;oBACL,GAAG;oBACH,GAAG;oBACH,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE;iBAC7B,CAAC,CAAA;gBAEF,SAAS,EAAE,EAAE,CAAA;YACf,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;YAClB,CAAC;QACH,CAAC;QACD,IAAI,EAAE,WAAW;QACjB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAA;IAEF,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;AAC5C,CAAC"}

package/dist/auth/client/token-refresh.d.ts

@@ -0,0 +1,21 @@
+import type { Client } from '../../client/index.js';
+import type { TokenRefreshConfig } from '../types.js';
+export type { TokenRefreshConfig };
+/**
+ * Refresh the access token using the configured refresh method.
+ * Handles concurrent refresh requests by queueing them per-client.
+ *
+ * @param client - TypeFerry client instance
+ * @param config - Optional configuration overrides
+ * @returns New access token, or null if refresh failed
+ */
+export declare function refreshAccessToken(client: Client, config?: Partial<TokenRefreshConfig>): Promise<string | null>;
+/**
+ * Set up automatic token refresh before expiry.
+ * Returns a cleanup function to stop the refresh timer.
+ *
+ * @param client - TypeFerry client instance
+ * @param config - Optional configuration overrides
+ * @returns Cleanup function
+ */
+export declare function setupTokenRefreshOnExpiry(client: Client, config?: Partial<TokenRefreshConfig>): () => void;

package/dist/auth/client/token-refresh.js

@@ -0,0 +1,212 @@
+import { LogLevel } from '../../client/logger.js';
+import { broadcastTokenRefresh, setupCrossTabSync } from './cross-tab-sync.js';
+const defaultConfig = {
+    refreshMethod: 'auth.refresh',
+    refreshBeforeExpirySec: 60,
+    broadcastChannelName: 'typeferry-token-sync',
+};
+/** Delay before retrying a failed refresh on transient (network) errors. */
+const RETRY_DELAY_MS = 5_000;
+const refreshStateMap = new WeakMap();
+function getRefreshState(client) {
+    let state = refreshStateMap.get(client);
+    if (!state) {
+        state = { isRefreshing: false, failedQueue: [] };
+        refreshStateMap.set(client, state);
+    }
+    return state;
+}
+function processQueue(state, error, token) {
+    state.failedQueue.forEach(({ resolve, reject }) => {
+        if (error) {
+            reject(error);
+        }
+        else {
+            resolve(token);
+        }
+    });
+    state.failedQueue = [];
+}
+/**
+ * Check if error is a terminal auth failure vs a transient network error.
+ * Terminal failures clear the context and redirect to login. Transient
+ * failures schedule a retry.
+ */
+function isAuthFailureError(err) {
+    if (err.status === 401 || err.status === 403)
+        return true;
+    if (err.code === 'AUTHENTICATION_FAILED')
+        return true;
+    const msg = err.message;
+    if (msg === 'Token refresh failed')
+        return true;
+    if (msg.includes('missingRefreshToken'))
+        return true;
+    if (msg.includes('invalidOrExpiredRefreshToken'))
+        return true;
+    return false;
+}
+/**
+ * Refresh the access token using the configured refresh method.
+ * Handles concurrent refresh requests by queueing them per-client.
+ *
+ * @param client - TypeFerry client instance
+ * @param config - Optional configuration overrides
+ * @returns New access token, or null if refresh failed
+ */
+export async function refreshAccessToken(client, config = {}) {
+    const opts = { ...defaultConfig, ...config };
+    const state = getRefreshState(client);
+    // Queue concurrent requests for the same client
+    if (state.isRefreshing) {
+        return new Promise((resolve, reject) => {
+            state.failedQueue.push({ resolve, reject });
+        });
+    }
+    state.isRefreshing = true;
+    try {
+        /**
+         * Refresh token is sent exclusively via the HttpOnly cookie
+         * (credentials: 'include' on fetch). No body param needed — the
+         * server reads from the cookie header directly.
+         */
+        client.logger.auth(LogLevel.INFO, 'Attempting token refresh', {
+            method: opts.refreshMethod,
+            hasToken: !!client.context.token,
+            exp: client.context.exp,
+        });
+        const result = await client.call(opts.refreshMethod, {}, {
+            ignoreInit: true,
+            http: true,
+        });
+        if (!result) {
+            throw new Error('Token refresh failed');
+        }
+        client.logger.auth(LogLevel.INFO, 'Token refresh succeeded', {
+            newExp: result.exp,
+        });
+        client.updateContext({
+            token: result.accessToken,
+            exp: result.exp,
+            iat: result.iat,
+            _tokenReceivedAt: Date.now(),
+        });
+        if (opts.broadcastChannelName) {
+            broadcastTokenRefresh(opts.broadcastChannelName, result.accessToken, result.exp, result.iat);
+        }
+        processQueue(state, null, result.accessToken);
+        return result.accessToken;
+    }
+    catch (error) {
+        const err = error;
+        const isAuthFailure = isAuthFailureError(err);
+        client.logger.auth(isAuthFailure ? LogLevel.WARN : LogLevel.ERROR, 'Token refresh failed', {
+            isAuthFailure,
+            status: err.status,
+            code: err.code,
+            hasToken: !!client.context.token,
+        }, err);
+        if (isAuthFailure)
+            client.clearContext();
+        processQueue(state, err, null);
+        throw error;
+    }
+    finally {
+        state.isRefreshing = false;
+    }
+}
+/**
+ * Set up automatic token refresh before expiry.
+ * Returns a cleanup function to stop the refresh timer.
+ *
+ * @param client - TypeFerry client instance
+ * @param config - Optional configuration overrides
+ * @returns Cleanup function
+ */
+export function setupTokenRefreshOnExpiry(client, config = {}) {
+    const opts = { ...defaultConfig, ...config };
+    let refreshTimeout = null;
+    const cleanupCrossTab = opts.broadcastChannelName
+        ? setupCrossTabSync(client, { channelName: opts.broadcastChannelName })
+        : () => { };
+    const scheduleRefresh = () => {
+        if (refreshTimeout) {
+            clearTimeout(refreshTimeout);
+            refreshTimeout = null;
+        }
+        const { exp, iat, _tokenReceivedAt } = client.context;
+        if (!exp)
+            return;
+        /**
+         * Clock-skew-safe scheduling: when server-issued `iat` and local
+         * `_tokenReceivedAt` are available, compute remaining lifetime using
+         * only server-side TTL and client-side elapsed time — both immune
+         * to absolute clock differences between client and server.
+         *
+         * Falls back to the classic `exp - now` calculation for tokens
+         * issued before the iat migration.
+         */
+        let timeUntilRefresh;
+        if (iat && _tokenReceivedAt) {
+            const tokenTtlMs = (exp - iat) * 1000;
+            const elapsedMs = Date.now() - _tokenReceivedAt;
+            timeUntilRefresh =
+                tokenTtlMs - elapsedMs - opts.refreshBeforeExpirySec * 1000;
+        }
+        else {
+            const now = Math.floor(Date.now() / 1000);
+            timeUntilRefresh = (exp - now - opts.refreshBeforeExpirySec) * 1000;
+        }
+        /**
+         * Attempt a refresh and retry once on transient (non-auth) failures.
+         *
+         * Auth failures (401/403) are terminal — the session is invalid and
+         * clearContext already ran inside refreshAccessToken. Network errors
+         * are transient, so we schedule a single retry after a short delay
+         * to avoid the token expiring silently.
+         */
+        const attemptRefresh = (meta) => {
+            refreshAccessToken(client, opts).catch(error => {
+                const err = error;
+                client.logger.auth(LogLevel.ERROR, 'Scheduled token refresh failed', meta, err);
+                if (!isAuthFailureError(err)) {
+                    refreshTimeout = setTimeout(scheduleRefresh, RETRY_DELAY_MS);
+                }
+            });
+        };
+        // If already expired or about to expire, refresh immediately
+        if (timeUntilRefresh <= 0) {
+            /**
+             * If a refresh is already in progress (e.g. this handler was called
+             * from the CONTEXT_CHANGED event emitted inside refreshAccessToken),
+             * defer rescheduling instead of queueing a redundant refresh call.
+             * The queued path would resolve but never reschedule, leaving the
+             * next automatic refresh unscheduled.
+             */
+            const state = getRefreshState(client);
+            if (state.isRefreshing) {
+                refreshTimeout = setTimeout(scheduleRefresh, 1000);
+                return;
+            }
+            attemptRefresh({ immediate: true });
+            return;
+        }
+        refreshTimeout = setTimeout(() => {
+            attemptRefresh({ scheduledDelayMs: timeUntilRefresh });
+        }, timeUntilRefresh);
+    };
+    // Schedule initial refresh
+    scheduleRefresh();
+    // Reschedule when context changes (e.g., after refresh)
+    const handleContextChange = () => scheduleRefresh();
+    client.on('context:changed', handleContextChange);
+    // Cleanup function
+    return () => {
+        if (refreshTimeout) {
+            clearTimeout(refreshTimeout);
+        }
+        client.off('context:changed', handleContextChange);
+        cleanupCrossTab();
+    };
+}
+//# sourceMappingURL=token-refresh.js.map

package/dist/auth/client/token-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-refresh.js","sourceRoot":"","sources":["../../../src/auth/client/token-refresh.ts"],"names":[],"mappings":"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"}

package/dist/auth/index.d.ts

@@ -0,0 +1,7 @@
+export type { AccessTokenPayload, AuthConfig, AuthContext, CookieOptions, CrossTabSyncConfig, DeviceInfo, Session, SessionManager, TokenPair, TokenRefreshConfig, } from './types.js';
+export { clearRefreshTokenCookie, getRefreshTokenFromRequest, setRefreshTokenCookie, } from './server/cookie-utils.js';
+export { parseDeviceInfo } from './server/device-info.js';
+export { decodeToken, signAccessToken, verifyAccessToken, } from './server/jwt-utils.js';
+export { InMemorySessionManager } from './server/session-manager.js';
+export { broadcastTokenRefresh, setupCrossTabSync, } from './client/cross-tab-sync.js';
+export { refreshAccessToken, setupTokenRefreshOnExpiry, } from './client/token-refresh.js';

package/dist/auth/index.js

@@ -0,0 +1,9 @@
+// Server utilities
+export { clearRefreshTokenCookie, getRefreshTokenFromRequest, setRefreshTokenCookie, } from './server/cookie-utils.js';
+export { parseDeviceInfo } from './server/device-info.js';
+export { decodeToken, signAccessToken, verifyAccessToken, } from './server/jwt-utils.js';
+export { InMemorySessionManager } from './server/session-manager.js';
+// Client utilities
+export { broadcastTokenRefresh, setupCrossTabSync, } from './client/cross-tab-sync.js';
+export { refreshAccessToken, setupTokenRefreshOnExpiry, } from './client/token-refresh.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAcA,mBAAmB;AACnB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EACL,WAAW,EACX,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAEjE,mBAAmB;AACnB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAA"}

package/dist/auth/server/cookie-utils.d.ts

@@ -0,0 +1,42 @@
+import type { CookieOptions } from '../types.js';
+/**
+ * Response-like object that can set headers.
+ */
+interface ResponseLike {
+    setHeader: (name: string, value: string) => void;
+}
+/**
+ * Request-like object that may contain cookies.
+ */
+interface RequestLike {
+    cookies?: Record<string, string>;
+    headers?: {
+        cookie?: string;
+    };
+}
+/**
+ * Set an HttpOnly refresh token cookie.
+ *
+ * @param res - Response object with setHeader method
+ * @param token - Refresh token value
+ * @param options - Cookie configuration
+ */
+export declare function setRefreshTokenCookie(res: ResponseLike, token: string, options: CookieOptions): void;
+/**
+ * Clear a refresh token cookie by setting it to expire immediately.
+ *
+ * @param res - Response object with setHeader method
+ * @param options - Cookie configuration (name, secure, path)
+ */
+export declare function clearRefreshTokenCookie(res: ResponseLike, options: Pick<CookieOptions, 'name' | 'secure' | 'sameSite' | 'path'>): void;
+/**
+ * Extract refresh token from a request.
+ * Checks parsed cookies first, then falls back to manual cookie header parsing.
+ * Automatically URL-decodes the cookie value.
+ *
+ * @param req - Request object with optional cookies or cookie header
+ * @param cookieName - Name of the cookie to extract
+ * @returns Cookie value if found, undefined otherwise
+ */
+export declare function getRefreshTokenFromRequest(req: RequestLike, cookieName: string): string | undefined;
+export {};