@marianmeres/ownsuite 2.0.0 → 2.1.0

package/AGENTS.md

@@ -19,9 +19,12 @@ entry: "./src/mod.ts"
 
 Client-side helper library for **owner-scoped** UIs. Generic domain managers for CRUD over collections where every row is implicitly filtered to the authenticated subject by the server. Mirrors the shape of `@marianmeres/ecsuite` but applies to arbitrary owner-scoped collections instead of hard-coded e-commerce domains.
 
+**Also (opt-in)** provides the blessed account-lifecycle surface for apps built on `@marianmeres/stack-account`: `suite.auth` (register / login / logout / OAuth init / password reset / delete account), `suite.profile` (`/me` CRUD + OAuth link list), `suite.session` (reactive JWT + subject, pluggable storage). Pass an `AuthAdapter` to `createOwnsuite({ adapters: { auth } })` to attach them.
+
 Pairs with:
 - **`@marianmeres/collection`** — `ownerIdScope` route hook (read-side owner enforcement).
 - **`@marianmeres/stack-common`** — `ownsuiteOptions()` server helper for mounting `/me/*` routes.
+- **`@marianmeres/stack-account`** — default adapters (`createStackAccountAuthAdapter`, `createStackAccountProfileAdapter`) target its REST surface.
 
 ## Architecture
 
@@ -70,17 +73,28 @@ src/
 ├── types/
 │   ├── mod.ts
 │   ├── state.ts                # DomainState/Wrapper/Error, OwnsuiteContext, OwnedCollectionState
-│   ├── events.ts               # OwnsuiteEventType, OwnsuiteEvent union, per-event interfaces
-│   └── adapter.ts              # OwnedCollectionAdapter, OwnedListResult, OwnedRowResult
+│   ├── events.ts               # OwnsuiteEventType, OwnsuiteEvent union (incl. auth:* / profile:* / oauth:*)
+│   ├── adapter.ts              # OwnedCollectionAdapter, OwnedListResult, OwnedRowResult
+│   └── auth.ts                 # AuthAdapter, ProfileAdapter, SessionState/Subject/Status, OAuth*
 ├── domains/
 │   ├── mod.ts
 │   ├── base.ts                 # BaseDomainManager abstract class (mirrors ecsuite)
-│   └── owned-collection.ts     # OwnedCollectionManager<TRow, TCreate, TUpdate>
+│   ├── owned-collection.ts     # OwnedCollectionManager<TRow, TCreate, TUpdate>
+│   ├── session.ts              # SessionManager + pluggable SessionStorage resolver
+│   ├── auth.ts                 # AuthManager (register/login/logout/OAuth/verify/delete)
+│   └── profile.ts              # ProfileManager (/me singleton)
+├── oauth/
+│   └── popup.ts                # openOAuthPopup + injectable PopupWindowHost for tests
 └── adapters/
     ├── mod.ts
-    └── mock.ts                 # createMockOwnedCollectionAdapter for tests
+    ├── mock.ts                 # createMockOwnedCollectionAdapter
+    ├── mock-auth.ts            # createMockAuthAdapter / createMockProfileAdapter / createMockAuthStore
+    └── stack-account.ts        # createStackAccountAuthAdapter / createStackAccountProfileAdapter
 tests/
-└── ownsuite.test.ts
+├── ownsuite.test.ts            # core suite + OwnedCollectionManager
+├── concurrency.test.ts         # critical-invariant coverage (abort-supersede, rollback, etc.)
+├── auth.test.ts                # AuthManager / ProfileManager / SessionManager
+└── oauth-popup.test.ts         # openOAuthPopup message / timeout / close / origin semantics
 ```
 
 ## Key Exports
@@ -110,8 +124,65 @@ export type {
 // Mock adapter (for tests)
 export { createMockOwnedCollectionAdapter } from "./adapters/mod.ts";
 export type { MockAdapterOptions } from "./adapters/mod.ts";
+
+// Account lifecycle (optional — attached when adapters.auth is supplied)
+export { SessionManager, AuthManager, ProfileManager } from "./domains/mod.ts";
+export type {
+	AuthAdapter, ProfileAdapter, AuthTokenResult, ProfileResult,
+	SessionState, SessionSubject, SessionStatus,
+	SessionStorage, SessionStorageType,
+	OAuthConnection, OAuthProvider, OAuthInitOptions, OAuthAction,
+} from "./types/mod.ts";
+
+// OAuth popup helper
+export { openOAuthPopup } from "./oauth/popup.ts";
+export type {
+	OAuthPopupMessage, OAuthPopupLoginMessage, OAuthPopupLinkMessage,
+	OpenOAuthPopupOptions, PopupWindowHost, PopupWindowHandle,
+} from "./oauth/popup.ts";
+
+// Default stack-account adapters
+export {
+	createStackAccountAuthAdapter,
+	createStackAccountProfileAdapter,
+} from "./adapters/mod.ts";
+export type { StackAccountAdapterOptions } from "./adapters/mod.ts";
+
+// Mock auth adapter (for tests)
+export {
+	createMockAuthAdapter, createMockProfileAdapter,
+	createMockAuthStore, verifyMockAccount,
+} from "./adapters/mod.ts";
+export type { MockAuthStore } from "./adapters/mod.ts";
 ```
 
+## Account lifecycle (optional)
+
+When `adapters.auth` is supplied, `createOwnsuite` instantiates three extra managers and attaches them as readonly suite properties:
+
+- **`suite.session: SessionManager`** — reactive `{ status, subject, jwt, expiresAt }` persisted via pluggable `SessionStorage` (`"local"` / `"session"` / `"memory"` / custom object). Hydrates on construction; discards expired sessions. Exposes `subscribe` (Svelte-compatible), `get()`, and state-mutation methods (`setAuthenticated`, `setUnverified`, `clear`, `patchSubject`). Writes are driven by `AuthManager`, not consumers directly.
+
+- **`suite.auth: AuthManager`** — verbs only, no state. `register` / `login` / `logout` / `resendVerification` / `requestPasswordReset` / `changePassword` / `deleteAccount` / `initiateOAuth` (`mode: "popup" | "redirect"`) / `handleOAuthCallback` (redirect mode). Each call pipes the result into the session and fires an `onIdentityChanged` hook that resets + re-initializes every owner-scoped domain with the fresh context.
+
+- **`suite.profile: ProfileManager`** — singleton (one-row) `/me` CRUD. `fetch` / `update` / `listOAuth` / `unlinkOAuth`. Every successful fetch/update patches the session subject in place so consumers reading `suite.session` see email / roles / verification / connections without a second fetch. Update emits `profile:updated`.
+
+The session subscribes to its own store and propagates `ctx.jwt` + `ctx.subjectId` into every registered owner-scoped domain automatically — authentication changes propagate without any manual wiring from consumers.
+
+### Auth events (emitted on the shared pubsub)
+
+- `auth:register` — `{ email, requiresVerification }`
+- `auth:login` — `{ email }`
+- `auth:logout` — `{ subjectId? }`
+- `auth:session:changed` — `{ session: SessionState }`
+- `auth:verification:required` — `{ email }` (fired when `status` transitions to `"unverified"`)
+- `profile:updated` — `{ email }`
+- `oauth:linked` — `{ connection }`
+- `oauth:unlinked` — `{ provider }`
+
+### OAuth popup protocol
+
+`suite.auth.initiateOAuth(provider, opts)` with `mode: "popup"` opens a popup at the server's `/oauth/{provider}/init` URL and awaits a `postMessage` from the server's callback page (`{ type: "oauth_login_success" | "oauth_link_success" | "oauth_error", ... }`). For `mode: "redirect"` the top window navigates and the app's callback page calls `suite.auth.handleOAuthCallback()` on mount.
+
 ## State Machine
 
 ```
@@ -290,13 +361,15 @@ dev:
 ## Testing
 
 ```bash
-deno task test       # run all tests (26 tests across ownsuite.test.ts + concurrency.test.ts)
+deno task test       # run all tests (44 tests across 4 files)
 deno task test:watch # watch mode
 ```
 
-`tests/concurrency.test.ts` covers the critical invariants: concurrent
-mutations, abort-supersede, getOne-not-setting-error, phantom-row
-prevention, destroy semantics, and the errors()/hasErrors() helpers.
+Coverage by file:
+- `tests/ownsuite.test.ts` — core suite + `OwnedCollectionManager` CRUD, events, rollback.
+- `tests/concurrency.test.ts` — critical invariants: concurrent mutations, abort-supersede, `getOne` not setting error, phantom-row prevention, destroy semantics, `errors()`/`hasErrors()` helpers.
+- `tests/auth.test.ts` — `AuthManager` / `ProfileManager` / `SessionManager`: register / login / logout / unverified gate / OAuth login (popup + redirect) / OAuth unlink / profile update patching session / deleteAccount / identity-change hook propagation.
+- `tests/oauth-popup.test.ts` — `openOAuthPopup` message / timeout / popup-closed / origin-mismatch semantics via injectable `PopupWindowHost`.
 
 ## Build & Publish
 
@@ -383,6 +456,12 @@ Non-breaking additions: `suite.destroy()`, `suite.errors()`,
 `suite.hasErrors()`, `suite.setContext(ctx, { replace, refresh })`,
 `manager.isDestroyed`, `manager.replaceContext(ctx)`.
 
+**Account lifecycle managers (opt-in addition).** `suite.auth` /
+`suite.session` / `suite.profile` attach automatically when
+`adapters.auth` is passed to `createOwnsuite`. Existing owner-scoped
+CRUD consumers see no change unless they opt in. Full surface is
+described in the "Account lifecycle (optional)" section above.
+
 ## Differences from `@marianmeres/ecsuite`
 
 | Aspect | ecsuite | ownsuite |

package/API.md

@@ -63,6 +63,10 @@ Orchestrator that coordinates owner-scoped domain managers and provides a shared
 
 **Parameters:** same as `createOwnsuite`.
 
+#### `suite.session`, `suite.auth`, `suite.profile`
+
+Readonly properties pointing at the account-lifecycle managers. Populated only when `config.adapters.auth` was supplied — `null` otherwise. Full surface documented under [Account lifecycle (optional)](#account-lifecycle-optional).
+
 #### `suite.registerDomain(name, cfg)`
 
 Register a new domain after construction. Throws if `name` is already registered.
@@ -280,12 +284,23 @@ interface OwnsuiteConfig {
 	context?: OwnsuiteContext;
 	domains?: Record<string, OwnsuiteDomainConfig>;
 	autoInitialize?: boolean;
+	adapters?: {
+		auth?: AuthAdapter;
+		profile?: ProfileAdapter;
+	};
+	session?: {
+		storage?: SessionStorageType;   // "local" | "session" | "memory" | SessionStorage
+		storageKey?: string;            // default: "ownsuite:session"
+	};
 }
 ```
 
 - `context` — initial context passed to every adapter call.
 - `domains` — domain registry at construction time. Keys are arbitrary labels.
 - `autoInitialize` — fire-and-forget `initialize()` in the constructor. Default: `false`.
+- `adapters.auth` — when provided, the suite builds `SessionManager` / `AuthManager` / `ProfileManager` and exposes them as `suite.session` / `suite.auth` / `suite.profile`. Without it, those properties are `null`.
+- `adapters.profile` — optional but recommended companion. Without it, login still succeeds but the subject is not hydrated from `/me`.
+- `session.storage` / `session.storageKey` — persistence config for the session. Ignored when no `adapters.auth` is provided.
 
 ### `OwnsuiteDomainConfig<TRow, TCreate, TUpdate>`
 
@@ -404,7 +419,16 @@ type OwnsuiteEventType =
 	| "own:row:fetched"
 	| "own:row:created"
 	| "own:row:updated"
-	| "own:row:deleted";
+	| "own:row:deleted"
+	// Account lifecycle — only emitted when adapters.auth is wired
+	| "auth:register"
+	| "auth:login"
+	| "auth:logout"
+	| "auth:session:changed"
+	| "auth:verification:required"
+	| "profile:updated"
+	| "oauth:linked"
+	| "oauth:unlinked";
 ```
 
 ### `OwnsuiteEvent`
@@ -482,3 +506,310 @@ export function createRestAdapter(stack: string, entity: string): OwnedCollectio
 ```
 
 The `@marianmeres/joy` admin SPA ships a reusable factory — `createOwnedCollectionAdapter()` in `src/routes/me/owned-collection-adapter.ts` — that implements exactly this shape.
+
+---
+
+## Account lifecycle (optional)
+
+Attached automatically when `adapters.auth` is passed to `createOwnsuite`. See also the example at the top of [README.md](README.md).
+
+### `createStackAccountAuthAdapter(options?)`
+
+Default `AuthAdapter` pointing at the `@marianmeres/stack-account` REST surface.
+
+**Parameters:**
+- `options` (`StackAccountAdapterOptions`, optional)
+  - `options.baseUrl` (`string`, optional) — mount path. Default: `"/api/account"`.
+  - `options.fetch` (`typeof fetch`, optional) — custom fetch (tests / SSR).
+
+**Returns:** `AuthAdapter`
+
+Endpoints targeted:
+
+```
+POST   {baseUrl}/register
+POST   {baseUrl}/login
+POST   {baseUrl}/logout
+POST   {baseUrl}/verify/resend
+POST   {baseUrl}/password/reset
+POST   {baseUrl}/password/change
+DELETE {baseUrl}/me
+GET    {baseUrl}/oauth/{provider}/init
+```
+
+### `createStackAccountProfileAdapter(options?)`
+
+Default `ProfileAdapter`.
+
+**Parameters:** same `StackAccountAdapterOptions` as above.
+
+**Returns:** `ProfileAdapter`
+
+Endpoints targeted: `GET/PUT {baseUrl}/me`, `GET {baseUrl}/me/oauth`, `DELETE {baseUrl}/me/oauth/{provider}`.
+
+### `createMockAuthStore(init?)` / `createMockAuthAdapter(store)` / `createMockProfileAdapter(store)` / `verifyMockAccount(store, email)`
+
+In-memory mock for tests and demos. `createMockAuthStore` builds a shared state object; the adapter factories close over it.
+
+**`createMockAuthStore(init?)`** returns `MockAuthStore`. `init.requireVerifiedEmail` (default `false`) toggles the email-verification gate; `init.seed` can pre-populate accounts.
+
+**`verifyMockAccount(store, email)`** marks an account as verified — stands in for the user clicking the link in a real verification email.
+
+**Example:**
+```typescript
+const store = createMockAuthStore({ requireVerifiedEmail: true });
+const suite = createOwnsuite({
+    adapters: {
+        auth: createMockAuthAdapter(store),
+        profile: createMockProfileAdapter(store),
+    },
+});
+await suite.auth!.register({
+    email: "alice@example.com",
+    password: "mysecretpassword",
+    password_confirm: "mysecretpassword",
+});
+// suite.session!.get().status === "unverified"
+verifyMockAccount(store, "alice@example.com");
+await suite.auth!.login({ email: "alice@example.com", password: "mysecretpassword" });
+// suite.session!.get().status === "authenticated"
+```
+
+---
+
+### `SessionManager`
+
+Reactive session state + persistence. No HTTP. Attached as `suite.session`.
+
+#### `session.subscribe(listener)` / `session.get()`
+
+Svelte-compatible store over [`SessionState`](#sessionstate).
+
+#### `session.getJwt(): string | null`
+
+Current JWT, or `null` when anonymous.
+
+#### `session.isAuthenticated` / `session.isUnverified` / `session.isAnonymous` (boolean getters)
+
+Shorthand reads.
+
+#### `session.setAuthenticated({ jwt, subject, expiresAt? })`
+
+Enter the `authenticated` state. Normally called by `AuthManager`, not consumers.
+
+#### `session.setUnverified(email)` / `session.clear()` / `session.patchSubject(patch)`
+
+Mutation helpers — typically driven by `AuthManager` / `ProfileManager`.
+
+#### `session.destroy()`
+
+Clear storage and in-memory state. Called by `suite.destroy()`.
+
+---
+
+### `AuthManager`
+
+Verbs only. Attached as `suite.auth`. No state of its own — results flow into `SessionManager`.
+
+| Method | Purpose |
+|---|---|
+| `register({ email, password, password_confirm, roles?, extras? })` | Create account. Returns an `AuthTokenResult`. When the server's verification gate is on, the result carries `requiresVerification: true` and the session flips to `"unverified"` — no JWT yet. |
+| `login({ email, password })` | Exchange credentials for a JWT. Session flips to `"authenticated"` on success, `"unverified"` if the server reports the gate. |
+| `logout()` | Best-effort server revoke + local clear. Idempotent. |
+| `resendVerification({ email, lang? })` | Trigger a fresh verification email. Anti-enumeration: always resolves. |
+| `requestPasswordReset({ email, lang? })` | Trigger a password-reset email. Anti-enumeration. |
+| `changePassword({ current_password?, new_password, confirm_password, token? })` | Authenticated self-change (with `current_password`) or token-based reset. |
+| `deleteAccount({ password?, confirm? })` | Irreversible server delete + local session clear + identity-changed hook. |
+| `initiateOAuth(provider, opts)` | Start an OAuth flow. `mode: "popup"` (default) resolves with the auth result from the popup's `postMessage`; `mode: "redirect"` navigates the top window. |
+| `handleOAuthCallback()` | For `mode: "redirect"` apps, call from your callback route to extract the result from the URL (delegated to `adapter.handleOAuthCallback`). |
+
+Successful identity changes (register-with-autologin, login, OAuth login, logout, deleteAccount) fire the orchestrator's `onIdentityChanged` hook, which resets every owner-scoped domain and re-initializes them with the new context.
+
+---
+
+### `ProfileManager`
+
+Singleton `/me` manager. Attached as `suite.profile`.
+
+| Method | Purpose |
+|---|---|
+| `fetch()` | GET `/me`. Aborts any in-flight fetch (supersede). Patches the session subject in place on success. |
+| `update({ email?, current_password? })` | PUT `/me`. Updates the session subject in place; emits `profile:updated`. |
+| `listOAuth()` | List the account's linked OAuth providers. |
+| `unlinkOAuth(provider)` | DELETE a provider connection; emits `oauth:unlinked`; re-fetches the profile. |
+| `get()` / `subscribe(fn)` | Read / subscribe to `ProfileState` (`{ profile, loading, error }`). |
+| `reset()` / `destroy()` | Abort in-flight fetch; drop state. |
+
+---
+
+### `openOAuthPopup(url, options?)`
+
+Open an OAuth popup and await the server's `postMessage`.
+
+**Parameters:**
+- `url` (`string`) — server OAuth init URL.
+- `options` (`OpenOAuthPopupOptions`, optional)
+  - `options.host` (`PopupWindowHost`, optional) — shim for tests. Default: `globalThis`.
+  - `options.closedPollMs` (`number`, optional) — detect popup-closed-without-message. Default: `500`.
+  - `options.timeoutMs` (`number`, optional) — hard timeout. Default: `0` (disabled).
+  - `options.expectedOrigin` (`string`, optional) — restrict accepted message origins.
+  - `options.features` (`string`, optional) — popup window features string.
+
+**Returns:** `Promise<OAuthPopupMessage>` — resolves with `{ type: "oauth_login_success", jwt, email, roles?, ... }` or `{ type: "oauth_link_success", provider }`. Rejects with `OAUTH_POPUP_BLOCKED` / `OAUTH_POPUP_CLOSED` / `OAUTH_POPUP_TIMEOUT` or the server-supplied error message.
+
+---
+
+## Account-lifecycle types
+
+### `SessionState`
+
+```typescript
+interface SessionState {
+    status: "anonymous" | "authenticated" | "unverified";
+    subject: SessionSubject | null;
+    jwt: string | null;
+    expiresAt: number | null;  // unix seconds
+}
+```
+
+### `SessionSubject`
+
+```typescript
+interface SessionSubject {
+    id: string;
+    email: string;
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;   // OAuth-only accounts: false
+}
+```
+
+### `SessionStatus` / `SessionStorage` / `SessionStorageType`
+
+```typescript
+type SessionStatus = "anonymous" | "authenticated" | "unverified";
+
+interface SessionStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    del(key: string): void;
+}
+
+type SessionStorageType = "local" | "session" | "memory" | SessionStorage;
+```
+
+### `AuthTokenResult`
+
+```typescript
+interface AuthTokenResult {
+    jwt?: string;                    // absent when requiresVerification is true
+    email: string;
+    roles: string[];
+    isVerified?: boolean;
+    validFrom?: number;
+    validUntil?: number;
+    requiresVerification?: boolean;  // server declined auto-login pending verify
+}
+```
+
+### `ProfileResult`
+
+```typescript
+interface ProfileResult {
+    email: string;
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;
+    oauthConnections: OAuthConnection[];
+}
+```
+
+### `OAuthProvider` / `OAuthAction` / `OAuthInitOptions` / `OAuthConnection`
+
+```typescript
+type OAuthProvider = "google" | "facebook" | "apple" | "twitter";
+type OAuthAction = "login" | "link";
+
+interface OAuthInitOptions {
+    action: OAuthAction;
+    redirect?: string;
+    lang?: string;
+    mode?: "popup" | "redirect";  // default "popup"
+}
+
+interface OAuthConnection {
+    provider: OAuthProvider;
+    display_name?: string;
+    avatar_url?: string;
+    email?: string;
+}
+```
+
+### `AuthAdapter`
+
+```typescript
+interface AuthAdapter {
+    register(input, ctx): Promise<AuthTokenResult>;
+    login(input, ctx): Promise<AuthTokenResult>;
+    logout(ctx): Promise<void>;
+    oauthInitUrl(provider, opts, ctx): string;
+    handleOAuthCallback?(ctx): Promise<AuthTokenResult>;
+    resendVerification(input, ctx): Promise<void>;
+    requestPasswordReset(input, ctx): Promise<void>;
+    changePassword(input, ctx): Promise<void>;
+    deleteAccount(input, ctx): Promise<{ deleted: true }>;
+}
+```
+
+Parameter shapes match [`src/types/auth.ts`](src/types/auth.ts). Implementations forward `ctx.jwt` as `Authorization: Bearer <jwt>` and `ctx.signal` to `fetch()`.
+
+### `ProfileAdapter`
+
+```typescript
+interface ProfileAdapter {
+    get(ctx): Promise<ProfileResult>;
+    update(input: { email?, current_password? }, ctx): Promise<ProfileResult>;
+    listOAuth(ctx): Promise<OAuthConnection[]>;
+    unlinkOAuth(provider, ctx): Promise<void>;
+}
+```
+
+### `StackAccountAdapterOptions`
+
+```typescript
+interface StackAccountAdapterOptions {
+    baseUrl?: string;    // default "/api/account"
+    fetch?: typeof fetch;
+}
+```
+
+### `OpenOAuthPopupOptions` / `PopupWindowHost` / `OAuthPopupMessage`
+
+See [src/oauth/popup.ts](src/oauth/popup.ts) for full definitions. `OAuthPopupMessage` is a union of `OAuthPopupLoginMessage` (`{ type: "oauth_login_success", jwt, email, roles?, ... }`) and `OAuthPopupLinkMessage` (`{ type: "oauth_link_success", provider }`). Errors posted by the server (`{ type: "oauth_error", error }`) cause the promise to reject.
+
+### `MockAuthStore`
+
+```typescript
+interface MockAuthStore {
+    accounts: Map<string, MockAccount>;
+    requireVerifiedEmail: boolean;
+    jwtsByEmail: Map<string, string>;
+}
+```
+
+---
+
+## Account-lifecycle events
+
+Emitted on the shared pubsub. Each payload has a `timestamp` (ms).
+
+| Event | Payload |
+|---|---|
+| `auth:register` | `{ email, requiresVerification }` |
+| `auth:login` | `{ email }` |
+| `auth:logout` | `{ subjectId? }` |
+| `auth:session:changed` | `{ session: SessionState }` |
+| `auth:verification:required` | `{ email }` (fired when status flips to `"unverified"`) |
+| `profile:updated` | `{ email }` |
+| `oauth:linked` | `{ connection: OAuthConnection }` |
+| `oauth:unlinked` | `{ provider: OAuthProvider }` |

package/README.md

@@ -24,6 +24,71 @@ Ownsuite gives front-end applications a uniform way to read, create, update and
 - **Event system** — subscribe to list fetches, row CRUD, and lifecycle transitions
 - **Mock adapter** — in-memory fixture for tests, with configurable failure injection and latency
 - **Explicit lifecycle** — `suite.destroy()` aborts in-flight work and releases listeners cleanly
+- **Account lifecycle (opt-in)** — `suite.auth` / `suite.session` / `suite.profile` for register / login / OAuth / verify / logout / profile edit / delete account, wired to pair with `@marianmeres/stack-account` via the bundled default adapters
+
+## Authentication (optional)
+
+Pass an `AuthAdapter` to `createOwnsuite` to attach the account-lifecycle managers. The default adapters target the `@marianmeres/stack-account` REST surface; apps with custom routes can write their own against the `AuthAdapter` / `ProfileAdapter` interfaces exported from this package.
+
+```typescript
+import {
+  createOwnsuite,
+  createStackAccountAuthAdapter,
+  createStackAccountProfileAdapter,
+} from "@marianmeres/ownsuite";
+
+const suite = createOwnsuite({
+  adapters: {
+    auth: createStackAccountAuthAdapter({ baseUrl: "/api/account" }),
+    profile: createStackAccountProfileAdapter({ baseUrl: "/api/account" }),
+  },
+  session: { storage: "local", storageKey: "myapp:session" },
+  // Existing owner-scoped domains continue to work — their ctx.jwt is
+  // populated automatically from the session and they re-initialize on
+  // every login / logout.
+  domains: {
+    orders: { adapter: ordersAdapter },
+  },
+});
+
+// Observable session — UI subscribes to this for logged-in state.
+suite.session!.subscribe(({ status, subject }) => {
+  if (status === "authenticated") console.log("hi", subject!.email);
+  if (status === "unverified")   console.log("check your inbox");
+  if (status === "anonymous")    console.log("signed out");
+});
+
+// Register → server requires email verification (default gate in stack-account)
+await suite.auth!.register({
+  email: "alice@example.com",
+  password: "mysecretpassword",
+  password_confirm: "mysecretpassword",
+});
+// suite.session!.get().status === "unverified"
+
+// After the user clicks the email link and the server flips isVerified:
+await suite.auth!.login({ email: "alice@example.com", password: "mysecretpassword" });
+// suite.session!.get().status === "authenticated"
+// Every registered owner-scoped domain is re-initialized with the new JWT.
+
+// OAuth popup flow — resolves when the callback page postMessages back
+await suite.auth!.initiateOAuth("google", { action: "login" });
+
+// Profile edit — changing email resets isVerified server-side and dispatches
+// a new verification email. Session subject is patched in place.
+await suite.profile!.update({
+  email: "renamed@example.com",
+  current_password: "mysecretpassword",
+});
+
+// Logout — revokes JWT server-side (via stack-account's jti deletion) and
+// clears local session storage. Owner-scoped domains reset to initializing.
+await suite.auth!.logout();
+```
+
+Session state is persisted through a pluggable `SessionStorage` backend (`"local"` / `"session"` / `"memory"` / custom object with `get`/`set`/`del`). Expired stored sessions are discarded on construction so a reload after the JWT lapses starts anonymous.
+
+Tests can use the in-memory mock adapters (`createMockAuthAdapter`, `createMockProfileAdapter`, `createMockAuthStore`, `verifyMockAccount`) and the injectable popup host for deterministic OAuth dances.
 
 ## Installation
 

package/dist/adapters/mock-auth.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module adapters/mock-auth
+ *
+ * In-memory mock implementations of AuthAdapter and ProfileAdapter.
+ * Drives the unit tests for AuthManager / ProfileManager / SessionManager
+ * without a real server. Consumers can also use it to build demos or
+ * storybooks that exercise the full suite.
+ *
+ * Deliberately small: everything is held in a shared `Store` object the
+ * adapters close over, so tests can peek at or mutate state directly.
+ */
+import type { AuthAdapter, OAuthConnection, ProfileAdapter } from "../types/mod.js";
+interface MockAccount {
+    email: string;
+    password: string;
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;
+    oauthConnections: OAuthConnection[];
+}
+export interface MockAuthStore {
+    accounts: Map<string, MockAccount>;
+    /** If true, register/login return requiresVerification=true until the
+     *  email is explicitly verified via `verifyMockAccount()`. */
+    requireVerifiedEmail: boolean;
+    /** Last-issued JWT per email (just a synthetic string). */
+    jwtsByEmail: Map<string, string>;
+}
+export declare function createMockAuthStore(init?: {
+    requireVerifiedEmail?: boolean;
+    seed?: MockAccount[];
+}): MockAuthStore;
+export declare function createMockAuthAdapter(store: MockAuthStore): AuthAdapter;
+export declare function createMockProfileAdapter(store: MockAuthStore): ProfileAdapter;
+/** Test helper — mark a mock account as verified as if the user had clicked
+ *  the link in the verification email. */
+export declare function verifyMockAccount(store: MockAuthStore, email: string): void;
+export {};