@marianmeres/ownsuite 2.2.3 → 2.3.0

package/AGENTS.md

@@ -22,6 +22,7 @@ Client-side helper library for **owner-scoped** UIs. Generic domain managers for
 **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.
@@ -101,9 +102,11 @@ tests/
 
 ```typescript
 // Main
-export { Ownsuite, createOwnsuite } from "./ownsuite.ts";
+export { createOwnsuite, Ownsuite } from "./ownsuite.ts";
 export type {
-	OwnsuiteConfig, OwnsuiteDomainConfig, SetContextOptions,
+	OwnsuiteConfig,
+	OwnsuiteDomainConfig,
+	SetContextOptions,
 } from "./ownsuite.ts";
 
 // Domain managers
@@ -112,13 +115,25 @@ export type { BaseDomainOptions, OwnedCollectionManagerOptions } from "./domains
 
 // Types
 export type {
-	DomainError, DomainState, DomainStateWrapper,
-	OwnsuiteContext, OwnedCollectionState,
-	OwnsuiteEvent, OwnsuiteEventType, DomainName,
-	StateChangedEvent, ErrorEvent, SyncedEvent,
-	ListFetchedEvent, RowFetchedEvent,
-	RowCreatedEvent, RowUpdatedEvent, RowDeletedEvent,
-	OwnedCollectionAdapter, OwnedListResult, OwnedRowResult,
+	DomainError,
+	DomainName,
+	DomainState,
+	DomainStateWrapper,
+	ErrorEvent,
+	ListFetchedEvent,
+	OwnedCollectionAdapter,
+	OwnedCollectionState,
+	OwnedListResult,
+	OwnedRowResult,
+	OwnsuiteContext,
+	OwnsuiteEvent,
+	OwnsuiteEventType,
+	RowCreatedEvent,
+	RowDeletedEvent,
+	RowFetchedEvent,
+	RowUpdatedEvent,
+	StateChangedEvent,
+	SyncedEvent,
 } from "./types/mod.ts";
 
 // Mock adapter (for tests)
@@ -126,19 +141,32 @@ 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 { AuthManager, ProfileManager, SessionManager } from "./domains/mod.ts";
 export type {
-	AuthAdapter, ProfileAdapter, AuthTokenResult, ProfileResult,
-	SessionState, SessionSubject, SessionStatus,
-	SessionStorage, SessionStorageType,
-	OAuthConnection, OAuthProvider, OAuthInitOptions, OAuthAction,
+	AuthAdapter,
+	AuthTokenResult,
+	OAuthAction,
+	OAuthConnection,
+	OAuthInitOptions,
+	OAuthProvider,
+	ProfileAdapter,
+	ProfileResult,
+	SessionState,
+	SessionStatus,
+	SessionStorage,
+	SessionStorageType,
+	SessionSubject,
 } from "./types/mod.ts";
 
 // OAuth popup helper
 export { openOAuthPopup } from "./oauth/popup.ts";
 export type {
-	OAuthPopupMessage, OAuthPopupLoginMessage, OAuthPopupLinkMessage,
-	OpenOAuthPopupOptions, PopupWindowHost, PopupWindowHandle,
+	OAuthPopupLinkMessage,
+	OAuthPopupLoginMessage,
+	OAuthPopupMessage,
+	OpenOAuthPopupOptions,
+	PopupWindowHandle,
+	PopupWindowHost,
 } from "./oauth/popup.ts";
 
 // Default stack-account adapters
@@ -150,8 +178,10 @@ export type { StackAccountAdapterOptions } from "./adapters/mod.ts";
 
 // Mock auth adapter (for tests)
 export {
-	createMockAuthAdapter, createMockProfileAdapter,
-	createMockAuthStore, verifyMockAccount,
+	createMockAuthAdapter,
+	createMockAuthStore,
+	createMockProfileAdapter,
+	verifyMockAccount,
 } from "./adapters/mod.ts";
 export type { MockAccount, MockAuthStore } from "./adapters/mod.ts";
 
@@ -211,7 +241,7 @@ Triggered by `initialize()`, `refresh()`, `create()`, `update()`, `delete()` on
 
 4. **`initialize()` never rejects.** Per-domain errors land in that domain's `error` state; the top-level promise resolves. Use `suite.hasErrors()` / `suite.errors()` to detect failed boots, or subscribe to `domain:error`.
 
-5. **Optimistic updates roll back per-row on failure.** `update` mutates the single target row; on error that row reverts to its pre-call value. `delete` removes the target row; on error it is re-inserted at its original position (unless another op has since re-added it). `create` does NOT optimistically insert. Rollback reads the *live* store so an interleaved `refresh()` that brought new rows is preserved.
+5. **Optimistic updates roll back per-row on failure.** `update` mutates the single target row; on error that row reverts to its pre-call value. `delete` removes the target row; on error it is re-inserted at its original position (unless another op has since re-added it). `create` does NOT optimistically insert. Rollback reads the _live_ store so an interleaved `refresh()` that brought new rows is preserved.
 
 6. **`OwnsuiteContext.subjectId` is a hint, not authorization.** The server is authoritative. Setting it client-side has no security effect. When subject changes, call `suite.setContext(ctx, { replace: true, refresh: true })` to clear stale per-subject caches.
 
@@ -259,7 +289,7 @@ suite.domain("orders").subscribe((s) => {
 
 ```typescript
 suite.on("own:row:created", (e) => {/* e.rowId, e.domain, e.timestamp */});
-suite.on("domain:error",     (e) => {/* e.error */});
+suite.on("domain:error", (e) => {/* e.error */});
 suite.onAny(({ event, data }) => {/* wildcard envelope */});
 ```
 
@@ -295,7 +325,11 @@ import { HTTP_ERROR } from "@marianmeres/http-utils";
 const adapter: OwnedCollectionAdapter = {
 	async list(ctx, query) {
 		const url = new URL(`/api/shop/me/col/order/mod`, location.origin);
-		if (query) for (const [k, v] of Object.entries(query)) url.searchParams.set(k, String(v));
+		if (query) {
+			for (const [k, v] of Object.entries(query)) {
+				url.searchParams.set(k, String(v));
+			}
+		}
 		const res = await fetch(url, { signal: ctx.signal }); // forward abort
 		if (!res.ok) throw new HTTP_ERROR.BadRequest(await res.text());
 		return await res.json(); // { data, meta }
@@ -309,10 +343,7 @@ Joy ships a reusable factory at `src/admin/packages/joy/src/routes/me/owned-coll
 ### Testing with the mock adapter
 
 ```typescript
-import {
-	createMockOwnedCollectionAdapter,
-	createOwnsuite,
-} from "@marianmeres/ownsuite";
+import { createMockOwnedCollectionAdapter, createOwnsuite } from "@marianmeres/ownsuite";
 
 const adapter = createMockOwnedCollectionAdapter({
 	seed: [{ model_id: "1", data: { label: "a" } }],
@@ -373,6 +404,7 @@ deno task test:watch # watch mode
 ```
 
 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.
@@ -400,6 +432,7 @@ The client-side scope assumes the server enforces owner-based filtering. This re
 3. **Auth middleware**: must populate `ctx.locals.subject` (typically via `@marianmeres/stack-common`'s `createJwtMiddleware`) before the collection routes handle the request.
 
 URL shape the default adapter helper expects:
+
 ```
 List   GET    {apiRoot}/{stack}/me/col/{entity}/mod
 Get    GET    {apiRoot}/{stack}/me/col/{entity}/mod/{id}
@@ -411,6 +444,7 @@ Delete DELETE {apiRoot}/{stack}/me/col/{entity}/mod/{id}
 ### Joy admin SPA pairing
 
 Joy ships:
+
 - `src/admin/packages/joy/src/components/layout/LayoutCustomer.svelte` — simplified chrome for `/me/*`.
 - `src/admin/packages/joy/src/routes/me/MeRouter.svelte` — route entry point.
 - `src/admin/packages/joy/src/routes/me/owned-collection-adapter.ts` — reusable adapter factory.
@@ -471,14 +505,14 @@ described in the "Account lifecycle (optional)" section above.
 
 ## Differences from `@marianmeres/ecsuite`
 
-| Aspect | ecsuite | ownsuite |
-|--------|---------|----------|
-| Domains | Fixed 6 (cart, wishlist, order, customer, payment, product) | Arbitrary, registered by name |
-| State shape | Domain-specific (cart items, orders list, etc.) | Generic `{ rows, meta }` per domain |
-| Persistence | localStorage for cart/wishlist | None (server is source of truth) |
-| Scoping | Customer-id hint in context | Server-enforced via `owner_id` |
-| Optimistic create | Yes (cart items) | No (no client-assigned id) |
-| Optimistic update/delete | Yes | Yes |
-| Event namespaces | `cart:*`, `order:*`, etc. | `own:list:*`, `own:row:*` |
+| Aspect                   | ecsuite                                                     | ownsuite                            |
+| ------------------------ | ----------------------------------------------------------- | ----------------------------------- |
+| Domains                  | Fixed 6 (cart, wishlist, order, customer, payment, product) | Arbitrary, registered by name       |
+| State shape              | Domain-specific (cart items, orders list, etc.)             | Generic `{ rows, meta }` per domain |
+| Persistence              | localStorage for cart/wishlist                              | None (server is source of truth)    |
+| Scoping                  | Customer-id hint in context                                 | Server-enforced via `owner_id`      |
+| Optimistic create        | Yes (cart items)                                            | No (no client-assigned id)          |
+| Optimistic update/delete | Yes                                                         | Yes                                 |
+| Event namespaces         | `cart:*`, `order:*`, etc.                                   | `own:list:*`, `own:row:*`           |
 
 Consumers that already use ecsuite can compose both suites in the same app.

package/API.md

@@ -7,11 +7,13 @@
 Convenience factory mirroring the ecsuite `createECSuite` convention. Equivalent to `new Ownsuite(config)`.
 
 **Parameters:**
+
 - `config` (`OwnsuiteConfig`, optional) — see [`OwnsuiteConfig`](#ownsuiteconfig).
 
 **Returns:** `Ownsuite`
 
 **Example:**
+
 ```typescript
 import { createOwnsuite } from "@marianmeres/ownsuite";
 
@@ -32,6 +34,7 @@ await suite.initialize();
 In-memory mock adapter for tests. Stores rows in a local `Map` keyed by `model_id`. Applies optional latency and can inject failures per operation — useful for exercising the optimistic-update rollback path deterministically.
 
 **Parameters:**
+
 - `options` (`MockAdapterOptions<TRow>`, optional)
   - `options.seed` (`TRow[]`, optional) — initial rows
   - `options.delayMs` (`number`, optional) — artificial latency per call. Default: `0`
@@ -44,6 +47,7 @@ In-memory mock adapter for tests. Stores rows in a local `Map` keyed by `model_i
 The returned adapter exposes an extra `_rows()` method for test assertions that doesn't exist on production adapters.
 
 **Example:**
+
 ```typescript
 const adapter = createMockOwnedCollectionAdapter({
 	seed: [{ model_id: "1", data: { label: "a" } }],
@@ -72,6 +76,7 @@ Readonly properties pointing at the account-lifecycle managers. Populated only w
 Register a new domain after construction. Throws if `name` is already registered.
 
 **Parameters:**
+
 - `name` (`string`) — unique domain label
 - `cfg` (`OwnsuiteDomainConfig<TRow, TCreate, TUpdate>`)
   - `cfg.adapter` (`OwnedCollectionAdapter`) — required
@@ -98,6 +103,7 @@ List registered domain names.
 Initialize all registered domains (or a subset). Runs in parallel. Individual domain errors land in that domain's error state and **do not** reject the returned promise.
 
 **Parameters:**
+
 - `names` (`string[]`, optional) — domain names to initialize. Default: all registered domains.
 
 **Returns:** `Promise<void>`
@@ -107,12 +113,14 @@ Initialize all registered domains (or a subset). Runs in parallel. Individual do
 Update the shared context and propagate to every registered domain manager.
 
 **Parameters:**
+
 - `ctx` (`OwnsuiteContext`)
 - `options` (`SetContextOptions`, optional)
   - `options.replace` (`boolean`, default `false`) — replace the context wholesale instead of merging. Use this when the subject changes and previous per-subject keys must not leak into adapter calls.
   - `options.refresh` (`boolean`, default `false`) — fire-and-forget `refresh()` on every domain after the context change. Recommended when `subjectId` changes so stale per-subject caches are cleared.
 
 **Example:**
+
 ```typescript
 // Subject change: drop old context + re-fetch every domain
 suite.setContext({ subjectId: newId }, { replace: true, refresh: true });
@@ -145,12 +153,14 @@ True after `destroy()` has been called.
 Subscribe to a specific event type.
 
 **Parameters:**
+
 - `type` (`OwnsuiteEventType`)
 - `subscriber` (`Subscriber`) — from `@marianmeres/pubsub`
 
 **Returns:** `Unsubscriber`
 
 **Example:**
+
 ```typescript
 const unsub = suite.on("own:row:created", (e) => {
 	console.log("created row", e.rowId, "in domain", e.domain);
@@ -178,6 +188,7 @@ Generic manager for a single owner-scoped collection domain. One instance per co
 Typically created via `Ownsuite.registerDomain()` — manual construction is possible but bypasses the shared pubsub.
 
 **Parameters:**
+
 - `domainName` (`string`) — label (informational, used in event payloads and logs)
 - `options` (`OwnedCollectionManagerOptions<TRow, TCreate, TUpdate>`, optional)
   - `options.adapter` (`OwnedCollectionAdapter`, optional)
@@ -204,6 +215,7 @@ Fetch the list from the server. Populates `data.rows` + `data.meta` and transiti
 Re-fetch the list. Same as `initialize` but re-entrant; accepts an adapter-specific query object.
 
 **Parameters:**
+
 - `query` (`Record<string, unknown>`, optional) — forwarded to `adapter.list(ctx, query)`
 
 #### `manager.getOne(id): Promise<TRow | null>`
@@ -217,6 +229,7 @@ Callers that need error detail should wrap this method and inspect the adapter e
 Create a new row. On success, prepends the server-returned row to the list. On failure, the list is unchanged and the manager transitions to `error`.
 
 **Parameters:**
+
 - `data` (`TCreate`) — creation payload. The server stamps `owner_id` — do not set it client-side.
 
 **Returns:** the server-returned row, or `null` on failure.
@@ -228,6 +241,7 @@ Update a row. Optimistically merges `data` into the existing row; on server fail
 If `id` is **not** in the current cached list (filtered out by an active query, or not loaded), the optimistic step is a no-op AND the successful server response is **not** inserted — call `refresh()` if you want the row to appear. The `own:row:updated` event is emitted regardless.
 
 **Parameters:**
+
 - `id` (`string`)
 - `data` (`TUpdate`)
 
@@ -289,8 +303,8 @@ interface OwnsuiteConfig {
 		profile?: ProfileAdapter;
 	};
 	session?: {
-		storage?: SessionStorageType;   // "local" | "session" | "memory" | SessionStorage
-		storageKey?: string;            // default: "ownsuite:session"
+		storage?: SessionStorageType; // "local" | "session" | "memory" | SessionStorage
+		storageKey?: string; // default: "ownsuite:session"
 	};
 }
 ```
@@ -315,8 +329,8 @@ interface OwnsuiteDomainConfig<TRow, TCreate, TUpdate> {
 
 ```typescript
 interface SetContextOptions {
-	replace?: boolean;   // default: false — merge into existing context
-	refresh?: boolean;   // default: false — fire refresh() on every domain
+	replace?: boolean; // default: false — merge into existing context
+	refresh?: boolean; // default: false — fire refresh() on every domain
 }
 ```
 
@@ -325,7 +339,7 @@ interface SetContextOptions {
 ```typescript
 interface OwnsuiteContext {
 	subjectId?: string;
-	signal?: AbortSignal;  // manager-injected, per-call
+	signal?: AbortSignal; // manager-injected, per-call
 	[key: string]: unknown;
 }
 ```
@@ -336,10 +350,17 @@ Context passed to adapters. **`subjectId` is a hint only** — the server author
 
 ```typescript
 interface OwnedCollectionAdapter<TRow, TCreate = unknown, TUpdate = unknown> {
-	list(ctx: OwnsuiteContext, query?: Record<string, unknown>): Promise<OwnedListResult<TRow>>;
+	list(
+		ctx: OwnsuiteContext,
+		query?: Record<string, unknown>,
+	): Promise<OwnedListResult<TRow>>;
 	getOne(id: string, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
 	create(data: TCreate, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
-	update(id: string, data: TUpdate, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+	update(
+		id: string,
+		data: TUpdate,
+		ctx: OwnsuiteContext,
+	): Promise<OwnedRowResult<TRow>>;
 	delete(id: string, ctx: OwnsuiteContext): Promise<boolean>;
 }
 ```
@@ -373,7 +394,7 @@ interface OwnedCollectionState<TRow> {
 
 ```typescript
 interface DomainStateWrapper<T> {
-	state: DomainState;           // "initializing" | "ready" | "syncing" | "error"
+	state: DomainState; // "initializing" | "ready" | "syncing" | "error"
 	data: T | null;
 	error: DomainError | null;
 	lastSyncedAt: number | null;
@@ -399,9 +420,9 @@ error        → syncing    (retry)
 
 ```typescript
 interface DomainError {
-	code: string;             // e.g. "SYNC_FAILED", "FETCH_FAILED"
+	code: string; // e.g. "SYNC_FAILED", "FETCH_FAILED"
 	message: string;
-	operation: string;        // e.g. "create", "update", "delete"
+	operation: string; // e.g. "create", "update", "delete"
 	originalError?: unknown;
 }
 ```
@@ -438,11 +459,11 @@ type OwnsuiteEvent =
 	| StateChangedEvent
 	| ErrorEvent
 	| SyncedEvent
-	| ListFetchedEvent      // + count
-	| RowFetchedEvent       // + rowId
-	| RowCreatedEvent       // + rowId
-	| RowUpdatedEvent       // + rowId
-	| RowDeletedEvent;      // + rowId
+	| ListFetchedEvent // + count
+	| RowFetchedEvent // + rowId
+	| RowCreatedEvent // + rowId
+	| RowUpdatedEvent // + rowId
+	| RowDeletedEvent; // + rowId
 ```
 
 See [src/types/events.ts](src/types/events.ts) for individual event interfaces.
@@ -453,7 +474,13 @@ See [src/types/events.ts](src/types/events.ts) for individual event interfaces.
 interface MockAdapterOptions<TRow> {
 	seed?: TRow[];
 	delayMs?: number;
-	failOn?: { list?: boolean; getOne?: boolean; create?: boolean; update?: boolean; delete?: boolean };
+	failOn?: {
+		list?: boolean;
+		getOne?: boolean;
+		create?: boolean;
+		update?: boolean;
+		delete?: boolean;
+	};
 	getRowId?: (row: TRow) => string;
 	newId?: () => string;
 	/** Reject create payloads containing `model_id` (default: true). */
@@ -516,6 +543,7 @@ Attached automatically when `adapters.auth` is passed to `createOwnsuite`. See a
 Default `AuthAdapter` pointing at a conventional account REST surface (register / login / logout / OAuth / verify).
 
 **Parameters:**
+
 - `options` (`StackAccountAdapterOptions`, optional)
   - `options.baseUrl` (`string`, optional) — mount path. Default: `"/api/account"`.
   - `options.fetch` (`typeof fetch`, optional) — custom fetch (tests / SSR).
@@ -554,18 +582,19 @@ In-memory mock for tests and demos. `createMockAuthStore` builds a shared state
 **`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),
-    },
+	adapters: {
+		auth: createMockAuthAdapter(store),
+		profile: createMockProfileAdapter(store),
+	},
 });
 await suite.auth!.register({
-    email: "alice@example.com",
-    password: "mysecretpassword",
-    password_confirm: "mysecretpassword",
+	email: "alice@example.com",
+	password: "mysecretpassword",
+	password_confirm: "mysecretpassword",
 });
 // suite.session!.get().status === "unverified"
 verifyMockAccount(store, "alice@example.com");
@@ -611,17 +640,17 @@ Clear storage and in-memory state. Called by `suite.destroy()`.
 
 Verbs only. Attached as `suite.auth`. No state of its own — results flow into `SessionManager`.
 
-| Method | Purpose |
-|---|---|
-| `register({ email, password, password_confirm, roles?, extras? }, options?)` | 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. `options.remember` pins the resulting session to `localStorage` (`true`) or `sessionStorage` (`false`); omit to use the `SessionManager` default. |
-| `login({ email, password }, options?)` | Exchange credentials for a JWT. Session flips to `"authenticated"` on success, `"unverified"` if the server reports the gate. `options.remember` selects per-login storage (see `register`). |
-| `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. `opts.remember` pins the resulting session's storage backend (only meaningful for `action: "login"`). |
-| `handleOAuthCallback(options?)` | For `mode: "redirect"` apps, call from your callback route to extract the result from the URL (delegated to `adapter.handleOAuthCallback`). `options.remember` pins the resulting session's storage — pass the same value the user picked before the redirect. |
+| Method                                                                          | Purpose                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `register({ email, password, password_confirm, roles?, extras? }, options?)`    | 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. `options.remember` pins the resulting session to `localStorage` (`true`) or `sessionStorage` (`false`); omit to use the `SessionManager` default. |
+| `login({ email, password }, options?)`                                          | Exchange credentials for a JWT. Session flips to `"authenticated"` on success, `"unverified"` if the server reports the gate. `options.remember` selects per-login storage (see `register`).                                                                                                                                                     |
+| `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. `opts.remember` pins the resulting session's storage backend (only meaningful for `action: "login"`).                                                                                  |
+| `handleOAuthCallback(options?)`                                                 | For `mode: "redirect"` apps, call from your callback route to extract the result from the URL (delegated to `adapter.handleOAuthCallback`). `options.remember` pins the resulting session's storage — pass the same value the user picked before the redirect.                                                                                   |
 
 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.
 
@@ -631,14 +660,14 @@ Successful identity changes (register-with-autologin, login, OAuth login, logout
 
 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. |
+| 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.                                                                  |
 
 ---
 
@@ -647,6 +676,7 @@ Singleton `/me` manager. Attached as `suite.profile`.
 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`.
@@ -665,10 +695,10 @@ Open an OAuth popup and await the server's `postMessage`.
 
 ```typescript
 interface SessionState {
-    status: "anonymous" | "authenticated" | "unverified";
-    subject: SessionSubject | null;
-    jwt: string | null;
-    expiresAt: number | null;  // unix seconds
+	status: "anonymous" | "authenticated" | "unverified";
+	subject: SessionSubject | null;
+	jwt: string | null;
+	expiresAt: number | null; // unix seconds
 }
 ```
 
@@ -676,11 +706,11 @@ interface SessionState {
 
 ```typescript
 interface SessionSubject {
-    id: string;
-    email: string;
-    roles: string[];
-    isVerified: boolean;
-    hasPassword: boolean;   // OAuth-only accounts: false
+	id: string;
+	email: string;
+	roles: string[];
+	isVerified: boolean;
+	hasPassword: boolean; // OAuth-only accounts: false
 }
 ```
 
@@ -690,9 +720,9 @@ interface SessionSubject {
 type SessionStatus = "anonymous" | "authenticated" | "unverified";
 
 interface SessionStorage {
-    get(key: string): string | null;
-    set(key: string, value: string): void;
-    del(key: string): void;
+	get(key: string): string | null;
+	set(key: string, value: string): void;
+	del(key: string): void;
 }
 
 type SessionStorageType = "local" | "session" | "memory" | SessionStorage;
@@ -702,13 +732,13 @@ type SessionStorageType = "local" | "session" | "memory" | SessionStorage;
 
 ```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
+	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
 }
 ```
 
@@ -716,11 +746,11 @@ interface AuthTokenResult {
 
 ```typescript
 interface ProfileResult {
-    email: string;
-    roles: string[];
-    isVerified: boolean;
-    hasPassword: boolean;
-    oauthConnections: OAuthConnection[];
+	email: string;
+	roles: string[];
+	isVerified: boolean;
+	hasPassword: boolean;
+	oauthConnections: OAuthConnection[];
 }
 ```
 
@@ -731,25 +761,25 @@ type OAuthProvider = "google" | "facebook" | "apple" | "twitter";
 type OAuthAction = "login" | "link";
 
 interface OAuthInitOptions {
-    action: OAuthAction;
-    redirect?: string;
-    lang?: string;
-    mode?: "popup" | "redirect";  // default "popup"
-    remember?: boolean;           // same semantics as AuthActionOptions.remember
+	action: OAuthAction;
+	redirect?: string;
+	lang?: string;
+	mode?: "popup" | "redirect"; // default "popup"
+	remember?: boolean; // same semantics as AuthActionOptions.remember
 }
 
 interface AuthActionOptions {
-    /** true → localStorage; false → sessionStorage; undefined → default.
-     *  Ignored when SessionManager was constructed with a custom
-     *  SessionStorage object. */
-    remember?: boolean;
+	/** true → localStorage; false → sessionStorage; undefined → default.
+	 *  Ignored when SessionManager was constructed with a custom
+	 *  SessionStorage object. */
+	remember?: boolean;
 }
 
 interface OAuthConnection {
-    provider: OAuthProvider;
-    display_name?: string;
-    avatar_url?: string;
-    email?: string;
+	provider: OAuthProvider;
+	display_name?: string;
+	avatar_url?: string;
+	email?: string;
 }
 ```
 
@@ -757,15 +787,15 @@ interface OAuthConnection {
 
 ```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 }>;
+	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 }>;
 }
 ```
 
@@ -775,10 +805,10 @@ Parameter shapes match [`src/types/auth.ts`](src/types/auth.ts). Implementations
 
 ```typescript
 interface ProfileAdapter {
-    get(ctx): Promise<ProfileResult>;
-    update(input: { email?, current_password? }, ctx): Promise<ProfileResult>;
-    listOAuth(ctx): Promise<OAuthConnection[]>;
-    unlinkOAuth(provider, ctx): Promise<void>;
+	get(ctx): Promise<ProfileResult>;
+	update(input: { email?; current_password? }, ctx): Promise<ProfileResult>;
+	listOAuth(ctx): Promise<OAuthConnection[]>;
+	unlinkOAuth(provider, ctx): Promise<void>;
 }
 ```
 
@@ -786,8 +816,8 @@ interface ProfileAdapter {
 
 ```typescript
 interface StackAccountAdapterOptions {
-    baseUrl?: string;    // default "/api/account"
-    fetch?: typeof fetch;
+	baseUrl?: string; // default "/api/account"
+	fetch?: typeof fetch;
 }
 ```
 
@@ -799,18 +829,18 @@ See [src/oauth/popup.ts](src/oauth/popup.ts) for full definitions. `OAuthPopupMe
 
 ```typescript
 interface MockAccount {
-    email: string;
-    password: string;         // plaintext — mock does no hashing
-    roles: string[];
-    isVerified: boolean;
-    hasPassword: boolean;
-    oauthConnections: OAuthConnection[];
+	email: string;
+	password: string; // plaintext — mock does no hashing
+	roles: string[];
+	isVerified: boolean;
+	hasPassword: boolean;
+	oauthConnections: OAuthConnection[];
 }
 
 interface MockAuthStore {
-    accounts: Map<string, MockAccount>;
-    requireVerifiedEmail: boolean;
-    jwtsByEmail: Map<string, string>;
+	accounts: Map<string, MockAccount>;
+	requireVerifiedEmail: boolean;
+	jwtsByEmail: Map<string, string>;
 }
 ```
 
@@ -822,13 +852,13 @@ Fields are public by design so test code can peek at / mutate them directly.
 
 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 }` |
+| 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 }` |
+| `profile:updated`            | `{ email }`                                             |
+| `oauth:linked`               | `{ connection: OAuthConnection }`                       |
+| `oauth:unlinked`             | `{ provider: OAuthProvider }`                           |

package/README.md

@@ -29,44 +29,44 @@ Pass an `AuthAdapter` to `createOwnsuite` to attach the account-lifecycle manage
 
 ```typescript
 import {
-  createOwnsuite,
-  createStackAccountAuthAdapter,
-  createStackAccountProfileAdapter,
+	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 },
-  },
+	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");
+	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 by default
 await suite.auth!.register({
-  email: "alice@example.com",
-  password: "mysecretpassword",
-  password_confirm: "mysecretpassword",
+	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" },
-  { remember: true }, // true → localStorage; false → sessionStorage (per-login override)
+	{ email: "alice@example.com", password: "mysecretpassword" },
+	{ remember: true }, // true → localStorage; false → sessionStorage (per-login override)
 );
 // suite.session!.get().status === "authenticated"
 // Every registered owner-scoped domain is re-initialized with the new JWT.
@@ -77,8 +77,8 @@ 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",
+	email: "renamed@example.com",
+	current_password: "mysecretpassword",
 });
 
 // Logout — revokes JWT server-side and clears local session storage.
@@ -157,14 +157,11 @@ Each domain holds a single list of rows owned by the authenticated subject. List
 ## Testing with the mock adapter
 
 ```typescript
-import {
-	createMockOwnedCollectionAdapter,
-	createOwnsuite,
-} from "@marianmeres/ownsuite";
+import { createMockOwnedCollectionAdapter, createOwnsuite } from "@marianmeres/ownsuite";
 
 const adapter = createMockOwnedCollectionAdapter({
 	seed: [{ model_id: "1", data: { label: "hello" } }],
-	failOn: { update: true },   // force update failures for rollback tests
+	failOn: { update: true }, // force update failures for rollback tests
 });
 
 const suite = createOwnsuite({ domains: { notes: { adapter } } });

package/dist/adapters/stack-account.js

@@ -65,9 +65,7 @@ async function requestJson(doFetch, url, init, ctx) {
         headers: {
             ...(init.headers ?? {}),
             ...authHeaders(ctx),
-            ...(init.body
-                ? { "Content-Type": "application/json" }
-                : {}),
+            ...(init.body ? { "Content-Type": "application/json" } : {}),
         },
         signal: ctx.signal,
     });
@@ -82,6 +80,72 @@ async function requestJson(doFetch, url, init, ctx) {
         return undefined;
     return (await res.json());
 }
+/**
+ * Coerce a server-provided validity marker to **epoch seconds**.
+ *
+ * `AuthTokenResult.validFrom` / `validUntil` are typed (and consumed
+ * downstream — notably the session-expiry check) as numeric epoch seconds, but
+ * the stack-account server sends ISO-8601 strings. Blind-casting the wire shape
+ * lands a string in a numeric field, which silently breaks `expiresAt * 1000`
+ * arithmetic (`NaN`, so an expired session never expires). This bridges the two
+ * tolerantly:
+ *   - ISO-8601 string   → parsed to epoch seconds
+ *   - epoch-seconds num  → returned as-is
+ *   - epoch-ms num       → divided down (heuristic: `> 1e12` ⇒ milliseconds)
+ *   - null / undefined / unparseable → `undefined`
+ */
+function toEpochSeconds(v) {
+    if (typeof v === "number" && Number.isFinite(v)) {
+        return v > 1e12 ? Math.floor(v / 1000) : v;
+    }
+    if (typeof v === "string") {
+        const ms = Date.parse(v);
+        return Number.isNaN(ms) ? undefined : Math.floor(ms / 1000);
+    }
+    return undefined;
+}
+/** Best-effort read of a JWT payload's numeric `exp` claim (epoch seconds).
+ *  The signature is NOT verified — the server is authoritative; this only
+ *  reads the expiry of an already-trusted token as a fallback when the
+ *  server's `validUntil` is missing or unparseable. Returns `undefined` for a
+ *  malformed / non-JWT string so callers degrade gracefully. */
+function jwtExpSeconds(jwt) {
+    if (!jwt)
+        return undefined;
+    const parts = jwt.split(".");
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
+        const bytes = Uint8Array.from(atob(b64 + pad), (c) => c.charCodeAt(0));
+        const payload = JSON.parse(new TextDecoder().decode(bytes));
+        return toEpochSeconds(payload.exp);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Translate the stack-account wire payload into ownsuite's
+ *  {@link AuthTokenResult}, converting `validFrom` / `validUntil` (ISO string
+ *  or numeric) to epoch seconds. Prefers the server's `validUntil`; falls back
+ *  to the JWT's own `exp` claim when `validUntil` is absent or unparseable, so
+ *  a malformed validity field can never produce an immortal client session.
+ *  Replaces the previous blind `r.data as AuthTokenResult` cast. */
+function normalizeAuthResult(data) {
+    const validFrom = toEpochSeconds(data.validFrom);
+    const validUntil = toEpochSeconds(data.validUntil) ??
+        jwtExpSeconds(data.jwt);
+    return {
+        jwt: data.jwt,
+        email: data.email,
+        roles: data.roles ?? [],
+        isVerified: data.isVerified,
+        requiresVerification: data.requiresVerification,
+        ...(validFrom !== undefined ? { validFrom } : {}),
+        ...(validUntil !== undefined ? { validUntil } : {}),
+    };
+}
 /** Build the default {@link AuthAdapter} for `@marianmeres/stack-account`.
  *  Points at `{baseUrl}/auth/*` (register/login/logout/verify/password/
  *  delete) and `{baseUrl}/oauth/*` (init + callback). */
@@ -91,11 +155,11 @@ export function createStackAccountAuthAdapter(opts = {}) {
     return {
         async register(input, ctx) {
             const r = await postJson(doFetch, join(base, "/register"), input, ctx);
-            return r.data;
+            return normalizeAuthResult(r.data);
         },
         async login(input, ctx) {
             const r = await postJson(doFetch, join(base, "/login"), input, ctx);
-            return r.data;
+            return normalizeAuthResult(r.data);
         },
         async logout(ctx) {
             await requestJson(doFetch, join(base, "/logout"), { method: "POST" }, ctx);

package/dist/domains/session.js

@@ -151,11 +151,16 @@ export class SessionManager {
                 storage.del(this.#storageKey);
                 return null;
             }
-            if (parsed.expiresAt !== null &&
-                parsed.expiresAt !== undefined &&
-                parsed.expiresAt * 1000 <= Date.now()) {
-                storage.del(this.#storageKey);
-                return null;
+            if (parsed.expiresAt !== null && parsed.expiresAt !== undefined) {
+                // Fail-closed: `expiresAt` MUST be finite epoch seconds. A
+                // present-but-non-finite value (e.g. an ISO string laundered
+                // through a buggy adapter) is treated as expired and wiped,
+                // rather than yielding `NaN <= now === false` → immortal session.
+                const exp = typeof parsed.expiresAt === "number" ? parsed.expiresAt : NaN;
+                if (!Number.isFinite(exp) || exp * 1000 <= Date.now()) {
+                    storage.del(this.#storageKey);
+                    return null;
+                }
             }
             return parsed;
         }

package/dist/oauth/popup.js

@@ -18,7 +18,7 @@ const DEFAULT_FEATURES = "width=500,height=700,noopener=no,noreferrer=no";
  * message is an error, or if the optional timeout fires.
  */
 export function openOAuthPopup(url, options = {}) {
-    const host = (options.host ?? globalThis);
+    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"));
     }

package/dist/ownsuite.js

@@ -211,9 +211,7 @@ export class Ownsuite {
     setContext(ctx, options = {}) {
         if (this.#destroyed)
             return;
-        this.#context = options.replace
-            ? { ...ctx }
-            : { ...this.#context, ...ctx };
+        this.#context = options.replace ? { ...ctx } : { ...this.#context, ...ctx };
         for (const m of this.#domains.values()) {
             if (options.replace)
                 m.replaceContext(this.#context);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ownsuite",
-	"version": "2.2.3",
+	"version": "2.3.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -22,9 +22,9 @@
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/clog": "^3.17.1",
-		"@marianmeres/collection-types": "^1.37.0",
-		"@marianmeres/http-utils": "^2.6.0",
+		"@marianmeres/clog": "^3.21.0",
+		"@marianmeres/collection-types": "^1.41.0",
+		"@marianmeres/http-utils": "^2.11.0",
 		"@marianmeres/pubsub": "^3.0.0",
 		"@marianmeres/store": "^3.0.1"
 	},