@saolabs/client 1.5.2 → 1.6.0

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);

package/src/core/services/HttpService.ts

@@ -15,6 +15,9 @@
  *   });
  */
 
+import { app } from '../helpers/app.js';
+import { AuthService } from './AuthService.js';
+
 // ─── Types ──────────────────────────────────────────────────────
 
 export interface HttpRequestConfig extends RequestInit {
@@ -171,10 +174,28 @@ export class HttpService {
             }
             if (!group) this.pending.set(requestKey, group = new Set());
             group.add(controller);
+            const auth = app.has('Auth') ? app<AuthService>('Auth') : null;
+            const authRevision = auth?.revision;
+            // Read at send time: session login/logout rotates Laravel's CSRF token.
+            if (typeof window !== 'undefined' && urlObj.origin === window.location.origin
+                && !['GET', 'HEAD', 'OPTIONS'].includes(config.method!)) {
+                const headers = config.headers ??= {};
+                const explicit = Object.keys(headers).some(key => ['x-csrf-token', 'x-xsrf-token'].includes(key.toLowerCase()));
+                const token = auth?.client.csrfToken ?? document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content;
+                if (!explicit && token) headers['X-CSRF-TOKEN'] = token;
+            }
             const raw = await fetch(fullUrl, config);
             const responseData = await raw.json().catch(() => ({}));
             controller.signal.throwIfAborted();
 
+            // Only our own server may synchronize auth; an older request cannot undo a newer login/logout.
+            if (auth && !auth.isTransitioning && auth.revision === authRevision && typeof window !== 'undefined'
+                && urlObj.origin === window.location.origin
+                && (!raw.url || new URL(raw.url).origin === window.location.origin)
+                && AuthService.isSnapshot(responseData?.auth)) {
+                auth.sync(responseData.auth);
+            }
+
             const viewContext = responseData?.viewContext;
             const currentContext = typeof window !== 'undefined'
                 ? (window as any).APP_CONFIGS?.view?.systemData?.__context__

package/src/core/services/ReactiveDependency.ts

@@ -0,0 +1,46 @@
+/** A service can participate in computed evaluation without exposing its storage. */
+export interface ReactiveDependency {
+    subscribe(callback: () => void): () => void;
+}
+
+let collecting: Set<ReactiveDependency> | null = null;
+
+export function trackDependency(source: ReactiveDependency): void {
+    collecting?.add(source);
+}
+
+/** Reconciles subscriptions after each synchronous evaluation, including branch changes. */
+export class DependencyTracker {
+    private subscriptions = new Map<ReactiveDependency, () => void>();
+    private destroyed = false;
+
+    constructor(private readonly invalidate: () => void) {}
+
+    evaluate<T>(read: () => T): T {
+        const previous = collecting;
+        const sources = new Set<ReactiveDependency>();
+        collecting = sources;
+        try { return read(); }
+        finally {
+            collecting = previous;
+            if (!this.destroyed) {
+                for (const [source, off] of this.subscriptions) {
+                    if (!sources.has(source)) { off(); this.subscriptions.delete(source); }
+                }
+                for (const source of sources) {
+                    if (!this.subscriptions.has(source)) {
+                        this.subscriptions.set(source, source.subscribe(() => {
+                            if (!this.destroyed) this.invalidate();
+                        }));
+                    }
+                }
+            }
+        }
+    }
+
+    destroy(): void {
+        this.destroyed = true;
+        for (const off of this.subscriptions.values()) off();
+        this.subscriptions.clear();
+    }
+}

package/src/core/services/index.ts

@@ -5,6 +5,8 @@ export * from "./HeadService.js";
 export * from "./SectionManager.js";
 export * from "./LoggerService.js";
 export * from './HelperService.js';
+export * from './AuthService.js';
+export * from './AuthClient.js';
 export * from './HttpService.js';
 export * from './MarkerRegistry.js';
 export * from "./StoreService.js";

package/src/core/view/ViewState.ts

@@ -1,6 +1,9 @@
 import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
 import type { StateManagerInterface, ViewStateInterface, StateItem, StateListener } from "../contracts/ViewStateInterface.js";
 import devtools from "../devtools/hook.js";
+import { DependencyTracker } from '../services/ReactiveDependency.js';
+import { AuthService } from '../services/AuthService.js';
+import { app } from '../helpers/app.js';
 
 type MutationChannel = {
     notify: (() => void) | null;
@@ -188,8 +191,9 @@ export class StateManager implements StateManagerInterface {
         return this.useState(value, key)[1];
     }
 
-    private computedNodes = new Map<string, { deps: string[]; dirty: () => void }>();
+    private computedNodes = new Map<string, { deps: string[]; dirty: () => void; tracker: DependencyTracker }>();
     private computedDependents = new Map<string | number, Set<string>>();
+    private authUnsubscribe: (() => void) | null = null;
 
     /** Invalidate the dependency graph synchronously; evaluation remains lazy. */
     private invalidateComputed(key: string | number, notify = true): void {
@@ -234,6 +238,7 @@ export class StateManager implements StateManagerInterface {
         if (deps.some(dep => reaches(dep))) throw new Error(`[ViewState] Computed dependency cycle: ${key}`);
         const existing = this.states[key] as any;
         if (existing && !existing.__computed__) throw new Error(`[ViewState] State already exists: ${key}`);
+        this.computedNodes.get(key)?.tracker.destroy();
         for (const dep of this.computedNodes.get(key)?.deps ?? []) {
             const dependents = this.computedDependents.get(dep);
             dependents?.delete(key);
@@ -242,6 +247,10 @@ export class StateManager implements StateManagerInterface {
         let cache: T;
         let dirty = true;
         let evaluating = false;
+        const tracker = new DependencyTracker(() => {
+            dirty = true;
+            this.enqueueChange(key);
+        });
         const slot: any = {
             key,
             __computed__: true,
@@ -252,7 +261,7 @@ export class StateManager implements StateManagerInterface {
                 if (dirty) {
                     if (evaluating) throw new Error(`[ViewState] Recursive computed read: ${key}`);
                     evaluating = true;
-                    try { cache = fn(); dirty = false; }
+                    try { cache = tracker.evaluate(fn); dirty = false; }
                     finally { evaluating = false; }
                 }
                 return cache;
@@ -262,7 +271,7 @@ export class StateManager implements StateManagerInterface {
         });
         this.states[key] = slot;
         this.setters[key] = slot.setValue;
-        this.computedNodes.set(key, { deps: [...new Set(deps)], dirty: () => { dirty = true; } });
+        this.computedNodes.set(key, { deps: [...new Set(deps)], dirty: () => { dirty = true; }, tracker });
         for (const dep of deps) {
             if (!this.computedDependents.has(dep)) this.computedDependents.set(dep, new Set());
             this.computedDependents.get(dep)!.add(key);
@@ -367,6 +376,21 @@ export class StateManager implements StateManagerInterface {
             if (!records) this.subscriptions.set(k, records = new Set());
             records.add(record);
         }
+        if (keys.has('@auth') && !this.authUnsubscribe) {
+            const application = this.controller?.App ?? app();
+            if (!application.has('Auth')) {
+                application.instance('Auth', AuthService.fromSnapshot(application.shared('auth')));
+            }
+            this.authUnsubscribe = (application.get('Auth') as AuthService).subscribe(() => this.enqueueChange('@auth'));
+        }
+        // Hydration may claim an SSR text node without evaluating its factory.
+        // Observed computed values still need their service dependencies connected.
+        try {
+            for (const k of keys) if (this.computedNodes.has(k)) this.getStateByKey(k);
+        } catch (error) {
+            this.removeSubscription(record);
+            throw error;
+        }
         return () => this.removeSubscription(record);
     }
 
@@ -378,6 +402,10 @@ export class StateManager implements StateManagerInterface {
             records?.delete(record);
             if (records?.size === 0) this.subscriptions.delete(k);
         }
+        if (!this.subscriptions.has('@auth')) {
+            this.authUnsubscribe?.();
+            this.authUnsubscribe = null;
+        }
     }
 
     unsubscribe(
@@ -1079,6 +1107,9 @@ export class StateManager implements StateManagerInterface {
             cancelAnimationFrame(this.flushRAF);
             this.flushRAF = null;
         }
+        this.authUnsubscribe?.();
+        this.authUnsubscribe = null;
+        for (const node of this.computedNodes.values()) node.tracker.destroy();
         this.computedNodes.clear();
         this.computedDependents.clear();
         this.versions.clear();