@marianmeres/ownsuite 1.0.3 → 2.1.0

package/dist/domains/auth.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module domains/auth
+ *
+ * AuthManager — verbs for the account lifecycle. Holds no state of its own:
+ *   - credentials flow through to the adapter,
+ *   - server responses are piped into the SessionManager,
+ *   - successful session changes trigger a refresh of owner-scoped domains
+ *     via a caller-supplied `switchIdentity` hook.
+ *
+ * Non-goals (explicit): password strength UI, form validation, rendering,
+ * i18n strings, CSRF/PKCE (server-side), refresh-token rotation, cookie
+ * management.
+ */
+import { type PubSub } from "@marianmeres/pubsub";
+import type { AuthAdapter, AuthTokenResult, OAuthInitOptions, OAuthProvider, OwnsuiteContext, ProfileAdapter } from "../types/mod.js";
+import type { SessionManager } from "./session.js";
+import type { ProfileManager } from "./profile.js";
+export interface AuthManagerOptions {
+    adapter: AuthAdapter;
+    session: SessionManager;
+    /** Profile manager — auth hydrates the session subject from `/me`
+     *  immediately after login so subscribers see roles/isVerified/etc.
+     *  without a second await. */
+    profile: ProfileManager;
+    pubsub?: PubSub;
+    /** Called after a successful identity change (register/login/OAuth
+     *  login/logout). The orchestrator wires this to reset + re-init every
+     *  owner-scoped domain with the fresh context. */
+    onIdentityChanged?: (ctx: OwnsuiteContext) => Promise<void> | void;
+    /** Also passed into adapter calls (correlation id, feature flags, etc.).
+     *  The JWT + signal are added per-op by the manager. */
+    context?: OwnsuiteContext;
+    /** When the adapter provides a profile adapter explicitly, we pass it
+     *  through to resolving the subject. Kept optional for mock-driven
+     *  tests that don't need a separate profile fetch. */
+    profileAdapter?: ProfileAdapter;
+}
+export declare class AuthManager {
+    #private;
+    constructor(options: AuthManagerOptions);
+    setContext(ctx: OwnsuiteContext): void;
+    replaceContext(ctx: OwnsuiteContext): void;
+    register(input: {
+        email: string;
+        password: string;
+        password_confirm: string;
+        roles?: string[];
+        extras?: Record<string, unknown>;
+    }): Promise<AuthTokenResult>;
+    login(input: {
+        email: string;
+        password: string;
+    }): Promise<AuthTokenResult>;
+    logout(): Promise<void>;
+    resendVerification(input: {
+        email: string;
+        lang?: string;
+    }): Promise<void>;
+    requestPasswordReset(input: {
+        email: string;
+        lang?: string;
+    }): Promise<void>;
+    changePassword(input: {
+        current_password?: string;
+        new_password: string;
+        confirm_password: string;
+        token?: string;
+    }): Promise<void>;
+    deleteAccount(input: {
+        password?: string;
+        confirm?: boolean;
+    }): Promise<void>;
+    /**
+     * Begin an OAuth flow. Returns:
+     *   - For popup mode: a Promise that resolves when the popup posts back
+     *     an auth result.
+     *   - For redirect mode: nothing useful; the top window navigates away.
+     */
+    initiateOAuth(provider: OAuthProvider, opts: OAuthInitOptions): Promise<AuthTokenResult | void>;
+    /** For the redirect-mode callback page: delegate to the adapter if
+     *  available to extract the result from the current URL/page state. */
+    handleOAuthCallback(): Promise<AuthTokenResult | void>;
+}

package/dist/domains/auth.js

@@ -0,0 +1,211 @@
+/**
+ * @module domains/auth
+ *
+ * AuthManager — verbs for the account lifecycle. Holds no state of its own:
+ *   - credentials flow through to the adapter,
+ *   - server responses are piped into the SessionManager,
+ *   - successful session changes trigger a refresh of owner-scoped domains
+ *     via a caller-supplied `switchIdentity` hook.
+ *
+ * Non-goals (explicit): password strength UI, form validation, rendering,
+ * i18n strings, CSRF/PKCE (server-side), refresh-token rotation, cookie
+ * management.
+ */
+import { createPubSub } from "@marianmeres/pubsub";
+import { openOAuthPopup } from "../oauth/popup.js";
+export class AuthManager {
+    #pubsub;
+    #adapter;
+    #session;
+    #profile;
+    #onIdentityChanged;
+    #context;
+    constructor(options) {
+        this.#adapter = options.adapter;
+        this.#session = options.session;
+        this.#profile = options.profile;
+        this.#pubsub = options.pubsub ?? createPubSub();
+        this.#onIdentityChanged = options.onIdentityChanged;
+        this.#context = options.context ?? {};
+    }
+    setContext(ctx) {
+        this.#context = { ...this.#context, ...ctx };
+    }
+    replaceContext(ctx) {
+        this.#context = { ...ctx };
+    }
+    #ctx(signal) {
+        const jwt = this.#session.getJwt();
+        return {
+            ...this.#context,
+            ...(jwt ? { jwt } : {}),
+            ...(signal ? { signal } : {}),
+        };
+    }
+    /** Flip the session state based on an AuthTokenResult. When the JWT is
+     *  present, we pull the profile to build a complete subject. When the
+     *  server returned requiresVerification, we surface the "unverified"
+     *  status without any profile fetch. Triggers identity-change hook on
+     *  actual login. */
+    async #applyAuthResult(result) {
+        if (result.requiresVerification || !result.jwt) {
+            this.#session.setUnverified(result.email);
+            this.#pubsub.publish("auth:verification:required", {
+                type: "auth:verification:required",
+                timestamp: Date.now(),
+                email: result.email,
+            });
+            return result;
+        }
+        // Set a provisional subject so subsequent calls (including the profile
+        // fetch itself) see the JWT on the session.
+        const provisional = {
+            id: "",
+            email: result.email,
+            roles: result.roles ?? [],
+            isVerified: result.isVerified ?? false,
+            hasPassword: true, // corrected by profile fetch below
+        };
+        this.#session.setAuthenticated({
+            jwt: result.jwt,
+            subject: provisional,
+            expiresAt: result.validUntil ?? null,
+        });
+        // Best-effort hydrate the subject from /me. If this fails we keep the
+        // provisional subject; consumers can retry via profile.fetch().
+        try {
+            await this.#profile.fetch();
+        }
+        catch {
+            // swallow — session stays authenticated with the provisional subject
+        }
+        if (this.#onIdentityChanged) {
+            try {
+                await this.#onIdentityChanged(this.#ctx());
+            }
+            catch {
+                // swallow — hook errors must not destabilize auth state
+            }
+        }
+        return result;
+    }
+    // ─────────────────────── verbs ──────────────────────────────────────────
+    async register(input) {
+        const result = await this.#adapter.register(input, this.#ctx());
+        this.#pubsub.publish("auth:register", {
+            type: "auth:register",
+            timestamp: Date.now(),
+            email: input.email,
+            requiresVerification: Boolean(result.requiresVerification),
+        });
+        return await this.#applyAuthResult(result);
+    }
+    async login(input) {
+        const result = await this.#adapter.login(input, this.#ctx());
+        this.#pubsub.publish("auth:login", {
+            type: "auth:login",
+            timestamp: Date.now(),
+            email: input.email,
+        });
+        return await this.#applyAuthResult(result);
+    }
+    async logout() {
+        const subjectId = this.#session.get().subject?.id;
+        try {
+            await this.#adapter.logout(this.#ctx());
+        }
+        catch {
+            // server logout is best-effort — still clear locally
+        }
+        this.#session.clear();
+        this.#pubsub.publish("auth:logout", {
+            type: "auth:logout",
+            timestamp: Date.now(),
+            subjectId,
+        });
+        if (this.#onIdentityChanged) {
+            try {
+                await this.#onIdentityChanged(this.#ctx());
+            }
+            catch {
+                // swallow
+            }
+        }
+    }
+    async resendVerification(input) {
+        await this.#adapter.resendVerification(input, this.#ctx());
+    }
+    async requestPasswordReset(input) {
+        await this.#adapter.requestPasswordReset(input, this.#ctx());
+    }
+    async changePassword(input) {
+        await this.#adapter.changePassword(input, this.#ctx());
+    }
+    async deleteAccount(input) {
+        await this.#adapter.deleteAccount(input, this.#ctx());
+        // Clear session locally and fire logout/identity-change.
+        this.#session.clear();
+        this.#pubsub.publish("auth:logout", {
+            type: "auth:logout",
+            timestamp: Date.now(),
+        });
+        if (this.#onIdentityChanged) {
+            try {
+                await this.#onIdentityChanged(this.#ctx());
+            }
+            catch {
+                // swallow
+            }
+        }
+    }
+    /**
+     * Begin an OAuth flow. Returns:
+     *   - For popup mode: a Promise that resolves when the popup posts back
+     *     an auth result.
+     *   - For redirect mode: nothing useful; the top window navigates away.
+     */
+    async initiateOAuth(provider, opts) {
+        const url = this.#adapter.oauthInitUrl(provider, opts, this.#ctx());
+        const mode = opts.mode ?? "popup";
+        if (mode === "redirect") {
+            if (typeof globalThis !== "undefined" && "location" in globalThis) {
+                globalThis.location.href = url;
+            }
+            return;
+        }
+        // popup mode — wait for postMessage.
+        const message = await openOAuthPopup(url);
+        if (message.type === "oauth_link_success") {
+            this.#pubsub.publish("oauth:linked", {
+                type: "oauth:linked",
+                timestamp: Date.now(),
+                connection: { provider },
+            });
+            // Refresh profile so the new connection appears.
+            try {
+                await this.#profile.fetch();
+            }
+            catch {
+                // swallow
+            }
+            return;
+        }
+        // login result
+        const result = {
+            jwt: message.jwt,
+            email: message.email,
+            roles: message.roles ?? [],
+            isVerified: true,
+        };
+        return await this.#applyAuthResult(result);
+    }
+    /** For the redirect-mode callback page: delegate to the adapter if
+     *  available to extract the result from the current URL/page state. */
+    async handleOAuthCallback() {
+        if (!this.#adapter.handleOAuthCallback) {
+            throw new Error("AuthManager: handleOAuthCallback is not implemented by the adapter");
+        }
+        const result = await this.#adapter.handleOAuthCallback(this.#ctx());
+        return await this.#applyAuthResult(result);
+    }
+}

package/dist/domains/base.d.ts

@@ -2,9 +2,10 @@
  * @module domains/base
  *
  * Base domain manager. Provides reactive state, state-machine transitions,
- * optimistic update pattern, and event emission. Mirrors the shape of
- * `@marianmeres/ecsuite`'s `BaseDomainManager` so consumers already familiar
- * with ecsuite can read/subscribe to ownsuite domains identically.
+ * optimistic update pattern, mutation serialization, abort-supersede reads,
+ * and event emission. Mirrors the shape of `@marianmeres/ecsuite`'s
+ * `BaseDomainManager` so consumers already familiar with ecsuite can
+ * read/subscribe to ownsuite domains identically.
  */
 import { type Clog } from "@marianmeres/clog";
 import { type StoreLike } from "@marianmeres/store";
@@ -25,6 +26,7 @@ export interface BaseDomainOptions {
  * @typeParam TAdapter - The adapter interface type for server communication.
  */
 export declare abstract class BaseDomainManager<TData, TAdapter> {
+    #private;
     protected readonly store: StoreLike<DomainStateWrapper<TData>>;
     protected readonly pubsub: PubSub;
     protected readonly domainName: DomainName;
@@ -36,9 +38,17 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     get subscribe(): StoreLike<DomainStateWrapper<TData>>["subscribe"];
     /** Get current state synchronously. */
     get(): DomainStateWrapper<TData>;
+    /** True after `destroy()` has been called. */
+    get isDestroyed(): boolean;
     setAdapter(adapter: TAdapter): void;
     getAdapter(): TAdapter | null;
+    /**
+     * Merge `ctx` into the current context. Keys not present in `ctx` are
+     * preserved. To replace the context entirely use `replaceContext`.
+     */
     setContext(context: OwnsuiteContext): void;
+    /** Replace the context object entirely (no merge with existing). */
+    replaceContext(context: OwnsuiteContext): void;
     getContext(): OwnsuiteContext;
     /** Transition to a new state. */
     protected setState(state: DomainState): void;
@@ -51,14 +61,60 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     /** Emit an event via pubsub. */
     protected emit(event: OwnsuiteEvent): void;
     /**
-     * Execute an async operation with the optimistic-update pattern:
-     *   1. capture current data for rollback
-     *   2. apply optimistic update immediately
-     *   3. flip to "syncing"
-     *   4. on success: mark synced, call onSuccess
-     *   5. on error: restore previous data, set error, call onError
+     * Create a new AbortController registered with this manager. `destroy()`
+     * and `reset()` abort all active controllers. Call `releaseController`
+     * when the operation is done (success or failure) to let the controller
+     * be garbage-collected.
+     */
+    protected newController(): AbortController;
+    /** Stop tracking a controller. Call after the associated op completes. */
+    protected releaseController(ctrl: AbortController): void;
+    /** Abort every active controller (reads, mutations, other). */
+    protected abortAll(reason?: string): void;
+    /**
+     * Serialize mutations. Each call queues behind any in-flight mutation on
+     * this manager. Rejections are swallowed on the chain so subsequent
+     * callers always proceed (their own fn can still throw/reject and the
+     * caller sees it).
+     */
+    protected serializeMutation<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Run a read with abort-supersede semantics. Calling a second read
+     * aborts the first (its signal flips to aborted before/after the
+     * adapter resolves). The callback receives the signal and should check
+     * `signal.aborted` after any async step to skip state writes that would
+     * overwrite a fresher response.
      */
-    protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError) => void): Promise<void>;
+    protected serializeRead(fn: (signal: AbortSignal) => Promise<void>): Promise<void>;
+    /**
+     * Execute an async mutation with the optimistic-update pattern:
+     *   1. apply optimistic update immediately
+     *   2. flip to "syncing"
+     *   3. on success: mark synced, call onSuccess
+     *   4. on error: call onError for caller-driven rollback, then set error
+     *
+     * Callers provide both the optimistic mutation and its inverse (via
+     * `onError`). The inverse runs against the *live* store, which matters
+     * when a refresh landed between the optimistic write and the failure.
+     *
+     * A snapshot is captured via `safeClone` and passed to `onError` for
+     * callers that prefer a whole-data restore over per-change inversion.
+     */
+    protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError, snapshot: TData | null) => void): Promise<void>;
     abstract initialize(): Promise<void>;
+    /**
+     * Reset to `initializing` state. Aborts any in-flight reads/mutations
+     * (their completions become no-ops once they observe `signal.aborted`),
+     * clears cached data, and emits `domain:state:changed`.
+     */
     reset(): void;
+    /**
+     * Dispose of this manager: abort in-flight ops, drop the adapter
+     * reference, and mark destroyed. Subsequent method calls are a best-
+     * effort no-op (they observe aborted controllers and return early).
+     *
+     * Note: the shared pubsub is NOT cleared — other consumers may still
+     * hold subscriptions against it. `Ownsuite.destroy()` owns that.
+     */
+    destroy(): void;
 }

package/dist/domains/base.js

@@ -2,13 +2,35 @@
  * @module domains/base
  *
  * Base domain manager. Provides reactive state, state-machine transitions,
- * optimistic update pattern, and event emission. Mirrors the shape of
- * `@marianmeres/ecsuite`'s `BaseDomainManager` so consumers already familiar
- * with ecsuite can read/subscribe to ownsuite domains identically.
+ * optimistic update pattern, mutation serialization, abort-supersede reads,
+ * and event emission. Mirrors the shape of `@marianmeres/ecsuite`'s
+ * `BaseDomainManager` so consumers already familiar with ecsuite can
+ * read/subscribe to ownsuite domains identically.
  */
 import { createClog } from "@marianmeres/clog";
 import { createStore } from "@marianmeres/store";
 import { createPubSub } from "@marianmeres/pubsub";
+/**
+ * Deep-clone helper with fallback. Uses `structuredClone` where available;
+ * if a payload contains non-cloneable values (functions, class instances),
+ * falls back to a JSON round-trip. A final fallback returns the original
+ * reference (preserves pre-cloning behavior rather than throwing).
+ */
+function safeClone(value) {
+    if (value === null || value === undefined)
+        return value;
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            return value;
+        }
+    }
+}
 /**
  * Abstract base class for ownsuite domain managers.
  *
@@ -22,6 +44,13 @@ export class BaseDomainManager {
     clog;
     adapter = null;
     context = {};
+    /** Mutation chain head. Each create/update/delete appends itself here. */
+    #mutationChain = Promise.resolve();
+    /** Controller for the currently-active read (initialize/refresh). */
+    #readController = null;
+    /** All active controllers created via `newController()`, for bulk abort. */
+    #activeControllers = new Set();
+    #destroyed = false;
     constructor(domainName, options = {}) {
         this.domainName = domainName;
         this.clog = createClog(`ownsuite:${domainName}`, { color: "auto" });
@@ -43,15 +72,27 @@ export class BaseDomainManager {
     get() {
         return this.store.get();
     }
+    /** True after `destroy()` has been called. */
+    get isDestroyed() {
+        return this.#destroyed;
+    }
     setAdapter(adapter) {
         this.adapter = adapter;
     }
     getAdapter() {
         return this.adapter;
     }
+    /**
+     * Merge `ctx` into the current context. Keys not present in `ctx` are
+     * preserved. To replace the context entirely use `replaceContext`.
+     */
     setContext(context) {
         this.context = { ...this.context, ...context };
     }
+    /** Replace the context object entirely (no merge with existing). */
+    replaceContext(context) {
+        this.context = { ...context };
+    }
     getContext() {
         return { ...this.context };
     }
@@ -111,15 +152,91 @@ export class BaseDomainManager {
         this.pubsub.publish(event.type, event);
     }
     /**
-     * Execute an async operation with the optimistic-update pattern:
-     *   1. capture current data for rollback
-     *   2. apply optimistic update immediately
-     *   3. flip to "syncing"
-     *   4. on success: mark synced, call onSuccess
-     *   5. on error: restore previous data, set error, call onError
+     * Create a new AbortController registered with this manager. `destroy()`
+     * and `reset()` abort all active controllers. Call `releaseController`
+     * when the operation is done (success or failure) to let the controller
+     * be garbage-collected.
+     */
+    newController() {
+        const ctrl = new AbortController();
+        this.#activeControllers.add(ctrl);
+        return ctrl;
+    }
+    /** Stop tracking a controller. Call after the associated op completes. */
+    releaseController(ctrl) {
+        this.#activeControllers.delete(ctrl);
+    }
+    /** Abort every active controller (reads, mutations, other). */
+    abortAll(reason) {
+        for (const c of this.#activeControllers) {
+            try {
+                c.abort(reason);
+            }
+            catch {
+                // ignore — abort() is idempotent in practice
+            }
+        }
+        this.#activeControllers.clear();
+        this.#readController = null;
+    }
+    /**
+     * Serialize mutations. Each call queues behind any in-flight mutation on
+     * this manager. Rejections are swallowed on the chain so subsequent
+     * callers always proceed (their own fn can still throw/reject and the
+     * caller sees it).
+     */
+    async serializeMutation(fn) {
+        const prev = this.#mutationChain;
+        // Chain tail intentionally swallows rejection — serial order only.
+        const mine = prev.then(() => fn(), () => fn());
+        this.#mutationChain = mine.then(() => undefined, () => undefined);
+        return mine;
+    }
+    /**
+     * Run a read with abort-supersede semantics. Calling a second read
+     * aborts the first (its signal flips to aborted before/after the
+     * adapter resolves). The callback receives the signal and should check
+     * `signal.aborted` after any async step to skip state writes that would
+     * overwrite a fresher response.
+     */
+    async serializeRead(fn) {
+        // Supersede: abort the previous read if any.
+        if (this.#readController) {
+            try {
+                this.#readController.abort("superseded");
+            }
+            catch {
+                // ignore
+            }
+            this.#activeControllers.delete(this.#readController);
+        }
+        const ctrl = this.newController();
+        this.#readController = ctrl;
+        try {
+            await fn(ctrl.signal);
+        }
+        finally {
+            if (this.#readController === ctrl)
+                this.#readController = null;
+            this.releaseController(ctrl);
+        }
+    }
+    /**
+     * Execute an async mutation with the optimistic-update pattern:
+     *   1. apply optimistic update immediately
+     *   2. flip to "syncing"
+     *   3. on success: mark synced, call onSuccess
+     *   4. on error: call onError for caller-driven rollback, then set error
+     *
+     * Callers provide both the optimistic mutation and its inverse (via
+     * `onError`). The inverse runs against the *live* store, which matters
+     * when a refresh landed between the optimistic write and the failure.
+     *
+     * A snapshot is captured via `safeClone` and passed to `onError` for
+     * callers that prefer a whole-data restore over per-change inversion.
      */
     async withOptimisticUpdate(operation, optimisticUpdate, serverSync, onSuccess, onError) {
-        const previousData = this.store.get().data;
+        const snapshot = safeClone(this.store.get().data);
         optimisticUpdate();
         this.setState("syncing");
         try {
@@ -128,24 +245,59 @@ export class BaseDomainManager {
             onSuccess?.(result);
         }
         catch (e) {
-            if (previousData !== null)
-                this.setData(previousData, false);
             const error = {
                 code: "SYNC_FAILED",
                 message: e instanceof Error ? e.message : "Unknown error",
                 originalError: e,
                 operation,
             };
+            if (onError) {
+                onError(error, snapshot);
+            }
+            else if (snapshot !== null) {
+                // Default rollback: restore full snapshot (pre-1.1.0 behavior).
+                this.setData(snapshot, false);
+            }
             this.setError(error);
-            onError?.(error);
         }
     }
+    /**
+     * Reset to `initializing` state. Aborts any in-flight reads/mutations
+     * (their completions become no-ops once they observe `signal.aborted`),
+     * clears cached data, and emits `domain:state:changed`.
+     */
     reset() {
+        this.abortAll("reset");
+        const prev = this.store.get().state;
         this.store.set({
             state: "initializing",
             data: null,
             error: null,
             lastSyncedAt: null,
         });
+        if (prev !== "initializing") {
+            this.emit({
+                type: "domain:state:changed",
+                domain: this.domainName,
+                timestamp: Date.now(),
+                previousState: prev,
+                newState: "initializing",
+            });
+        }
+    }
+    /**
+     * Dispose of this manager: abort in-flight ops, drop the adapter
+     * reference, and mark destroyed. Subsequent method calls are a best-
+     * effort no-op (they observe aborted controllers and return early).
+     *
+     * Note: the shared pubsub is NOT cleared — other consumers may still
+     * hold subscriptions against it. `Ownsuite.destroy()` owns that.
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.abortAll("destroyed");
+        this.adapter = null;
     }
 }

package/dist/domains/mod.d.ts

@@ -1,2 +1,5 @@
 export * from "./base.js";
 export * from "./owned-collection.js";
+export * from "./session.js";
+export * from "./profile.js";
+export * from "./auth.js";

package/dist/domains/mod.js

@@ -1,2 +1,5 @@
 export * from "./base.js";
 export * from "./owned-collection.js";
+export * from "./session.js";
+export * from "./profile.js";
+export * from "./auth.js";