@icp-sdk/auth 5.0.0 → 6.1.0

package/README.md

@@ -40,25 +40,109 @@ 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();
+
+// restore an existing session if there is one, otherwise sign in
+let identity;
+try {
+  identity = authClient.isAuthenticated()
+    ? await authClient.getIdentity()
+    : await authClient.signIn();
+} catch (error) {
+  console.error('Sign-in failed:', error);
+  throw error;
+}
+
+console.log('Identity:', identity.getPrincipal().toString());
 
-const authClient = await AuthClient.create();
-const identity = authClient.getIdentity(); // At this point, you'll get a Principal.anonymous()
+// later, to end the session
+await authClient.logout();
+```
 
-async function onSuccess() {
-  console.log('Login successful');
+### One-Click OpenID Sign-In
 
-  const identity = authClient.getIdentity(); // At this point, you'll get an authenticated identity
-  console.log(authClient.isAuthenticated()); // true
+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'
+});
+```
+
+### Requesting Identity Attributes
+
+Internet Identity can provide signed identity attributes (e.g., email) alongside authentication. Your backend canister initiates the flow by issuing a nonce tied to the action — this way, even if an attribute bundle is intercepted, it can't be replayed or used for a different action.
+
+Here's a registration flow where the backend needs the user's email:
+
+```typescript
+import { AuthClient } from '@icp-sdk/auth/client';
+import { AttributesIdentity } from '@icp-sdk/core/identity';
+import { HttpAgent, Actor } from '@icp-sdk/core/agent';
+
+const authClient = new AuthClient();
+
+// the backend issues a nonce scoped to registration —
+// this starts the action and binds the upcoming attributes to it
+const anonymousAgent = await HttpAgent.create();
+const backend = Actor.createActor(backendIdl, { agent: anonymousAgent, canisterId });
+const nonce: Uint8Array = await backend.registerBegin();
+
+// sign-in and attribute request happen in parallel — the user sees a single II interaction
+try {
+  const signInPromise = authClient.signIn();
+  const attributesPromise = authClient.requestAttributes({ keys: ['email'], nonce });
+
+  await signInPromise;
+  const { data, signature } = await attributesPromise;
+
+  // wrap the identity so the signed attributes are included in the canister call
+  const identityWithAttributes = new AttributesIdentity({
+    inner: await authClient.getIdentity(),
+    attributes: { data, signature },
+    signer: { canisterId: Principal.fromText('rdmx6-jaaaa-aaaaa-aaadq-cai') }, // Internet Identity canister ID
+  });
+  const agent = await HttpAgent.create({ identity: identityWithAttributes });
+  const app = Actor.createActor(appIdl, { agent, canisterId });
+
+  // the backend verifies the nonce, origin, and timestamp, then extracts the email
+  await app.registerFinish();
+} catch (error) {
+  console.error('Registration failed:', error);
 }
+```
+
+The signed attribute bundle includes implicit fields that your backend canister should verify:
+
+- **`implicit:nonce`** — ties the attributes to a specific canister-initiated action, preventing replay and cross-action reuse. Must originate from the backend, not the frontend.
+- **`implicit:origin`** — the requesting origin, verified by the canister to prevent a malicious dapp from forwarding attribute bundles to your backend.
+- **`implicit:issued_at_timestamp_ns`** — issuance timestamp, allowing the canister to reject stale attributes even if the nonce hasn't expired yet.
+
+> Attributes can also be requested after sign-in — for example, when a user later triggers an action like linking an email. The flow is the same: the backend issues a nonce for that action, the frontend calls `requestAttributes`, and the backend verifies the result.
+
+#### OpenID-Scoped Attributes
 
-await authClient.login({
-  identityProvider,
-  onSuccess,
+When using one-click sign-in, attributes can be scoped to the OpenID provider. Scoped attributes have implicit consent — the user authenticates and shares attributes in a single step without an additional prompt:
+
+```typescript
+import { AuthClient, scopedKeys } from '@icp-sdk/auth/client';
+
+const authClient = new AuthClient({
+  openIdProvider: 'google',
 });
 
-// later in your app
-await authClient.logout();
+const nonce: Uint8Array = await backend.registerBegin();
+const signInPromise = authClient.signIn();
+// requests name, email, and verified_email from the
+// Google account linked to the user's Internet Identity
+const attributesPromise = authClient.requestAttributes({
+  keys: scopedKeys({ openIdProvider: 'google' }),
+  nonce,
+});
+
+await signInPromise;
+const { data, signature } = await attributesPromise;
+// ... wrap with AttributesIdentity and complete the action as above
 ```
 
 Additional documentation can be found [here](https://js.icp.build/auth/latest/).

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

@@ -1,177 +1,173 @@
-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';
+export declare const OPENID_PROVIDER_URLS: {
+    readonly google: "https://accounts.google.com";
+    readonly apple: "https://appleid.apple.com";
+    readonly microsoft: "https://login.microsoftonline.com/{tid}/v2.0";
+};
+declare const DEFAULT_OPENID_SCOPE_KEYS: readonly ["name", "email", "verified_email"];
 /**
- * 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 sign-in.
      *
-     * 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 OnErrorFunc = (error?: string) => void | Promise<void>;
-export interface AuthClientLoginOptions {
-    /**
-     * Identity provider
-     * @default "https://identity.internetcomputer.org"
-     */
-    identityProvider?: string | URL;
+/**
+ * Options for {@link AuthClient.signIn}.
+ */
+export interface AuthClientSignInOptions {
     /**
-     * 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).
+     * Restrict the delegation to specific canisters.
      */
-    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;
+    targets?: Principal[];
+}
+export interface SignedAttributes {
+    data: Uint8Array;
+    signature: Uint8Array;
+}
+/**
+ * Manages authentication and identity for Internet Computer web apps.
+ *
+ * @example
+ * const authClient = new AuthClient();
+ *
+ * const identity = authClient.isAuthenticated()
+ *   ? await authClient.getIdentity()
+ *   : await authClient.signIn();
+ */
+export declare class AuthClient {
+    #private;
+    idleManager: IdleManager | undefined;
+    constructor(options?: AuthClientCreateOptions);
     /**
-     * Auth Window feature config string
-     * @example "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100"
+     * Returns the current identity, restoring a previous session if available.
      */
-    windowOpenerFeatures?: string;
+    getIdentity(): Promise<Identity>;
     /**
-     * Callback once login has completed
+     * Checks whether the user has an active, non-expired session.
      */
-    onSuccess?: OnSuccessFunc;
+    isAuthenticated(): boolean;
     /**
-     * Callback in case authentication fails
+     * Opens the identity provider, requests a delegation, and returns the authenticated identity.
+     *
+     * @param options - Sign-in options.
+     * @param options.maxTimeToLive - Maximum lifetime of the delegation in nanoseconds.
+     * @param options.targets - Restrict the delegation to specific canisters.
+     * @returns The authenticated identity.
+     * @throws When authentication fails.
+     *
+     * @example
+     * try {
+     *   const identity = await authClient.signIn();
+     * } catch (error) {
+     *   console.error('Sign-in failed:', error);
+     * }
      */
-    onError?: OnErrorFunc;
+    signIn(options?: AuthClientSignInOptions): Promise<Identity>;
     /**
-     * Extra values to be passed in the login request during the authorize-ready phase
+     * Requests signed identity attributes from the identity provider.
+     *
+     * @param params - Request parameters.
+     * @param params.keys - Attribute keys to request (e.g. `['email', 'name']`).
+     * @param params.nonce - 32-byte nonce issued by the RP canister.
+     * @returns Signed attribute data and signature.
+     * @throws When the identity provider returns an error or an invalid response.
+     */
+    requestAttributes(params: {
+        keys: string[];
+        nonce: Uint8Array;
+    }): Promise<SignedAttributes>;
+    /**
+     * 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.
      */
-    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}
- */
-export declare class AuthClient {
-    private _identity;
-    private _key;
-    private _chain;
-    private _storage;
-    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.
-     * @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);
-     *  }
-     * });
-     */
-    login(options?: AuthClientLoginOptions): Promise<void>;
-    private _getEventHandler;
-    private _handleFailure;
-    private _removeEventListener;
     logout(options?: {
         returnTo?: string;
     }): Promise<void>;
 }
+/**
+ * Scopes attribute keys to an OpenID provider.
+ *
+ * When using one-click sign-in, attributes can be scoped to the same provider
+ * so the user grants access in a single step without an additional prompt.
+ *
+ * @param params.openIdProvider - The OpenID provider the keys should be scoped to.
+ * @param params.keys - The attribute keys to scope. Defaults to `['name', 'email', 'verified_email']`.
+ * @returns The scoped attribute keys as `openid:<provider-url>:<key>`.
+ *
+ * @example
+ * scopedKeys({ openIdProvider: 'google', keys: ['email'] });
+ * // ['openid:https://accounts.google.com:email']
+ */
+export declare function scopedKeys<P extends keyof typeof OPENID_PROVIDER_URLS, K extends string = (typeof DEFAULT_OPENID_SCOPE_KEYS)[number]>(params: {
+    openIdProvider: P;
+    keys?: readonly K[];
+}): `openid:${(typeof OPENID_PROVIDER_URLS)[P]}:${K}`[];
 export {};