@marianmeres/ownsuite 2.0.0 → 2.2.1

package/dist/domains/session.js

@@ -0,0 +1,323 @@
+/**
+ * @module domains/session
+ *
+ * SessionManager — source of truth for the JWT and the authenticated subject.
+ *
+ * This is NOT an `OwnedCollectionManager` — there's no list-of-rows and no
+ * remote adapter. The session is a single reactive record, persisted via a
+ * pluggable `SessionStorage`, that drives every other manager (its JWT and
+ * subjectId end up on `OwnsuiteContext`).
+ *
+ * Consumers subscribe directly (`suite.session.subscribe(fn)`) or read the
+ * current snapshot (`suite.session.get()`). Writes go through the high-
+ * level `AuthManager` methods (`login`, `logout`, etc.) which call into
+ * this manager.
+ */
+import { createStore } from "@marianmeres/store";
+import { createPubSub } from "@marianmeres/pubsub";
+const DEFAULT_STORAGE_KEY = "ownsuite:session";
+const BUILT_IN_ORDER = [
+    "local",
+    "session",
+    "memory",
+];
+const EMPTY = {
+    status: "anonymous",
+    subject: null,
+    jwt: null,
+    expiresAt: null,
+};
+/** In-memory session storage — survives the current JS realm only. */
+export function createMemorySessionStorage() {
+    const map = new Map();
+    return {
+        get(k) {
+            return map.has(k) ? map.get(k) : null;
+        },
+        set(k, v) {
+            map.set(k, v);
+        },
+        del(k) {
+            map.delete(k);
+        },
+    };
+}
+/** Resolve a `SessionStorageType` union to a concrete `SessionStorage`.
+ *  Gracefully falls back to memory storage when running in an environment
+ *  without Web Storage (SSR, worker without storage, etc). */
+export function resolveSessionStorage(type = "local") {
+    if (typeof type === "object" && type !== null)
+        return type;
+    if (type === "memory")
+        return createMemorySessionStorage();
+    const backend = type === "session"
+        ? "sessionStorage"
+        : "localStorage";
+    const g = globalThis;
+    const store = g[backend];
+    if (!store)
+        return createMemorySessionStorage();
+    return {
+        get(k) {
+            try {
+                return store.getItem(k);
+            }
+            catch {
+                return null;
+            }
+        },
+        set(k, v) {
+            try {
+                store.setItem(k, v);
+            }
+            catch {
+                // quota exceeded / disabled — degrade silently
+            }
+        },
+        del(k) {
+            try {
+                store.removeItem(k);
+            }
+            catch {
+                // ignore
+            }
+        },
+    };
+}
+/**
+ * Session manager — pure reactive state + persistence, no HTTP.
+ *
+ * Writes are driven by the AuthManager. On construction it hydrates by
+ * probing the built-in backends in order `local → session → memory` and
+ * adopting whichever holds a non-expired payload as the active backend for
+ * the rest of the instance's lifetime (until `clear()`). Stale blobs on the
+ * other built-in backends are wiped on adoption.
+ *
+ * When constructed with a custom `SessionStorage` object, there is a single
+ * backend and per-login `remember` choices are silently ignored.
+ */
+export class SessionManager {
+    #store;
+    #pubsub;
+    #storageKey;
+    /** Set only when the consumer passed a `SessionStorage` object at
+     *  construction — then there is one backend and no toggling. */
+    #customStorage;
+    /** Resolved eagerly in the string-storage case so `clear()` can wipe
+     *  every backend and per-login overrides can switch between them. */
+    #builtIn;
+    #defaultStorageType;
+    #activeStorage;
+    #activeStorageType;
+    constructor(options = {}) {
+        this.#pubsub = options.pubsub ?? createPubSub();
+        this.#storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+        this.#store = createStore({ ...EMPTY });
+        const configured = options.storage ?? "local";
+        if (typeof configured === "string") {
+            this.#customStorage = null;
+            this.#builtIn = {
+                local: resolveSessionStorage("local"),
+                session: resolveSessionStorage("session"),
+                memory: createMemorySessionStorage(),
+            };
+            this.#defaultStorageType = configured;
+            this.#activeStorage = this.#builtIn[configured];
+            this.#activeStorageType = configured;
+        }
+        else {
+            this.#customStorage = configured;
+            this.#builtIn = null;
+            this.#defaultStorageType = "local";
+            this.#activeStorage = configured;
+            this.#activeStorageType = "custom";
+        }
+        this.#hydrate();
+    }
+    /** Try to parse a payload and validate shape + expiry. Returns the state
+     *  on success, or `null` (and deletes the stored blob) on any failure. */
+    #readCandidate(storage) {
+        const raw = storage.get(this.#storageKey);
+        if (!raw)
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                typeof parsed.status !== "string") {
+                storage.del(this.#storageKey);
+                return null;
+            }
+            if (parsed.expiresAt !== null &&
+                parsed.expiresAt !== undefined &&
+                parsed.expiresAt * 1000 <= Date.now()) {
+                storage.del(this.#storageKey);
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            storage.del(this.#storageKey);
+            return null;
+        }
+    }
+    /** Read from storage and populate the store. Expired sessions are wiped.
+     *  In the built-in case, probes `local → session → memory` and wipes
+     *  the losing backends so stale blobs can't leak back in. */
+    #hydrate() {
+        if (this.#customStorage) {
+            const parsed = this.#readCandidate(this.#customStorage);
+            if (parsed)
+                this.#store.set(parsed);
+            return;
+        }
+        const builtIn = this.#builtIn;
+        for (const type of BUILT_IN_ORDER) {
+            const parsed = this.#readCandidate(builtIn[type]);
+            if (!parsed)
+                continue;
+            // Adopt this backend; wipe the others so a later login-with-toggle
+            // can't accidentally re-hydrate a stale blob.
+            for (const other of BUILT_IN_ORDER) {
+                if (other !== type)
+                    builtIn[other].del(this.#storageKey);
+            }
+            this.#activeStorage = builtIn[type];
+            this.#activeStorageType = type;
+            this.#store.set(parsed);
+            return;
+        }
+    }
+    #persist() {
+        const s = this.#store.get();
+        if (s.status === "anonymous") {
+            this.#activeStorage.del(this.#storageKey);
+        }
+        else {
+            this.#activeStorage.set(this.#storageKey, JSON.stringify(s));
+        }
+    }
+    #emitChange() {
+        this.#pubsub.publish("auth:session:changed", {
+            type: "auth:session:changed",
+            timestamp: Date.now(),
+            session: this.#store.get(),
+        });
+    }
+    /** Svelte-compatible subscribe. */
+    get subscribe() {
+        return this.#store.subscribe;
+    }
+    /** Current session state snapshot. */
+    get() {
+        return this.#store.get();
+    }
+    get isAuthenticated() {
+        return this.#store.get().status === "authenticated";
+    }
+    get isUnverified() {
+        return this.#store.get().status === "unverified";
+    }
+    get isAnonymous() {
+        return this.#store.get().status === "anonymous";
+    }
+    /** JWT for adapter `Authorization` headers, or null when anonymous. */
+    getJwt() {
+        return this.#store.get().jwt;
+    }
+    /** Transition to authenticated. Called after login/register/OAuth succeed
+     *  and the subject has been loaded.
+     *
+     *  When `opts.storage` is one of `"local"` / `"session"` / `"memory"`,
+     *  pins this session to that built-in backend; subsequent
+     *  `patchSubject` / `setUnverified` writes land on the same backend.
+     *  The previously-active backend's blob is wiped as part of the switch
+     *  so "Remember me" toggles don't leave stale data behind.
+     *
+     *  Ignored when the manager was constructed with a custom `SessionStorage`
+     *  object (single backend) or when `opts.storage` is itself an object
+     *  (no multi-backend custom storage by design). */
+    setAuthenticated(opts) {
+        const { jwt, subject, expiresAt = null, storage } = opts;
+        if (typeof storage === "string" && this.#builtIn) {
+            if (this.#activeStorage !== this.#builtIn[storage]) {
+                this.#activeStorage.del(this.#storageKey);
+                this.#activeStorage = this.#builtIn[storage];
+                this.#activeStorageType = storage;
+            }
+        }
+        this.#store.set({
+            status: "authenticated",
+            subject,
+            jwt,
+            expiresAt,
+        });
+        this.#persist();
+        this.#emitChange();
+    }
+    /** Server confirmed credentials but refuses login until email is
+     *  verified. Expose the email so the UI can prompt "check your inbox"
+     *  without a second server call. No JWT in this state. */
+    setUnverified(email) {
+        this.#store.set({
+            status: "unverified",
+            subject: {
+                id: "",
+                email,
+                roles: [],
+                isVerified: false,
+                hasPassword: false,
+            },
+            jwt: null,
+            expiresAt: null,
+        });
+        this.#persist();
+        this.#emitChange();
+    }
+    /** Drop the session. Every built-in backend (local + session + memory)
+     *  is wiped — not just the active one — so stale blobs from a previous
+     *  "Remember me" toggle can't leak back in on the next construction.
+     *  Resets the active backend to the manager's configured default.
+     *  Downstream domains should be reset by the suite orchestrator. */
+    clear() {
+        this.#wipeAllBackends();
+        if (this.#builtIn) {
+            this.#activeStorage = this.#builtIn[this.#defaultStorageType];
+            this.#activeStorageType = this.#defaultStorageType;
+        }
+        if (this.#store.get().status === "anonymous")
+            return;
+        this.#store.set({ ...EMPTY });
+        this.#emitChange();
+    }
+    #wipeAllBackends() {
+        if (this.#customStorage) {
+            this.#customStorage.del(this.#storageKey);
+            return;
+        }
+        const builtIn = this.#builtIn;
+        for (const type of BUILT_IN_ORDER) {
+            builtIn[type].del(this.#storageKey);
+        }
+    }
+    /** Patch the subject in place without touching the JWT. Used when the
+     *  profile manager changes email / linked providers / etc. */
+    patchSubject(patch) {
+        const s = this.#store.get();
+        if (!s.subject)
+            return;
+        const next = {
+            ...s,
+            subject: { ...s.subject, ...patch },
+        };
+        this.#store.set(next);
+        this.#persist();
+        this.#emitChange();
+    }
+    /** Test / reset hook — clears every backend AND in-memory state without
+     *  emitting. Used by teardown. */
+    destroy() {
+        this.#wipeAllBackends();
+        this.#store.set({ ...EMPTY });
+    }
+}

package/dist/mod.d.ts

@@ -29,3 +29,4 @@ export * from "./ownsuite.js";
 export * from "./domains/mod.js";
 export * from "./types/mod.js";
 export * from "./adapters/mod.js";
+export * from "./oauth/popup.js";

package/dist/mod.js

@@ -29,3 +29,4 @@ export * from "./ownsuite.js";
 export * from "./domains/mod.js";
 export * from "./types/mod.js";
 export * from "./adapters/mod.js";
+export * from "./oauth/popup.js";

package/dist/oauth/popup.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module oauth/popup
+ *
+ * `openOAuthPopup(url)` — opens a popup window at the OAuth init URL and
+ * resolves with the postMessage the server's callback page posts back.
+ *
+ * Server shape (stack-account): the OAuth callback page renders a `<script>`
+ * that does `window.opener.postMessage({ type, jwt, email, ... }, "*")`.
+ * We listen for those messages, validate the `type` field, and resolve.
+ *
+ * For tests, an injectable window-like interface lets us shim `postMessage`
+ * via a MessageChannel without a real browser.
+ */
+export interface OAuthPopupLoginMessage {
+    type: "oauth_login_success";
+    jwt: string;
+    email: string;
+    roles?: string[];
+    isNewAccount?: boolean;
+    redirectUrl?: string;
+}
+export interface OAuthPopupLinkMessage {
+    type: "oauth_link_success";
+    provider: string;
+}
+export interface OAuthPopupErrorMessage {
+    type: "oauth_error";
+    error: string;
+}
+export type OAuthPopupMessage = OAuthPopupLoginMessage | OAuthPopupLinkMessage;
+/**
+ * Minimal window-like surface we need. Real `Window` satisfies this; tests
+ * supply a shim.
+ */
+export interface PopupWindowHost {
+    open(url: string, target: string, features?: string): PopupWindowHandle | null;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+}
+export interface PopupWindowHandle {
+    closed: boolean;
+    focus?(): void;
+    close?(): void;
+}
+export interface OpenOAuthPopupOptions {
+    /** Host window — defaults to `globalThis` when running in the browser. */
+    host?: PopupWindowHost;
+    /** How often to poll for popup-closed-without-message. Default 500ms. */
+    closedPollMs?: number;
+    /** Hard timeout in ms; 0 disables. Default 0. */
+    timeoutMs?: number;
+    /** Restrict accepted message origins. Default: no origin check (the
+     *  server's postMessage uses "*" intentionally; origin validation is the
+     *  caller's responsibility if needed). */
+    expectedOrigin?: string;
+    /** Popup window features string. */
+    features?: string;
+}
+/**
+ * Open the OAuth popup at `url` and await a success message from it.
+ * Rejects if the popup is closed before a message arrives, if the received
+ * message is an error, or if the optional timeout fires.
+ */
+export declare function openOAuthPopup(url: string, options?: OpenOAuthPopupOptions): Promise<OAuthPopupMessage>;

package/dist/oauth/popup.js

@@ -0,0 +1,104 @@
+/**
+ * @module oauth/popup
+ *
+ * `openOAuthPopup(url)` — opens a popup window at the OAuth init URL and
+ * resolves with the postMessage the server's callback page posts back.
+ *
+ * Server shape (stack-account): the OAuth callback page renders a `<script>`
+ * that does `window.opener.postMessage({ type, jwt, email, ... }, "*")`.
+ * We listen for those messages, validate the `type` field, and resolve.
+ *
+ * For tests, an injectable window-like interface lets us shim `postMessage`
+ * via a MessageChannel without a real browser.
+ */
+const DEFAULT_FEATURES = "width=500,height=700,noopener=no,noreferrer=no";
+/**
+ * Open the OAuth popup at `url` and await a success message from it.
+ * Rejects if the popup is closed before a message arrives, if the received
+ * message is an error, or if the optional timeout fires.
+ */
+export function openOAuthPopup(url, options = {}) {
+    const host = (options.host ?? globalThis);
+    if (typeof host.open !== "function" || typeof host.addEventListener !== "function") {
+        return Promise.reject(new Error("openOAuthPopup: host window does not support popups"));
+    }
+    const features = options.features ?? DEFAULT_FEATURES;
+    const closedPollMs = options.closedPollMs ?? 500;
+    const popup = host.open(url, "oauth_popup", features);
+    if (!popup) {
+        return Promise.reject(new Error("OAUTH_POPUP_BLOCKED"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let pollTimer;
+        let timeoutTimer;
+        const cleanup = () => {
+            settled = true;
+            host.removeEventListener("message", onMessage);
+            if (pollTimer !== undefined)
+                clearInterval(pollTimer);
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+        };
+        const onMessage = (event) => {
+            if (settled)
+                return;
+            if (options.expectedOrigin !== undefined &&
+                event.origin !== options.expectedOrigin) {
+                return; // silently drop mismatched origin messages
+            }
+            const data = event.data;
+            if (!data || typeof data !== "object" || typeof data.type !== "string") {
+                return;
+            }
+            if (data.type === "oauth_login_success" ||
+                data.type === "oauth_link_success") {
+                cleanup();
+                try {
+                    popup.close?.();
+                }
+                catch {
+                    // ignore
+                }
+                resolve(data);
+                return;
+            }
+            if (data.type === "oauth_error") {
+                cleanup();
+                try {
+                    popup.close?.();
+                }
+                catch {
+                    // ignore
+                }
+                reject(new Error(data.error));
+                return;
+            }
+        };
+        host.addEventListener("message", onMessage);
+        if (closedPollMs > 0) {
+            pollTimer = setInterval(() => {
+                if (settled)
+                    return;
+                if (popup.closed) {
+                    cleanup();
+                    reject(new Error("OAUTH_POPUP_CLOSED"));
+                }
+            }, closedPollMs);
+        }
+        if (options.timeoutMs && options.timeoutMs > 0) {
+            timeoutTimer = setTimeout(() => {
+                if (settled)
+                    return;
+                cleanup();
+                try {
+                    popup.close?.();
+                }
+                catch {
+                    // ignore
+                }
+                reject(new Error("OAUTH_POPUP_TIMEOUT"));
+            }, options.timeoutMs);
+        }
+    });
+}

package/dist/ownsuite.d.ts

@@ -14,7 +14,11 @@ import { type Subscriber, type Unsubscriber } from "@marianmeres/pubsub";
 import type { DomainError, OwnsuiteContext } from "./types/state.js";
 import type { OwnedCollectionAdapter } from "./types/adapter.js";
 import type { OwnsuiteEventType } from "./types/events.js";
+import type { AuthAdapter, ProfileAdapter, SessionStorageType } from "./types/auth.js";
 import { OwnedCollectionManager } from "./domains/owned-collection.js";
+import { AuthManager } from "./domains/auth.js";
+import { ProfileManager } from "./domains/profile.js";
+import { SessionManager } from "./domains/session.js";
 /**
  * Configuration for a single domain at construction time. The caller
  * provides a unique name and an adapter. A custom `getRowId` is optional
@@ -32,6 +36,18 @@ export interface OwnsuiteConfig {
     domains?: Record<string, OwnsuiteDomainConfig>;
     /** Auto-initialize all registered domains on creation (default: false). */
     autoInitialize?: boolean;
+    /** Auth / profile adapters. When present, ownsuite builds the
+     *  SessionManager / AuthManager / ProfileManager trio and exposes them
+     *  as `suite.auth`, `suite.profile`, `suite.session`. */
+    adapters?: {
+        auth?: AuthAdapter;
+        profile?: ProfileAdapter;
+    };
+    /** Session persistence config. Ignored when no auth adapter is provided. */
+    session?: {
+        storage?: SessionStorageType;
+        storageKey?: string;
+    };
 }
 /** Options for {@link Ownsuite.setContext}. */
 export interface SetContextOptions {
@@ -60,6 +76,11 @@ export interface SetContextOptions {
  */
 export declare class Ownsuite {
     #private;
+    /** Optional auth/session/profile managers. Present iff `adapters.auth`
+     *  was supplied at construction. */
+    readonly session: SessionManager | null;
+    readonly auth: AuthManager | null;
+    readonly profile: ProfileManager | null;
     constructor(config?: OwnsuiteConfig);
     /** True after `destroy()` has been called. */
     get isDestroyed(): boolean;

package/dist/ownsuite.js

@@ -13,6 +13,9 @@
 import { createClog } from "@marianmeres/clog";
 import { createPubSub, } from "@marianmeres/pubsub";
 import { OwnedCollectionManager } from "./domains/owned-collection.js";
+import { AuthManager } from "./domains/auth.js";
+import { ProfileManager } from "./domains/profile.js";
+import { SessionManager } from "./domains/session.js";
 /**
  * Main Ownsuite class — coordinates owner-scoped domain managers.
  *
@@ -38,9 +41,70 @@ export class Ownsuite {
     // deno-lint-ignore no-explicit-any
     #domains = new Map();
     #destroyed = false;
+    /** Optional auth/session/profile managers. Present iff `adapters.auth`
+     *  was supplied at construction. */
+    session = null;
+    auth = null;
+    profile = null;
     constructor(config = {}) {
         this.#pubsub = createPubSub();
         this.#context = { ...(config.context ?? {}) };
+        // Build session / auth / profile managers if the auth adapter is wired.
+        if (config.adapters?.auth) {
+            const session = new SessionManager({
+                storage: config.session?.storage,
+                storageKey: config.session?.storageKey,
+                pubsub: this.#pubsub,
+            });
+            this.session = session;
+            // Profile adapter is optional but strongly encouraged. Without it
+            // login still works — we just don't hydrate roles/isVerified from
+            // /me after auth and consumers must call auth-result-based state
+            // themselves.
+            const profileAdapter = config.adapters.profile;
+            if (profileAdapter) {
+                this.profile = new ProfileManager({
+                    adapter: profileAdapter,
+                    session,
+                    pubsub: this.#pubsub,
+                    context: this.#context,
+                });
+            }
+            // AuthManager requires a profile manager to hydrate the subject
+            // after login. If none was provided, build a stub that throws —
+            // AuthManager will still call it inside a try/catch and recover.
+            const profileForAuth = this.profile ?? new ProfileManager({
+                adapter: {
+                    get: () => Promise.reject(new Error("no profile adapter configured")),
+                    update: () => Promise.reject(new Error("no profile adapter configured")),
+                    listOAuth: () => Promise.resolve([]),
+                    unlinkOAuth: () => Promise.reject(new Error("no profile adapter configured")),
+                },
+                session,
+                pubsub: this.#pubsub,
+                context: this.#context,
+            });
+            this.auth = new AuthManager({
+                adapter: config.adapters.auth,
+                session,
+                profile: profileForAuth,
+                pubsub: this.#pubsub,
+                context: this.#context,
+                onIdentityChanged: (ctx) => this.#onIdentityChanged(ctx),
+            });
+            // Listen for session changes to keep the suite-wide context
+            // `jwt` / `subjectId` in sync with the authenticated session.
+            session.subscribe((s) => {
+                const patch = {
+                    jwt: s.jwt ?? undefined,
+                    subjectId: s.subject?.id || undefined,
+                };
+                this.#context = { ...this.#context, ...patch };
+                for (const m of this.#domains.values()) {
+                    m.setContext(patch);
+                }
+            });
+        }
         for (const [name, cfg] of Object.entries(config.domains ?? {})) {
             this.registerDomain(name, cfg);
         }
@@ -51,6 +115,26 @@ export class Ownsuite {
             void this.initialize();
         }
     }
+    /** Identity-change hook fired by the AuthManager after a successful
+     *  login / register / logout / OAuth login. Reset every owner-scoped
+     *  domain so their subscribed state reflects the new subject (or the
+     *  anonymous state). Subsequent fetches pick up the new ctx.jwt. */
+    async #onIdentityChanged(ctx) {
+        for (const m of this.#domains.values())
+            m.setContext(ctx);
+        for (const m of this.#domains.values())
+            m.reset();
+        // Re-init for authenticated state; stay at "initializing" for logout
+        // (so stale data doesn't flash while consumers unmount).
+        if (ctx.jwt) {
+            try {
+                await this.initialize();
+            }
+            catch {
+                // initialize() doesn't reject on domain errors, but guard anyway.
+            }
+        }
+    }
     /** True after `destroy()` has been called. */
     get isDestroyed() {
         return this.#destroyed;
@@ -190,6 +274,8 @@ export class Ownsuite {
         for (const m of this.#domains.values())
             m.destroy();
         this.#domains.clear();
+        this.profile?.destroy();
+        this.session?.destroy();
         // Our internal pubsub: clear all subscribers. Best-effort — if a custom
         // pubsub implementation doesn't expose `unsubscribeAll`, skip it.
         const ps = this.#pubsub;