capacitor-oidc 0.1.0 → 0.1.1

package/README.md

@@ -104,7 +104,7 @@ callback route, call `signinCallback()`; on the web logout callback route, call
 `web` or `native`, then the matching `ios` or `android` override.
 
 A runnable Keycloak-backed iOS application and its UI test live in
-[`example`](example).
+[`example`](example/).
 
 ## Documentation
 
@@ -127,7 +127,7 @@ npm run verify:android
 
 Architecture decisions and contributor constraints are documented in
 [ARCHITECTURE.md](ARCHITECTURE.md), [REQUIREMENTS.md](REQUIREMENTS.md), and
-[docs/adr](docs/adr).
+[docs/adr](docs/adr/).
 
 ## License
 

package/SECURITY.md

@@ -12,33 +12,6 @@ with PKCE and cannot contain a client secret. Native authorization and provider
 logout run in system authentication UI, never an embedded WebView; web uses
 normal browser redirect or popup navigation.
 
-## ID-token validation in `oidc-client-ts` 3.5.0
-
-The pinned `oidc-client-ts` 3.5.0 decodes ID-token claims and validates `sub`,
-`nonce`, and selected refresh-token continuity claims. It does not independently
-compare the decoded `iss`, `aud`, and `exp` claims with the configured client and
-current time. This behavior is visible in the
-[v3.5.0 ResponseValidator](https://github.com/authts/oidc-client-ts/blob/v3.5.0/src/ResponseValidator.ts)
-and is the subject of the open upstream report
-[authts/oidc-client-ts#2475](https://github.com/authts/oidc-client-ts/issues/2475).
-
-The practical exposure is narrower than an implicit-flow token parser: this
-package uses Authorization Code Flow only, and the token response comes from the
-configured token endpoint over TLS after state, nonce, and PKCE processing. The
-upstream project has not yet classified or resolved the report.
-
-This is a standards-conformance and threat-model consideration, not a categorical
-claim that every application using `oidc-client-ts` is unsafe. Consumers should
-evaluate it against their provider, reliance on ID-token claims, and assurance
-requirements. Resource servers must always validate access tokens independently;
-an application must not use unverified client-side profile claims as its API
-authorization boundary.
-
-The package will follow the upstream resolution and cover the expected behavior
-in provider integration tests before a stable v1 decision. It will not add a
-package-local JWT or cryptographic-validation layer, because duplicating protocol
-security code would expand the attack surface and create a second OIDC engine.
-
 ## Secure-storage boundary
 
 OIDC transactions and sessions are stored through iOS Keychain or an Android
@@ -59,3 +32,26 @@ absent. Their behavior must be verified in packaged applications on supported
 physical devices.
 
 See [Testing](docs/TESTING.md) for current platform and provider coverage.
+
+## Known issues
+
+### ID-token claim validation in `oidc-client-ts` 3.5.0
+
+The pinned `oidc-client-ts` 3.5.0 decodes ID-token claims and validates `sub`,
+`nonce`, and selected refresh-token continuity claims. It does not independently
+compare the decoded `iss`, `aud`, and `exp` claims with the configured client and
+current time. This behavior is visible in the
+[v3.5.0 ResponseValidator](https://github.com/authts/oidc-client-ts/blob/v3.5.0/src/ResponseValidator.ts)
+and is the subject of the unresolved upstream report
+[authts/oidc-client-ts#2475](https://github.com/authts/oidc-client-ts/issues/2475).
+
+This package uses Authorization Code Flow, so the token response comes from the
+configured token endpoint over TLS after state, nonce, and PKCE processing.
+Applications that rely on `iss`, `aud`, or `exp` claims should still evaluate
+the upstream gap against their assurance requirements. Resource servers must
+validate access tokens independently, and client-side ID-token claims must not
+be an API authorization boundary.
+
+The package will follow the upstream resolution and cover the expected behavior
+in provider integration tests before a stable v1 decision. It will not add a
+package-local JWT validation layer that would duplicate protocol security code.

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 every web and native redirect and post-logout redirect URI 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
 
@@ -188,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

@@ -20,4 +20,4 @@ setup for each native platform and your identity provider.
 - [Requirements and acceptance criteria](../REQUIREMENTS.md)
 - [Testing](TESTING.md)
 - [Publishing](PUBLISHING.md)
-- [Architecture decisions](adr)
+- [Architecture decisions](adr/)

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,6 +1,6 @@
 {
   "name": "capacitor-oidc",
-  "version": "0.1.0",
+  "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",
@@ -49,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",
@@ -79,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",