@zakkster/lite-auth 1.0.0

package/Auth.d.ts

@@ -0,0 +1,191 @@
+// Type definitions for @zakkster/lite-auth
+// Project: https://www.npmjs.com/package/@zakkster/lite-auth
+// Definitions by: Zahary Shinikchiev
+
+/**
+ * A read-only reactive value. Call it to read (tracked inside a computation),
+ * `.peek()` to read without tracking, `.subscribe()` to observe changes. This
+ * is the lite-signal ReadonlySignal shape, restated here so the type surface is
+ * self-contained.
+ */
+export interface ReadonlySignal<T> {
+    (): T;
+    peek(): T;
+    subscribe(run: (value: T) => void): () => void;
+}
+
+export type AuthErrorCode =
+    | "invalid_credentials"
+    | "network"
+    | "refresh_failed"
+    | "no_refresh_token"
+    | "expired"
+    | "storage"
+    | "aborted"
+    | "misconfigured";
+
+/**
+ * Typed error thrown by the awaited actions (`signIn`, `refresh`) and surfaced
+ * reactively on `error` for ambient failures.
+ */
+export class AuthError extends Error {
+    name: "AuthError";
+    code: AuthErrorCode;
+    cause?: unknown;
+    constructor(code: AuthErrorCode, message: string, opts?: { cause?: unknown });
+}
+
+export type AuthStatus = "idle" | "authenticating" | "refreshing";
+
+/**
+ * The unit of authenticated state. `user` is opaque to lite-auth and surfaced
+ * as-is through the `session` projection.
+ */
+export interface SessionRecord<User = unknown> {
+    user: User;
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch milliseconds. When present, drives expiry checks and refresh scheduling. */
+    expiresAt?: number;
+}
+
+/**
+ * Pluggable authentication backend. Only `signIn` is required; provide
+ * `refresh` to enable token renewal and `signOut` for server-side revocation.
+ */
+export interface AuthAdapter<User = unknown, Credentials = unknown> {
+    signIn(credentials: Credentials, signal: AbortSignal): Promise<SessionRecord<User>>;
+    refresh?(record: SessionRecord<User>, signal: AbortSignal): Promise<SessionRecord<User>>;
+    signOut?(record: SessionRecord<User>): Promise<void> | void;
+}
+
+export interface RefreshConfig {
+    enabled: boolean;
+    /** Seconds before `expiresAt` at which to refresh. Default 60. */
+    threshold?: number;
+}
+
+/** Anything Web-Storage-shaped. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+export type StorageOption = "localStorage" | "sessionStorage" | "memory" | StorageLike;
+
+/**
+ * Minimal registry shape (a subset of the object returned by lite-signal's
+ * `createRegistry`). lite-auth only ever uses `signal`, `computed`, and
+ * `batch`, so any compatible registry works. The optional `dispose` is the
+ * registry-bound node disposer; when present, lite-auth uses it on teardown
+ * to return signal and computed nodes to the right pool.
+ */
+export interface SignalRegistry {
+    signal: <T>(initial: T) => ReadonlySignal<T> & {
+        set(value: T): void;
+        update(fn: (value: T) => T): void;
+    };
+    computed: <T>(fn: () => T) => ReadonlySignal<T>;
+    batch: <T>(fn: () => T) => T;
+    dispose?: (node: unknown) => void;
+}
+
+export interface AuthConfig<User = unknown, Credentials = unknown> {
+    /** The backend that exchanges credentials for a session record. */
+    adapter: AuthAdapter<User, Credentials>;
+    /**
+     * Where to persist the session. Default `"localStorage"`; throws an
+     * AuthError("misconfigured") if Web Storage is unavailable. Use `"memory"`
+     * for SSR, tests, or session-only flows.
+     */
+    storage?: StorageOption;
+    /** Storage key and default cross-tab channel key. Default `"lite-auth.session.v1"`. */
+    storageKey?: string;
+    /** BroadcastChannel name for cross-tab sync. Defaults to `storageKey`. */
+    channelName?: string;
+    /** Enable cross-tab propagation. Requires `@zakkster/lite-channel` to be installed. Default `false`. */
+    crossTab?: boolean;
+    /** Opt-in background token refresh. */
+    refresh?: RefreshConfig;
+    /** Forwarded to lite-channel's `createTabSync`. `persist` is always forced off (lite-auth owns disk). */
+    channelOptions?: Record<string, unknown>;
+    /**
+     * Advanced: run lite-auth's own signals inside a custom lite-signal
+     * registry for isolation. Note that lite-persist's write-back uses the
+     * global signal graph, so a custom registry pairs best with
+     * `storage: "memory"`.
+     */
+    registry?: SignalRegistry;
+    /** Fired when an unauthenticated session becomes authenticated (not on restore). */
+    onSignIn?: (user: User) => void;
+    /** Fired when an authenticated session becomes unauthenticated (local or cross-tab). */
+    onSignOut?: () => void;
+    /** Fired when a session expires and cannot be refreshed. */
+    onSessionExpire?: () => void;
+    /** Fired after a successful token refresh. */
+    onTokenRefresh?: (record: SessionRecord<User>) => void;
+    /** Ambient (non-thrown) failures: background refresh, storage, cross-tab. */
+    onError?: (error: AuthError) => void;
+}
+
+export interface Auth<User = unknown, Credentials = unknown> {
+    /** The current user, or `null` when unauthenticated. */
+    readonly session: ReadonlySignal<User | null>;
+    /** Whether a session is currently active. */
+    readonly isAuthenticated: ReadonlySignal<boolean>;
+    /** The current access token, or `null`. */
+    readonly token: ReadonlySignal<string | null>;
+    /** The current session's expiry in epoch ms, or `null`. */
+    readonly expiresAt: ReadonlySignal<number | null>;
+    /** Coarse activity state for spinners and guards. */
+    readonly status: ReadonlySignal<AuthStatus>;
+    /** The most recent error, cleared on the next successful action. */
+    readonly error: ReadonlySignal<AuthError | null>;
+    /** Resolves once boot hydration, optional channel attach, and any boot-time refresh have settled. */
+    readonly ready: Promise<void>;
+    /** Exchange credentials for a session. Rejects with an AuthError on failure. */
+    signIn(credentials: Credentials): Promise<User>;
+    /** Clear the session locally (optimistic) and best-effort revoke server-side. Never rejects. */
+    signOut(): Promise<void>;
+    /** Force a token refresh now. Rejects with an AuthError on failure. */
+    refresh(): Promise<void>;
+    /** Register a sign-in listener. Returns an idempotent disposer. */
+    onSignIn(fn: (user: User) => void): () => void;
+    /** Register a sign-out listener. Returns an idempotent disposer. */
+    onSignOut(fn: () => void): () => void;
+    /** Register a session-expiry listener. Returns an idempotent disposer. */
+    onSessionExpire(fn: () => void): () => void;
+    /** Register a token-refresh listener. Returns an idempotent disposer. */
+    onTokenRefresh(fn: (record: SessionRecord<User>) => void): () => void;
+    /** Tear down timers, subscriptions, and the channel. Leaves stored data intact. */
+    dispose(): void;
+}
+
+/** Create a reactive authentication controller. */
+export function createAuth<User = unknown, Credentials = unknown>(
+    config: AuthConfig<User, Credentials>,
+): Auth<User, Credentials>;
+
+export interface FetchAdapterOptions<User = unknown> {
+    signInUrl: string;
+    refreshUrl?: string;
+    signOutUrl?: string;
+    /** Static headers, or a getter evaluated per request so rotated tokens stay fresh. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Map a raw JSON response to a SessionRecord. Defaults to reading `{ user, accessToken, refreshToken?, expiresAt? }`. */
+    parseSession?: (json: unknown) => SessionRecord<User>;
+    /** Override the fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+}
+
+/**
+ * A REST adapter over fetch. POSTs JSON to the configured endpoints. When a
+ * response omits `expiresAt`, it is derived from the access token's JWT `exp`.
+ */
+export function fetchAdapter<User = unknown, Credentials = unknown>(
+    opts: FetchAdapterOptions<User>,
+): AuthAdapter<User, Credentials>;
+
+/** Decode a JWT's `exp` claim and return it as epoch milliseconds, or `undefined`. */
+export function decodeJwtExp(token: string): number | undefined;

package/Auth.js

@@ -0,0 +1,720 @@
+/**
+ * @zakkster/lite-auth
+ *
+ * Session-as-a-signal authentication for the lite-* ecosystem.
+ *
+ * The whole of auth state lives in one reactive value. Everything an
+ * application binds to is a projection of that value:
+ *
+ *     signal<SessionRecord | undefined>  (private source of truth)
+ *         |- session         computed -> User | null
+ *         |- isAuthenticated computed -> boolean
+ *         |- token           computed -> string | null
+ *         |- expiresAt       computed -> number | null
+ *
+ * Persistence is delegated to @zakkster/lite-persist (boot hydration plus
+ * debounced write-through). Cross-tab propagation is delegated to
+ * @zakkster/lite-channel (BroadcastChannel, presence, leader election).
+ * The two are kept on separate axes: lite-persist owns disk with its own
+ * cross-tab path disabled (syncTabs:false); lite-channel owns the wire.
+ *
+ * Token refresh is timer-based and, under crossTab, performed only by the
+ * leader tab. Refresh tokens are frequently single-use, so electing one
+ * refresher avoids a rotation race across tabs; followers receive the new
+ * record over the channel.
+ *
+ * MIT License. Copyright (c) Zahary Shinikchiev.
+ */
+
+import {
+    signal as defaultSignal,
+    computed as defaultComputed,
+    batch as defaultBatch,
+    dispose as disposeReactive,
+} from "@zakkster/lite-signal";
+import {persist} from "@zakkster/lite-persist";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed error thrown by awaited imperative actions (signIn / refresh) and
+ * surfaced reactively on the `error` signal for ambient failures.
+ *
+ * The `code` discriminant mirrors the named-error pattern used elsewhere in
+ * the ecosystem (see lite-signal's CapacityError).
+ */
+export class AuthError extends Error {
+    /**
+     * @param {("invalid_credentials"|"network"|"refresh_failed"|"no_refresh_token"|"expired"|"storage"|"aborted"|"misconfigured")} code
+     * @param {string} message
+     * @param {{ cause?: unknown }} [opts]
+     */
+    constructor(code, message, opts) {
+        super(message);
+        this.name = "AuthError";
+        this.code = code;
+        if (opts && "cause" in opts) this.cause = opts.cause;
+    }
+}
+
+function toAuthError(err, fallbackCode) {
+    if (err instanceof AuthError) return err;
+    // DOMException / AbortError from fetch and AbortController.
+    if (err && (err.name === "AbortError" || err.code === 20)) {
+        return new AuthError("aborted", "operation aborted", {cause: err});
+    }
+    // Network-layer failures from fetch reject as TypeError.
+    if (err instanceof TypeError) {
+        return new AuthError("network", err.message || "network error", {cause: err});
+    }
+    return new AuthError(fallbackCode, err && err.message ? err.message : String(err), {cause: err});
+}
+
+// ---------------------------------------------------------------------------
+// Record validation and helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the structural shape of a session record. Throws a plain Error
+ * (mapped to the caller's fallback code by toAuthError) on malformed input.
+ */
+function validateRecord(rec) {
+    if (rec == null || typeof rec !== "object") {
+        throw new Error("lite-auth: session record must be an object");
+    }
+    if (rec.user == null) {
+        throw new Error("lite-auth: session record is missing `user`");
+    }
+    if (typeof rec.accessToken !== "string" || rec.accessToken.length === 0) {
+        throw new Error("lite-auth: session record is missing a string `accessToken`");
+    }
+    if (rec.refreshToken != null && typeof rec.refreshToken !== "string") {
+        throw new Error("lite-auth: `refreshToken` must be a string when present");
+    }
+    if (rec.expiresAt != null && typeof rec.expiresAt !== "number") {
+        throw new Error("lite-auth: `expiresAt` must be a number (epoch ms) when present");
+    }
+    return rec;
+}
+
+function isExpired(rec, nowMs) {
+    return rec != null && rec.expiresAt != null && nowMs >= rec.expiresAt;
+}
+
+/**
+ * Decode the `exp` claim of a JWT and return it as epoch milliseconds.
+ * Returns undefined for non-JWTs or unreadable payloads. Pure and zero-dep;
+ * works under both browser (atob) and Node (Buffer).
+ *
+ * @param {string} token
+ * @returns {number | undefined}
+ */
+export function decodeJwtExp(token) {
+    if (typeof token !== "string") return undefined;
+    const dot1 = token.indexOf(".");
+    if (dot1 < 0) return undefined;
+    const dot2 = token.indexOf(".", dot1 + 1);
+    if (dot2 < 0) return undefined;
+    let b64 = token.slice(dot1 + 1, dot2).replace(/-/g, "+").replace(/_/g, "/");
+    const padLen = (4 - (b64.length % 4)) % 4;
+    if (padLen > 0) b64 += padLen === 1 ? "=" : padLen === 2 ? "==" : "===";
+    let json;
+    try {
+        if (typeof atob === "function") {
+            json = atob(b64);
+        } else if (typeof Buffer !== "undefined") {
+            json = Buffer.from(b64, "base64").toString("binary");
+        } else {
+            return undefined;
+        }
+        const payload = JSON.parse(json);
+        if (payload && typeof payload.exp === "number") return payload.exp * 1000;
+    } catch {
+        return undefined;
+    }
+    return undefined;
+}
+
+/**
+ * Resolve the `storage` option into a Web-Storage-shaped backend, or null for
+ * memory mode (signal-only, no disk).
+ */
+function resolveStorage(storage) {
+    if (storage === "memory") return null;
+    if (storage == null || storage === "localStorage") {
+        if (typeof globalThis.localStorage === "undefined") {
+            throw new AuthError(
+                "misconfigured",
+                'localStorage is unavailable; use storage:"memory" outside the browser',
+            );
+        }
+        return globalThis.localStorage;
+    }
+    if (storage === "sessionStorage") {
+        if (typeof globalThis.sessionStorage === "undefined") {
+            throw new AuthError(
+                "misconfigured",
+                'sessionStorage is unavailable; use storage:"memory" outside the browser',
+            );
+        }
+        return globalThis.sessionStorage;
+    }
+    if (typeof storage.getItem === "function" && typeof storage.setItem === "function") {
+        return storage; // custom StorageLike
+    }
+    throw new AuthError("misconfigured", "unknown storage backend: " + String(storage));
+}
+
+// ---------------------------------------------------------------------------
+// Built-in fetch adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * A REST adapter over fetch. POSTs JSON to the configured endpoints and parses
+ * `{ user, accessToken, refreshToken?, expiresAt? }` from each response. When
+ * `expiresAt` is absent it is derived from the access token's JWT `exp` claim.
+ *
+ * @param {{
+ *   signInUrl: string,
+ *   refreshUrl?: string,
+ *   signOutUrl?: string,
+ *   headers?: Record<string,string> | (() => Record<string,string>),
+ *   parseSession?: (json: unknown) => any,
+ *   fetch?: typeof fetch,
+ * }} opts
+ */
+export function fetchAdapter(opts) {
+    if (!opts || typeof opts.signInUrl !== "string") {
+        throw new AuthError("misconfigured", "fetchAdapter requires a signInUrl");
+    }
+    const f = opts.fetch || globalThis.fetch;
+    if (typeof f !== "function") {
+        throw new AuthError("misconfigured", "no fetch implementation available");
+    }
+    // Headers may be a static object or a getter evaluated per request. A getter
+    // keeps dynamic values (e.g. an Authorization token rotated by background
+    // refresh) fresh on every call rather than frozen at adapter-construction.
+    const headerOpt = opts.headers;
+    const resolveHeaders = () => {
+        const dyn = typeof headerOpt === "function" ? headerOpt() : headerOpt;
+        return Object.assign({"content-type": "application/json"}, dyn || {});
+    };
+
+    function parse(json) {
+        if (opts.parseSession) return validateRecord(opts.parseSession(json));
+        const rec = {
+            user: json && json.user,
+            accessToken: json && json.accessToken,
+            refreshToken: json && json.refreshToken,
+            expiresAt: json && json.expiresAt,
+        };
+        if (rec.expiresAt == null && typeof rec.accessToken === "string") {
+            rec.expiresAt = decodeJwtExp(rec.accessToken);
+        }
+        return validateRecord(rec);
+    }
+
+    const adapter = {
+        async signIn(credentials, signal) {
+            const res = await f(opts.signInUrl, {
+                method: "POST",
+                headers: resolveHeaders(),
+                body: JSON.stringify(credentials),
+                signal,
+            });
+            if (!res.ok) {
+                throw new AuthError("invalid_credentials", "sign-in failed with status " + res.status);
+            }
+            return parse(await res.json());
+        },
+    };
+
+    if (opts.refreshUrl) {
+        adapter.refresh = async (record, signal) => {
+            // The built-in REST adapter clearly cannot refresh without a token.
+            // Surface the documented `no_refresh_token` code rather than letting
+            // the server 4xx through as a generic `refresh_failed`. Custom
+            // adapters remain free to handle a missing token however they like;
+            // the core does not preempt them.
+            if (record.refreshToken == null) {
+                throw new AuthError("no_refresh_token", "no refresh token in current session");
+            }
+            const res = await f(opts.refreshUrl, {
+                method: "POST",
+                headers: resolveHeaders(),
+                body: JSON.stringify({refreshToken: record.refreshToken}),
+                signal,
+            });
+            if (!res.ok) {
+                throw new AuthError("refresh_failed", "token refresh failed with status " + res.status);
+            }
+            return parse(await res.json());
+        };
+    }
+
+    if (opts.signOutUrl) {
+        adapter.signOut = async (record) => {
+            await f(opts.signOutUrl, {
+                method: "POST",
+                headers: resolveHeaders(),
+                body: JSON.stringify({refreshToken: record.refreshToken}),
+            });
+        };
+    }
+
+    return adapter;
+}
+
+// ---------------------------------------------------------------------------
+// createAuth
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a reactive authentication controller.
+ *
+ * @param {import("./Auth.js").AuthConfig} config
+ * @returns {import("./Auth.js").Auth}
+ */
+export function createAuth(config) {
+    if (!config || !config.adapter || typeof config.adapter.signIn !== "function") {
+        throw new AuthError("misconfigured", "createAuth requires an adapter with a signIn() method");
+    }
+
+    const adapter = config.adapter;
+    const R = config.registry || {signal: defaultSignal, computed: defaultComputed, batch: defaultBatch};
+    const storageKey = config.storageKey || "lite-auth.session.v1";
+    const channelName = config.channelName || storageKey;
+    const crossTab = config.crossTab === true;
+    const refreshCfg = config.refresh || {enabled: false};
+    const refreshEnabled = refreshCfg.enabled === true;
+    const threshold = (typeof refreshCfg.threshold === "number" ? refreshCfg.threshold : 60) * 1000;
+    const onError = typeof config.onError === "function" ? config.onError : null;
+
+    // -- core state ---------------------------------------------------------
+    // The empty state is `undefined`, not `null`: lite-persist removes a key
+    // only when the signal value is `undefined` (a `null` would be written as
+    // the string "null"). Public projections still surface `null` for "no
+    // user"; all internal emptiness checks are loose (`== null`).
+    const _record = R.signal(/** @type {any} */ (undefined));
+    const status = R.signal("idle");
+    const error = R.signal(/** @type {AuthError | null} */ (null));
+
+    const session = R.computed(() => {
+        const r = _record();
+        return r ? r.user : null;
+    });
+    const isAuthenticated = R.computed(() => _record() != null);
+    const token = R.computed(() => {
+        const r = _record();
+        return r ? r.accessToken : null;
+    });
+    const expiresAt = R.computed(() => {
+        const r = _record();
+        return r && r.expiresAt != null ? r.expiresAt : null;
+    });
+
+    // -- generation counter: bumps on every record mutation (local, refresh,
+    //    sign-out, or cross-tab). Async actions capture it before awaiting and
+    //    bail if it moved underneath them.
+    let gen = 0;
+    const disposers = [];
+    disposers.push(_record.subscribe(() => {
+        gen++;
+    }));
+
+    // Mutable wiring shared across boot, scheduling, and teardown. Declared up
+    // here so the boot-time refresh path below can touch them without tripping
+    // the temporal dead zone.
+    let timer = null;
+    let bus = null;
+    let busReady = false;
+    let refreshAbort = null;
+    let signInAbort = null;
+    let disposed = false;
+    let wireNode = null; // cross-tab string-wire signal, disposed on teardown
+
+    function setError(err) {
+        error.set(err);
+        if (onError) {
+            try {
+                onError(err);
+            } catch (e) {
+                reportHookError(e);
+            }
+        }
+    }
+
+    function clearError() {
+        if (error.peek() !== null) error.set(null);
+    }
+
+    // -- lifecycle hooks ----------------------------------------------------
+    const signInCbs = [];
+    const signOutCbs = [];
+    const expireCbs = [];
+    const refreshCbs = [];
+
+    function register(list, fn) {
+        list.push(fn);
+        let live = true;
+        return () => {
+            if (!live) return;
+            live = false;
+            const i = list.indexOf(fn);
+            if (i >= 0) list.splice(i, 1);
+        };
+    }
+
+    function reportHookError(e) {
+        // A throwing user callback must not break the others or the graph.
+        if (typeof console !== "undefined" && console.error) {
+            console.error("lite-auth: lifecycle hook threw", e);
+        }
+    }
+
+    function emit(list, arg) {
+        // Iterate a copy so a callback may dispose itself mid-emit.
+        const copy = list.slice();
+        for (let i = 0; i < copy.length; i++) {
+            try {
+                copy[i](arg);
+            } catch (e) {
+                reportHookError(e);
+            }
+        }
+    }
+
+    if (config.onSignIn) register(signInCbs, config.onSignIn);
+    if (config.onSignOut) register(signOutCbs, config.onSignOut);
+    if (config.onSessionExpire) register(expireCbs, config.onSessionExpire);
+    if (config.onTokenRefresh) register(refreshCbs, config.onTokenRefresh);
+
+    // -- persistence (lite-persist; cross-tab path disabled) ----------------
+    const backend = resolveStorage(config.storage);
+    if (backend) {
+        // Pre-validate any stored value so a corrupt entry cannot throw out of
+        // createAuth via lite-persist's synchronous boot read.
+        try {
+            const raw = backend.getItem(storageKey);
+            if (raw !== null) {
+                const parsed = JSON.parse(raw);
+                if (parsed != null) validateRecord(parsed);
+            }
+        } catch (e) {
+            try {
+                backend.removeItem(storageKey);
+            } catch { /* ignore */
+            }
+            setError(new AuthError("storage", "discarded a corrupt stored session", {cause: e}));
+        }
+        try {
+            const stop = persist(_record, storageKey, {
+                storage: backend,
+                syncTabs: false, // lite-channel owns cross-tab
+                debounce: 0, // session writes are rare; favour durability
+                flushOnDispose: true,
+                deserialize: (str) => {
+                    const v = JSON.parse(str);
+                    return v == null ? undefined : validateRecord(v);
+                },
+            });
+            disposers.push(stop);
+        } catch (e) {
+            setError(new AuthError("storage", "failed to initialise persistence", {cause: e}));
+        }
+    }
+
+    // -- boot expiry handling ----------------------------------------------
+    let bootSettled = Promise.resolve();
+    {
+        const rec0 = _record.peek();
+        if (isExpired(rec0, Date.now())) {
+            if (refreshEnabled && adapter.refresh && rec0.refreshToken) {
+                bootSettled = doRefresh(rec0, false).catch(() => {
+                });
+            } else {
+                emit(expireCbs);
+                _record.set(undefined); // lite-persist removes the key
+            }
+        }
+    }
+
+    // -- lifecycle dispatch (attached post-hydration so a restored session is
+    //    the baseline and does not fire onSignIn) ---------------------------
+    let lifeInit = false;
+    let prevHadUser = false;
+    disposers.push(_record.subscribe((rec) => {
+        const hasUser = rec != null;
+        if (!lifeInit) {
+            lifeInit = true;
+            prevHadUser = hasUser;
+            return;
+        }
+        if (hasUser === prevHadUser) {
+            prevHadUser = hasUser;
+            return;
+        }
+        prevHadUser = hasUser;
+        if (hasUser) emit(signInCbs, rec.user);
+        else emit(signOutCbs);
+    }));
+
+    // -- refresh scheduling -------------------------------------------------
+    function leaderNow() {
+        if (!crossTab) return true;
+        if (!busReady || !bus) return false; // do not schedule before the bus is wired
+        return bus.isLeader.peek();
+    }
+
+    function rearm() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (disposed || !refreshEnabled || !adapter.refresh) return;
+        const rec = _record.peek();
+        if (rec == null || rec.expiresAt == null) return;
+        if (!leaderNow()) return;
+        const delay = Math.max(0, rec.expiresAt - Date.now() - threshold);
+        timer = setTimeout(() => {
+            timer = null;
+            const r = _record.peek();
+            if (r != null) doRefresh(r, false).catch(() => {
+            });
+        }, delay);
+    }
+
+    // (Re)arm whenever the record changes. subscribe fires once on attach,
+    // establishing the baseline schedule for a hydrated session.
+    disposers.push(_record.subscribe(rearm));
+
+    async function doRefresh(rec, manual) {
+        if (refreshAbort) refreshAbort.abort();
+        refreshAbort = new AbortController();
+        const mySignal = refreshAbort.signal;
+        const myGen = gen;
+        status.set("refreshing");
+        let next;
+        try {
+            if (!adapter.refresh) throw new AuthError("misconfigured", "adapter has no refresh()");
+            next = await adapter.refresh(rec, mySignal);
+            next = validateRecord(next);
+        } catch (e) {
+            if (status.peek() === "refreshing") status.set("idle");
+            const err = toAuthError(e, "refresh_failed");
+            // Superseded mid-flight (sign-out, fresh sign-in, or cross-tab change).
+            if (mySignal.aborted || gen !== myGen) {
+                if (manual) throw err;
+                return;
+            }
+            setError(err);
+            // Unrecoverable: the session is effectively dead. Expire then clear.
+            emit(expireCbs);
+            _record.set(undefined);
+            if (manual) throw err;
+            return;
+        }
+        if (mySignal.aborted || gen !== myGen) {
+            if (status.peek() === "refreshing") status.set("idle");
+            if (manual) throw new AuthError("aborted", "refresh superseded");
+            return;
+        }
+        R.batch(() => {
+            clearError();
+            _record.set(next);
+            status.set("idle");
+        });
+        emit(refreshCbs, next);
+    }
+
+    // -- cross-tab wiring (async; lite-channel is an optional peer) ----------
+    if (crossTab) {
+        const attach = (async () => {
+            let mod;
+            try {
+                mod = await import("@zakkster/lite-channel");
+            } catch (e) {
+                setError(new AuthError(
+                    "misconfigured",
+                    'crossTab:true requires @zakkster/lite-channel to be installed',
+                    {cause: e},
+                ));
+                return;
+            }
+            if (disposed) return;
+            const opts = Object.assign({}, config.channelOptions, {persist: false});
+            bus = mod.createTabSync(channelName, opts);
+
+            // lite-channel applies inbound values inside a lite-signal batch().
+            // Because batch defers subscriber notifications to commit time, its
+            // internal "applying" echo guard has already been cleared when the
+            // subscriber finally runs -- so syncing the record OBJECT directly
+            // ping-pongs forever (every structuredClone hop is a fresh reference
+            // that never dedupes by Object.is). We therefore sync a STRING wire:
+            // identical strings dedupe by value, so when the originating tab
+            // receives the echo its wire is unchanged and the loop stops.
+            const EMPTY = "\u0000"; // "no session" sentinel; never collides with JSON
+            const enc = (rec) => (rec == null ? EMPTY : JSON.stringify(rec));
+            const _wire = R.signal(enc(_record.peek()));
+            wireNode = _wire;
+            let lastWire = enc(_record.peek());
+
+            // Outbound: a local record change is pushed onto the wire to broadcast.
+            disposers.push(_record.subscribe(() => {
+                const s = enc(_record.peek());
+                if (s === lastWire) return; // wire already reflects this value
+                lastWire = s;
+                _wire.set(s);
+            }));
+
+            // Inbound: a genuinely new wire value (from another tab) is adopted
+            // into the record. Setting lastWire first makes the outbound
+            // subscriber treat the resulting record change as already-sent.
+            disposers.push(_wire.subscribe(() => {
+                const s = _wire.peek();
+                if (s === lastWire) return; // our own reflection or an echo we hold
+                lastWire = s;
+                let next;
+                if (s === EMPTY) {
+                    next = undefined;
+                } else {
+                    try {
+                        next = validateRecord(JSON.parse(s));
+                    } catch {
+                        return; // ignore an unparseable/foreign payload
+                    }
+                }
+                _record.set(next);
+            }));
+
+            bus.sync(_wire);
+            busReady = true;
+            disposers.push(bus.isLeader.subscribe(rearm));
+            rearm(); // leadership is known now; schedule if we are the leader
+        })();
+        bootSettled = bootSettled.then(() => attach);
+    }
+
+    const ready = bootSettled.then(() => undefined);
+
+    // -- public actions -----------------------------------------------------
+    async function signIn(credentials) {
+        if (signInAbort) signInAbort.abort();
+        signInAbort = new AbortController();
+        const mySignal = signInAbort.signal;
+        const myGen = gen;
+        status.set("authenticating");
+        let rec;
+        try {
+            rec = await adapter.signIn(credentials, mySignal);
+            rec = validateRecord(rec);
+        } catch (e) {
+            if (status.peek() === "authenticating") status.set("idle");
+            const err = toAuthError(e, "invalid_credentials");
+            setError(err);
+            throw err;
+        }
+        if (mySignal.aborted || gen !== myGen) {
+            if (status.peek() === "authenticating") status.set("idle");
+            throw new AuthError("aborted", "sign-in superseded");
+        }
+        R.batch(() => {
+            clearError();
+            _record.set(rec);
+            status.set("idle");
+        });
+        return rec.user;
+    }
+
+    async function signOut() {
+        const rec = _record.peek();
+        if (refreshAbort) refreshAbort.abort();
+        if (signInAbort) signInAbort.abort();
+        // Optimistic local clear: logout always succeeds locally and offline.
+        R.batch(() => {
+            _record.set(undefined);
+            status.set("idle");
+        });
+        if (rec && adapter.signOut) {
+            try {
+                await adapter.signOut(rec);
+            } catch (e) {
+                // Best effort: a failed server revoke never resurrects the
+                // local session and never throws from signOut.
+                setError(toAuthError(e, "network"));
+            }
+        }
+    }
+
+    async function refresh() {
+        const rec = _record.peek();
+        if (rec == null) throw new AuthError("expired", "no active session to refresh");
+        if (!adapter.refresh) throw new AuthError("misconfigured", "adapter has no refresh()");
+        if (rec.refreshToken == null) {
+            // Adapters may not need a refresh token; only flag when the default
+            // contract clearly cannot proceed. Left permissive: the adapter is
+            // the authority. Callers relying on tokens should ensure one exists.
+        }
+        return doRefresh(rec, true);
+    }
+
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (refreshAbort) refreshAbort.abort();
+        if (signInAbort) signInAbort.abort();
+        for (let i = 0; i < disposers.length; i++) {
+            try {
+                disposers[i]();
+            } catch { /* idempotent */
+            }
+        }
+        disposers.length = 0;
+        if (bus) {
+            try {
+                bus.dispose();
+            } catch { /* ignore */
+            }
+            bus = null;
+        }
+        // Release pooled reactive nodes back to the registry, so repeated
+        // create/dispose cycles (SSR per request, test harnesses) do not
+        // accumulate nodes. For a custom registry, use its own dispose so the
+        // right pool is touched -- the imported disposeReactive is bound to
+        // the default registry and would silently no-op on foreign nodes. A
+        // no-op for registries whose primitives are not lite-signal nodes.
+        const disposeNode = typeof R.dispose === "function" ? R.dispose : disposeReactive;
+        const nodes = [session, isAuthenticated, token, expiresAt, _record, status, error];
+        if (wireNode) nodes.push(wireNode);
+        for (let i = 0; i < nodes.length; i++) {
+            try {
+                disposeNode(nodes[i]);
+            } catch { /* ignore */
+            }
+        }
+    }
+
+    return {
+        session,
+        isAuthenticated,
+        token,
+        expiresAt,
+        status,
+        error,
+        ready,
+        signIn,
+        signOut,
+        refresh,
+        onSignIn: (fn) => register(signInCbs, fn),
+        onSignOut: (fn) => register(signOutCbs, fn),
+        onSessionExpire: (fn) => register(expireCbs, fn),
+        onTokenRefresh: (fn) => register(refreshCbs, fn),
+        dispose,
+    };
+}

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-02
+
+### Added
+
+- `createAuth(config)`: a reactive authentication controller built around one
+  private `signal<SessionRecord | undefined>` source of truth.
+- Reactive projections: `session`, `isAuthenticated`, `token`, `expiresAt`,
+  `status`, and `error`.
+- Cross-tab logout and login over `BroadcastChannel` via the optional, lazily
+  loaded `@zakkster/lite-channel` peer (`crossTab: true`).
+- Durable persistence via `@zakkster/lite-persist`: synchronous boot hydration
+  and debounced write-through, with `"localStorage"`, `"sessionStorage"`,
+  `"memory"`, and custom Web-Storage backends.
+- Opt-in, timer-based token refresh that, under `crossTab`, is performed only by
+  the elected leader tab to avoid refresh-token rotation races.
+- Lifecycle hooks `onSignIn`, `onSignOut`, `onSessionExpire`, `onTokenRefresh`,
+  each returning an idempotent disposer, plus matching config callbacks.
+- Hybrid error model: awaited actions reject with a typed `AuthError`; ambient
+  failures surface on the `error` signal and the `onError` hook.
+- `fetchAdapter(options)`: a REST adapter over fetch with JWT `exp` fallback for
+  `expiresAt`.
+- `decodeJwtExp(token)`: a pure, zero-dependency JWT `exp` decoder.
+- `ready` promise that resolves after boot hydration, optional channel attach,
+  and any boot-time refresh have settled.
+- Full TypeScript definitions (`Auth.d.ts`).
+- Test suite of 50 deterministic tests under `node --test`.
+
+[1.0.0]: https://github.com/PeshoVurtoleta/lite-auth/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# @zakkster/lite-auth
+
+Session-as-a-signal authentication for the `lite-*` ecosystem. The entire auth state is one reactive value; everything your UI binds to is a projection of it. Cross-tab logout, pluggable backends, optional leader-only token refresh, and durable persistence come built in. Zero runtime dependencies.
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-auth.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-auth)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-auth?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-auth)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-auth?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-auth)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-auth?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-auth)
+[![lite-signal peer](https://img.shields.io/npm/dependency-version/@zakkster/lite-auth/peer/@zakkster/lite-signal?style=for-the-badge&color=blue)](https://github.com/PeshoVurtoleta/lite-signal)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
+
+- One source of truth: a private `signal<SessionRecord | undefined>`.
+- Reactive projections: `session`, `isAuthenticated`, `token`, `expiresAt`, `status`, `error`.
+- Cross-tab logout (and login) over `BroadcastChannel`, via `@zakkster/lite-channel`.
+- Durable boot hydration and debounced write-through, via `@zakkster/lite-persist`.
+- Opt-in background refresh, performed by a single leader tab to avoid rotation races.
+- Hybrid error model: awaited actions throw typed `AuthError`; ambient failures surface on a signal.
+
+## Install
+
+```sh
+npm install @zakkster/lite-auth @zakkster/lite-signal @zakkster/lite-persist
+# cross-tab is optional; install it only if you set crossTab: true
+npm install @zakkster/lite-channel
+```
+
+`@zakkster/lite-signal` and `@zakkster/lite-persist` are required peers. `@zakkster/lite-channel` is an optional peer, loaded lazily and only when `crossTab: true`.
+
+## Quick start
+
+```js
+import { createAuth, fetchAdapter } from "@zakkster/lite-auth";
+
+const auth = createAuth({
+  adapter: fetchAdapter({
+    signInUrl: "/api/login",
+    refreshUrl: "/api/refresh",
+    signOutUrl: "/api/logout",
+  }),
+  crossTab: true,
+  refresh: { enabled: true, threshold: 60 }, // refresh 60s before expiry
+});
+
+// Bind anywhere a lite-signal value can be read.
+auth.isAuthenticated.subscribe((on) => {
+  document.body.dataset.auth = on ? "in" : "out";
+});
+
+await auth.ready; // boot hydration + channel attach settled
+
+await auth.signIn({ username: "ada", password: "lovelace" });
+console.log(auth.session.peek());        // { ...your user }
+console.log(auth.token.peek());          // "eyJ..."
+
+await auth.signOut();                    // every other tab logs out too
+```
+
+## The model
+
+The whole library is projections over one private record signal. Reading a projection inside a computation tracks it, so views update automatically.
+
+```mermaid
+flowchart TD
+    REC["_record: signal&lt;SessionRecord | undefined&gt;"]
+    REC --> SESSION["session: User | null"]
+    REC --> ISAUTH["isAuthenticated: boolean"]
+    REC --> TOKEN["token: string | null"]
+    REC --> EXP["expiresAt: number | null"]
+    REC --> STATUS["status: idle | authenticating | refreshing"]
+    REC --> ERR["error: AuthError | null"]
+```
+
+The empty state is `undefined` rather than `null`: `lite-persist` removes a stored key only when the signal value is `undefined`. The public projections still surface `null` for "no user".
+
+## Three decoupled axes
+
+Persistence, cross-tab sync, and refresh are independent and individually optional. They are deliberately kept on separate channels so they never fight: `lite-persist` owns disk with its own cross-tab path disabled (`syncTabs: false`), and `lite-channel` owns the wire with persistence disabled (`persist: false`).
+
+```mermaid
+flowchart LR
+    UI["your components"] -->|bind| PROJ["projections"]
+    PROJ --> REC["record signal"]
+    REC -->|"write-through (syncTabs:false)"| DISK["lite-persist to Storage"]
+    DISK -.->|"boot hydration"| REC
+    REC <-->|"string wire (persist:false)"| BUS["lite-channel / BroadcastChannel"]
+    REC -->|"leader-only timer"| RT["refresh()"]
+    RT -->|"new record"| REC
+```
+
+## Cross-tab logout
+
+This is the headline feature. With `crossTab: true`, signing in or out in one tab propagates to every other tab on the same `channelName`. A logout in one tab clears the session everywhere; a login adopts the session in the others.
+
+```js
+const auth = createAuth({ adapter, crossTab: true });
+auth.onSignOut(() => router.push("/login")); // fires in the tab that logged out AND the others
+```
+
+Only user-identity-plus-token state crosses the wire, never your credentials. Under the cookie/session pattern described below, nothing secret crosses at all.
+
+## Token refresh
+
+Refresh is opt-in and timer-based. A refresh is scheduled `threshold` seconds before `expiresAt`; on success the new record replaces the old and the timer re-arms for the next cycle. On failure the session expires (`onSessionExpire`, then `onSignOut`).
+
+Under `crossTab: true`, **only the leader tab refreshes**. Refresh tokens are frequently single-use, so electing one refresher avoids a rotation race where two tabs spend the same token; followers receive the rotated record over the channel.
+
+```js
+createAuth({
+  adapter,
+  crossTab: true,
+  refresh: { enabled: true, threshold: 30 },
+});
+```
+
+If the access token is a JWT and the adapter omits `expiresAt`, it is derived from the token's `exp` claim automatically.
+
+## Persistence
+
+Persistence is delegated to `@zakkster/lite-persist`: a synchronous boot read hydrates the session before your first paint, and writes are debounced through to storage. Choose the backend with `storage`:
+
+- `"localStorage"` (default) survives restarts.
+- `"sessionStorage"` lasts for the tab session.
+- `"memory"` keeps nothing on disk (SSR, tests, or strict session-only flows).
+- any Web-Storage-shaped object for a custom backend.
+
+A corrupt stored value is discarded (not thrown) and surfaces as an `AuthError` with code `storage`; a failed write (for example a full quota) is swallowed and the session simply stays live in memory.
+
+## Error handling
+
+A hybrid model keeps imperative call sites honest while not letting background failures throw into the void:
+
+- Awaited actions (`signIn`, `refresh`) reject with a typed `AuthError`.
+- Ambient failures (background refresh, storage, cross-tab) update the `error` signal and call the `onError` hook.
+- `signOut` is optimistic and local-first: it clears immediately, never rejects, and a failed server-side revoke never resurrects the session.
+
+```js
+try {
+  await auth.signIn(creds);
+} catch (e) {
+  if (e.code === "invalid_credentials") showBadPassword();
+  else if (e.code === "network") showOffline();
+}
+
+auth.error.subscribe((e) => { if (e) toast(e.message); });
+```
+
+`AuthError.code` is one of: `invalid_credentials`, `network`, `refresh_failed`, `no_refresh_token`, `expired`, `storage`, `aborted`, `misconfigured`.
+
+## Custom adapters
+
+`fetchAdapter` covers the common REST case. For anything else, implement the small adapter contract directly:
+
+```js
+const adapter = {
+  async signIn(credentials, signal) {
+    // return { user, accessToken, refreshToken?, expiresAt? }
+  },
+  async refresh(record, signal) {   // optional
+    // return a fresh record
+  },
+  async signOut(record) {           // optional
+    // revoke server-side; throwing here never resurrects the local session
+  },
+};
+```
+
+`signal` is an `AbortSignal` that fires when a call is superseded (a newer `signIn`, a `signOut`, or disposal), so a well-behaved adapter can cancel its in-flight request.
+
+### Dynamic headers (token rotation)
+
+`fetchAdapter`'s `headers` may be a static object or a getter evaluated on every request. A getter keeps a rotating value, such as an `Authorization` token refreshed in the background, fresh rather than frozen at adapter-construction time:
+
+```js
+fetchAdapter({
+  signInUrl: "/api/login",
+  refreshUrl: "/api/refresh",
+  // re-read on every request, so a rotated token is never stale
+  headers: () => ({ Authorization: `Bearer ${auth.token.peek() ?? ""}` }),
+});
+```
+
+If you pass a plain object instead, its values are captured once; for any value that changes over the session (most commonly the access token), use the getter form or apply the token through your own request layer.
+
+## A note on encrypted-cookie / httpOnly sessions
+
+httpOnly or encrypted-cookie sessions are not outdated; they are arguably more XSS-resistant, because the token never enters JavaScript. They are a different architecture, not one this library replaces. lite-auth targets token-in-JS single-page apps because a client-side reactive library can only be reactive over state the client can actually see, and an httpOnly token is invisible to JS by design.
+
+lite-auth can still serve the cookie model as a session mode: the token never touches storage, `signIn` posts credentials and the server sets the cookie, boot hydrates the user from a `/me` endpoint, `signOut` hits a logout endpoint, and refresh happens server-side. That pairing is in fact the most secure companion to cross-tab logout, because the only thing synced across tabs is user identity, with zero secrets on the wire. This is a planned follow-on via a `restore` adapter hook (boot hydration is storage-only today).
+
+## API
+
+- `createAuth(config) -> Auth` builds the controller. See `Auth.d.ts` for the full typed surface.
+- `fetchAdapter(options) -> AuthAdapter` a REST adapter over fetch.
+- `decodeJwtExp(token) -> number | undefined` reads a JWT `exp` as epoch ms.
+- `AuthError` the typed error class.
+
+The `Auth` object exposes the six read-only signals above, a `ready` promise, the actions `signIn` / `signOut` / `refresh`, the hook registrars `onSignIn` / `onSignOut` / `onSessionExpire` / `onTokenRefresh` (each returns an idempotent disposer), and `dispose()`. Disposing tears down timers, subscriptions, and the channel but leaves stored data intact (it is not a sign-out).
+
+## Compatibility note
+
+lite-auth syncs a serialized string across tabs rather than the record object. `lite-channel` applies inbound values inside a lite-signal `batch()`, which defers subscriber notification; that timing defeats the library's reference-based echo suppression for object values (each cross-tab hop is a fresh reference). A string wire dedupes by value, so an echo terminates after a single hop. This is an implementation detail, but it is the reason the wire payload is a string.
+
+## License
+
+MIT (c) Zahary Shinikchiev. See [LICENSE](./LICENSE).

package/llms.txt

@@ -0,0 +1,114 @@
+# @zakkster/lite-auth
+
+> Session-as-a-signal authentication for the lite-* ecosystem. The entire auth
+> state is one reactive value (a private signal holding a SessionRecord or
+> undefined); session, isAuthenticated, token, expiresAt, status and error are
+> computed projections of it. Cross-tab logout/login over BroadcastChannel,
+> durable persistence, optional leader-only token refresh. Zero runtime deps.
+
+## Install
+
+npm install @zakkster/lite-auth @zakkster/lite-signal @zakkster/lite-persist
+Optional (only with crossTab:true): npm install @zakkster/lite-channel
+
+Peers: @zakkster/lite-signal (required), @zakkster/lite-persist (required),
+@zakkster/lite-channel (optional, lazy-loaded when crossTab:true).
+ESM only. Single file: Auth.js. Types: Auth.d.ts.
+
+## Exports
+
+- createAuth(config) -> Auth
+- fetchAdapter(options) -> AuthAdapter
+- decodeJwtExp(token: string) -> number | undefined
+- class AuthError extends Error { code, cause? }
+
+## createAuth(config)
+
+config:
+- adapter: AuthAdapter (REQUIRED). { signIn(creds, signal)->Promise<record>,
+  refresh?(record, signal)->Promise<record>, signOut?(record)->Promise<void> }
+- storage: "localStorage" (default) | "sessionStorage" | "memory" | StorageLike
+- storageKey: string (default "lite-auth.session.v1"); also the default channel key
+- channelName: string (default = storageKey)
+- crossTab: boolean (default false); requires @zakkster/lite-channel
+- refresh: { enabled: boolean, threshold?: number /* seconds, default 60 */ }
+- channelOptions: object forwarded to lite-channel createTabSync (persist forced off)
+- registry: custom lite-signal registry { signal, computed, batch }
+  (advanced; pairs best with storage:"memory" because lite-persist uses the global graph)
+- onSignIn(user) / onSignOut() / onSessionExpire() / onTokenRefresh(record): hooks
+- onError(error: AuthError): ambient (non-thrown) failures
+
+returns Auth:
+- session: ReadonlySignal<User | null>
+- isAuthenticated: ReadonlySignal<boolean>
+- token: ReadonlySignal<string | null>
+- expiresAt: ReadonlySignal<number | null>   // epoch ms
+- status: ReadonlySignal<"idle" | "authenticating" | "refreshing">
+- error: ReadonlySignal<AuthError | null>
+- ready: Promise<void>   // resolves after boot hydration + channel attach + boot refresh
+- signIn(credentials) -> Promise<User>        // throws AuthError on failure
+- signOut() -> Promise<void>                   // optimistic, never throws
+- refresh() -> Promise<void>                   // throws AuthError on failure
+- onSignIn/onSignOut/onSessionExpire/onTokenRefresh(fn) -> () => void  // idempotent disposer
+- dispose() -> void   // tears down timers/subscriptions/channel; leaves storage intact
+
+A ReadonlySignal<T> is callable (tracked read), has .peek() (untracked) and
+.subscribe(fn) -> dispose (fires immediately, then on change).
+
+## SessionRecord
+
+{ user: any, accessToken: string, refreshToken?: string, expiresAt?: number /* epoch ms */ }
+The user value is opaque to lite-auth.
+
+## AuthError.code values
+
+invalid_credentials | network | refresh_failed | no_refresh_token | expired |
+storage | aborted | misconfigured
+
+## Behaviour
+
+- Boot hydration is synchronous: a stored session is available before ready resolves.
+- A restored session is the baseline; onSignIn does NOT fire on restore.
+- Empty state is `undefined` internally so lite-persist removes the key on sign-out;
+  projections still surface null.
+- Persistence: lite-persist with syncTabs:false (lite-channel owns cross-tab),
+  debounce:0, flushOnDispose:true. Corrupt stored value -> discarded + error("storage").
+  Write/quota failure -> swallowed; session stays in memory.
+- Cross-tab: lite-channel with persist:false. A serialized STRING is synced (not the
+  object) so value-dedupe terminates the echo. signIn/signOut/refresh propagate.
+- Refresh: timer fires threshold seconds before expiresAt. Under crossTab, only the
+  leader tab (lite-channel isLeader) refreshes; followers receive the rotated record.
+  JWT exp is used when the adapter omits expiresAt.
+- Concurrency: last-call-wins. A superseded signIn/refresh rejects with code "aborted".
+  signOut aborts an in-flight refresh and is never resurrected by it.
+
+## fetchAdapter(options)
+
+options: { signInUrl, refreshUrl?, signOutUrl?, headers?, parseSession?(json), fetch? }
+POSTs JSON; reads { user, accessToken, refreshToken?, expiresAt? }; derives expiresAt
+from the access token's JWT exp claim when absent.
+
+## Minimal example
+
+import { createAuth, fetchAdapter } from "@zakkster/lite-auth";
+const auth = createAuth({
+  adapter: fetchAdapter({ signInUrl: "/api/login", refreshUrl: "/api/refresh" }),
+  crossTab: true,
+  refresh: { enabled: true, threshold: 60 },
+});
+await auth.ready;
+await auth.signIn({ username, password });
+auth.isAuthenticated.subscribe(on => render(on));
+await auth.signOut(); // logs out every tab
+
+## Custom adapter
+
+const adapter = {
+  async signIn(credentials, signal) { /* return SessionRecord */ },
+  async refresh(record, signal) { /* return SessionRecord */ },   // optional
+  async signOut(record) { /* revoke server-side */ },             // optional
+};
+
+## License
+
+MIT (c) Zahary Shinikchiev.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@zakkster/lite-auth",
+  "version": "1.0.0",
+  "description": "Session-as-a-signal authentication for the lite-* ecosystem: a reactive User|null with cross-tab logout, pluggable backends, and leader-only token refresh. Zero runtime dependencies.",
+  "type": "module",
+  "main": "./Auth.js",
+  "types": "./Auth.d.ts",
+  "exports": {
+    ".": {
+      "types": "./Auth.d.ts",
+      "node": "./Auth.js",
+      "import": "./Auth.js",
+      "default": "./Auth.js"
+    }
+  },
+  "files": [
+    "Auth.js",
+    "Auth.d.ts",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test --test-reporter=spec test/*.test.mjs",
+    "test:gc": "node --expose-gc --test --test-reporter=spec test/*.test.mjs",
+    "test:coverage": "c8 node --test --test-reporter=spec test/*.test.mjs",
+    "bench": "node bench/bench.mjs",
+    "demo:build": "esbuild Auth.js --bundle --format=esm --outfile=demo/lite-auth.bundle.js",
+    "verify": "npm test && npm run bench"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "session",
+    "signal",
+    "signals",
+    "reactive",
+    "cross-tab",
+    "broadcastchannel",
+    "jwt",
+    "token-refresh",
+    "lite",
+    "zero-dependency"
+  ],
+  "author": "Zahary Shinikchiev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-auth.git"
+  },
+  "homepage": "https://github.com/PeshoVurtoleta/lite-auth#readme",
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-auth/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "peerDependencies": {
+    "@zakkster/lite-signal": "^1.1.2",
+    "@zakkster/lite-persist": "^1.0.0",
+    "@zakkster/lite-channel": "^1.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@zakkster/lite-channel": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@zakkster/lite-channel": "^1.0.1",
+    "@zakkster/lite-persist": "^1.0.0",
+    "@zakkster/lite-signal": "^1.1.4",
+    "c8": "^11.0.0",
+    "esbuild": "^0.28.0"
+  }
+}