capacitor-oidc 0.0.6 → 0.1.1

package/docs/API.md

@@ -1,63 +1,62 @@
 # API and `oidc-client-ts` compatibility
 
-`CapacitorUserManager` extends `UserManager` from `oidc-client-ts`. The adapter
-adds a small native-friendly surface and preserves upstream session objects,
-events, settings, refresh, UserInfo, and revocation behavior where they apply to
-a native public client.
+`CapacitorUserManager` extends `UserManager` from `oidc-client-ts`. Applications
+use the package's manager on web, iOS, and Android; the package selects browser or
+native navigation, storage, renewal, and lifecycle behavior.
 
-## Added API
+## Portable API
 
-| API                                                     | Purpose                                                                  |
-| ------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `CapacitorUserManager.create(settings, nativeOptions?)` | Configures native storage and creates the manager.                       |
-| `signin(args?)`                                         | Runs interactive Authorization Code Flow with PKCE in system UI.         |
-| `signout(args?)`                                        | Runs provider logout in system UI.                                       |
-| `getValidUser(minimumValiditySeconds?)`                 | Returns the user or performs one refresh-token renewal.                  |
-| `cancel()`                                              | Rejects the pending native session.                                      |
-| `dispose()`                                             | Stops renewal, removes the app listener, and cancels pending navigation. |
+| API                                          | Purpose                                                       |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| `CapacitorUserManager.create(configuration)` | Resolves the current platform and restores its stored user.   |
+| `signin(args?)`                              | Starts the configured redirect, popup, or native interaction. |
+| `signout(args?)`                             | Starts the configured provider logout interaction.            |
+| `getValidUser(minimumValiditySeconds?)`      | Returns the user or performs one serialized renewal.          |
+| `cancel()`                                   | Cancels pending native navigation; it is a no-op on web.      |
+| `dispose()`                                  | Stops renewal and disposes platform lifecycle work.           |
 
-Only one configured manager and one interactive native authentication session are
-supported at a time.
+`signin()` and `signout()` return `Promise<void>` consistently. Read user state
+through `getUser()`, `getValidUser()`, or `events`. Configuration-level arguments
+are shallowly merged with call-level arguments, with call values taking
+precedence.
 
-## Relevant inherited API
+## Configuration
 
-The following upstream APIs remain available:
-
-- `getUser()`, `storeUser()`, and `removeUser()`;
-- `signinSilent()` for refresh-token renewal;
-- `revokeTokens()`;
-- `startSilentRenew()` and `stopSilentRenew()`;
-- `events`, including user-loaded, user-unloaded, token-expiring, token-expired,
-  and silent-renew-error events;
-- the upstream `User`, profile, settings, metadata, UserInfo, and token response
-  types.
-
-`signinPopup()` and `signoutPopup()` are inherited and use the native navigator,
-but applications should prefer `signin()` and `signout()`.
-
-## Unsupported browser API
-
-These inherited browser-oriented methods reject with `UNSUPPORTED_RUNTIME`:
+```ts
+interface CapacitorUserManagerConfiguration {
+  common: CapacitorUserManagerCommonSettings;
+  web?: CapacitorWebUserManagerConfiguration;
+  native?: CapacitorNativeUserManagerConfiguration;
+  ios?: CapacitorNativeUserManagerOverride;
+  android?: CapacitorNativeUserManagerOverride;
+}
+```
 
-- `signinRedirect()`, `signinRedirectCallback()`, and `signinCallback()`;
-- `signinSilentCallback()` and iframe-based silent authentication;
-- `signoutRedirect()`, `signoutRedirectCallback()`, and `signoutCallback()`;
-- `signoutSilent()` and `signoutSilentCallback()`;
-- `querySessionStatus()`;
-- Resource Owner Password Credentials.
+Resolution is `common -> web` in a browser and
+`common -> native -> ios|android` on native platforms. All merges are shallow.
 
-The native settings type excludes:
+The web section accepts public-client `UserManagerSettings`, including custom
+`stateStore` and `userStore`, DPoP, silent iframe settings, and session
+monitoring. It also accepts:
 
-- `client_secret` and `client_authentication`;
-- `disablePKCE` and `response_type`;
-- `dpop`;
-- `monitorSession` and `silent_redirect_uri`;
-- custom `stateStore` and `userStore`.
+```ts
+interface CapacitorWebUserManagerConfiguration {
+  settings: CapacitorWebUserManagerSettings;
+  signinMode?: 'redirect' | 'popup';
+  signoutMode?: 'redirect' | 'popup';
+  signinArgs?: CapacitorSigninArgs;
+  signoutArgs?: CapacitorSignoutArgs;
+}
+```
 
-The adapter forces Authorization Code Flow with PKCE, secure native stores, and
-no iframe session monitoring.
+`oidc-client-ts` defaults popup sign-in and sign-out callbacks from
+`settings.redirect_uri` and `settings.post_logout_redirect_uri`. Popup sign-out
+requires either `settings.post_logout_redirect_uri` or
+`settings.popup_post_logout_redirect_uri`. Set the popup-specific URI only when
+it needs to differ.
 
-## Native options
+The native section and platform overrides accept native-compatible settings,
+default arguments, and these options:
 
 ```ts
 interface CapacitorOidcNativeOptions {
@@ -70,22 +69,69 @@ interface CapacitorOidcNativeOptions {
 }
 ```
 
-`storageNamespace` defaults to `default`. Use a stable, application-specific
+`storageNamespace` defaults to `default`. Use a stable application-specific
 value and do not change it between releases unless intentionally starting a new
 session store.
 
+All platforms reject `client_secret`, `client_authentication`, `disablePKCE`,
+and `response_type`. The manager forces Authorization Code Flow with PKCE.
+Native settings additionally exclude browser stores, DPoP, iframe callbacks,
+and browser session monitoring.
+
+### Legacy native configuration
+
+The native-only factory signature from earlier releases remains available so an
+application can upgrade before moving its configuration:
+
+```ts
+const manager = await CapacitorUserManager.create(
+  {
+    authority: 'https://identity.example.com',
+    client_id: 'mobile-app',
+    redirect_uri: 'com.example.app:/callback',
+    scope: 'openid profile offline_access',
+  },
+  { storageNamespace: 'primary' },
+);
+```
+
+This signature and `CapacitorUserManagerSettings` are deprecated. They remain
+native-only and do not infer browser settings. New code should use the layered
+configuration above. `signin()` now returns `Promise<void>` for every factory
+signature; use `getUser()`, `getValidUser()`, or events to read the signed-in
+user.
+
+## Inherited API by platform
+
+| Upstream capability                        | Web                       | iOS and Android                 |
+| ------------------------------------------ | ------------------------- | ------------------------------- |
+| `getUser()`, `storeUser()`, `removeUser()` | Browser stores            | Secure native stores            |
+| `signinRedirect()` and callback            | Supported                 | `UNSUPPORTED_RUNTIME`           |
+| `signinPopup()`                            | Browser popup             | Native system authentication UI |
+| `signinSilent()`                           | Refresh token or iframe   | Refresh token only              |
+| `signoutRedirect()` and callback           | Supported                 | `UNSUPPORTED_RUNTIME`           |
+| `signoutPopup()`                           | Browser popup             | Native system authentication UI |
+| Silent logout and session monitoring       | Supported when configured | `UNSUPPORTED_RUNTIME`           |
+| `revokeTokens()`, UserInfo, and events     | Supported                 | Supported                       |
+| Resource Owner Password Credentials        | Unsupported               | Unsupported                     |
+
+Browser callback dispatch through `signinCallback()` and `signoutCallback()` is
+supported on web. Native callbacks complete inside the system authentication
+session.
+
+The package re-exports `User`, `WebStorageStateStore`, `StateStore`, and
+`UserManagerEvents`, so normal application code does not need to import
+`oidc-client-ts` directly.
+
 ## Adapter error codes
 
-| Code                       | Meaning                                                                  |
-| -------------------------- | ------------------------------------------------------------------------ |
-| `AUTH_SESSION_IN_PROGRESS` | Another native login or logout is active.                                |
-| `USER_CANCELLED`           | The user or application cancelled the system session.                    |
-| `BROWSER_UNAVAILABLE`      | No compatible browser exists or the request endpoint is insecure.        |
-| `INVALID_CALLBACK`         | The callback is absent, malformed, or does not match the configured URI. |
-| `SECURE_STORAGE_ERROR`     | Keychain or Keystore-backed storage failed.                              |
-| `UNSUPPORTED_RUNTIME`      | Web Crypto is unavailable or a browser-only API was called.              |
+| Code                       | Meaning                                                                       |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `AUTH_SESSION_IN_PROGRESS` | Another native login or logout is active.                                     |
+| `USER_CANCELLED`           | The user or application cancelled the native system session.                  |
+| `BROWSER_UNAVAILABLE`      | No compatible native browser exists or the request endpoint is insecure.      |
+| `INVALID_CALLBACK`         | A native callback is absent, malformed, or does not match the configured URI. |
+| `SECURE_STORAGE_ERROR`     | Keychain or Keystore-backed storage failed.                                   |
+| `UNSUPPORTED_RUNTIME`      | Required platform configuration or capability is unavailable.                 |
 
 OAuth and OIDC server errors remain upstream `oidc-client-ts` errors.
-
-For the complete upstream model and event API, use the
-[`oidc-client-ts` documentation](https://authts.github.io/oidc-client-ts/).

package/docs/GETTING_STARTED.md

@@ -2,19 +2,18 @@
 
 ## 1. Configure a public client
 
-Create a native or public client at your identity provider with:
+Create a public client at your identity provider with:
 
 - Authorization Code Flow enabled;
 - PKCE with the `S256` challenge method;
 - no client secret;
-- an exact native redirect URI, such as `com.example.app:/callback`;
-- an exact post-logout redirect URI when the provider supports one;
+- every web, iOS, and Android redirect URI registered exactly;
+- every post-logout redirect URI registered exactly;
 - the `openid` scope and any application scopes you need;
-- a refresh-token or offline-access grant if the app must renew sessions.
+- refresh tokens or offline access when the app must renew sessions.
 
-The redirect URI must be registered at the provider and in the native app. A
-minor difference in scheme, host, path, casing, or slash placement can prevent
-the callback from completing.
+A minor difference in scheme, host, path, casing, or slash placement can prevent
+a callback from completing.
 
 ## 2. Install the package
 
@@ -23,57 +22,95 @@ npm install capacitor-oidc @capacitor/app
 npx cap sync
 ```
 
-Complete the [iOS or Android setup](PLATFORM_SETUP.md) before running the app.
+Complete the [iOS or Android setup](PLATFORM_SETUP.md) before running a native
+build.
 
 ## 3. Create one manager
 
-Create and retain one manager for the application session. Recreating managers
-for individual API calls also recreates listeners and can produce competing
-renewal work.
+Create and retain one manager for the application session. The package detects
+the current platform and resolves settings in this order:
+
+```text
+web:     common -> web
+iOS:     common -> native -> ios
+Android: common -> native -> android
+```
+
+Every merge is shallow, including configured sign-in and sign-out arguments.
 
 ```ts
-import { CapacitorUserManager } from 'capacitor-oidc';
+import { CapacitorUserManager, WebStorageStateStore } from 'capacitor-oidc';
 
-export const auth = await CapacitorUserManager.create(
-  {
+export const auth = await CapacitorUserManager.create({
+  common: {
     authority: 'https://identity.example.com',
-    client_id: 'mobile-app',
-    redirect_uri: 'com.example.app:/callback',
-    post_logout_redirect_uri: 'com.example.app:/logout-callback',
+    client_id: 'public-app',
     scope: 'openid profile offline_access',
     automaticSilentRenew: true,
     loadUserInfo: true,
     revokeTokensOnSignout: true,
   },
-  {
-    prefersEphemeralWebBrowserSession: false,
-    storageNamespace: 'primary',
+  web: {
+    settings: {
+      redirect_uri: `${window.location.origin}/callback`,
+      post_logout_redirect_uri: `${window.location.origin}/logout-callback`,
+      stateStore: new WebStorageStateStore({ store: window.sessionStorage }),
+      userStore: new WebStorageStateStore({ store: window.localStorage }),
+    },
+  },
+  native: {
+    settings: {
+      redirect_uri: 'com.example.app:/callback',
+      post_logout_redirect_uri: 'com.example.app:/logout-callback',
+    },
+    options: {
+      prefersEphemeralWebBrowserSession: false,
+      storageNamespace: 'primary',
+    },
+  },
+  ios: {
+    settings: { redirect_uri: 'com.example.ios:/callback' },
+  },
+  android: {
+    settings: { redirect_uri: 'com.example.android:/callback' },
   },
-);
+});
 ```
 
-`prefersEphemeralWebBrowserSession` defaults to `false`, allowing the system
-browser to reuse an existing provider session. Set it to `true` when an isolated
-session is more important than shared SSO. Android fallback browsers may ignore
-the preference.
+The `web` and `native` sections are optional so a single-platform application
+does not need unused settings. Creation fails clearly if the running platform has
+no matching configuration.
 
-`create()` restores the stored user from secure native storage. When
-`automaticSilentRenew` is enabled, any necessary renewal then runs without
-blocking manager creation. Listen for `silentRenewError` to handle a failed
-startup renewal; temporary failures preserve the stored session.
+Browser-only settings such as custom stores, DPoP, silent iframe callbacks, and
+session monitoring belong in `web.settings`. Native stores and navigation are
+owned by the package and cannot be replaced. Public clients cannot configure a
+secret, disable PKCE, or change the response type on any platform.
 
-## 4. Sign in
+## 4. Handle web callbacks
 
-```ts
-const user = await auth.signin();
+Call the matching callback method on the configured browser route:
 
-console.log(user.profile.sub);
+```ts
+if (window.location.pathname === '/callback') {
+  await auth.signinCallback();
+} else if (window.location.pathname === '/logout-callback') {
+  await auth.signoutCallback();
+}
 ```
 
-The promise resolves after the system authentication session returns to the app,
-the authorization response is validated, and the code is exchanged.
+Native callbacks are completed by the system authentication session and do not
+need application routing.
 
-Listen for session changes through the normal `oidc-client-ts` events:
+## 5. Sign in
+
+```ts
+await auth.signin();
+```
+
+On web, `signin()` uses redirect navigation by default. Set `signinMode: 'popup'`
+in the web section to use a popup. On native platforms it uses the system
+authentication UI. The portable method returns no user because a browser redirect
+leaves the page; read the user after the callback or subscribe to events:
 
 ```ts
 auth.events.addUserLoaded((user) => {
@@ -85,14 +122,12 @@ auth.events.addSilentRenewError((error) => {
 });
 ```
 
-## 5. Get a usable access token
+## 6. Get a usable access token
 
 ```ts
 const user = await auth.getValidUser(30);
 
-if (!user) {
-  // No signed-in session is available.
-} else {
+if (user) {
   await fetch('https://api.example.com/profile', {
     headers: { Authorization: `Bearer ${user.access_token}` },
   });
@@ -100,33 +135,21 @@ if (!user) {
 ```
 
 `getValidUser(30)` returns the current user when its access token is valid for at
-least 30 more seconds. Otherwise it performs one refresh-token renewal. Concurrent
-renewal triggers share the same request.
+least 30 more seconds. Otherwise it performs one renewal. Concurrent renewal
+triggers share the same request. Native renewal requires a refresh token and
+never falls back to an iframe; web renewal retains the normal browser behavior.
 
-## 6. Sign out
+## 7. Sign out and dispose
 
 ```ts
 await auth.signout();
-```
-
-`signout()` opens the provider's end-session endpoint in the same native system
-authentication UI. Provider-specific parameters can be passed through
-`extraQueryParams`; see [Provider configuration](PROVIDERS.md).
-
-Use `removeUser()` when the application intentionally needs local-only logout.
-
-## 7. Dispose application listeners
-
-```ts
 await auth.dispose();
 ```
 
-Call `dispose()` when the manager will no longer be used. It stops silent renewal,
-removes the Capacitor app-state listener, and cancels a pending native session.
-
-## Browser builds
+Web sign-out uses redirects by default and supports `signoutMode: 'popup'`.
+Native sign-out uses the system authentication UI. Use `removeUser()` when the
+application intentionally needs local-only logout.
 
-`CapacitorUserManager` depends on native Capacitor plugins and is not a web
-replacement for `UserManager`. Applications that also run in a normal browser
-should instantiate `UserManager` from `oidc-client-ts` for the web branch and
-`CapacitorUserManager` for the native branch.
+Call `dispose()` when the manager will no longer be used. It stops renewal and,
+on native platforms, removes the app-state listener and cancels pending native
+navigation.

package/docs/PLATFORM_SETUP.md

@@ -39,12 +39,23 @@ entitlement to the application and extension, then configure the expanded access
 group:
 
 ```ts
-const manager = await CapacitorUserManager.create(settings, {
+const manager = await CapacitorUserManager.create({
+  common: {
+    authority: 'https://identity.example.com',
+    client_id: 'public-app',
+  },
+  native: {
+    settings: { redirect_uri: 'com.example.app:/callback' },
+    options: { storageNamespace: 'primary' },
+  },
   ios: {
-    keychainAccessGroup: 'TEAMID.group.com.example.app',
-    keychainAccessibility: 'afterFirstUnlockThisDeviceOnly',
+    options: {
+      ios: {
+        keychainAccessGroup: 'TEAMID.group.com.example.app',
+        keychainAccessibility: 'afterFirstUnlockThisDeviceOnly',
+      },
+    },
   },
-  storageNamespace: 'primary',
 });
 ```
 

package/docs/PROVIDERS.md

@@ -1,33 +1,27 @@
 # Provider configuration
 
-`capacitor-oidc` works with providers that support Authorization Code Flow with
-PKCE for public clients and permit token-related requests from the configured
-Capacitor origin.
-
-## Provider checklist
-
-For every provider:
-
-1. Create a native, mobile, SPA, or other public client. Do not create or embed a
-   client secret.
-2. Enable Authorization Code Flow and PKCE with `S256`.
-3. Register the native redirect and post-logout redirect URIs exactly.
-4. Enable refresh tokens and request the provider's offline-access scope if the
-   app must renew sessions.
-5. Allow the app's Capacitor origin through CORS for discovery, token, refresh,
-   UserInfo, and revocation endpoints used by your configuration.
-6. Use HTTPS for provider endpoints.
-
-The recipes below identify the relevant authority and provider-console choices.
-They do not replace the provider's own security guidance.
-
-| Provider           | Current package validation                                      |
-| ------------------ | --------------------------------------------------------------- |
-| Amazon Cognito     | Basic login tested on a physical iOS device; edge cases remain. |
-| Auth0              | Configuration guidance only.                                    |
-| Keycloak           | Configuration guidance only.                                    |
-| Okta               | Configuration guidance only.                                    |
-| Microsoft Entra ID | Configuration guidance only.                                    |
+The recipes below cover the settings that differ between providers.
+`capacitor-oidc` does not contain provider-specific protocol code; it passes the
+configured OpenID Connect settings to `oidc-client-ts`.
+
+## Requirements
+
+Use a public client that supports Authorization Code Flow with `S256` PKCE.
+Register every web and native redirect URI and post-logout redirect URI exactly,
+and configure the provider application without a client secret. A secret cannot
+be kept in a Capacitor app.
+
+If the app refreshes or revokes tokens, or loads UserInfo from the Capacitor
+runtime, the provider must allow the configured Capacitor origin to call those
+endpoints. Request `offline_access`, or the provider's equivalent, when the app
+needs refresh tokens. Use HTTPS outside local test environments.
+
+## Test status
+
+The basic Amazon Cognito sign-in flow has been tested on a physical iOS device.
+The Auth0, Keycloak, Okta, and Microsoft Entra ID sections document expected
+configuration, but those recipes are not yet covered by the package's provider
+integration tests.
 
 ## Amazon Cognito
 
@@ -43,20 +37,33 @@ const domain = 'https://example.auth.eu-central-1.amazoncognito.com';
 const issuer = `https://cognito-idp.${region}.amazonaws.com/${userPoolId}`;
 
 const manager = await CapacitorUserManager.create({
-  authority: issuer,
-  client_id: clientId,
-  redirect_uri: 'com.example.app://oauth',
-  scope: 'openid email profile aws.cognito.signin.user.admin',
-  automaticSilentRenew: true,
-  revokeTokensOnSignout: true,
-  metadata: {
-    issuer,
-    authorization_endpoint: `${domain}/oauth2/authorize`,
-    token_endpoint: `${domain}/oauth2/token`,
-    userinfo_endpoint: `${domain}/oauth2/userInfo`,
-    revocation_endpoint: `${domain}/oauth2/revoke`,
-    end_session_endpoint: `${domain}/logout`,
-    jwks_uri: `${issuer}/.well-known/jwks.json`,
+  common: {
+    authority: issuer,
+    client_id: clientId,
+    scope: 'openid email profile aws.cognito.signin.user.admin',
+    automaticSilentRenew: true,
+    revokeTokensOnSignout: true,
+    metadata: {
+      issuer,
+      authorization_endpoint: `${domain}/oauth2/authorize`,
+      token_endpoint: `${domain}/oauth2/token`,
+      userinfo_endpoint: `${domain}/oauth2/userInfo`,
+      revocation_endpoint: `${domain}/oauth2/revoke`,
+      end_session_endpoint: `${domain}/logout`,
+      jwks_uri: `${issuer}/.well-known/jwks.json`,
+    },
+  },
+  web: {
+    settings: { redirect_uri: 'https://app.example.com/oauth' },
+    signoutArgs: {
+      extraQueryParams: { client_id: clientId, logout_uri: 'https://app.example.com' },
+    },
+  },
+  native: {
+    settings: { redirect_uri: 'com.example.app://oauth' },
+    signoutArgs: {
+      extraQueryParams: { client_id: clientId, logout_uri: 'com.example.app://oauth' },
+    },
   },
 });
 ```
@@ -65,8 +72,8 @@ Configure the Cognito app client without a secret and register
 `com.example.app://oauth` as an allowed callback and sign-out URL.
 
 Cognito logout uses `logout_uri` instead of the standard
-`post_logout_redirect_uri`. Leave `post_logout_redirect_uri` unset in the manager
-settings and pass Cognito's parameters when signing out:
+`post_logout_redirect_uri`. Leave `post_logout_redirect_uri` unset and configure
+the platform-specific default arguments as above, or pass them for one call:
 
 ```ts
 await manager.signout({
@@ -175,7 +182,7 @@ and [redirect URI restrictions](https://learn.microsoft.com/en-us/entra/identity
 
 ## Other providers
 
-Start with the generic checklist and the provider's OpenID Connect discovery
+Start with the requirements above and the provider's OpenID Connect discovery
 document. If discovery does not describe a usable native flow, pass explicit
 `metadata` through the upstream `UserManagerSettings` rather than adding
 provider-specific code to this package.

package/docs/README.md

@@ -1,8 +1,8 @@
 # Documentation
 
-`capacitor-oidc` is a native Capacitor adapter for `oidc-client-ts`. Start with
-[Getting started](GETTING_STARTED.md), then complete the setup for both your
-native platform and identity provider.
+`capacitor-oidc` provides one `oidc-client-ts`-based manager for web, iOS, and
+Android. Start with [Getting started](GETTING_STARTED.md), then complete the
+setup for each native platform and your identity provider.
 
 ## Use the package
 
@@ -20,4 +20,4 @@ native platform and identity provider.
 - [Requirements and acceptance criteria](../REQUIREMENTS.md)
 - [Testing](TESTING.md)
 - [Publishing](PUBLISHING.md)
-- [Architecture decisions](adr)
+- [Architecture decisions](adr/)

package/docs/TESTING.md

@@ -18,6 +18,7 @@ npm run verify:android
 CI currently runs:
 
 - TypeScript linting, Vitest, package builds, and `npm pack --dry-run`;
+- unit coverage for web/native configuration resolution and navigation dispatch;
 - iOS XCTest in an iOS 18.5 simulator;
 - Android unit tests, assembly, and lint with SDK 36;
 - packaged iOS and Android consumer builds with Capacitor 7 and 8;
@@ -35,7 +36,8 @@ also remain incomplete.
 
 ## Required physical-device coverage
 
-Before a stable release, verify on physical iOS and Android devices:
+Before a stable release, verify browser redirects, callbacks, popup navigation,
+renewal, and logout, plus these flows on physical iOS and Android devices:
 
 - system login and logout UI, provider-consent UI, cancellation, and callbacks;
 - Web Crypto availability in the packaged Capacitor WebView;