@marianmeres/ownsuite 2.0.0 → 2.2.1

package/dist/domains/auth.js

@@ -0,0 +1,224 @@
+/**
+ * @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.
+     *
+     *  `remember` translates to a per-login storage pin on the session:
+     *  `true` → `"local"`, `false` → `"session"`, `undefined` → session
+     *  manager's configured default. Silently no-op in the verification-gate
+     *  branch (no JWT yet → nothing to persist). */
+    async #applyAuthResult(result, remember) {
+        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
+        };
+        const storage = remember === true
+            ? "local"
+            : remember === false
+                ? "session"
+                : undefined;
+        this.#session.setAuthenticated({
+            jwt: result.jwt,
+            subject: provisional,
+            expiresAt: result.validUntil ?? null,
+            ...(storage ? { storage } : {}),
+        });
+        // 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, options) {
+        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, options?.remember);
+    }
+    async login(input, options) {
+        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, options?.remember);
+    }
+    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, opts.remember);
+    }
+    /** For the redirect-mode callback page: delegate to the adapter if
+     *  available to extract the result from the current URL/page state.
+     *  `options.remember` pins the resulting session to local/session
+     *  storage — pass the same value the user picked before the redirect. */
+    async handleOAuthCallback(options) {
+        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, options?.remember);
+    }
+}

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

package/dist/domains/profile.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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 { type StoreLike } from "@marianmeres/store";
+import { type PubSub } from "@marianmeres/pubsub";
+import type { OAuthConnection, OAuthProvider, OwnsuiteContext, ProfileAdapter, ProfileResult } from "../types/mod.js";
+import type { SessionManager } from "./session.js";
+export interface ProfileManagerOptions {
+    adapter: ProfileAdapter;
+    session: SessionManager;
+    /** Shared pubsub for event emission. Private if omitted. */
+    pubsub?: PubSub;
+    /** Initial context passed to adapter calls. Extended per-call with
+     *  `jwt` and `signal` by the manager. */
+    context?: OwnsuiteContext;
+}
+export interface ProfileState {
+    /** Null until the first successful fetch. */
+    profile: ProfileResult | null;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Most recent error, or null. Cleared on the next successful call. */
+    error: Error | null;
+}
+/**
+ * Profile manager — singleton state for `/me`.
+ */
+export declare class ProfileManager {
+    #private;
+    constructor(options: ProfileManagerOptions);
+    get subscribe(): StoreLike<ProfileState>["subscribe"];
+    get(): ProfileState;
+    setContext(ctx: OwnsuiteContext): void;
+    replaceContext(ctx: OwnsuiteContext): void;
+    /** Fetch `/me`. Supersedes any in-flight fetch. */
+    fetch(): Promise<ProfileResult>;
+    /** Update profile (currently: email). Triggers a re-verification email
+     *  server-side when the gate is on. Returns the refreshed profile. */
+    update(input: {
+        email?: string;
+        current_password?: string;
+    }): Promise<ProfileResult>;
+    listOAuth(): Promise<OAuthConnection[]>;
+    unlinkOAuth(provider: OAuthProvider): Promise<void>;
+    reset(): void;
+    destroy(): void;
+}

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,92 @@
+/**
+ * @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 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 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.
+     *
+     *  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: {
+        jwt: string;
+        subject: SessionSubject;
+        expiresAt?: number | null;
+        storage?: SessionStorageType;
+    }): 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. 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(): 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 every backend AND in-memory state without
+     *  emitting. Used by teardown. */
+    destroy(): void;
+}