@saolabs/client 1.5.2 → 1.7.1

package/src/core/routers/ClientMiddleware.ts

@@ -0,0 +1,124 @@
+import type {ApplicationInterface} from '../contracts/ApplicationInterface.js';
+import type {ActiveRoute, Route, Router} from './Router.js';
+
+export interface ClientMiddlewareContext {
+    app: ApplicationInterface;
+    router: Router;
+    to: Route;
+    from: ActiveRoute | null;
+    /** Complete local destination, including query and fragment. */
+    url: string;
+    signal: AbortSignal;
+}
+export type ClientMiddlewareResult = void | boolean | {redirect: string; replace?: boolean};
+export type ClientMiddleware = (context: ClientMiddlewareContext, ...parameters: string[]) => ClientMiddlewareResult | Promise<ClientMiddlewareResult>;
+export type ClientMiddlewareHandler = ClientMiddleware | {handle: ClientMiddleware};
+export type ClientMiddlewareRef = string | ClientMiddlewareHandler;
+export interface ClientMiddlewareConfig {
+    aliases?: Record<string, ClientMiddlewareHandler>;
+    groups?: Record<string, readonly ClientMiddlewareRef[]>;
+    global?: readonly ClientMiddlewareRef[];
+    /** Optional project-only assignment by exact route name. */
+    routes?: Record<string, readonly ClientMiddlewareRef[]>;
+}
+
+/** Per-router registry. Projects register configuration through bootstrap, not the builder. */
+export class ClientMiddlewareRegistry {
+    private configs = new Set<ClientMiddlewareConfig>();
+
+    register(config: ClientMiddlewareConfig): () => void {
+        const names = new Set<string>();
+        for (const current of [...this.configs, config]) {
+            for (const name of [...Object.keys(current.aliases ?? {}), ...Object.keys(current.groups ?? {})]) {
+                if (!/^[A-Za-z_][\w.-]*$/.test(name) || names.has(name)) throw new Error(`Duplicate or invalid client middleware alias: ${name}`);
+                names.add(name);
+            }
+            for (const handler of Object.values(current.aliases ?? {})) this.assertHandler(handler);
+        }
+        const installed = {
+            aliases: {...config.aliases},
+            groups: Object.fromEntries(Object.entries(config.groups ?? {}).map(([name, refs]) => [name, [...refs]])),
+            global: [...config.global ?? []],
+            routes: Object.fromEntries(Object.entries(config.routes ?? {}).map(([name, refs]) => [name, [...refs]])),
+        };
+        this.configs.add(installed);
+        return () => { this.configs.delete(installed); };
+    }
+
+    has(route: Route): boolean { return this.configs.size > 0 || route.meta?.middleware !== undefined; }
+    clear(): void { this.configs.clear(); }
+
+    async run(context: ClientMiddlewareContext): Promise<ClientMiddlewareResult> {
+        const aliases: Record<string, ClientMiddlewareHandler> = Object.create(null);
+        const groups: Record<string, readonly ClientMiddlewareRef[]> = Object.create(null);
+        const global: ClientMiddlewareRef[] = [], local: ClientMiddlewareRef[] = [];
+        for (const config of this.configs) {
+            Object.assign(aliases, config.aliases); Object.assign(groups, config.groups);
+            global.push(...config.global ?? []);
+            local.push(...(context.to.name ? config.routes?.[context.to.name] ?? [] : []));
+        }
+        const declared = context.to.meta?.middleware ?? [];
+        if (!Array.isArray(declared)) throw new TypeError('Route meta.middleware must be an array.');
+        const pipeline: Array<{handler: ClientMiddlewareHandler; parameters: string[]}> = [];
+        const expand = (ref: ClientMiddlewareRef, stack: string[] = []) => {
+            if (typeof ref !== 'string') { this.assertHandler(ref); pipeline.push({handler:ref, parameters:[]}); return; }
+            const colon = ref.indexOf(':');
+            const name = colon < 0 ? ref : ref.slice(0, colon);
+            const parameters = colon < 0 ? [] : ref.slice(colon + 1).split(',');
+            if (Object.prototype.hasOwnProperty.call(groups, name)) {
+                if (parameters.length || stack.includes(name)) throw new Error(`Invalid or recursive client middleware group: ${[...stack, name].join(' -> ')}`);
+                for (const child of groups[name]) expand(child, [...stack, name]);
+            } else {
+                if (!Object.prototype.hasOwnProperty.call(aliases, name)) throw new Error(`Unknown client middleware: ${name}`);
+                pipeline.push({handler:aliases[name], parameters});
+            }
+        };
+        for (const ref of [...global, ...declared, ...local]) expand(ref);
+        for (const {handler, parameters} of pipeline) {
+            if (context.signal.aborted) return false;
+            const result = await this.waitForResult(
+                typeof handler === 'function' ? handler(context, ...parameters) : handler.handle(context, ...parameters), context.signal);
+            if (context.signal.aborted) return false;
+            if (result === false) return false;
+            if (result && typeof result === 'object' && typeof result.redirect === 'string') return result;
+            if (result !== undefined && result !== true) throw new TypeError('Client middleware must return true, false, void or {redirect}.');
+        }
+        return true;
+    }
+
+    private assertHandler(handler: unknown): asserts handler is ClientMiddlewareHandler {
+        if (typeof handler !== 'function' && (!handler || typeof (handler as any).handle !== 'function')) {
+            throw new TypeError('Client middleware must be a function or an instance with handle(context).');
+        }
+    }
+
+    /** A middleware that ignores AbortSignal must not hold up a newer navigation. */
+    private waitForResult(value: ClientMiddlewareResult | Promise<ClientMiddlewareResult>, signal: AbortSignal): Promise<ClientMiddlewareResult> {
+        return new Promise((resolve, reject) => {
+            const abort = () => { signal.removeEventListener('abort', abort); resolve(false); };
+            if (signal.aborted) { Promise.resolve(value).catch(() => {}); resolve(false); return; }
+            signal.addEventListener('abort', abort, {once:true});
+            Promise.resolve(value).then(result => { signal.removeEventListener('abort', abort); resolve(result); },
+                error => { signal.removeEventListener('abort', abort); reject(error); });
+        });
+    }
+}
+
+export interface AuthMiddlewareOptions {
+    redirect: string | ((context: ClientMiddlewareContext) => string);
+    guard?: string;
+}
+
+export function authMiddleware(options: AuthMiddlewareOptions): ClientMiddleware {
+    return (context, guard = options.guard) => {
+        if (context.app.Auth.guard(guard).check()) return true;
+        return {redirect: typeof options.redirect === 'function' ? options.redirect(context) : options.redirect};
+    };
+}
+
+export function guestMiddleware(options: AuthMiddlewareOptions): ClientMiddleware {
+    return (context, guard = options.guard) => {
+        if (context.app.Auth.guard(guard).guest()) return true;
+        return {redirect: typeof options.redirect === 'function' ? options.redirect(context) : options.redirect};
+    };
+}

package/src/core/routers/Router.ts

@@ -15,6 +15,8 @@
  */
 
 import type { ViewManagerInterface } from "../contracts/ViewManagerInterface.js";
+import {app as application} from '../helpers/app.js';
+import {ClientMiddlewareRegistry, type ClientMiddlewareConfig} from './ClientMiddleware.js';
 
 // ─── Types ──────────────────────────────────────────────────────
 
@@ -177,6 +179,9 @@ export class Router {
     /** Navigation guards */
     private _beforeEach: NavigationGuard | null = null;
     private navigationGuards = new Set<NavigationGuard>();
+    private middleware = new ClientMiddlewareRegistry();
+    private middlewareAbort: AbortController | null = null;
+    private middlewareRedirects = 0;
     /**
      * NHIỀU hook, không phải một.
      *
@@ -317,6 +322,9 @@ export class Router {
             const { children, ...own } = route;
             const path = Router.joinRoutePath(parentPath, route.path ?? '');
             const meta = { ...parentMeta, ...(route.meta ?? {}) };
+            if (parentMeta.middleware && route.meta?.middleware) {
+                meta.middleware = [...parentMeta.middleware, ...route.meta.middleware];
+            }
 
             const flatChildren = children && children.length
                 ? this.flattenRouteTree(children, path, meta)
@@ -349,7 +357,9 @@ export class Router {
         }
         for (const route of this.flattenRouteTree(routes)) {
             const component = route.component || route.view || '';
-            this.addRoute(route.path, component, route.meta || {});
+            // Preserve legacy flattened option keys while keeping the named route
+            // and its actual meta object available to middleware and guards.
+            this.addRoute(route.path, component, {...route.meta, name:route.name, meta:route.meta});
             if (route.name) {
                 this.addRouteConfig(route);
             }
@@ -396,6 +406,9 @@ export class Router {
         return () => { this.navigationGuards.delete(guard); };
     }
 
+    /** Register project aliases/groups/global middleware. Returns a disposer. */
+    useMiddleware(config: ClientMiddlewareConfig): () => void { return this.middleware.register(config); }
+
     /** Đăng ký hook chạy sau mỗi lần điều hướng. Trả về hàm HUỶ đăng ký. */
     afterEach(hook: AfterNavigationHook): () => void {
         this.afterHooks.add(hook);
@@ -551,7 +564,7 @@ export class Router {
         }
 
         const initialPath = this.mode === 'history'
-            ? (window.location.pathname + window.location.search)
+            ? (window.location.pathname + window.location.search + window.location.hash)
             : (window.location.hash.substring(1) || this.defaultRoute);
 
         // Set initial active route (without mounting view)
@@ -578,6 +591,7 @@ export class Router {
      * Stop the router — remove event listeners.
      */
     stop(): void {
+        this.middlewareAbort?.abort();
         window.removeEventListener('popstate', this._handlePopState);
         window.removeEventListener('hashchange', this._handlePopState);
         document.removeEventListener('click', this._handleAutoNavigation);
@@ -664,6 +678,7 @@ export class Router {
         this.routeCache.clear();
         this._beforeEach = null;
         this.navigationGuards.clear();
+        this.middleware.clear();
         this.afterHooks.clear();
         this.currentRoute = null;
         this.liveRegion?.remove();
@@ -710,7 +725,9 @@ export class Router {
      * Đang navigate dở → ghi nhận request MỚI NHẤT, xử lý sau khi xong
      * (không drop im lặng như trước).
      */
-    private requestNavigation(path: string, type: NavigationType): void {
+    private requestNavigation(path: string, type: NavigationType, middlewareRedirect = false): void {
+        this.middlewareAbort?.abort();
+        if (!middlewareRedirect) this.middlewareRedirects = 0;
         const request: NavigationRequest = { id: ++this.navigationSequence, path, type };
         if (this.isNavigating) {
             this.pendingNavigation = request;
@@ -734,6 +751,8 @@ export class Router {
         this.isNavigating = true;
         // Khai ngoài try: `finally` phải nhả được kể cả khi render ném giữa chừng.
         let releaseHeight: () => void = () => {};
+        const middlewareAbort = new AbortController();
+        this.middlewareAbort = middlewareAbort;
 
         try {
             const { pathname, queryString, fragment } = this.splitLocation(path);
@@ -751,12 +770,40 @@ export class Router {
                 return;
             }
 
-            const { route, params } = match;
+            const { route: matchedRoute, params } = match;
+            let route = matchedRoute;
             const from = this.currentRoute;
 
+            const viewName = route.component || route.view;
+            const vm = this.viewManager ?? this.App?.View;
+            const viewMiddleware = viewName ? vm?.getViewMiddleware?.(viewName) ?? [] : [];
+            if (viewMiddleware.length) {
+                const declared = route.meta?.middleware ?? [];
+                if (!Array.isArray(declared)) throw new TypeError('Route meta.middleware must be an array.');
+                route = {...route, meta:{...route.meta, middleware:[...declared, ...viewMiddleware]}};
+            }
+
             // Create ActiveRoute
             const activeRoute = new ActiveRoute(route, normalizedPath, params, query, fragment, uri);
 
+            // Run before any page fetch, factory, mount/hydration or history commit.
+            if (this.middleware.has(route)) {
+                const result = await this.middleware.run({app:this.App ?? application(), router:this,
+                    to:{...route, params, query}, from, url:path, signal:middlewareAbort.signal});
+                if (middlewareAbort.signal.aborted || requestId !== this.navigationSequence) return;
+                if (result !== true) {
+                    if (type === 'pop') this.restoreUrlAfterFailedPop(from);
+                    if (result && typeof result === 'object') {
+                        const url = new URL(result.redirect, window.location.origin);
+                        if (url.origin !== window.location.origin || url.username || url.password) throw new Error('Client middleware redirects must stay on the current origin.');
+                        const destination = url.pathname + url.search + url.hash;
+                        if (destination === path || ++this.middlewareRedirects > 8) throw new Error('Client middleware redirect loop.');
+                        this.requestNavigation(destination, result.replace === false ? 'push' : 'replace', true);
+                    }
+                    return;
+                }
+            }
+
             // Before guard — chạy TRƯỚC khi đụng vào history: guard chặn thì URL giữ nguyên
             if (this._beforeEach) {
                 const allow = await this._beforeEach(route, from, normalizedPath);
@@ -838,8 +885,12 @@ export class Router {
                 }
             }
         } catch (error) {
-            console.error('[Router] Navigation error:', error);
+            if (!middlewareAbort.signal.aborted) {
+                if (type === 'pop') this.restoreUrlAfterFailedPop(this.currentRoute);
+                console.error('[Router] Navigation error:', error);
+            }
         } finally {
+            if (this.middlewareAbort === middlewareAbort) this.middlewareAbort = null;
             releaseHeight();
             this.isNavigating = false;
             if (requestId === this.navigationSequence) this.activeNavigationUrl = null;

package/src/core/services/AuthClient.ts

@@ -0,0 +1,163 @@
+import { AuthService, type AuthSnapshot } from './AuthService.js';
+
+export interface AuthProviderInfo { name: string; label: string; url: string }
+export interface AuthClientConfig {
+    version: 1;
+    guard: string;
+    csrfToken: string | null;
+    usernameField: string;
+    endpoints: { session: string; login: string | null; logout: string };
+    providers: AuthProviderInfo[];
+}
+export interface AuthClientOptions {
+    fetch?: typeof fetch;
+    navigate?: (url: string) => void;
+}
+
+/** Same-origin session transport; no dependency on Router, View or a context API. */
+export class AuthClient {
+    private config: AuthClientConfig | null = null;
+    private queue: Promise<unknown> = Promise.resolve();
+    private requests = new Set<AbortController>();
+    private disposed = false;
+    private generation = 0;
+
+    constructor(private readonly auth: AuthService, private readonly options: AuthClientOptions = {}) {}
+
+    configure(config: AuthClientConfig | null): this {
+        if (config !== null) {
+            if (config.version !== 1 || typeof config.guard !== 'string' || !config.guard
+                || typeof config.usernameField !== 'string' || !config.usernameField
+                || (config.csrfToken !== null && typeof config.csrfToken !== 'string')
+                || !Array.isArray(config.providers)) throw new TypeError('Invalid Auth API configuration.');
+            this.localUrl(config.endpoints?.session);
+            this.localUrl(config.endpoints?.logout);
+            if (config.endpoints.login !== null) this.localUrl(config.endpoints.login);
+            for (const provider of config.providers) {
+                if (typeof provider.name !== 'string' || !provider.name || typeof provider.label !== 'string') {
+                    throw new TypeError('Invalid auth provider.');
+                }
+                this.localUrl(provider.url);
+            }
+        }
+        this.config = config === null ? null : structuredClone(config);
+        this.generation++;
+        return this;
+    }
+
+    get available(): boolean { return this.config !== null && !this.disposed; }
+    get csrfToken(): string | null { return this.config?.csrfToken ?? null; }
+    get usernameField(): string | null { return this.config?.usernameField ?? null; }
+    get providers(): AuthProviderInfo[] { return structuredClone(this.config?.providers ?? []); }
+
+    login(credentials: Record<string, string | boolean>): Promise<AuthSnapshot> {
+        // Do not retain the caller's mutable object while waiting for another operation.
+        return this.enqueue('login', { ...credentials });
+    }
+    logout(): Promise<AuthSnapshot> { return this.enqueue('logout'); }
+    refresh(): Promise<AuthSnapshot> { return this.enqueue('session'); }
+
+    loginUrl(provider: string, options: { next?: string } = {}): string {
+        this.assertAvailable();
+        const item = this.config!.providers.find(item => item.name === provider);
+        if (!item) throw new Error(`Auth provider "${provider}" is not enabled.`);
+        const url = this.localUrl(item.url);
+        const next = this.localUrl(options.next ?? (window.location.pathname + window.location.search + window.location.hash));
+        url.searchParams.set('next', next.pathname + next.search + next.hash);
+        return url.href;
+    }
+
+    /** OAuth redirects through the server; callback restores auth via a fresh SSR bootstrap. */
+    loginWith(provider: string, options: { next?: string } = {}): void {
+        const url = this.loginUrl(provider, options);
+        (this.options.navigate ?? (url => window.location.assign(url)))(url);
+    }
+
+    private enqueue(action: 'session' | 'login' | 'logout', body?: object): Promise<AuthSnapshot> {
+        const work = this.queue.then(async () => {
+            this.assertAvailable();
+            if (!this.config!.endpoints[action]) throw new Error('Password login is not enabled.');
+            const finish = action === 'session' ? () => {} : this.auth.beginClientTransition();
+            try {
+                // A refresh obtains the cookie/CSRF token when boot ran without a session.
+                if (action !== 'session' && !this.config!.csrfToken) await this.request('session');
+                return await this.request(action, body);
+            } finally { finish(); }
+        });
+        // A failed login must not poison later logout/refresh operations.
+        this.queue = work.catch(() => {});
+        return work;
+    }
+
+    private async request(action: 'session' | 'login' | 'logout', body?: object): Promise<AuthSnapshot> {
+        this.assertAvailable();
+        const config = this.config!;
+        const url = this.localUrl(config.endpoints[action]!);
+        const revision = this.auth.revision;
+        const generation = this.generation;
+        const controller = new AbortController();
+        this.requests.add(controller);
+        const timeout = setTimeout(() => controller.abort(), 30000);
+        try {
+            const headers: Record<string, string> = { Accept: 'application/json', 'X-Requested-With': 'XMLHttpRequest' };
+            if (action !== 'session') {
+                if (!config.csrfToken) throw new Error('Auth API did not provide a CSRF token.');
+                headers['X-CSRF-TOKEN'] = config.csrfToken;
+                headers['Content-Type'] = 'application/json';
+            }
+            const response = await (this.options.fetch ?? fetch)(url.href, {
+                method: action === 'session' ? 'GET' : 'POST', headers,
+                credentials: 'same-origin', mode: 'same-origin', redirect: 'error', cache: 'no-store',
+                signal: controller.signal,
+                ...(action === 'session' ? {} : {body: JSON.stringify(body ?? {})}),
+            });
+            if (response.url) this.localUrl(response.url);
+            const payload = await response.json();
+            controller.signal.throwIfAborted();
+            if (!response.ok) {
+                throw Object.assign(new Error(typeof payload?.message === 'string' ? payload.message : `Authentication request failed (${response.status}).`),
+                    {status: response.status, errors: payload?.errors});
+            }
+            if (this.disposed || generation !== this.generation || revision !== this.auth.revision) {
+                throw Object.assign(new Error('Authentication changed while the request was pending.'), {name: 'AbortError'});
+            }
+            // Validate the next configuration before committing either state or CSRF.
+            const next = new AuthClient(this.auth);
+            next.configure(payload.authClient);
+            if (!payload.authClient) throw new TypeError('Missing Auth API configuration.');
+            new AuthService().initialize(payload.auth); // deep validation without emitting or changing current auth
+            // Subscribers may immediately send a request. Publish the new CSRF first.
+            this.configure(payload.authClient);
+            const meta = typeof document === 'undefined' ? null : document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]');
+            if (meta && this.config?.csrfToken) meta.content = this.config.csrfToken;
+            this.auth.sync(payload.auth, action === 'session' ? 'sync' : action);
+            return payload.auth;
+        } finally {
+            clearTimeout(timeout);
+            this.requests.delete(controller);
+        }
+    }
+
+    private localUrl(value: string): URL {
+        if (typeof window === 'undefined' || typeof value !== 'string' || !value.trim()) {
+            throw new TypeError('Auth API requires a browser and a same-origin URL.');
+        }
+        const url = new URL(value, window.location.origin);
+        if (url.origin !== window.location.origin || !['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+            throw new TypeError('Auth API URLs must use the current origin.');
+        }
+        return url;
+    }
+
+    private assertAvailable(): void {
+        if (!this.available) throw new Error('Auth API is not configured or has been destroyed.');
+    }
+
+    destroy(): void {
+        this.disposed = true;
+        this.generation++;
+        for (const controller of this.requests) controller.abort();
+        this.requests.clear();
+        this.config = null;
+    }
+}

package/src/core/services/AuthService.ts

@@ -0,0 +1,177 @@
+import { trackDependency } from './ReactiveDependency.js';
+import { AuthClient } from './AuthClient.js';
+
+export type AuthUser = Readonly<{ id: string | number; [key: string]: any }>;
+export interface AuthSnapshot {
+    version: 1;
+    defaultGuard: string;
+    guards: Record<string, { user: AuthUser | null }>;
+}
+export interface AuthChange {
+    guard: string;
+    user: AuthUser | null;
+    previousUser: AuthUser | null;
+    source: 'login' | 'logout' | 'sync';
+}
+export type AuthEvent = 'login' | 'logout' | 'change';
+type Listener = (change: AuthChange) => void;
+type Context = {
+    defaultGuard: string;
+    users: Map<string, AuthUser | null>;
+    instances: Map<string, AuthService>;
+    listeners: Set<{ guard: string | null; event: AuthEvent; callback: Listener }>;
+    revision: number;
+    client?: AuthClient;
+    transitions: number;
+};
+
+/** Client view of server authentication. login/logout record successful server actions; they make no HTTP requests. */
+export class AuthService {
+    private readonly context: Context;
+    private readonly guardName: string | null;
+
+    constructor(user: AuthUser | null = null, defaultGuard = 'web', context?: Context, guardName: string | null = null) {
+        this.context = context ?? {
+            defaultGuard, users: new Map([[defaultGuard, AuthService.copyUser(user)]]),
+            instances: new Map(), listeners: new Set(), revision: 0, transitions: 0,
+        };
+        this.guardName = guardName;
+    }
+
+    static fromSnapshot(snapshot?: unknown): AuthService {
+        const service = new AuthService();
+        if (snapshot !== undefined) service.applySnapshot(snapshot, true);
+        return service;
+    }
+
+    get revision(): number { return this.context.revision; }
+    get client(): AuthClient { return this.context.client ??= new AuthClient(this); }
+    get isTransitioning(): boolean { return this.context.transitions > 0; }
+    /** Internal transport barrier: page responses cannot overwrite an in-flight login/logout. */
+    beginClientTransition(): () => void {
+        this.context.revision++;
+        this.context.transitions++;
+        let finished = false;
+        return () => {
+            if (finished) return;
+            finished = true;
+            this.context.transitions--;
+            this.context.revision++;
+        };
+    }
+    private get name(): string { return this.guardName ?? this.context.defaultGuard; }
+
+    guard(name?: string | null): AuthService {
+        if (name == null) return this;
+        if (!name.trim()) throw new TypeError('An auth guard must have a name.');
+        let guard = this.context.instances.get(name);
+        if (!guard) {
+            guard = new AuthService(null, this.context.defaultGuard, this.context, name);
+            this.context.instances.set(name, guard);
+        }
+        return guard;
+    }
+
+    check(): boolean { return this.user() !== null; }
+    guest(): boolean { return !this.check(); }
+    id(): string | number | null { return this.user()?.id ?? null; }
+    user<T extends AuthUser = AuthUser>(): T | null {
+        trackDependency(this);
+        return (this.context.users.get(this.name) ?? null) as T | null;
+    }
+
+    /** Call only after the server accepted login (including registration/OAuth). */
+    login(user: AuthUser): this { return this.setUser(user, 'login'); }
+    /** Call only after the server confirmed logout or session expiry. */
+    logout(): this { return this.setUser(null, 'logout'); }
+
+    setUser(user: AuthUser | null, source: AuthChange['source'] = 'sync'): this {
+        const next = AuthService.copyUser(user);
+        const previous = this.user();
+        // Even a repeated explicit login/logout invalidates older in-flight responses.
+        if (source !== 'sync' || !AuthService.sameUser(previous, next)) this.context.revision++;
+        this.context.users.set(this.name, next);
+        this.emit(this.name, previous, next, source);
+        return this;
+    }
+
+    /** Authoritative page-data response. A snapshot replaces guards omitted by the server too. */
+    sync(snapshot: unknown, source: AuthChange['source'] = 'sync'): this { return this.applySnapshot(snapshot, false, source); }
+    /** Bootstrap only: restore the server session without reporting a new login. */
+    initialize(snapshot: unknown): this { return this.applySnapshot(snapshot, true); }
+
+    on(event: AuthEvent, callback: Listener): () => void {
+        const listener = { guard: this.guardName, event, callback };
+        this.context.listeners.add(listener);
+        return () => { this.context.listeners.delete(listener); };
+    }
+    subscribe(callback: Listener): () => void { return this.on('change', callback); }
+    destroy(): void { this.context.client?.destroy(); this.context.revision++; this.context.listeners.clear(); this.context.instances.clear(); this.context.users.clear(); }
+
+    private applySnapshot(snapshot: unknown, silent: boolean, source: AuthChange['source'] = 'sync'): this {
+        if (!AuthService.isSnapshot(snapshot)) throw new TypeError('Invalid auth snapshot.');
+        // Validate everything before replacing any current state.
+        const users = new Map(Object.entries(snapshot.guards).map(([name, guard]) => [name, AuthService.copyUser(guard.user)]));
+        const previous = this.context.users;
+        const previousDefault = this.context.defaultGuard;
+        this.context.users = users;
+        this.context.defaultGuard = snapshot.defaultGuard;
+        if (source !== 'sync' || previousDefault !== snapshot.defaultGuard || [...new Set([...previous.keys(), ...users.keys()])]
+            .some(name => !AuthService.sameUser(previous.get(name) ?? null, users.get(name) ?? null))) this.context.revision++;
+        if (!silent) {
+            for (const name of new Set([...previous.keys(), ...users.keys()])) {
+                this.emit(name, previous.get(name) ?? null, users.get(name) ?? null, source);
+            }
+            if (previousDefault !== snapshot.defaultGuard && AuthService.sameUser(previous.get(snapshot.defaultGuard) ?? null, users.get(snapshot.defaultGuard) ?? null)) {
+                this.emit(snapshot.defaultGuard, previous.get(previousDefault) ?? null, users.get(snapshot.defaultGuard) ?? null, source);
+            }
+        }
+        return this;
+    }
+
+    private emit(guard: string, previousUser: AuthUser | null, user: AuthUser | null, source: AuthChange['source']): void {
+        if (AuthService.sameUser(previousUser, user)) return;
+        const change = { guard, previousUser, user, source };
+        const identityChanged = previousUser?.id !== user?.id;
+        const events: AuthEvent[] = [];
+        if (identityChanged && previousUser) events.push('logout');
+        if (identityChanged && user) events.push('login');
+        events.push('change');
+        for (const event of events) {
+            for (const listener of [...this.context.listeners]) {
+                if (!this.context.listeners.has(listener) || listener.event !== event
+                    || (listener.guard !== null && listener.guard !== guard)) continue;
+                try { listener.callback(change); }
+                catch (error) { console.error('[AuthService] Listener error:', error); }
+            }
+        }
+    }
+
+    static isSnapshot(value: any): value is AuthSnapshot {
+        return value?.version === 1 && typeof value.defaultGuard === 'string' && value.defaultGuard.length > 0
+            && value.guards !== null && typeof value.guards === 'object' && !Array.isArray(value.guards)
+            && Object.prototype.hasOwnProperty.call(value.guards, value.defaultGuard)
+            && Object.values(value.guards).every((guard: any) => guard && Object.prototype.hasOwnProperty.call(guard, 'user')
+                && (guard.user === null || (typeof guard.user === 'object' && !Array.isArray(guard.user)
+                    && (typeof guard.user.id === 'string' || typeof guard.user.id === 'number'))));
+    }
+    private static copyUser(user: AuthUser | null): AuthUser | null {
+        if (user === null) return null;
+        if (!user || Array.isArray(user) || (typeof user.id !== 'string' && typeof user.id !== 'number')
+            || (typeof user.id === 'number' && !Number.isFinite(user.id))) {
+            throw new TypeError('An authenticated user must have an id.');
+        }
+        const copy = structuredClone(user);
+        JSON.stringify(copy); // Reject non-JSON user data before changing any state.
+        const seen = new WeakSet<object>();
+        const freeze = (value: any): void => {
+            if (!value || typeof value !== 'object' || seen.has(value)) return;
+            seen.add(value);
+            for (const item of Object.values(value)) freeze(item);
+            Object.freeze(value);
+        };
+        freeze(copy);
+        return copy;
+    }
+    private static sameUser(a: AuthUser | null, b: AuthUser | null): boolean { return JSON.stringify(a) === JSON.stringify(b); }
+}

package/src/core/services/HelperService.ts

@@ -2,6 +2,7 @@ import { TranslationService, type TranslationConfig } from './TranslationService
 import { CollectionProxyInterface, HelperInterface } from "../contracts/HelperInterface.js";
 import { ApplicationInterface } from "../contracts/ApplicationInterface.js";
 import { app } from "../helpers/app.js";
+import { AuthService } from './AuthService.js';
 
 /**
  * HelperService — PHP-compatible helper functions for SaoView runtime.
@@ -46,6 +47,15 @@ export class HelperService implements HelperInterface {
         if (App) this.App = App;
     }
 
+    auth(guard?: string | null): AuthService {
+        const application = this.App ?? app();
+        if (!application.has('Auth')) application.instance('Auth', AuthService.fromSnapshot(application.shared('auth')));
+        return application.get('Auth').guard(guard);
+    }
+
+    /** Compatibility for previously compiled @auth/@guest views. */
+    isAuth(guard?: string | null): boolean { return this.auth(guard).check(); }
+
     app<T = any>(key?: any, value?: any): T | ApplicationInterface 
     {
         return app(key, value);