capacitor-oidc 0.0.1-alpha.2 → 0.0.2

package/CapacitorOidc.podspec

@@ -10,7 +10,7 @@ Pod::Spec.new do |spec|
   spec.license = package['license']
   spec.homepage = package['homepage']
   spec.author = package['author']
-  spec.source = { git: repository_url, tag: spec.version.to_s }
+  spec.source = { git: repository_url, tag: "v#{spec.version}" }
   spec.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
   spec.ios.deployment_target = '15.0'
   spec.dependency 'Capacitor', '>= 7.0'

package/README.md

@@ -1,32 +1,44 @@
 # capacitor-oidc
 
-A small native Capacitor adapter for [`oidc-client-ts`](https://github.com/authts/oidc-client-ts).
+[![npm](https://img.shields.io/npm/v/capacitor-oidc)](https://www.npmjs.com/package/capacitor-oidc)
+[![CI](https://github.com/jojopirker/capacitor-oidc/actions/workflows/ci.yml/badge.svg)](https://github.com/jojopirker/capacitor-oidc/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/capacitor-oidc)](LICENSE)
 
-> [!WARNING]
-> This package is not ready for production use. `oidc-client-ts` 3.5.0 does not validate the required ID-token `iss`, `aud`, and `exp` claims. See [Security](SECURITY.md).
+Native OAuth 2.0 and OpenID Connect for Capacitor, powered by
+[`oidc-client-ts`](https://github.com/authts/oidc-client-ts).
 
-The package keeps OAuth and OpenID Connect in `oidc-client-ts`. Its native code only presents system authentication UI and stores state securely:
+`capacitor-oidc` adapts the familiar `UserManager` API to native iOS and Android
+applications. It keeps protocol behavior in `oidc-client-ts` and adds only the
+Capacitor-specific pieces:
 
-- iOS: `ASWebAuthenticationSession` and Keychain.
-- Android: Auth Tab with its Custom Tab fallback, plus AES-GCM protected storage with a key held by Android Keystore.
-- TypeScript: a native `INavigator`, secure `StateStore`, foreground refresh serialization, and a resume check.
+- system authentication UI instead of an embedded WebView;
+- secure native storage for OIDC transactions and sessions;
+- refresh-token renewal when the app is active or resumes;
+- a native-readable session snapshot for app widgets.
 
-It does not patch `fetch`, add native OIDC networking, accept client secrets, render authentication in a WebView, or implement iframe renewal.
+On iOS, authentication uses `ASWebAuthenticationSession`. On Android, it uses
+AndroidX Auth Tab with its Custom Tab fallback.
+
+## Requirements
+
+- Capacitor 7 or 8
+- iOS 15 or newer
+- Android API 24 or newer
+- Android compile SDK 36, Java 21, and a compatible Android Gradle Plugin
+- an OAuth public client using Authorization Code Flow with PKCE
+- Web Crypto in the packaged Capacitor WebView
+- CORS support for the app's Capacitor origin on OIDC HTTP endpoints
+
+Never ship a client secret in a Capacitor application.
 
 ## Install
 
 ```sh
-npm install capacitor-oidc oidc-client-ts @capacitor/app
+npm install capacitor-oidc @capacitor/app
 npx cap sync
 ```
 
-The package supports Capacitor 7 and newer.
-
-All discovery, token, refresh, UserInfo, and revocation requests use normal WebView `fetch`. The provider must allow the app's configured Capacitor origin through CORS.
-
-Authorization and logout endpoints must use HTTPS. Plain HTTP is accepted only for loopback local development.
-
-## Usage
+## Quick start
 
 ```ts
 import { CapacitorUserManager } from 'capacitor-oidc';
@@ -42,96 +54,35 @@ const manager = await CapacitorUserManager.create(
     revokeTokensOnSignout: true,
   },
   {
-    prefersEphemeralWebBrowserSession: false,
     storageNamespace: 'primary',
-    ios: {
-      keychainAccessGroup: 'TEAMID.group.com.example.app',
-      keychainAccessibility: 'afterFirstUnlockThisDeviceOnly',
-    },
   },
 );
 
 const user = await manager.signin();
 const validUser = await manager.getValidUser(30);
+
 await manager.signout();
 await manager.dispose();
 ```
 
-`automaticSilentRenew` uses `oidc-client-ts`'s foreground expiry timer. Native silent renewal uses a refresh token only and never falls back to an iframe. Concurrent renewal triggers share one request. Returning to the foreground calls `getValidUser()` so a token that expired while the app was suspended is refreshed.
-
-The operating system can suspend or terminate the app, so exact background refresh timing is not promised.
-
-## Redirect setup
+Register the redirect and post-logout redirect URIs exactly at your provider and
+in the native application. The provider client must be public and must allow
+Authorization Code Flow with PKCE.
 
-Register the redirect URI as a native public-client redirect at the provider. Never put a client secret in the app.
+`CapacitorUserManager` is for native Capacitor runtimes. For a browser build, use
+the normal `UserManager` from `oidc-client-ts` and select the implementation with
+`Capacitor.isNativePlatform()` in the application.
 
-For an iOS custom scheme, add it to the application target's `CFBundleURLTypes`. HTTPS callbacks through `ASWebAuthenticationSession` require iOS 17.4 or newer and the appropriate Associated Domains configuration.
+## Documentation
 
-For an Android custom-scheme redirect, keep the host app's `MainActivity` in Capacitor's default `singleTask` launch mode and add this intent filter inside that existing activity declaration. This ensures callbacks from Auth Tab's Custom Tab fallback reach the plugin instance that opened the session. Replace the scheme with the one used by your redirect URI:
-
-```xml
-<activity
-  android:name=".MainActivity"
-  android:launchMode="singleTask">
-  <intent-filter>
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data android:scheme="com.example.app" />
-  </intent-filter>
-</activity>
-```
-
-HTTPS callbacks require a verified App Link and Digital Asset Links. Auth Tab handles the result directly when the installed browser supports it and falls back to a Custom Tab on older browsers.
-
-Calling `cancel()` on Android rejects the pending JavaScript promise, but Android does not provide an API to forcibly close an already-open system Auth Tab or Custom Tab. Ephemeral browsing is requested on both platforms and may be ignored by an Android fallback browser.
-
-Provider-specific logout parameters remain available through `oidc-client-ts`. For Amazon Cognito, leave `post_logout_redirect_uri` unset in the manager settings and pass its `client_id` and `logout_uri` parameters when signing out:
-
-```ts
-await manager.signout({
-  extraQueryParams: {
-    client_id: 'mobile-app',
-    logout_uri: 'com.example.app:/logout-callback',
-  },
-});
-```
-
-## Secure storage and widgets
-
-`userStore` and transaction `stateStore` are separate secure namespaces. Each successful user write also updates a versioned native `StoredSessionV1` snapshot. The snapshot is an eventually consistent widget cache, not the canonical OIDC session.
-
-An iOS app and WidgetKit extension can construct the public `TokenVault` with the same Keychain access group:
-
-```swift
-let vault = TokenVault(accessGroup: "TEAMID.group.com.example.app")
-let session = try vault.loadSession(namespace: "primary")
-```
-
-Replace `TEAMID` with the Apple Developer Team ID. Both targets must carry the same
-Keychain Sharing entitlement, normally declared as
-`$(AppIdentifierPrefix)group.com.example.app`; the runtime option uses its expanded
-`TEAMID.group.com.example.app` value. The default accessibility is
-`AfterFirstUnlockThisDeviceOnly`; Keychain synchronization and biometric gating are disabled.
-
-An Android app widget in the same package can use the public native vault:
-
-```java
-TokenVault vault = new TokenVault(context);
-StoredSessionV1 session = vault.loadSession("primary");
-```
-
-Widgets may read the current session. Autonomous native refresh is deliberately not implemented.
-
-## Logout behavior
-
-`signout()` uses the provider's end-session endpoint in the same native authentication UI. If `revokeTokensOnSignout` is enabled, upstream revocation runs before local state is cleared. A revocation failure therefore preserves the local session and its renewal timer; after revocation succeeds, a later browser or callback failure leaves the app locally signed out. Removing the user cancels its expiry timer without disabling renewal for a later sign-in with the same manager.
-
-## Unsupported APIs
-
-Use `signin()` and `signout()` for interactive flows. Redirect navigation, iframe logout, and browser session monitoring reject with `UNSUPPORTED_RUNTIME`. Resource Owner Password Credentials, DPoP, client secrets, exact background scheduling, and autonomous widget refresh are outside v1.
-
-Only one interactive native authentication session and one configured manager are supported at a time.
+- [Getting started](docs/GETTING_STARTED.md)
+- [iOS and Android setup](docs/PLATFORM_SETUP.md)
+- [Provider configuration](docs/PROVIDERS.md)
+- [API and `oidc-client-ts` compatibility](docs/API.md)
+- [Sessions, secure storage, and widgets](docs/SESSIONS_AND_WIDGETS.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Testing status](docs/TESTING.md)
+- [Security](SECURITY.md)
 
 ## Development
 
@@ -141,9 +92,9 @@ npm run verify:ios
 npm run verify:android
 ```
 
-Physical-device verification remains required for Web Crypto, system consent UI, redirects, and shared widget access before a production release. See [Testing](docs/TESTING.md) for the full matrix.
-
-See [Publishing](docs/PUBLISHING.md) for the guarded npm trusted-publishing setup and release process.
+Architecture decisions and contributor constraints are documented in
+[ARCHITECTURE.md](ARCHITECTURE.md), [REQUIREMENTS.md](REQUIREMENTS.md), and
+[docs/adr](docs/adr).
 
 ## License
 

package/SECURITY.md

@@ -7,25 +7,54 @@
 and storing state securely. The package does not patch `fetch`, process JWTs, or
 implement OAuth endpoints in Swift or Java.
 
-## Known limitation in the pinned OIDC engine
+Installed applications are public clients. They must use Authorization Code Flow
+with PKCE and must not contain a client secret. Authorization and provider logout
+run in system authentication UI, never an embedded WebView.
 
-This prerelease pins `oidc-client-ts` 3.5.0. Its ID-token response validation
-checks `sub`, `nonce`, and selected refresh-token continuity claims, but does not
-check the required `iss`, `aud`, and `exp` claims. The 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 tracked in [authts/oidc-client-ts#2475](https://github.com/authts/oidc-client-ts/issues/2475).
+## ID-token validation in `oidc-client-ts` 3.5.0
 
-The current alpha must not be treated as production-ready. Before a stable
-release, use an upstream version that performs the required validation and cover
-it with provider integration tests, or replace ADR 0001 with a different protocol
-engine decision. Do not add package-local JWT or cryptographic validation as a
-workaround.
+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
+Keystore-backed vault. Configuring an iOS Keychain access group gives every
+entitled target access to the plugin's canonical session, transaction data, and
+widget snapshot. Treat those extensions as part of the application's credential
+trust boundary.
+
+The widget snapshot can contain access, refresh, and ID tokens. Autonomous widget
+refresh is not currently implemented; see
+[Sessions, secure storage, and widgets](docs/SESSIONS_AND_WIDGETS.md).
 
 ## Runtime assumptions
 
 `oidc-client-ts` requires `crypto.subtle` and `crypto.getRandomValues`.
 `CapacitorUserManager.create()` rejects with `UNSUPPORTED_RUNTIME` when they are
-absent. Their presence and behavior must also be verified in packaged applications
-on physical iOS and Android devices.
+absent. Their behavior must be verified in packaged applications on supported
+physical devices.
 
-See [Testing](docs/TESTING.md) for the remaining device and provider coverage.
+See [Testing](docs/TESTING.md) for current platform and provider coverage.

package/docs/API.md

@@ -0,0 +1,91 @@
+# 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.
+
+## Added 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. |
+
+Only one configured manager and one interactive native authentication session are
+supported at a time.
+
+## Relevant inherited API
+
+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`:
+
+- `signinRedirect()`, `signinRedirectCallback()`, and `signinCallback()`;
+- `signinSilentCallback()` and iframe-based silent authentication;
+- `signoutRedirect()`, `signoutRedirectCallback()`, and `signoutCallback()`;
+- `signoutSilent()` and `signoutSilentCallback()`;
+- `querySessionStatus()`;
+- Resource Owner Password Credentials.
+
+The native settings type excludes:
+
+- `client_secret` and `client_authentication`;
+- `disablePKCE` and `response_type`;
+- `dpop`;
+- `monitorSession` and `silent_redirect_uri`;
+- custom `stateStore` and `userStore`.
+
+The adapter forces Authorization Code Flow with PKCE, secure native stores, and
+no iframe session monitoring.
+
+## Native options
+
+```ts
+interface CapacitorOidcNativeOptions {
+  prefersEphemeralWebBrowserSession?: boolean;
+  storageNamespace?: string;
+  ios?: {
+    keychainAccessGroup?: string;
+    keychainAccessibility?: 'afterFirstUnlockThisDeviceOnly' | 'whenUnlockedThisDeviceOnly';
+  };
+}
+```
+
+`storageNamespace` defaults to `default`. Use a stable, application-specific
+value and do not change it between releases unless intentionally starting a new
+session store.
+
+## 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.              |
+
+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

@@ -0,0 +1,132 @@
+# Getting started
+
+## 1. Configure a public client
+
+Create a native or 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;
+- the `openid` scope and any application scopes you need;
+- a refresh-token or offline-access grant if 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.
+
+## 2. Install the package
+
+```sh
+npm install capacitor-oidc @capacitor/app
+npx cap sync
+```
+
+Complete the [iOS or Android setup](PLATFORM_SETUP.md) before running the app.
+
+## 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.
+
+```ts
+import { CapacitorUserManager } from 'capacitor-oidc';
+
+export const auth = await CapacitorUserManager.create(
+  {
+    authority: 'https://identity.example.com',
+    client_id: 'mobile-app',
+    redirect_uri: 'com.example.app:/callback',
+    post_logout_redirect_uri: 'com.example.app:/logout-callback',
+    scope: 'openid profile offline_access',
+    automaticSilentRenew: true,
+    loadUserInfo: true,
+    revokeTokensOnSignout: true,
+  },
+  {
+    prefersEphemeralWebBrowserSession: false,
+    storageNamespace: 'primary',
+  },
+);
+```
+
+`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 current alpha restores the stored user during `create()`. If that user needs
+immediate renewal and the device is offline, manager creation can reject. This
+behavior is tracked for improvement; applications should currently initialize
+the manager where they can present an authentication or connectivity error.
+
+## 4. Sign in
+
+```ts
+const user = await auth.signin();
+
+console.log(user.profile.sub);
+```
+
+The promise resolves after the system authentication session returns to the app,
+the authorization response is validated, and the code is exchanged.
+
+Listen for session changes through the normal `oidc-client-ts` events:
+
+```ts
+auth.events.addUserLoaded((user) => {
+  console.log('Signed in as', user.profile.sub);
+});
+
+auth.events.addSilentRenewError((error) => {
+  console.error('Token renewal failed', error);
+});
+```
+
+## 5. Get a usable access token
+
+```ts
+const user = await auth.getValidUser(30);
+
+if (!user) {
+  // No signed-in session is available.
+} else {
+  await fetch('https://api.example.com/profile', {
+    headers: { Authorization: `Bearer ${user.access_token}` },
+  });
+}
+```
+
+`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.
+
+## 6. Sign out
+
+```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
+
+`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.

package/docs/PLATFORM_SETUP.md

@@ -0,0 +1,98 @@
+# iOS and Android setup
+
+## iOS
+
+The package supports iOS 15 and newer. Interactive login and logout use
+`ASWebAuthenticationSession`, including the operating system's provider-consent
+dialog and sheet presentation.
+
+### Custom-scheme callback
+
+For `com.example.app:/callback`, register `com.example.app` in the application
+target's `Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>com.example.app</string>
+    </array>
+  </dict>
+</array>
+```
+
+Use an application-specific scheme that your organization controls. Register the
+complete URI at the provider.
+
+### HTTPS callback
+
+HTTPS callbacks through `ASWebAuthenticationSession` require iOS 17.4 or newer.
+Configure the appropriate Associated Domains entitlement and association file,
+then register the exact HTTPS callback at the provider.
+
+### Shared Keychain access
+
+To let an iOS widget read the stored session, add the same Keychain Sharing
+entitlement to the application and extension, then configure the expanded access
+group:
+
+```ts
+const manager = await CapacitorUserManager.create(settings, {
+  ios: {
+    keychainAccessGroup: 'TEAMID.group.com.example.app',
+    keychainAccessibility: 'afterFirstUnlockThisDeviceOnly',
+  },
+  storageNamespace: 'primary',
+});
+```
+
+See [Sessions, secure storage, and widgets](SESSIONS_AND_WIDGETS.md) before
+enabling shared access.
+
+## Android
+
+The Android adapter supports API 24 and newer. It is currently built and tested
+with compile SDK 36, Android Gradle Plugin 8.9.1, Java 21, AndroidX Activity
+1.11.0, and AndroidX Browser 1.10.0. Capacitor 7 applications may therefore need
+their Android toolchain upgraded even though the JavaScript peer dependency
+allows Capacitor 7.
+
+### Custom-scheme callback
+
+Keep the host application's existing `MainActivity` in Capacitor's default
+`singleTask` launch mode. Add the callback intent filter inside that same activity
+declaration:
+
+```xml
+<activity
+  android:name=".MainActivity"
+  android:launchMode="singleTask">
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="com.example.app" />
+  </intent-filter>
+</activity>
+```
+
+The `singleTask` activity receives callbacks from Auth Tab's Custom Tab fallback
+through `onNewIntent`, allowing Capacitor to route the URL to the plugin instance
+that opened the session.
+
+### HTTPS callback
+
+Configure a verified Android App Link and publish a matching Digital Asset Links
+file. Register the exact HTTPS URI at the identity provider.
+
+### Auth Tab behavior
+
+AndroidX Auth Tab handles the result directly when the installed browser supports
+it and falls back to a Custom Tab on older browsers. Calling `cancel()` rejects
+the pending JavaScript promise, but Android does not expose an API that forcibly
+closes an already-visible system Auth Tab or Custom Tab.
+
+Ephemeral browsing is requested when configured and may be ignored by a fallback
+browser.

package/docs/PROVIDERS.md

@@ -0,0 +1,184 @@
+# 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.                                    |
+
+## Amazon Cognito
+
+Cognito separates the OIDC issuer from the managed-login domain. Use the user
+pool issuer as `authority` and provide explicit metadata pointing browser-facing
+endpoints at the managed-login domain:
+
+```ts
+const region = 'eu-central-1';
+const userPoolId = 'eu-central-1_example';
+const clientId = 'public-client-id';
+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`,
+  },
+});
+```
+
+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:
+
+```ts
+await manager.signout({
+  extraQueryParams: {
+    client_id: clientId,
+    logout_uri: 'com.example.app://oauth',
+  },
+});
+```
+
+See the AWS documentation for the
+[authorization endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html),
+[token endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html),
+and [logout endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/logout-endpoint.html).
+
+## Auth0
+
+Use the tenant or custom domain as the authority:
+
+```ts
+const settings = {
+  authority: 'https://example.eu.auth0.com',
+  client_id: 'native-application-client-id',
+  redirect_uri: 'com.example.app:/callback',
+  post_logout_redirect_uri: 'com.example.app:/logout-callback',
+  scope: 'openid profile email offline_access',
+  automaticSilentRenew: true,
+};
+```
+
+Create a Native application, register both callback URLs, enable refresh-token
+rotation as appropriate, and add the Capacitor origin to the allowed web origins
+used for CORS.
+
+See Auth0's [Capacitor quickstart](https://auth0.com/docs/quickstart/native/ionic-react)
+and [refresh-token rotation guidance](https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-rotation).
+
+## Keycloak
+
+Use the realm URL as the authority:
+
+```ts
+const settings = {
+  authority: 'https://identity.example.com/realms/example',
+  client_id: 'mobile-app',
+  redirect_uri: 'com.example.app:/callback',
+  post_logout_redirect_uri: 'com.example.app:/logout-callback',
+  scope: 'openid profile offline_access',
+  automaticSilentRenew: true,
+};
+```
+
+Create an OpenID Connect client with client authentication disabled, Standard
+Flow enabled, an exact valid redirect URI, and the Capacitor origin in Web
+Origins. Configure valid post-logout redirect URIs when using provider logout.
+
+See the Keycloak documentation for
+[managing OIDC clients](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients).
+
+## Okta
+
+Use the authorization-server issuer as the authority. For the default custom
+authorization server this commonly has the following form:
+
+```ts
+const settings = {
+  authority: 'https://example.okta.com/oauth2/default',
+  client_id: 'native-application-client-id',
+  redirect_uri: 'com.example.app:/callback',
+  post_logout_redirect_uri: 'com.example.app:/logout-callback',
+  scope: 'openid profile offline_access',
+  automaticSilentRenew: true,
+};
+```
+
+Create a Native Application integration, require PKCE, and register exact sign-in
+and sign-out redirect URIs.
+
+See Okta's guide to
+[signing users into a mobile app with redirect](https://developer.okta.com/docs/guides/sign-into-mobile-app-redirect/).
+
+## Microsoft Entra ID
+
+Use a tenant-specific v2 issuer when the application belongs to one tenant:
+
+```ts
+const settings = {
+  authority: 'https://login.microsoftonline.com/TENANT_ID/v2.0',
+  client_id: 'application-client-id',
+  redirect_uri: 'com.example.app:/callback',
+  post_logout_redirect_uri: 'com.example.app:/logout-callback',
+  scope: 'openid profile offline_access',
+  automaticSilentRenew: true,
+};
+```
+
+Configure a mobile and desktop application platform, register the native redirect
+URI accepted by the app registration, and enable public-client flows required by
+your tenant policy. Multi-tenant authorities and account selection require an
+application-specific design rather than simply replacing `TENANT_ID` with a
+shared authority.
+
+See Microsoft Learn for
+[mobile and desktop authentication flows](https://learn.microsoft.com/en-us/entra/identity-platform/scenario-desktop-overview)
+and [redirect URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/reply-url).
+
+## Other providers
+
+Start with the generic checklist 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.
+
+Provider-specific compatibility reports and tested configuration examples are
+welcome as focused contributions.

package/docs/PUBLISHING.md

@@ -71,11 +71,15 @@ Stable production releases additionally require the checks in
 3. Publish a GitHub release whose tag is exactly `vX.Y.Z` or `vX.Y.Z-prerelease`. Mark a prerelease version as a GitHub prerelease.
 4. Approve the `npm-production` deployment after its checks are visible.
 
-The workflow installs from the lockfile without a package-manager cache, verifies
-the package, inspects the tarball, and publishes it publicly under `latest` for a
-stable release or `next` for a prerelease. The job is skipped unless
-`NPM_PUBLISH_ENABLED` is exactly `true`. npm automatically generates provenance for
-a public package published from this public repository through a trusted publisher.
+The workflow first installs from the lockfile without a package-manager cache,
+verifies the package, and creates the release tarball in a job without OIDC
+permissions. After that succeeds, the `npm-production` environment gates a separate
+job that downloads and publishes only that tarball, with package scripts disabled.
+The privileged job does not check out source, install dependencies, or run repository
+build scripts. Stable releases use `latest`; prereleases use `next`. The workflow is
+skipped unless `NPM_PUBLISH_ENABLED` is exactly `true`. npm automatically generates
+provenance for a public package published from this public repository through a
+trusted publisher.
 
 After the first trusted publication succeeds, configure npm to disallow traditional
 token publishing and revoke unused automation tokens. Trusted publishing continues

package/docs/README.md

@@ -0,0 +1,23 @@
+# 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.
+
+## Use the package
+
+- [Getting started](GETTING_STARTED.md)
+- [iOS and Android setup](PLATFORM_SETUP.md)
+- [Provider configuration](PROVIDERS.md)
+- [API and `oidc-client-ts` compatibility](API.md)
+- [Sessions, secure storage, and widgets](SESSIONS_AND_WIDGETS.md)
+- [Troubleshooting](TROUBLESHOOTING.md)
+- [Security](../SECURITY.md)
+
+## Contribute and release
+
+- [Architecture](../ARCHITECTURE.md)
+- [Requirements and acceptance criteria](../REQUIREMENTS.md)
+- [Testing](TESTING.md)
+- [Publishing](PUBLISHING.md)
+- [Architecture decisions](adr)

package/docs/SESSIONS_AND_WIDGETS.md

@@ -0,0 +1,82 @@
+# Sessions, secure storage, and widgets
+
+## Canonical session storage
+
+The canonical `oidc-client-ts` user and authorization transaction state are
+stored in separate native-secure namespaces. Values are never written to
+`localStorage`.
+
+- iOS stores generic-password items in Keychain with synchronization disabled.
+- Android encrypts values with AES-GCM using a non-exportable Android Keystore
+  key and writes ciphertext to app-private no-backup storage.
+
+The default iOS accessibility is `AfterFirstUnlockThisDeviceOnly`. Biometric
+gating is not enabled because unattended foreground renewal must remain possible.
+
+## Renewal lifecycle
+
+When `automaticSilentRenew` is enabled, `oidc-client-ts` schedules renewal while
+the JavaScript runtime is active. The adapter also checks the current user when
+the application resumes.
+
+Native silent renewal requires a refresh token and never falls back to an iframe.
+Concurrent renewal requests share one operation so a rotating refresh token is
+not used twice. A terminal `invalid_grant` removes the local user; a temporary
+network failure preserves it.
+
+The operating system can suspend or terminate the process. The package therefore
+does not guarantee exact background refresh timing.
+
+## Widget snapshot
+
+Each successful canonical user write also updates a versioned `StoredSessionV1`
+snapshot containing:
+
+- issuer and client ID;
+- access token and expiration;
+- refresh token when issued;
+- ID token when issued;
+- token type and scope.
+
+The refresh and ID tokens are intentionally retained so a future coordinated
+native widget-refresh implementation does not require a storage-format migration.
+This makes the widget extension part of the same credential trust boundary as
+the host application.
+
+The current plugin does **not** perform autonomous widget refresh. Widgets can use
+a valid access token from the snapshot, but they must tolerate an expired, absent,
+or temporarily stale snapshot. Independently rotating a refresh token in widget
+code can invalidate the canonical application session and is not currently a
+supported workflow.
+
+The snapshot is an eventually consistent cache: the canonical OIDC user and the
+snapshot are separate writes.
+
+## iOS widget access
+
+Configure the same Keychain Sharing entitlement on the application and WidgetKit
+extension. Both targets normally declare
+`$(AppIdentifierPrefix)group.com.example.app`; the JavaScript option uses the
+expanded `TEAMID.group.com.example.app` value.
+
+```swift
+let vault = TokenVault(accessGroup: "TEAMID.group.com.example.app")
+let session = try vault.loadSession(namespace: "primary")
+```
+
+Configuring `keychainAccessGroup` places the plugin's canonical session,
+transaction state, and widget snapshot in that shared access group. Do not grant
+the entitlement to an extension you do not trust with the complete OIDC session.
+
+## Android widget access
+
+An Android app widget in the same application package and UID can use the public
+native vault:
+
+```java
+TokenVault vault = new TokenVault(context);
+StoredSessionV1 session = vault.loadSession("primary");
+```
+
+Before using `session.accessToken`, compare `session.expiresAt` with the current
+time and leave enough margin for the widget request to complete.

package/docs/TESTING.md

@@ -1,42 +1,53 @@
 # Testing
 
-## Local checks
+## Automated checks
 
-Run the TypeScript checks and package build:
+Run TypeScript linting, unit tests, and the package build:
 
 ```sh
 npm run verify
 ```
 
-`verify` also checks that the TypeScript, Swift, and Java bridge constants still
-match `contracts/native-api.json`.
-
-Build the native libraries with:
+Build and test the native libraries with:
 
 ```sh
 npm run verify:ios
 npm run verify:android
 ```
 
-CI runs Vitest, the iOS XCTest suite in a simulator, Android unit tests, native
-builds, Android lint, and `npm pack --dry-run`. The shared `StoredSessionV1`
-fixture is decoded or produced by all three platform implementations.
+CI currently runs:
+
+- TypeScript linting, Vitest, package builds, and `npm pack --dry-run`;
+- 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;
+- cross-platform decoding of the versioned `StoredSessionV1` fixture.
+
+## Current manual validation
 
-## Physical-device coverage
+Basic Amazon Cognito login has been tested in a packaged application on a
+physical iOS device. The system authentication UI, callback, code exchange, and
+resulting session work in that path.
 
-Before a stable release, install example applications on physical iOS and Android
-devices and verify:
+This does not yet cover all iOS cancellation, logout, refresh, rotation, restart,
+ephemeral-session, and error edge cases. Physical Android and the provider matrix
+also remain incomplete.
+
+## Required physical-device coverage
+
+Before a stable release, verify 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;
-- shared and ephemeral iOS browser sessions;
+- shared and ephemeral browser sessions;
 - Keychain and Keystore persistence across app restarts;
-- session reads from iOS and Android widgets.
+- refresh before expiry and refresh after resuming beyond expiry;
+- reads from iOS and Android widgets.
 
 ## Provider integration coverage
 
-Run the following flows against at least two conforming providers, including a
-locally configurable provider:
+The target matrix contains at least two conforming providers, including a locally
+configurable provider, and covers:
 
 - discovery and explicit metadata;
 - login, code exchange, UserInfo, and logout;
@@ -45,3 +56,6 @@ locally configurable provider:
 - invalid state, nonce, callback, and ID-token claims;
 - a provider that omits refresh tokens;
 - a provider that rejects the configured Capacitor origin through CORS.
+
+Provider configuration examples that have not been tested on physical devices are
+labelled as guidance in [Provider configuration](PROVIDERS.md).

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,67 @@
+# Troubleshooting
+
+## Login fails before system UI opens
+
+- Confirm `crypto.subtle` and `crypto.getRandomValues` exist in the packaged
+  Capacitor WebView.
+- Confirm the authorization endpoint uses HTTPS.
+- Confirm discovery succeeds, or provide complete static `metadata`.
+- Inspect the error `code`; `BROWSER_UNAVAILABLE` and `UNSUPPORTED_RUNTIME`
+  identify adapter failures.
+
+## The provider reports a redirect mismatch
+
+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.
+
+## Android does not return to the app
+
+- Keep `MainActivity` in `singleTask` launch mode.
+- Put the callback intent filter inside the existing `MainActivity` declaration.
+- Match the `<data android:scheme>` value to `redirect_uri`.
+- If using HTTPS, verify the App Link and Digital Asset Links association.
+
+See [Android setup](PLATFORM_SETUP.md#android).
+
+## iOS does not show the expected sheet or consent dialog
+
+`ASWebAuthenticationSession` controls both presentation and the provider-consent
+dialog. The operating system decides when consent is required and can remember a
+previous decision. Verify that the Capacitor view controller has an active window
+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.
+
+## No refresh token is available
+
+- Request the provider's offline-access scope when required.
+- 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`.
+
+## Manager creation fails while offline
+
+The current alpha validates the restored session during
+`CapacitorUserManager.create()`. If the stored access token needs renewal, a
+temporary token-endpoint failure can reject creation. Initialize the manager from
+a place that can surface a retry action. A future implementation should make
+creation succeed offline and report renewal failure through `silentRenewError`.
+
+## 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).
+
+## `USER_CANCELLED` appears but Android UI remains visible
+
+Android does not provide an API for forcibly closing an already-open Auth Tab or
+Custom Tab. `cancel()` rejects the pending JavaScript operation and clears plugin
+state; the user may still need to close the browser UI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capacitor-oidc",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.2",
   "description": "A minimal Capacitor adapter for standards-based OpenID Connect authentication.",
   "main": "dist/plugin.cjs",
   "module": "dist/esm/index.js",
@@ -8,7 +8,8 @@
   "files": [
     "android/src/main/",
     "android/build.gradle",
-    "contracts/",
+    "contracts/fixtures/stored-session-v1.json",
+    "contracts/stored-session-v1.schema.json",
     "dist/",
     "docs/",
     "ios/Sources",
@@ -19,8 +20,7 @@
   ],
   "license": "Apache-2.0",
   "author": {
-    "name": "Jojo Pirker",
-    "email": "j.pirker@gmail.com"
+    "name": "Jojo Pirker"
   },
   "repository": {
     "type": "git",