@marianmeres/ownsuite 1.0.3 → 2.1.0

package/dist/domains/profile.js

@@ -0,0 +1,170 @@
+/**
+ * @module domains/profile
+ *
+ * ProfileManager — a singleton (one-row) reactive container for the
+ * authenticated subject's `/me` data: email, roles, verification flag,
+ * whether the account has a password, and the list of linked OAuth
+ * connections.
+ *
+ * Deliberately NOT an OwnedCollectionManager. The underlying `/me` endpoint
+ * is a single-record resource: no list, no optimistic create/delete, and
+ * update returns the full profile. Shoehorning it into the collection
+ * manager would leak CRUD semantics that don't apply and complicate
+ * ownership semantics.
+ *
+ * This manager mutates the companion `SessionManager`'s subject in place
+ * when the profile changes (e.g. email edited) so consumers reading from
+ * `suite.session` see the update without a second fetch.
+ */
+import { createStore } from "@marianmeres/store";
+import { createPubSub } from "@marianmeres/pubsub";
+const EMPTY = {
+    profile: null,
+    loading: false,
+    error: null,
+};
+/**
+ * Profile manager — singleton state for `/me`.
+ */
+export class ProfileManager {
+    #store;
+    #pubsub;
+    #adapter;
+    #session;
+    #context;
+    /** Currently-active read controller, for abort-supersede semantics. */
+    #readController = null;
+    constructor(options) {
+        this.#adapter = options.adapter;
+        this.#session = options.session;
+        this.#pubsub = options.pubsub ?? createPubSub();
+        this.#context = options.context ?? {};
+        this.#store = createStore({ ...EMPTY });
+    }
+    get subscribe() {
+        return this.#store.subscribe;
+    }
+    get() {
+        return this.#store.get();
+    }
+    setContext(ctx) {
+        this.#context = { ...this.#context, ...ctx };
+    }
+    replaceContext(ctx) {
+        this.#context = { ...ctx };
+    }
+    /** Build a per-op context with the current JWT from the session. */
+    #ctxFor(signal) {
+        const jwt = this.#session.getJwt();
+        return {
+            ...this.#context,
+            ...(jwt ? { jwt } : {}),
+            signal,
+        };
+    }
+    #abortActiveRead(reason = "superseded") {
+        if (this.#readController) {
+            try {
+                this.#readController.abort(reason);
+            }
+            catch {
+                // ignore
+            }
+            this.#readController = null;
+        }
+    }
+    /** Fetch `/me`. Supersedes any in-flight fetch. */
+    async fetch() {
+        this.#abortActiveRead();
+        const ctrl = new AbortController();
+        this.#readController = ctrl;
+        this.#store.update((s) => ({ ...s, loading: true }));
+        try {
+            const profile = await this.#adapter.get(this.#ctxFor(ctrl.signal));
+            if (ctrl.signal.aborted) {
+                // A newer request already took over; don't overwrite its data.
+                throw new Error("aborted");
+            }
+            this.#store.set({
+                profile,
+                loading: false,
+                error: null,
+            });
+            // Keep the session's subject in sync with /me so consumers reading
+            // from session don't need to also subscribe to profile.
+            this.#session.patchSubject({
+                email: profile.email,
+                roles: profile.roles,
+                isVerified: profile.isVerified,
+                hasPassword: profile.hasPassword,
+            });
+            return profile;
+        }
+        catch (e) {
+            if (!ctrl.signal.aborted) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                this.#store.update((s) => ({ ...s, loading: false, error: err }));
+            }
+            throw e;
+        }
+        finally {
+            if (this.#readController === ctrl)
+                this.#readController = null;
+        }
+    }
+    /** Update profile (currently: email). Triggers a re-verification email
+     *  server-side when the gate is on. Returns the refreshed profile. */
+    async update(input) {
+        const ctrl = new AbortController();
+        this.#store.update((s) => ({ ...s, loading: true }));
+        try {
+            const profile = await this.#adapter.update(input, this.#ctxFor(ctrl.signal));
+            this.#store.set({ profile, loading: false, error: null });
+            this.#session.patchSubject({
+                email: profile.email,
+                roles: profile.roles,
+                isVerified: profile.isVerified,
+                hasPassword: profile.hasPassword,
+            });
+            this.#pubsub.publish("profile:updated", {
+                type: "profile:updated",
+                timestamp: Date.now(),
+                email: profile.email,
+            });
+            return profile;
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            this.#store.update((s) => ({ ...s, loading: false, error: err }));
+            throw e;
+        }
+    }
+    async listOAuth() {
+        const ctrl = new AbortController();
+        return await this.#adapter.listOAuth(this.#ctxFor(ctrl.signal));
+    }
+    async unlinkOAuth(provider) {
+        const ctrl = new AbortController();
+        await this.#adapter.unlinkOAuth(provider, this.#ctxFor(ctrl.signal));
+        this.#pubsub.publish("oauth:unlinked", {
+            type: "oauth:unlinked",
+            timestamp: Date.now(),
+            provider,
+        });
+        // Refresh so the profile reflects the new connection list.
+        try {
+            await this.fetch();
+        }
+        catch {
+            // swallow — caller already got a successful unlink
+        }
+    }
+    reset() {
+        this.#abortActiveRead("reset");
+        this.#store.set({ ...EMPTY });
+    }
+    destroy() {
+        this.#abortActiveRead("destroyed");
+        this.#store.set({ ...EMPTY });
+    }
+}

package/dist/domains/session.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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 { type StoreLike } from "@marianmeres/store";
+import { type PubSub } from "@marianmeres/pubsub";
+import type { SessionState, SessionStorage, SessionStorageType, SessionSubject } from "../types/auth.js";
+/** In-memory session storage — survives the current JS realm only. */
+export declare function createMemorySessionStorage(): SessionStorage;
+/** 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 declare function resolveSessionStorage(type?: SessionStorageType): SessionStorage;
+export interface SessionManagerOptions {
+    /** Storage backend for session persistence. Default: "local". */
+    storage?: SessionStorageType;
+    /** Key used in the storage backend. Default: "ownsuite:session". */
+    storageKey?: string;
+    /** Shared pubsub for event emission. When omitted, a private one is
+     *  created — useful for standalone testing of the manager. */
+    pubsub?: PubSub;
+}
+/**
+ * Session manager — pure reactive state + persistence, no HTTP.
+ *
+ * Writes are driven by the AuthManager. On construction it hydrates from
+ * storage; if the stored JWT has expired, it transitions to anonymous and
+ * clears the storage.
+ */
+export declare class SessionManager {
+    #private;
+    constructor(options?: SessionManagerOptions);
+    /** Svelte-compatible subscribe. */
+    get subscribe(): StoreLike<SessionState>["subscribe"];
+    /** Current session state snapshot. */
+    get(): SessionState;
+    get isAuthenticated(): boolean;
+    get isUnverified(): boolean;
+    get isAnonymous(): boolean;
+    /** JWT for adapter `Authorization` headers, or null when anonymous. */
+    getJwt(): string | null;
+    /** Transition to authenticated. Called after login/register/OAuth succeed
+     *  and the subject has been loaded. */
+    setAuthenticated(opts: {
+        jwt: string;
+        subject: SessionSubject;
+        expiresAt?: number | null;
+    }): void;
+    /** 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: string): void;
+    /** Drop the session. Storage is cleared; downstream domains should be
+     *  reset by the suite orchestrator. */
+    clear(): void;
+    /** Patch the subject in place without touching the JWT. Used when the
+     *  profile manager changes email / linked providers / etc. */
+    patchSubject(patch: Partial<SessionSubject>): void;
+    /** Test / reset hook — clears storage AND in-memory state without
+     *  emitting. Used by teardown. */
+    destroy(): void;
+}

package/dist/domains/session.js

@@ -0,0 +1,226 @@
+/**
+ * @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 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 from
+ * storage; if the stored JWT has expired, it transitions to anonymous and
+ * clears the storage.
+ */
+export class SessionManager {
+    #store;
+    #pubsub;
+    #storage;
+    #storageKey;
+    constructor(options = {}) {
+        this.#pubsub = options.pubsub ?? createPubSub();
+        this.#storage = resolveSessionStorage(options.storage ?? "local");
+        this.#storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+        this.#store = createStore({ ...EMPTY });
+        this.#hydrate();
+    }
+    /** Read from storage and populate the store. Expired sessions are wiped. */
+    #hydrate() {
+        const raw = this.#storage.get(this.#storageKey);
+        if (!raw)
+            return;
+        try {
+            const parsed = JSON.parse(raw);
+            // Basic shape check.
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                typeof parsed.status !== "string") {
+                this.#storage.del(this.#storageKey);
+                return;
+            }
+            // Expiry check (only meaningful when expiresAt is set).
+            if (parsed.expiresAt !== null &&
+                parsed.expiresAt !== undefined &&
+                parsed.expiresAt * 1000 <= Date.now()) {
+                this.#storage.del(this.#storageKey);
+                return;
+            }
+            this.#store.set(parsed);
+        }
+        catch {
+            this.#storage.del(this.#storageKey);
+        }
+    }
+    #persist() {
+        const s = this.#store.get();
+        if (s.status === "anonymous") {
+            this.#storage.del(this.#storageKey);
+        }
+        else {
+            this.#storage.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. */
+    setAuthenticated(opts) {
+        const { jwt, subject, expiresAt = null } = opts;
+        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. Storage is cleared; downstream domains should be
+     *  reset by the suite orchestrator. */
+    clear() {
+        if (this.#store.get().status === "anonymous")
+            return;
+        this.#store.set({ ...EMPTY });
+        this.#persist();
+        this.#emitChange();
+    }
+    /** 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 storage AND in-memory state without
+     *  emitting. Used by teardown. */
+    destroy() {
+        this.#storage.del(this.#storageKey);
+        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);
+        }
+    });
+}