@icp-sdk/auth 5.0.0-beta.2 → 6.0.0

package/README.md

@@ -40,25 +40,37 @@ Here's a simple example of how to use the `@icp-sdk/auth` package to authenticat
 ```typescript
 import { AuthClient } from '@icp-sdk/auth/client';
 
-const identityProvider = 'https://id.ai/';
+const authClient = new AuthClient();
 
-const authClient = await AuthClient.create();
-const identity = authClient.getIdentity(); // At this point, you'll get a Principal.anonymous()
-
-async function onSuccess() {
-  console.log('Login successful');
+// Check for an existing session (synchronous)
+if (authClient.isAuthenticated()) {
+  const identity = await authClient.getIdentity();
+  console.log('Restored session:', identity.getPrincipal().toString());
+}
 
-  const identity = authClient.getIdentity(); // At this point, you'll get an authenticated identity
-  console.log(authClient.isAuthenticated()); // true
+// Log in
+try {
+  await authClient.login();
+  const identity = await authClient.getIdentity();
+  console.log('Logged in:', identity.getPrincipal().toString());
+} catch (error) {
+  console.error('Login failed:', error);
 }
 
-await authClient.login({
-  identityProvider,
-  onSuccess,
+// Log out
+await authClient.logout();
+```
+
+### One-Click OpenID Sign-In
+
+Skip the Internet Identity authentication method screen and offer sign-in options like Google directly in your app:
+
+```typescript
+const authClient = new AuthClient({
+  openIdProvider: 'google', // or 'apple' or 'microsoft'
 });
 
-// later in your app
-await authClient.logout();
+await authClient.login();
 ```
 
 Additional documentation can be found [here](https://js.icp.build/auth/latest/).

package/dist/esm/client/auth-client.d.ts

@@ -1,175 +1,145 @@
-import { Identity, SignIdentity } from '@icp-sdk/core/agent';
-import { DelegationChain, PartialIdentity } from '@icp-sdk/core/identity';
-import { Principal } from '@icp-sdk/core/principal';
-import { IdleManager, IdleManagerOptions } from './idle-manager.ts';
-import { AuthClientStorage } from './storage.ts';
+import { type Identity, type SignIdentity } from '@icp-sdk/core/agent';
+import { type PartialIdentity } from '@icp-sdk/core/identity';
+import type { Principal } from '@icp-sdk/core/principal';
+import { IdleManager, type IdleManagerOptions } from './idle-manager.js';
+import { type AuthClientStorage } from './storage.js';
 declare const ECDSA_KEY_LABEL = "ECDSA";
 declare const ED25519_KEY_LABEL = "Ed25519";
 type BaseKeyType = typeof ECDSA_KEY_LABEL | typeof ED25519_KEY_LABEL;
-export declare const ERROR_USER_INTERRUPT = "UserInterrupt";
+export type OpenIdProvider = 'google' | 'apple' | 'microsoft';
 /**
- * List of options for creating an {@link AuthClient}.
+ * Options for creating an {@link AuthClient}.
  */
 export interface AuthClientCreateOptions {
     /**
-     * An {@link SignIdentity} or {@link PartialIdentity} to authenticate via delegation.
+     * An identity to authenticate via delegation.
      */
     identity?: SignIdentity | PartialIdentity;
     /**
-     * Optional storage with get, set, and remove. Uses {@link IdbStorage} by default.
-     * @see {@link AuthClientStorage}
+     * Persistent storage backend. Defaults to IndexedDB.
+     * @default IdbStorage
      */
     storage?: AuthClientStorage;
     /**
-     * Type to use for the base key.
+     * Type of session key to generate on each login.
      *
-     * If you are using a custom storage provider that does not support CryptoKey storage,
-     * you should use `Ed25519` as the key type, as it can serialize to a string.
+     * Use `'Ed25519'` when your storage provider does not support `CryptoKey`.
      * @default 'ECDSA'
      */
     keyType?: BaseKeyType;
     /**
-     * Options to handle idle timeouts
+     * Idle timeout configuration.
      * @default after 10 minutes, invalidates the identity
      */
     idleOptions?: IdleOptions;
     /**
-     * Options to handle login, passed to the login method
+     * Identity provider URL.
+     * @default "https://id.ai/authorize"
      */
-    loginOptions?: AuthClientLoginOptions;
+    identityProvider?: string | URL;
+    /**
+     * Derivation origin for the identity provider.
+     * @see https://github.com/dfinity/internet-identity/blob/main/docs/internet-identity-spec.adoc
+     */
+    derivationOrigin?: string | URL;
+    /**
+     * Window features string for the authentication popup.
+     * @example "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100"
+     */
+    windowOpenerFeatures?: string;
+    /**
+     * OpenID provider for one-click sign-in. When set, the identity provider
+     * URL includes an `openid` search param so the user authenticates via
+     * the chosen provider (e.g. Google) instead of seeing Internet Identity directly.
+     */
+    openIdProvider?: OpenIdProvider;
 }
 export interface IdleOptions extends IdleManagerOptions {
     /**
-     * Disables idle functionality for {@link IdleManager}
+     * Disables idle functionality entirely.
      * @default false
      */
     disableIdle?: boolean;
     /**
-     * Disables default idle behavior - call logout & reload window
+     * Disables the default idle callback (logout & reload).
      * @default false
      */
     disableDefaultIdleCallback?: boolean;
 }
-export type OnSuccessFunc = (() => void | Promise<void>) | ((message: InternetIdentityAuthResponseSuccess) => void | Promise<void>);
+export type OnSuccessFunc = () => void | Promise<void>;
 export type OnErrorFunc = (error?: string) => void | Promise<void>;
+/**
+ * Options for {@link AuthClient.login}.
+ */
 export interface AuthClientLoginOptions {
     /**
-     * Identity provider
-     * @default "https://identity.internetcomputer.org"
-     */
-    identityProvider?: string | URL;
-    /**
-     * Expiration of the authentication in nanoseconds
-     * @default  BigInt(8) hours * BigInt(3_600_000_000_000) nanoseconds
+     * Maximum lifetime of the delegation in nanoseconds.
+     * @default 8 hours
      */
     maxTimeToLive?: bigint;
     /**
-     * If present, indicates whether or not the Identity Provider should allow the user to authenticate and/or register using a temporary key/PIN identity. Authenticating dapps may want to prevent users from using Temporary keys/PIN identities because Temporary keys/PIN identities are less secure than Passkeys (webauthn credentials) and because Temporary keys/PIN identities generally only live in a browser database (which may get cleared by the browser/OS).
-     */
-    allowPinAuthentication?: boolean;
-    /**
-     * Origin for Identity Provider to use while generating the delegated identity. For II, the derivation origin must authorize this origin by setting a record at `<derivation-origin>/.well-known/ii-alternative-origins`.
-     * @see https://github.com/dfinity/internet-identity/blob/main/docs/internet-identity-spec.adoc
-     */
-    derivationOrigin?: string | URL;
-    /**
-     * Auth Window feature config string
-     * @example "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100"
+     * Restrict the delegation to specific canisters.
      */
-    windowOpenerFeatures?: string;
+    targets?: Principal[];
     /**
-     * Callback once login has completed
+     * Called after a successful login.
      */
     onSuccess?: OnSuccessFunc;
     /**
-     * Callback in case authentication fails
+     * Called when login fails. When provided the error is **not** re-thrown,
+     * allowing the caller to handle it via this callback instead.
      */
     onError?: OnErrorFunc;
-    /**
-     * Extra values to be passed in the login request during the authorize-ready phase
-     */
-    customValues?: Record<string, unknown>;
-}
-export interface InternetIdentityAuthResponseSuccess {
-    kind: 'authorize-client-success';
-    delegations: {
-        delegation: {
-            pubkey: Uint8Array;
-            expiration: bigint;
-            targets?: Principal[];
-        };
-        signature: Uint8Array;
-    }[];
-    userPublicKey: Uint8Array;
-    authnMethod: 'passkey' | 'pin' | 'recovery';
 }
 /**
- * Tool to manage authentication and identity
- * @see {@link AuthClient}
+ * Manages authentication and identity for Internet Computer web apps.
+ *
+ * @example
+ * const authClient = new AuthClient();
+ *
+ * if (authClient.isAuthenticated()) {
+ *   const identity = await authClient.getIdentity();
+ * }
+ *
+ * await authClient.login({
+ *   onSuccess: () => console.log('Logged in!'),
+ * });
  */
 export declare class AuthClient {
-    private _identity;
-    private _key;
-    private _chain;
-    private _storage;
+    #private;
     idleManager: IdleManager | undefined;
-    private _createOptions;
-    private _idpWindow?;
-    private _eventHandler?;
-    /**
-     * Create an AuthClient to manage authentication and identity
-     * @param {AuthClientCreateOptions} options - Options for creating an {@link AuthClient}
-     * @see {@link AuthClientCreateOptions}
-     * @param options.identity Optional Identity to use as the base
-     * @see {@link SignIdentity}
-     * @param options.storage Storage mechanism for delegation credentials
-     * @see {@link AuthClientStorage}
-     * @param options.keyType Type of key to use for the base key
-     * @param {IdleOptions} options.idleOptions Configures an {@link IdleManager}
-     * @see {@link IdleOptions}
-     * Default behavior is to clear stored identity and reload the page when a user goes idle, unless you set the disableDefaultIdleCallback flag or pass in a custom idle callback.
-     * @example
-     * const authClient = await AuthClient.create({
-     *   idleOptions: {
-     *     disableIdle: true
-     *   }
-     * })
-     */
-    static create(options?: AuthClientCreateOptions): Promise<AuthClient>;
-    protected constructor(_identity: Identity | PartialIdentity, _key: SignIdentity | PartialIdentity, _chain: DelegationChain | null, _storage: AuthClientStorage, idleManager: IdleManager | undefined, _createOptions: AuthClientCreateOptions | undefined, _idpWindow?: Window | undefined, _eventHandler?: ((event: MessageEvent) => void) | undefined);
-    private _registerDefaultIdleCallback;
-    private _handleSuccess;
-    getIdentity(): Identity;
-    isAuthenticated(): Promise<boolean>;
-    /**
-     * AuthClient Login - Opens up a new window to authenticate with Internet Identity
-     * @param {AuthClientLoginOptions} options - Options for logging in, merged with the options set during creation if any. Note: we only perform a shallow merge for the `customValues` property.
-     * @param options.identityProvider Identity provider
-     * @param options.maxTimeToLive Expiration of the authentication in nanoseconds
-     * @param options.allowPinAuthentication If present, indicates whether or not the Identity Provider should allow the user to authenticate and/or register using a temporary key/PIN identity. Authenticating dapps may want to prevent users from using Temporary keys/PIN identities because Temporary keys/PIN identities are less secure than Passkeys (webauthn credentials) and because Temporary keys/PIN identities generally only live in a browser database (which may get cleared by the browser/OS).
-     * @param options.derivationOrigin Origin for Identity Provider to use while generating the delegated identity
-     * @param options.windowOpenerFeatures Configures the opened authentication window
-     * @param options.onSuccess Callback once login has completed
-     * @param options.onError Callback in case authentication fails
-     * @param options.customValues Extra values to be passed in the login request during the authorize-ready phase. Note: we only perform a shallow merge for the `customValues` property.
+    constructor(options?: AuthClientCreateOptions);
+    /**
+     * Returns the current identity, restoring a previous session if available.
+     */
+    getIdentity(): Promise<Identity>;
+    /**
+     * Checks whether the user has an active, non-expired session.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Opens the identity provider and requests a delegation.
+     *
+     * @param options - Login options.
+     * @param options.maxTimeToLive - Maximum lifetime of the delegation in nanoseconds.
+     * @param options.targets - Restrict the delegation to specific canisters.
+     * @param options.onSuccess - Called after a successful login.
+     * @param options.onError - Called when login fails. When provided the error is not re-thrown.
+     * @throws When authentication fails and no `onError` callback is provided.
+     *
      * @example
-     * const authClient = await AuthClient.create();
-     * authClient.login({
-     *  identityProvider: 'http://<canisterID>.127.0.0.1:8000',
-     *  maxTimeToLive: BigInt (7) * BigInt(24) * BigInt(3_600_000_000_000), // 1 week
-     *  windowOpenerFeatures: "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100",
-     *  onSuccess: () => {
-     *    console.log('Login Successful!');
-     *  },
-     *  onError: (error) => {
-     *    console.error('Login Failed: ', error);
-     *  }
+     * await authClient.login({
+     *   onSuccess: () => console.log('Logged in!'),
+     *   onError: (err) => console.error(err),
      * });
      */
     login(options?: AuthClientLoginOptions): Promise<void>;
-    private _getEventHandler;
-    private _handleFailure;
-    private _removeEventListener;
+    /**
+     * Clears the stored session and resets the client to an anonymous state.
+     *
+     * @param options - Logout options.
+     * @param options.returnTo - URL to navigate to after logout.
+     */
     logout(options?: {
         returnTo?: string;
     }): Promise<void>;