capacitor-oidc 0.0.6 → 0.1.1

package/docs/TROUBLESHOOTING.md

@@ -15,6 +15,12 @@ The authorization request's `redirect_uri` must exactly match a callback
 registered for the provider client. Check scheme, host, port, path, case, and
 trailing slashes. Wildcard callback hosts are commonly unsupported.
 
+## Web login returns without a user
+
+Make the configured web callback route call `signinCallback()`. A logout callback
+route must call `signoutCallback()` instead. Both routes must use exactly the URI
+registered with the provider.
+
 ## Android does not return to the app
 
 - Keep `MainActivity` in `singleTask` launch mode.
@@ -33,9 +39,10 @@ and that the callback scheme is registered in the target.
 
 ## Token, UserInfo, refresh, or revocation fails with a network error
 
-These requests use the WebView's normal `fetch`. Configure the provider endpoint
-to allow the app's Capacitor origin through CORS. Static discovery metadata does
-not remove CORS requirements from token, UserInfo, refresh, or revocation calls.
+These requests use the runtime's normal `fetch`. Configure the provider endpoint
+to allow both web application and Capacitor origins through CORS. Static discovery
+metadata does not remove CORS requirements from token, UserInfo, refresh, or
+revocation calls.
 
 ## No refresh token is available
 
@@ -43,22 +50,25 @@ not remove CORS requirements from token, UserInfo, refresh, or revocation calls.
 - Enable the refresh-token grant for the public client.
 - Check provider-specific consent and rotation settings.
 
-When the current user is expired and has no refresh token, `getValidUser()`
-removes the local user and returns `null`.
+On native platforms, an expired user without a refresh token is removed and
+`getValidUser()` returns `null`. Web behavior follows the configured upstream
+silent-renew settings and may use an iframe.
 
 ## Startup renewal fails
 
-`CapacitorUserManager.create()` restores secure local state but does not wait for
-token renewal. When `automaticSilentRenew` is enabled, a required startup renewal
-runs asynchronously and reports failures through `silentRenewError`. Temporary
-token-endpoint failures preserve the stored session; a terminal `invalid_grant`
-removes it.
+On native platforms, `CapacitorUserManager.create()` restores secure local state
+but does not wait for token renewal. When `automaticSilentRenew` is enabled, a
+required startup renewal runs asynchronously and reports failures through
+`silentRenewError`. Temporary token-endpoint failures preserve the stored
+session; a terminal `invalid_grant` removes it. Web automatic renewal follows
+`oidc-client-ts` behavior.
 
 ## Logout does not return to the app
 
-Register the post-logout URI at the provider and in the native application. Some
-providers use non-standard parameters. Amazon Cognito uses `logout_uri`; see
-[Provider configuration](PROVIDERS.md#amazon-cognito).
+Register the post-logout URI at the provider, add the browser callback route, and
+register native schemes in each native application. Some providers use
+non-standard parameters. Amazon Cognito uses `logout_uri`; see [Provider
+configuration](PROVIDERS.md#amazon-cognito).
 
 ## `USER_CANCELLED` appears but Android UI remains visible
 

package/docs/adr/0004-use-one-manager-across-platforms.md

@@ -0,0 +1,64 @@
+# ADR 0004: Use one manager across platforms
+
+## Status
+
+Accepted
+
+## Context
+
+The first package boundary was intentionally native-only. It kept the custom
+code small by adapting `oidc-client-ts` only where Capacitor needed native system
+authentication UI and secure storage. Browser methods were rejected, and the
+documentation told applications to instantiate `oidc-client-ts` directly for
+web.
+
+That boundary moved platform selection into every consuming application. A
+cross-platform app had to duplicate common settings, create two manager types,
+branch for sign-in, callbacks, refresh, and logout, and depend directly on the
+underlying library. The package abstracted native mechanics but did not provide
+the originally intended application-level abstraction.
+
+## Decision
+
+`CapacitorUserManager` is the public manager for web, iOS, and Android.
+Configuration is split into:
+
+- required `common` public-client settings;
+- optional `web` settings and redirect-or-popup interaction choices;
+- optional `native` settings and native options;
+- optional `ios` and `android` overrides of the native section.
+
+Resolution is shallow and happens once:
+
+```text
+web:     common -> web
+iOS:     common -> native -> ios
+Android: common -> native -> android
+```
+
+Web uses the upstream browser navigators and configured browser stores. Native
+uses `CapacitorNavigator`, secure stores, refresh-token-only renewal, and the app
+resume listener. `signin()` and `signout()` return `Promise<void>` on all
+platforms; applications read session state through events or user accessors.
+
+The public manager is a common base and factory backed by internal web and
+native implementations. Legacy native input is normalized before implementation
+selection, so both factory signatures use the same native behavior.
+
+All platforms remain public clients using code flow with PKCE. Web-only
+capabilities stay in the web settings. Native does not accept custom stores,
+DPoP, iframe callbacks, or browser session monitoring.
+
+## Consequences
+
+- Applications no longer branch between two manager implementations or import
+  `oidc-client-ts` directly for normal use.
+- Web callbacks remain explicit application routes through `signinCallback()`
+  and `signoutCallback()`.
+- Platform-specific provider values and interaction arguments can differ without
+  duplicating common configuration.
+- The pre-1.0 native factory signature is normalized into the new implementation
+  as a deprecated migration path. The `Promise<void>` sign-in contract remains a
+  return-type change for applications that previously used the returned user.
+- The package still owns no OIDC protocol implementation or provider-specific
+  behavior.

package/docs/adr/index.md

@@ -0,0 +1,6 @@
+# Architecture decisions
+
+- [Use `oidc-client-ts`](0001-use-oidc-client-ts.md)
+- [Keep the native boundary small](0002-keep-the-native-boundary-small.md)
+- [Share session storage with widgets](0003-share-session-storage-with-widgets.md)
+- [Use one manager across platforms](0004-use-one-manager-across-platforms.md)

package/docs/frameworks/ANGULAR.md

@@ -0,0 +1,129 @@
+# Angular integration
+
+The [Angular example](/examples/angular/) keeps one OIDC manager in a root
+service. The service completes browser callbacks, restores the current user,
+and exposes signals for templates.
+
+## Install
+
+```sh
+npm install capacitor-oidc @capacitor/app
+npx cap sync
+```
+
+## Configure the provider
+
+Keep deploy-specific values in an Angular environment file:
+
+```ts
+// src/environments/environment.ts
+export const environment = {
+  authority: 'https://identity.example.com',
+  clientId: 'public-app',
+};
+```
+
+## Create a root service
+
+`providedIn: 'root'` gives the application one manager, independent of route
+and component lifetimes:
+
+```ts
+@Injectable({ providedIn: 'root' })
+export class OidcService {
+  readonly user = signal<User | null>(null);
+
+  private readonly manager = CapacitorUserManager.create({
+    common: {
+      authority: environment.authority,
+      client_id: environment.clientId,
+      scope: 'openid profile offline_access',
+      automaticSilentRenew: false,
+    },
+    web: {
+      settings: {
+        redirect_uri: `${window.location.origin}/callback`,
+        post_logout_redirect_uri: `${window.location.origin}/logout-callback`,
+      },
+    },
+    native: {
+      settings: {
+        redirect_uri: 'capacitor-oidc-example:/callback',
+        post_logout_redirect_uri: 'capacitor-oidc-example:/logout-callback',
+      },
+      options: { storageNamespace: 'angular-example' },
+    },
+  });
+}
+```
+
+The runnable example keeps automatic renewal off so the bundled realm's
+30-second test tokens can be renewed with the example's button. For a normal
+provider, enable automatic renewal and keep its expiry-notification threshold
+below the provider's access-token lifetime.
+
+## Initialize from the root component
+
+The service handles browser callbacks before exposing the restored user:
+
+```ts
+async initialize() {
+  const auth = await this.manager;
+
+  auth.events.addUserLoaded((user) => this.user.set(user));
+  auth.events.addUserUnloaded(() => this.user.set(null));
+
+  if (window.location.pathname === '/callback') {
+    await auth.signinCallback();
+    window.history.replaceState({}, '', '/');
+  } else if (window.location.pathname === '/logout-callback') {
+    await auth.signoutCallback();
+    window.history.replaceState({}, '', '/');
+  }
+
+  this.user.set(await auth.getUser());
+}
+```
+
+Call it once from the root component:
+
+```ts
+export class AppComponent implements OnInit {
+  readonly oidc = inject(OidcService);
+
+  ngOnInit() {
+    void this.oidc.initialize();
+  }
+}
+```
+
+Native callbacks finish inside the plugin and do not need Angular Router
+routes.
+
+## Bind actions
+
+The root service can expose `signin()`, `getValidUser(60)`, and `signout()` as
+methods. Components read the current `user` signal and do not hold their own
+manager.
+
+Call `dispose()` only when the Angular application is shutting down.
+
+## Run the example
+
+```sh
+npm ci
+npm run build
+npm run e2e:keycloak:up
+npm --prefix examples/angular install
+npm --prefix examples/angular run dev
+```
+
+Sign in with the disposable `demo` / `demo` account. Stop the local realm with
+`npm run e2e:keycloak:down` when finished.
+
+This local realm workflow is for the browser example. Android resolves
+`localhost` inside the device or emulator, and native platforms should not use
+the example's cleartext HTTP authority. Before building for iOS or Android,
+replace `environment.authority` with an HTTPS authority reachable from that
+device and register the configured native callback scheme at the provider. See
+[iOS and Android setup](../PLATFORM_SETUP.md).

package/docs/frameworks/REACT.md

@@ -0,0 +1,134 @@
+# React integration
+
+The [React example](/examples/react/) creates its OIDC manager outside the
+component tree, restores the user when the application mounts, and keeps React
+state aligned with the manager's user events.
+
+## Install
+
+```sh
+npm install capacitor-oidc @capacitor/app
+npx cap sync
+```
+
+## Create the manager outside React
+
+A module-level promise prevents component renders from constructing multiple
+managers:
+
+```ts
+// src/auth.ts
+import { CapacitorUserManager } from 'capacitor-oidc';
+
+const manager = CapacitorUserManager.create({
+  common: {
+    authority: import.meta.env.VITE_OIDC_AUTHORITY,
+    client_id: import.meta.env.VITE_OIDC_CLIENT_ID,
+    scope: 'openid profile offline_access',
+    automaticSilentRenew: false,
+  },
+  web: {
+    settings: {
+      redirect_uri: `${window.location.origin}/callback`,
+      post_logout_redirect_uri: `${window.location.origin}/logout-callback`,
+    },
+  },
+  native: {
+    settings: {
+      redirect_uri: 'capacitor-oidc-example:/callback',
+      post_logout_redirect_uri: 'capacitor-oidc-example:/logout-callback',
+    },
+    options: { storageNamespace: 'react-example' },
+  },
+});
+
+export function getUserManager() {
+  return manager;
+}
+
+let callback: Promise<void> | undefined;
+
+export function completeWebCallback(auth: CapacitorUserManager) {
+  callback ??= (async () => {
+    if (window.location.pathname === '/callback') {
+      await auth.signinCallback();
+      window.history.replaceState({}, '', '/');
+    } else if (window.location.pathname === '/logout-callback') {
+      await auth.signoutCallback();
+      window.history.replaceState({}, '', '/');
+    }
+  })();
+
+  return callback;
+}
+```
+
+The runnable example supplies local Keycloak defaults and keeps automatic
+renewal off so its 30-second test tokens can be renewed with the example's
+button. For a normal provider, enable automatic renewal and keep its
+expiry-notification threshold below the provider's access-token lifetime. Set
+the two Vite environment variables for your provider.
+
+## Initialize from the application root
+
+Complete browser callbacks, subscribe to user events, and restore the stored
+user from the root component:
+
+```tsx
+useEffect(() => {
+  let active = true;
+  let auth: CapacitorUserManager | undefined;
+  const userLoaded = (user: User) => active && setUser(user);
+  const userUnloaded = () => active && setUser(null);
+
+  void getUserManager().then(async (manager) => {
+    if (!active) return;
+    auth = manager;
+    manager.events.addUserLoaded(userLoaded);
+    manager.events.addUserUnloaded(userUnloaded);
+    await completeWebCallback(manager);
+    const storedUser = await manager.getUser();
+    if (active) setUser(storedUser);
+  });
+
+  return () => {
+    active = false;
+    auth?.events.removeUserLoaded(userLoaded);
+    auth?.events.removeUserUnloaded(userUnloaded);
+  };
+}, []);
+```
+
+Native callbacks complete inside the plugin and do not require React Router
+routes.
+
+## Bind actions
+
+```ts
+await auth.signin();
+setUser(await auth.getValidUser(60));
+await auth.signout();
+```
+
+Retain the manager when React routes change. Call `dispose()` only when the
+whole application is shutting down.
+
+## Run the example
+
+```sh
+npm ci
+npm run build
+npm run e2e:keycloak:up
+npm --prefix examples/react install
+npm --prefix examples/react run dev
+```
+
+Sign in with the disposable `demo` / `demo` account. Stop the local realm with
+`npm run e2e:keycloak:down` when finished.
+
+This local realm workflow is for the browser example. Android resolves
+`localhost` inside the device or emulator, and native platforms should not use
+the example's cleartext HTTP authority. Before building for iOS or Android, set
+`VITE_OIDC_AUTHORITY` to an HTTPS authority reachable from that device and
+register the configured native callback scheme at the provider. See
+[iOS and Android setup](../PLATFORM_SETUP.md).

package/docs/frameworks/VUE.md

@@ -0,0 +1,118 @@
+# Vue integration
+
+The [Vue example](/examples/vue/) is a small Capacitor application with one
+OIDC manager for the application lifetime. It restores the stored user when
+Vue mounts, completes browser callbacks, and exposes sign-in, renewal, and
+sign-out actions.
+
+## Install
+
+```sh
+npm install capacitor-oidc @capacitor/app
+npx cap sync
+```
+
+## Create the manager once
+
+Keep manager creation outside Vue components so route changes cannot create a
+second manager:
+
+```ts
+// src/auth.ts
+import { CapacitorUserManager } from 'capacitor-oidc';
+
+const manager = CapacitorUserManager.create({
+  common: {
+    authority: import.meta.env.VITE_OIDC_AUTHORITY,
+    client_id: import.meta.env.VITE_OIDC_CLIENT_ID,
+    scope: 'openid profile offline_access',
+    automaticSilentRenew: false,
+  },
+  web: {
+    settings: {
+      redirect_uri: `${window.location.origin}/callback`,
+      post_logout_redirect_uri: `${window.location.origin}/logout-callback`,
+    },
+  },
+  native: {
+    settings: {
+      redirect_uri: 'capacitor-oidc-example:/callback',
+      post_logout_redirect_uri: 'capacitor-oidc-example:/logout-callback',
+    },
+    options: { storageNamespace: 'vue-example' },
+  },
+});
+
+export function getUserManager() {
+  return manager;
+}
+```
+
+The runnable example supplies local Keycloak defaults as a convenience and
+keeps automatic renewal off so its 30-second test tokens can be renewed with
+the example's button. For a normal provider, enable automatic renewal and keep
+its expiry-notification threshold below the provider's access-token lifetime.
+Use environment variables for your provider in an application.
+
+## Restore state and handle callbacks
+
+Initialize authentication from the root component. Browser callback routes
+must be handled before rendering the restored user:
+
+```ts
+const auth = await getUserManager();
+
+if (window.location.pathname === '/callback') {
+  await auth.signinCallback();
+  window.history.replaceState({}, '', '/');
+} else if (window.location.pathname === '/logout-callback') {
+  await auth.signoutCallback();
+  window.history.replaceState({}, '', '/');
+}
+
+user.value = await auth.getUser();
+
+auth.events.addUserLoaded((loadedUser) => {
+  user.value = loadedUser;
+});
+
+auth.events.addUserUnloaded(() => {
+  user.value = null;
+});
+```
+
+Native callbacks are completed by the plugin and do not need Vue Router
+routes.
+
+## Bind actions
+
+```ts
+await auth.signin();
+user.value = await auth.getValidUser(60);
+await auth.signout();
+```
+
+Call `dispose()` only when the application is shutting down, not whenever a
+route component unmounts.
+
+## Run the example
+
+Start the repository's local Keycloak realm, then start the Vue app:
+
+```sh
+npm ci
+npm run build
+npm run e2e:keycloak:up
+npm --prefix examples/vue install
+npm --prefix examples/vue run dev
+```
+
+Sign in with the disposable `demo` / `demo` account. Stop the local realm with
+`npm run e2e:keycloak:down` when finished.
+
+This local realm workflow is for the browser example. Android resolves
+`localhost` inside the device or emulator, and native platforms should not use
+the example's cleartext HTTP authority. Before building for iOS or Android, set
+`VITE_OIDC_AUTHORITY` to an HTTPS authority reachable from that device and
+register the configured native callback scheme at the provider. See
+[iOS and Android setup](../PLATFORM_SETUP.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capacitor-oidc",
-  "version": "0.0.6",
-  "description": "Capacitor plugin for native OAuth 2.0 and OpenID Connect authentication on iOS and Android, powered by oidc-client-ts.",
+  "version": "0.1.1",
+  "description": "OAuth 2.0 and OpenID Connect authentication for Capacitor web, iOS, and Android, powered by oidc-client-ts.",
   "keywords": [
     "capacitor",
     "capacitor-plugin",
@@ -11,6 +11,7 @@
     "openid-connect",
     "oidc",
     "pkce",
+    "web",
     "ios",
     "android",
     "oidc-client-ts"
@@ -48,6 +49,9 @@
     "build": "npm run clean && tsc && rollup -c rollup.config.mjs",
     "check:package": "node -e \"import('./dist/esm/index.js')\"",
     "clean": "rimraf dist",
+    "docs:build": "vitepress build . && cp LICENSE .vitepress/dist/LICENSE",
+    "docs:dev": "vitepress dev .",
+    "docs:preview": "vitepress preview .",
     "e2e:keycloak:down": "docker compose -f test/e2e/keycloak/compose.yml down",
     "e2e:keycloak:up": "test/e2e/keycloak/create-certificate.sh test/e2e/keycloak/.certificates && docker compose -f test/e2e/keycloak/compose.yml up -d",
     "example:build": "npm --prefix example run build",
@@ -78,6 +82,8 @@
     "rimraf": "6.1.0",
     "rollup": "4.62.5",
     "typescript": "5.9.3",
+    "vite": "7.3.6",
+    "vitepress": "2.0.0-alpha.19",
     "vitest": "3.2.7"
   },
   "prettier": "@ionic/prettier-config",