@icp-sdk/auth 8.0.2 → 9.0.0

package/src/client/index.ts

@@ -2,13 +2,29 @@
  * @module api/client
  */
 
+export { type AppDelegationSource, SessionGoneError } from './app-delegation-source.js';
 export * from './auth-client.js';
-export { type DBCreateOptions, IdbKeyVal } from './db.js';
-export * from './idle-manager.js';
 export {
-  type AuthClientStorage,
-  IdbStorage,
-  KEY_STORAGE_DELEGATION,
-  KEY_STORAGE_KEY,
-  LocalStorage,
-} from './storage.js';
+  CookieStateStorage,
+  type CookieStateStorageOptions,
+} from './cookie-state-storage.js';
+export type { Credential, CredentialStorage } from './credential-storage.js';
+export { DB_VERSION, type DBCreateOptions, IdbKeyVal } from './db.js';
+export { watchActivity, watchForeground } from './foreground-refresh.js';
+export { IdbCredentialStorage } from './idb-credential-storage.js';
+export { LocalCredentialStorage } from './local-credential-storage.js';
+export { MemoryCredentialStorage } from './memory-credential-storage.js';
+export { InteractionRequiredError, requestSessionDelegation } from './session-delegation.js';
+export { SessionIdentity, type SessionIdentityOptions } from './session-identity.js';
+export { SessionMinter, type SessionMinterOptions } from './session-minter.js';
+export {
+  DEFAULT_SHARED_MEMORY_NAME,
+  SharedMemoryCredentialStorage,
+} from './shared-memory-credential-storage.js';
+export { isValidSsoDomain } from './sso.js';
+export {
+  LocalStateStorage,
+  MemoryStateStorage,
+  type SessionState,
+  type StateStorage,
+} from './state-storage.js';

package/src/client/local-credential-storage.ts

@@ -0,0 +1,68 @@
+import { DelegationChain, Ed25519KeyIdentity } from '@icp-sdk/core/identity';
+import type { Credential, CredentialStorage } from './credential-storage.js';
+
+/** What one slot holds: the key as JSON, and the chain as JSON. */
+interface StoredCredential {
+  key: string;
+  chain?: string;
+}
+
+/**
+ * Credentials in `localStorage`, for where IndexedDB is unavailable.
+ *
+ * `localStorage` holds strings, so the key has to be one: this generates an
+ * Ed25519 identity, whose private bytes serialise, rather than the
+ * non-extractable key {@link IdbCredentialStorage} uses. That is the trade the
+ * medium imposes, and it is why generation belongs to the store.
+ * @see implements {@link CredentialStorage}
+ */
+export class LocalCredentialStorage implements CredentialStorage<Ed25519KeyIdentity> {
+  public readonly shared = true;
+  public readonly durable = true;
+
+  /**
+   * @param prefix - Prepended to every slot, so two clients under one origin can
+   *   be kept apart.
+   */
+  constructor(public readonly prefix = 'ic-') {}
+
+  public create(): Promise<Ed25519KeyIdentity> {
+    return Promise.resolve(Ed25519KeyIdentity.generate());
+  }
+
+  public get(slot: string): Promise<Credential<Ed25519KeyIdentity> | null> {
+    const raw = this.#localStorage().getItem(this.prefix + slot);
+    if (raw === null) return Promise.resolve(null);
+
+    try {
+      const stored = JSON.parse(raw) as StoredCredential;
+      const identity = Ed25519KeyIdentity.fromJSON(stored.key);
+      const chain = stored.chain === undefined ? undefined : DelegationChain.fromJSON(stored.chain);
+      return Promise.resolve({ identity, chain });
+    } catch {
+      return Promise.resolve(null);
+    }
+  }
+
+  public set(slot: string, credential: Credential<Ed25519KeyIdentity>): Promise<void> {
+    const stored: StoredCredential = {
+      key: JSON.stringify(credential.identity.toJSON()),
+      chain: credential.chain && JSON.stringify(credential.chain.toJSON()),
+    };
+    this.#localStorage().setItem(this.prefix + slot, JSON.stringify(stored));
+    return Promise.resolve();
+  }
+
+  public remove(slot: string): Promise<void> {
+    this.#localStorage().removeItem(this.prefix + slot);
+    return Promise.resolve();
+  }
+
+  #localStorage(): Storage {
+    const ls = globalThis.localStorage;
+    if (!ls) {
+      throw new Error('Could not find local storage.');
+    }
+    return ls;
+  }
+}

package/src/client/memory-credential-storage.ts

@@ -0,0 +1,41 @@
+import { ECDSAKeyIdentity } from '@icp-sdk/core/identity';
+import type { Credential, CredentialStorage } from './credential-storage.js';
+
+/**
+ * Credentials held for the lifetime of the instance and shared with nothing.
+ *
+ * For tests and for environments with neither IndexedDB nor `localStorage`. A
+ * reload starts from nothing, and other tabs see nothing, so every tab of an
+ * origin is alone.
+ *
+ * Records are handed back as they were given rather than round-tripped through
+ * an encoding, which is what lets this hold a non-extractable key at all.
+ * @see implements {@link CredentialStorage}
+ */
+export class MemoryCredentialStorage implements CredentialStorage<ECDSAKeyIdentity> {
+  public readonly shared = false;
+  public readonly durable = false;
+
+  // On the instance and never on the module: two clients on one page must not
+  // see each other's slots, and no state may carry between tests in one process.
+  #credentials = new Map<string, Credential<ECDSAKeyIdentity>>();
+
+  public create(): Promise<ECDSAKeyIdentity> {
+    // Nothing is serialised here, so the key never has to be readable.
+    return ECDSAKeyIdentity.generate({ extractable: false });
+  }
+
+  public get(slot: string): Promise<Credential<ECDSAKeyIdentity> | null> {
+    return Promise.resolve(this.#credentials.get(slot) ?? null);
+  }
+
+  public set(slot: string, credential: Credential<ECDSAKeyIdentity>): Promise<void> {
+    this.#credentials.set(slot, credential);
+    return Promise.resolve();
+  }
+
+  public remove(slot: string): Promise<void> {
+    this.#credentials.delete(slot);
+    return Promise.resolve();
+  }
+}

package/src/client/session-delegation.ts

@@ -0,0 +1,138 @@
+import type { DerEncodedPublicKey } from '@icp-sdk/core/agent';
+import { Delegation, DelegationChain } from '@icp-sdk/core/identity';
+import { Principal } from '@icp-sdk/core/principal';
+import type { Signer } from '@icp-sdk/signer';
+import { fromBase64, toBase64 } from './base64.js';
+
+/**
+ * The method Internet Identity answers with a session rather than a long-lived
+ * delegation. Named for its provider because a JSON-RPC method travels over a
+ * transport shared with other signers, unlike a canister method.
+ */
+const SESSION_DELEGATION_METHOD = 'ii_session_delegation';
+
+/**
+ * The code Internet Identity denies a `prompt: 'none'` request with.
+ *
+ * In ICRC-25's 3xxx user-action range, which is what lets a caller tell a request
+ * that needs a ceremony apart from a transport or protocol failure.
+ */
+const INTERACTION_REQUIRED_CODE = 3002;
+
+/**
+ * Internet Identity had nothing to answer a silent request from.
+ *
+ * The one denial that is not a failure: it says a ceremony is needed, so the
+ * caller signs in interactively rather than retrying. It is also the only
+ * dependable evidence that a shared record is stale rather than replaced, which
+ * is what lets an origin retract a record it did not write.
+ *
+ * Thrown only for a request that asked not to render anything. An interactive
+ * sign-in that the user abandons is a different outcome and is not this.
+ */
+export class InteractionRequiredError extends Error {
+  /**
+   * Why, where Internet Identity said: `login_required` where it holds no
+   * session, `account_selection_required` where it holds more than one and the
+   * request named none.
+   *
+   * A caller may word its prompt from this and does not have to branch on it, so
+   * it is deliberately a string rather than a union — a value this library does
+   * not know is not a reason to fail.
+   */
+  readonly reason: string | undefined;
+
+  constructor(message: string, reason?: string) {
+    super(message);
+    this.name = 'InteractionRequiredError';
+    this.reason = reason;
+  }
+}
+
+interface SessionDelegationResult {
+  publicKey: string;
+  signerDelegation: {
+    delegation: { pubkey: string; expiration: string; targets?: string[] };
+    signature: string;
+  }[];
+}
+
+const looksLikeResult = (value: unknown): value is SessionDelegationResult => {
+  const result = value as SessionDelegationResult | undefined;
+  return (
+    typeof result?.publicKey === 'string' &&
+    Array.isArray(result?.signerDelegation) &&
+    // An empty list builds a chain whose earliest expiry is 0, so it reads as a
+    // session that expired at the epoch rather than as a bad response.
+    result.signerDelegation.length > 0
+  );
+};
+
+/**
+ * Asks the identity provider for a session, and returns the chain it signed.
+ *
+ * The chain is restricted to the Internet Identity canister, so it is not
+ * something an application can call its own canisters with. It is what app
+ * delegations are minted from.
+ */
+export async function requestSessionDelegation(
+  signer: Signer,
+  params: {
+    sessionPublicKey: DerEncodedPublicKey;
+    maxTimeToLive?: bigint;
+    maxTimeToIdle?: bigint;
+    derivationOrigin?: string;
+  },
+): Promise<DelegationChain> {
+  const response = await signer.sendRequest({
+    jsonrpc: '2.0',
+    id: globalThis.crypto.randomUUID(),
+    method: SESSION_DELEGATION_METHOD,
+    params: {
+      sessionPublicKey: toBase64(params.sessionPublicKey),
+      ...(params.maxTimeToLive === undefined
+        ? {}
+        : { maxTimeToLive: params.maxTimeToLive.toString() }),
+      ...(params.maxTimeToIdle === undefined
+        ? {}
+        : { maxTimeToIdle: params.maxTimeToIdle.toString() }),
+      ...(params.derivationOrigin === undefined
+        ? {}
+        : { icrc95DerivationOrigin: params.derivationOrigin }),
+    },
+  });
+
+  if ('error' in response) {
+    // The code carries the only thing a caller can act on, and dropping it left
+    // `interaction_required` indistinguishable from a transport failure except by
+    // matching a message this library does not define.
+    if (response.error.code === INTERACTION_REQUIRED_CODE) {
+      const data = response.error.data;
+      const reason =
+        typeof data === 'object' && data !== null && 'reason' in data
+          ? String((data as { reason: unknown }).reason)
+          : undefined;
+      throw new InteractionRequiredError(response.error.message, reason);
+    }
+    throw new Error(response.error.message);
+  }
+
+  const result = response.result;
+  if (!looksLikeResult(result)) {
+    throw new Error(
+      'Invalid session response: missing publicKey, or missing or empty signerDelegation',
+    );
+  }
+
+  return DelegationChain.fromDelegations(
+    result.signerDelegation.map(({ delegation, signature }) => ({
+      delegation: new Delegation(
+        fromBase64(delegation.pubkey),
+        BigInt(delegation.expiration),
+        delegation.targets?.map((target) => Principal.fromText(target)),
+      ),
+      signature: fromBase64(signature) as DelegationChain['delegations'][number]['signature'],
+    })),
+    fromBase64(result.publicKey) as DerEncodedPublicKey,
+  );
+}