@marianmeres/ownsuite 2.0.0 → 2.2.1

package/dist/types/auth.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @module types/auth
+ *
+ * Types for the auth / profile / session managers that extend ownsuite with
+ * a first-class identity lifecycle (register, login, logout, OAuth link/
+ * unlink, email verification, password reset, delete account, profile edit).
+ *
+ * Design notes:
+ *  - The adapter pattern mirrors `OwnedCollectionAdapter` — consumers plug in
+ *    an implementation; no HTTP code lives in managers.
+ *  - The `SessionManager` is the single source of truth for the JWT and the
+ *    current subject. Adapters never hold auth state.
+ *  - OAuth initiation returns a URL — the popup / redirect dance is handled
+ *    by the `openOAuthPopup` helper (see `oauth/popup.ts`) rather than the
+ *    adapter itself.
+ */
+import type { OwnsuiteContext } from "./state.js";
+/** Lifecycle state of the current session. */
+export type SessionStatus = 
+/** No JWT. Either never logged in or explicitly logged out. */
+"anonymous"
+/** JWT present, subject loaded, login succeeded. */
+ | "authenticated"
+/**
+ * Account exists and credentials were correct BUT the server is blocking
+ * login because the email is not yet verified. UI should surface "check
+ * your email" without a second round-trip. Emitted when `auth.login()`
+ * or `auth.register()` hits the verification gate.
+ */
+ | "unverified";
+/**
+ * Minimal subject shape exposed to consumers. Matches what stack-account's
+ * `/me` returns plus the fields needed for role-gating.
+ */
+export interface SessionSubject {
+    id: string;
+    email: string;
+    roles: string[];
+    isVerified: boolean;
+    /** Whether the account has a password (OAuth-only accounts do not). */
+    hasPassword: boolean;
+}
+/** Observable session state — stored by the SessionManager. */
+export interface SessionState {
+    status: SessionStatus;
+    subject: SessionSubject | null;
+    jwt: string | null;
+    /** Unix-seconds expiry (optional — not every server shape returns one). */
+    expiresAt: number | null;
+}
+/**
+ * Pluggable storage for persisting session state across reloads. Consumers
+ * can pass "local" / "session" / "memory" or supply their own object
+ * matching this interface (useful for Tauri, WebExtensions, SSR guards).
+ */
+export interface SessionStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    del(key: string): void;
+}
+export type SessionStorageType = "local" | "session" | "memory" | SessionStorage;
+export type OAuthProvider = "google" | "facebook" | "apple" | "twitter";
+export interface OAuthConnection {
+    provider: OAuthProvider;
+    display_name?: string;
+    avatar_url?: string;
+    email?: string;
+}
+/** Action verb for the OAuth init URL — `login` creates/looks-up an account,
+ *  `link` attaches the provider to the currently authenticated subject. */
+export type OAuthAction = "login" | "link";
+export interface OAuthInitOptions {
+    action: OAuthAction;
+    /** Where to redirect after the provider callback (server honours this). */
+    redirect?: string;
+    /** Language code forwarded to the server for error-page localization. */
+    lang?: string;
+    /** `"popup"` (default) or `"redirect"` — the manager uses this to decide
+     *  whether to open a popup and wait for a postMessage, or redirect the
+     *  top window. */
+    mode?: "popup" | "redirect";
+    /** Same semantics as {@link AuthActionOptions.remember} — pins the
+     *  resulting session to `localStorage` (`true`) or `sessionStorage`
+     *  (`false`). Only meaningful for `action: "login"`. */
+    remember?: boolean;
+}
+/**
+ * Options accepted by `AuthManager.login` / `register` /
+ * `handleOAuthCallback` to express per-login storage preference
+ * ("Remember me").
+ */
+export interface AuthActionOptions {
+    /** `true` → persist the resulting session to `localStorage` (survives
+     *  browser restart).
+     *  `false` → persist to `sessionStorage` (dies with the tab).
+     *  `undefined` → use the `SessionManager`'s configured default backend.
+     *
+     *  Silently ignored when the `SessionManager` was constructed with a
+     *  custom `SessionStorage` object — the single custom backend is used
+     *  regardless. */
+    remember?: boolean;
+}
+/**
+ * Uniform result shape for `register` / `login` / OAuth success. When the
+ * server returns `requiresVerification: true` (i.e. the verification gate is
+ * on and the email is not yet verified), the JWT will be absent and the
+ * manager flips session.status to "unverified".
+ */
+export interface AuthTokenResult {
+    jwt?: string;
+    email: string;
+    roles: string[];
+    isVerified?: boolean;
+    validFrom?: number;
+    validUntil?: number;
+    /** Set by the server when login auto-login is declined for a not-yet-
+     *  verified account. Mutually exclusive with jwt in practice. */
+    requiresVerification?: boolean;
+}
+export interface ProfileResult {
+    email: string;
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;
+    oauthConnections: OAuthConnection[];
+}
+export interface AuthAdapter {
+    register(input: {
+        email: string;
+        password: string;
+        password_confirm: string;
+        roles?: string[];
+        /** Optional extras — consumer forwards any configured
+         *  registrationFields the server expects. */
+        extras?: Record<string, unknown>;
+    }, ctx: OwnsuiteContext): Promise<AuthTokenResult>;
+    login(input: {
+        email: string;
+        password: string;
+    }, ctx: OwnsuiteContext): Promise<AuthTokenResult>;
+    /** Best-effort server-side revocation. Must not throw on
+     *  already-anonymous state. */
+    logout(ctx: OwnsuiteContext): Promise<void>;
+    /** Sync URL builder. The manager opens this URL in a popup (default) or
+     *  redirects the top window depending on mode. */
+    oauthInitUrl(provider: OAuthProvider, opts: OAuthInitOptions, ctx: OwnsuiteContext): string;
+    /** For the redirect-mode callback path: extract result from the current
+     *  URL (or a server-rendered payload) and return it. Popup-mode uses the
+     *  `openOAuthPopup` helper directly and does not call this. */
+    handleOAuthCallback?(ctx: OwnsuiteContext): Promise<AuthTokenResult>;
+    resendVerification(input: {
+        email: string;
+        lang?: string;
+    }, ctx: OwnsuiteContext): Promise<void>;
+    requestPasswordReset(input: {
+        email: string;
+        lang?: string;
+    }, ctx: OwnsuiteContext): Promise<void>;
+    changePassword(input: {
+        /** Required for authenticated self-change. */
+        current_password?: string;
+        new_password: string;
+        confirm_password: string;
+        /** Required for token-based reset. */
+        token?: string;
+    }, ctx: OwnsuiteContext): Promise<void>;
+    deleteAccount(input: {
+        password?: string;
+        confirm?: boolean;
+    }, ctx: OwnsuiteContext): Promise<{
+        deleted: true;
+    }>;
+}
+export interface ProfileAdapter {
+    get(ctx: OwnsuiteContext): Promise<ProfileResult>;
+    update(input: {
+        email?: string;
+        current_password?: string;
+    }, ctx: OwnsuiteContext): Promise<ProfileResult>;
+    listOAuth(ctx: OwnsuiteContext): Promise<OAuthConnection[]>;
+    unlinkOAuth(provider: OAuthProvider, ctx: OwnsuiteContext): Promise<void>;
+}

package/dist/types/auth.js

@@ -0,0 +1,17 @@
+/**
+ * @module types/auth
+ *
+ * Types for the auth / profile / session managers that extend ownsuite with
+ * a first-class identity lifecycle (register, login, logout, OAuth link/
+ * unlink, email verification, password reset, delete account, profile edit).
+ *
+ * Design notes:
+ *  - The adapter pattern mirrors `OwnedCollectionAdapter` — consumers plug in
+ *    an implementation; no HTTP code lives in managers.
+ *  - The `SessionManager` is the single source of truth for the JWT and the
+ *    current subject. Adapters never hold auth state.
+ *  - OAuth initiation returns a URL — the popup / redirect dance is handled
+ *    by the `openOAuthPopup` helper (see `oauth/popup.ts`) rather than the
+ *    adapter itself.
+ */
+export {};

package/dist/types/events.d.ts

@@ -4,6 +4,7 @@
  * Event type definitions for the ownsuite event system.
  */
 import type { DomainError, DomainState } from "./state.js";
+import type { OAuthConnection, OAuthProvider, SessionState } from "./auth.js";
 /**
  * Domain identifier in ownsuite is an arbitrary string (the collection name
  * or any label the consumer chose), unlike ecsuite's fixed enum of six
@@ -11,7 +12,7 @@ import type { DomainError, DomainState } from "./state.js";
  */
 export type DomainName = string;
 /** Event types emitted by the suite. */
-export type OwnsuiteEventType = "domain:state:changed" | "domain:error" | "domain:synced" | "own:list:fetched" | "own:row:fetched" | "own:row:created" | "own:row:updated" | "own:row:deleted";
+export type OwnsuiteEventType = "domain:state:changed" | "domain:error" | "domain:synced" | "own:list:fetched" | "own:row:fetched" | "own:row:created" | "own:row:updated" | "own:row:deleted" | "auth:register" | "auth:login" | "auth:logout" | "auth:session:changed" | "auth:verification:required" | "profile:updated" | "oauth:linked" | "oauth:unlinked";
 /** Base event data. */
 export interface OwnsuiteEventBase {
     /** Event timestamp */
@@ -59,5 +60,43 @@ export interface RowDeletedEvent extends OwnsuiteEventBase {
     type: "own:row:deleted";
     rowId: string;
 }
+export interface AuthEventBase {
+    timestamp: number;
+}
+export interface AuthRegisterEvent extends AuthEventBase {
+    type: "auth:register";
+    email: string;
+    /** True when the server requires email verification (no auto-login). */
+    requiresVerification: boolean;
+}
+export interface AuthLoginEvent extends AuthEventBase {
+    type: "auth:login";
+    email: string;
+}
+export interface AuthLogoutEvent extends AuthEventBase {
+    type: "auth:logout";
+    /** Id of the subject that just logged out, if known. */
+    subjectId?: string;
+}
+export interface AuthSessionChangedEvent extends AuthEventBase {
+    type: "auth:session:changed";
+    session: SessionState;
+}
+export interface AuthVerificationRequiredEvent extends AuthEventBase {
+    type: "auth:verification:required";
+    email: string;
+}
+export interface ProfileUpdatedEvent extends AuthEventBase {
+    type: "profile:updated";
+    email: string;
+}
+export interface OAuthLinkedEvent extends AuthEventBase {
+    type: "oauth:linked";
+    connection: OAuthConnection;
+}
+export interface OAuthUnlinkedEvent extends AuthEventBase {
+    type: "oauth:unlinked";
+    provider: OAuthProvider;
+}
 /** All event types union. */
-export type OwnsuiteEvent = StateChangedEvent | ErrorEvent | SyncedEvent | ListFetchedEvent | RowFetchedEvent | RowCreatedEvent | RowUpdatedEvent | RowDeletedEvent;
+export type OwnsuiteEvent = StateChangedEvent | ErrorEvent | SyncedEvent | ListFetchedEvent | RowFetchedEvent | RowCreatedEvent | RowUpdatedEvent | RowDeletedEvent | AuthRegisterEvent | AuthLoginEvent | AuthLogoutEvent | AuthSessionChangedEvent | AuthVerificationRequiredEvent | ProfileUpdatedEvent | OAuthLinkedEvent | OAuthUnlinkedEvent;

package/dist/types/mod.d.ts

@@ -1,3 +1,4 @@
 export * from "./state.js";
 export * from "./events.js";
 export * from "./adapter.js";
+export * from "./auth.js";

package/dist/types/mod.js

@@ -1,3 +1,4 @@
 export * from "./state.js";
 export * from "./events.js";
 export * from "./adapter.js";
+export * from "./auth.js";

package/dist/types/state.d.ts

@@ -42,6 +42,13 @@ export interface DomainStateWrapper<T> {
 export interface OwnsuiteContext {
     /** Hint — not used for authorization. The server is authoritative. */
     subjectId?: string;
+    /**
+     * JWT to pass through to adapters as the `Authorization: Bearer <jwt>`
+     * credential. Managed by the `SessionManager` — consumers don't set this
+     * directly. When present, adapters must forward it. When absent, the
+     * server will treat the request as anonymous.
+     */
+    jwt?: string;
     /**
      * Per-operation abort signal injected by the manager. Adapters should
      * forward this to `fetch(url, { signal: ctx.signal })`. Aborts fire on

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ownsuite",
-	"version": "2.0.0",
+	"version": "2.2.1",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",