@gosso/client 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,49 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-24
+
+### Changed
+- Promote `0.4.0-rc.2` to `latest` without runtime code changes after Blog and Admin integration verification.
+
+## [0.4.0-rc.2] - 2026-08-24
+
+### Fixed
+- Correct the release workflow's tag-to-package version validation before its first npm publish attempt.
+
+## [0.4.0-rc.1] - 2026-08-24
+
+### Added
+- Add typed `ApiError` responses with HTTP status and stable error codes.
+- Add SDK-owned password reset request and completion methods.
+- Add exact `allowedApiOrigins` enforcement for authenticated requests.
+- Add a 0.4 migration guide and package provenance release workflow.
+
+### Changed
+- Normalize Gouno, OAuth, empty, and invalid JSON API responses through the shared envelope parser.
+- Make HttpOnly Cookie Session the default when `sessionMode` is omitted.
+- Return a discriminated Cookie or legacy-token result from OAuth callbacks.
+- Keep explicit legacy token sessions in memory only; page reload requires reauthentication.
+
+### Security
+- Fail closed when Web Crypto is unavailable instead of generating OAuth state and PKCE verifier values with `Math.random`.
+- Stop writing access and refresh tokens to Web Storage or JavaScript cookies.
+- Reject credentialed requests to untrusted origins and reject external or protocol-relative login/logout return paths.
+
+## [0.3.0] - 2026-08-15
+### Added
+- Add `subscribe(listener)` to `GossoClient` so every SPA can observe the
+  cookie-session snapshot without maintaining a duplicate authentication store.
+- Add `refreshIdentityRequests` for the GOSSO Admin SPA, whose protected API
+  requests are served by the same origin as the identity provider.
+
+## [0.2.1] - 2026-08-14
+### Fixed
+- Select application and Gosso CSRF cookies by exact request target instead of cookie order.
+- Recover an expired Gosso CSRF cookie before Cookie Session refresh, retry application requests once, and restart PKCE without redirect loops when refresh fails.
+- Coordinate Cookie Session refresh within a page and across tabs using single-flight and Web Locks.
+- Clear client state after logout only when Gosso confirms server-side session revocation.
+
 ## [0.2.0] - 2026-08-12
 ### Added
 - Add opt-in `sessionMode: "cookie"` for HttpOnly Cookie-backed SPA sessions. It keeps access and refresh tokens out of JavaScript-accessible storage while preserving PKCE, MFA, passkeys and account-management APIs.

package/MIGRATING.md

@@ -0,0 +1,15 @@
+# Migrating to 0.4
+
+Version 0.4 makes HttpOnly Cookie Session the default. Omit `sessionMode`, or
+set it to `cookie`. Gosso must be reachable over HTTPS and configured with an
+exact credentialed CORS origin when it is not same-origin.
+
+Cookie callbacks return `{ sessionMode: 'cookie', redirectTo }`; tokens are set
+only by Gosso with `Set-Cookie` and are not available to JavaScript. Replace
+code that reads `tokenSet`, Web Storage, or an access-token cookie with
+`getSnapshot()`, `subscribe()`, and `apiFetch()`.
+
+`sessionMode: 'token'` remains an explicit legacy option. Its tokens live only
+in memory and disappear on reload. `apiFetch` sends credentials only to the
+page origin, issuer origin, or an exact origin listed in `allowedApiOrigins`.
+All login and logout return values must be application-local paths.

package/README.md

@@ -5,10 +5,12 @@ Browser SDK for Gosso OAuth/OIDC single-page application clients.
 `@gosso/client` provides the protocol and account self-service layer for ordinary Gosso clients:
 
 - Authorization Code + PKCE redirects and callback handling
-- token storage, userinfo loading, logout, and automatic refresh
-- authenticated `apiFetch` with bearer headers and 401 retry
+- HttpOnly Cookie Session, userinfo loading, logout, and automatic refresh
+- origin-restricted authenticated `apiFetch` with CSRF handling and 401 retry
 - username/password login, MFA verification, and passkey login
 - profile, password, email, MFA, passkey, and session management APIs
+- password reset request and completion APIs
+- typed API errors for consistent consumer handling
 
 The package intentionally does not ship React UI. Build app-specific pages with your own design system and call the SDK methods underneath.
 
@@ -31,6 +33,8 @@ export const gossoClient = createGossoClient({
   postLoginDefaultPath: '/admin',
   loginPath: '/login',
   storagePrefix: 'my-app',
+  sessionProfileEndpoint: '/api/me/session',
+  csrfCookieName: 'blog_csrf_token',
 });
 ```
 
@@ -87,6 +91,9 @@ await gossoClient.confirmEmailChange(newEmail, code);
 const mfaStatus = await gossoClient.getMfaStatus();
 const passkeys = await gossoClient.listPasskeys();
 const sessions = await gossoClient.listSessions();
+
+await gossoClient.requestPasswordReset(email);
+await gossoClient.resetPassword(resetToken, newPassword);
 ```
 
 ## Configuration
@@ -100,20 +107,38 @@ interface GossoClientConfig {
   postLoginDefaultPath: string;
   loginPath: string;
   storagePrefix: string;
+  sessionMode?: 'token' | 'cookie';
+  allowedApiOrigins?: readonly string[];
+  sessionProfileEndpoint?: string;
+  csrfCookieName?: string;
   fetchImpl?: typeof fetch;
   onAuthRequired?: () => void;
   onSessionChanged?: (snapshot: SessionSnapshot) => void;
 }
 ```
 
-Use a unique `storagePrefix` for each SPA on the same origin to avoid token collisions.
+Cookie Session is the default when `sessionMode` is omitted. Use a unique
+`storagePrefix` for each SPA on the same origin to isolate transient PKCE,
+profile, and refresh-coordination state.
+
+`apiFetch` accepts the page origin and issuer origin by default. Add only exact,
+trusted HTTPS origins to `allowedApiOrigins`; credentials are rejected before a
+request is sent to any other origin.
+
+In Cookie Session mode, `csrfCookieName` belongs to the application API only. Gosso identity requests always use `__Host-csrf_token` on HTTPS, or `csrf_token` only for an HTTP development issuer. Cookie lookup is exact and never depends on `document.cookie` order.
+
+Gosso's default lifetimes are independent: Access Token 15 minutes, Refresh Token 168 hours, Session 24 hours, and CSRF Cookie 4 hours (capped at 24 hours). A missing CSRF Cookie does not invalidate the Refresh Token: the SDK first performs a safe session GET to recover Gosso's CSRF Cookie, then refreshes and retries the original application request once.
 
 ## Security Notes
 
 - Use Authorization Code + PKCE for browser clients.
 - Serve production clients over HTTPS.
 - Keep the Gosso issuer and app behind a same-origin gateway when possible.
-- Tokens are stored in browser `localStorage` and mirrored to an `access_token` cookie for same-origin Gosso redirects. Treat XSS prevention as part of your security boundary.
+- Cookie Session is the secure default; access and refresh tokens remain in server-set `__Host-*` HttpOnly cookies and are never written by the SDK to Web Storage or JavaScript cookies.
+- Explicit `sessionMode: "token"` is a legacy, tab-local mode. Tokens stay in memory, disappear on reload, and are sent only to configured origins.
+- Cookie Session refresh is single-flight within a page and coordinated across tabs with the Web Locks API. Only a non-sensitive refresh generation marker is stored in `localStorage`.
+- OAuth state and PKCE verifier generation requires Web Crypto and fails closed when a cryptographically secure random source is unavailable.
+- Login and logout return locations must be application-local paths. See [MIGRATING.md](./MIGRATING.md) before upgrading from 0.3 or earlier.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,6 @@
+# Security Policy
+
+Only the latest minor version receives security fixes. Report vulnerabilities
+through GitHub Security Advisories and do not disclose credentials or exploit
+details in public issues. Include the affected version, impact, and a minimal
+reproduction. Maintainers aim to acknowledge reports within seven days.

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import type { AuthCallbackResult, AuthenticationResult, GossoClientConfig, LoginResult, MfaEnrollment, MfaStatus, PasskeyInfo, SessionInfo, SessionListener, SessionSnapshot, TokenResponse, UserProfile } from "./types.js";
+export declare const defaultConfig: Pick<GossoClientConfig, "scope" | "postLoginDefaultPath" | "loginPath" | "storagePrefix" | "sessionMode">;
+export declare function createGossoClient(inputConfig: GossoClientConfig): {
+    config: {
+        issuer: string;
+        sessionMode: "token" | "cookie" | undefined;
+        clientId: string;
+        redirectUri: string;
+        scope: string;
+        postLoginDefaultPath: string;
+        loginPath: string;
+        storagePrefix: string;
+        allowedApiOrigins?: readonly string[];
+        sessionProfileEndpoint?: string;
+        csrfCookieName?: string;
+        refreshIdentityRequests?: boolean;
+        fetchImpl?: typeof fetch;
+        onAuthRequired?: () => void;
+        onSessionChanged?: (snapshot: SessionSnapshot) => void;
+    };
+    storageKeys: {
+        accessToken: string;
+        refreshToken: string;
+        userProfile: string;
+        pkceVerifier: string;
+        authState: string;
+        postLoginRedirect: string;
+        tokenIssuedAt: string;
+        tokenExpiresIn: string;
+        refreshLock: string;
+        refreshGeneration: string;
+        authRedirectGuard: string;
+    };
+    getAccessToken: () => string | null;
+    getRefreshToken: () => string | null;
+    getUserProfile: () => UserProfile | null;
+    getSnapshot: () => SessionSnapshot;
+    subscribe: (listener: SessionListener) => () => void;
+    isLoggedIn: () => boolean;
+    isAdmin: () => boolean;
+    saveTokenSet: (data: TokenResponse | {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+    }) => void;
+    clear: () => void;
+    logout: (redirectTo?: string) => Promise<void>;
+    redirectToAuthorize: (customRedirectUri?: string) => Promise<void>;
+    exchangeCodeForToken: (code: string, state: string) => Promise<AuthenticationResult>;
+    handleRedirectCallback: (code: string, state: string) => Promise<AuthCallbackResult>;
+    fetchUserProfile: (accessToken?: string | null) => Promise<UserProfile>;
+    refreshAccessToken: () => Promise<string>;
+    apiFetch: (url: string, options?: RequestInit) => Promise<Response>;
+    loginWithPassword: (username: string, password: string) => Promise<LoginResult>;
+    requestPasswordReset: (email: string) => Promise<void>;
+    resetPassword: (token: string, newPassword: string) => Promise<void>;
+    verifyMfa: (mfaToken: string, code: string, type?: "totp" | "passkey") => Promise<AuthenticationResult>;
+    loginWithPasskey: () => Promise<AuthenticationResult>;
+    updateProfile: (displayName: string) => Promise<UserProfile>;
+    changePassword: (currentPassword: string, newPassword: string) => Promise<void>;
+    requestEmailChange: (newEmail: string, password: string) => Promise<void>;
+    confirmEmailChange: (newEmail: string, code: string) => Promise<UserProfile>;
+    getMfaStatus: () => Promise<MfaStatus>;
+    enrollMfa: () => Promise<MfaEnrollment>;
+    activateMfa: (code: string) => Promise<string[]>;
+    disableMfa: (currentPassword: string) => Promise<void>;
+    generateBackupCodes: () => Promise<string[]>;
+    listPasskeys: () => Promise<PasskeyInfo[]>;
+    registerPasskey: (name: string) => Promise<void>;
+    deletePasskey: (id: string) => Promise<void>;
+    listSessions: () => Promise<SessionInfo[]>;
+    getCurrentSession: () => Promise<SessionInfo>;
+    revokeSession: (id: string) => Promise<void>;
+};
+export type GossoClient = ReturnType<typeof createGossoClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,SAAS,EAET,WAAW,EAEX,WAAW,EACX,eAAe,EACf,eAAe,EACf,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AA+BpB,eAAO,MAAM,aAAa,EAAE,IAAI,CAC9B,iBAAiB,EACf,OAAO,GACP,sBAAsB,GACtB,WAAW,GACX,eAAe,GACf,aAAa,CAOhB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BA8CnC,MAAM,GAAG,IAAI;2BAEZ,MAAM,GAAG,IAAI;0BAZjB,WAAW,GAAG,IAAI;uBAelB,eAAe;0BAwBV,eAAe;;;yBAStC,aAAa,GACb;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;;;8CAqapB,MAAM;iCAwBrD,MAAM,SACL,MAAM,KACZ,OAAO,CAAC,oBAAoB,CAAC;mCA0CxB,MAAM,SACL,MAAM,KACZ,OAAO,CAAC,kBAAkB,CAAC;uDArO3B,OAAO,CAAC,WAAW,CAAC;8BA9Dc,OAAO,CAAC,MAAM,CAAC;oBAkH7C,MAAM,YACF,WAAW,KACnB,OAAO,CAAC,QAAQ,CAAC;kCAqOR,MAAM,YACN,MAAM,KACf,OAAO,CAAC,WAAW,CAAC;kCAuBoB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;2BAiBxD,MAAM,eACA,MAAM,KAClB,OAAO,CAAC,IAAI,CAAC;0BAcJ,MAAM,QACV,MAAM,SACN,MAAM,GAAG,SAAS,KACvB,OAAO,CAAC,oBAAoB,CAAC;4BAqBG,OAAO,CAAC,oBAAoB,CAAC;iCAuEtB,MAAM;sCAW7B,MAAM,eACV,MAAM;mCAgBuB,MAAM,YAAY,MAAM;mCAexB,MAAM,QAAQ,MAAM;wBAgBjC,OAAO,CAAC,SAAS,CAAC;qBAKrB,OAAO,CAAC,aAAa,CAAC;wBAOjB,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CAAC;kCAqBhB,MAAM;+BASX,OAAO,CAAC,MAAM,EAAE,CAAC;wBAYxB,OAAO,CAAC,WAAW,EAAE,CAAC;4BAQhB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;wBAkE1B,MAAM;wBAOR,OAAO,CAAC,WAAW,EAAE,CAAC;6BAajB,OAAO,CAAC,WAAW,CAAC;wBAQvB,MAAM;EAiDxC;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC"}