@icp-sdk/auth 8.0.2 → 9.0.0

package/src/client/session-minter.ts

@@ -0,0 +1,286 @@
+import {
+  Actor,
+  type DerEncodedPublicKey,
+  HttpAgent,
+  type HttpAgentOptions,
+  type SignIdentity,
+} from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+import { Delegation, DelegationChain, DelegationIdentity } from '@icp-sdk/core/identity';
+import type { Principal } from '@icp-sdk/core/principal';
+import { type AppDelegationSource, SessionGoneError } from './app-delegation-source.js';
+
+/**
+ * Just the three methods an app calls with a session chain. Written out rather
+ * than generated because this package carries no Internet Identity declarations,
+ * and generating them for three methods would mean carrying the whole interface.
+ */
+const idlFactory: IDL.InterfaceFactory = ({ IDL }) => {
+  const SessionKey = IDL.Vec(IDL.Nat8);
+  const Timestamp = IDL.Nat64;
+  const AppSessionError = IDL.Variant({
+    NoSuchSession: IDL.Null,
+    NoSuchDelegation: IDL.Null,
+    InternalCanisterError: IDL.Text,
+  });
+  const CandidDelegation = IDL.Record({
+    pubkey: SessionKey,
+    expiration: Timestamp,
+    targets: IDL.Opt(IDL.Vec(IDL.Principal)),
+    permissions: IDL.Opt(IDL.Text),
+  });
+  return IDL.Service({
+    app_prepare_delegation: IDL.Func(
+      [IDL.Record({ session_key: SessionKey })],
+      [
+        IDL.Variant({
+          Ok: IDL.Record({ user_key: SessionKey, expiration: Timestamp }),
+          Err: AppSessionError,
+        }),
+      ],
+      [],
+    ),
+    app_get_delegation: IDL.Func(
+      [IDL.Record({ session_key: SessionKey, expiration: Timestamp })],
+      [
+        IDL.Variant({
+          Ok: IDL.Record({ delegation: CandidDelegation, signature: SessionKey }),
+          Err: AppSessionError,
+        }),
+      ],
+      ['query'],
+    ),
+    app_revoke_session: IDL.Func([], [IDL.Variant({ Ok: IDL.Null, Err: AppSessionError })], []),
+  });
+};
+
+type AppSessionError =
+  | { NoSuchSession: null }
+  | { NoSuchDelegation: null }
+  | { InternalCanisterError: string };
+type Result<T> = { Ok: T } | { Err: AppSessionError };
+
+interface SessionService {
+  app_prepare_delegation(request: {
+    session_key: Uint8Array;
+  }): Promise<Result<{ user_key: Uint8Array; expiration: bigint }>>;
+  app_get_delegation(request: { session_key: Uint8Array; expiration: bigint }): Promise<
+    Result<{
+      delegation: {
+        pubkey: Uint8Array;
+        expiration: bigint;
+        targets: [] | [Principal[]];
+        permissions: [] | [string];
+      };
+      signature: Uint8Array;
+    }>
+  >;
+  app_revoke_session(): Promise<Result<null>>;
+}
+
+const isGone = (error: AppSessionError): boolean => 'NoSuchSession' in error;
+
+/**
+ * Raised when the canister signed nothing for the key and expiration asked for,
+ * which means the expiration was not one `app_prepare_delegation` returned.
+ *
+ * Its own error because the remedy is its own: prepare again and use what comes
+ * back. Signing in afresh is not it — the session is live, or the call would have
+ * been refused for being no session at all.
+ */
+class NoSuchDelegationError extends Error {
+  constructor() {
+    super('Internet Identity signed no delegation for this key and expiration');
+    this.name = 'NoSuchDelegationError';
+  }
+}
+
+/**
+ * Unwraps a canister result, turning the one terminal error into
+ * {@link SessionGoneError}, the retryable one into
+ * {@link NoSuchDelegationError}, and everything else into a plain failure.
+ */
+export const unwrapSessionResult = <T>(result: Result<T>): T => {
+  if ('Ok' in result) return result.Ok;
+  if (isGone(result.Err)) throw new SessionGoneError();
+  if ('NoSuchDelegation' in result.Err) throw new NoSuchDelegationError();
+  // A candid variant, so interpolating it directly renders "[object Object]" and
+  // throws away the canister's own explanation of what went wrong.
+  const detail = 'InternalCanisterError' in result.Err ? result.Err.InternalCanisterError : '';
+  throw new Error(
+    `Internet Identity could not mint a delegation${detail === '' ? '' : `: ${detail}`}`,
+  );
+};
+
+export interface SessionMinterOptions {
+  /** The key the session chain delegates to. Signs the calls made here. */
+  sessionKey: SignIdentity;
+
+  /** The chain proving those calls come from the session. Restricted to II. */
+  sessionChain: DelegationChain;
+
+  /** The canister these calls go to. */
+  canisterId: Principal;
+
+  /**
+   * Options for the agent making them. `identity` is not among them: the agent
+   * signs as the session, which is what a mint call rests on.
+   */
+  agentOptions?: Omit<HttpAgentOptions, 'identity'>;
+}
+
+/** Mints app delegations by asking the Internet Identity canister for one. */
+export class SessionMinter implements AppDelegationSource {
+  readonly #service: SessionService;
+
+  private constructor(service: SessionService) {
+    this.#service = service;
+  }
+
+  static async create(options: SessionMinterOptions): Promise<SessionMinter> {
+    const { canisterId } = options;
+    assertChainReaches(options.sessionChain, canisterId);
+    const agent = await HttpAgent.create({
+      ...options.agentOptions,
+      // Last, so no agent option can replace the session these calls are made as.
+      identity: DelegationIdentity.fromDelegation(options.sessionKey, options.sessionChain),
+    });
+    return new SessionMinter(Actor.createActor<SessionService>(idlFactory, { agent, canisterId }));
+  }
+
+  /**
+   * Prepares and fetches an app delegation, once more if the fetch finds nothing
+   * signed for what the prepare handed out.
+   *
+   * The pair is two calls, and only the first of them is an update: an expiration
+   * the canister will not sign for is one this session no longer holds, and the
+   * answer is to prepare again rather than to sign in again. Attempted a second
+   * time and no further — a third would be pursuing something other than the race
+   * this covers.
+   */
+  async mint(appPublicKey: DerEncodedPublicKey): Promise<DelegationChain> {
+    try {
+      return await this.#mintOnce(appPublicKey);
+    } catch (error) {
+      if (!(error instanceof NoSuchDelegationError)) throw error;
+      return await this.#mintOnce(appPublicKey);
+    }
+  }
+
+  /**
+   * Ends the session at the canister.
+   *
+   * Idempotent at the canister: a session that is already gone is `Ok`, because
+   * the caller wanted it gone and it is gone. What comes back as an error is the
+   * canister failing to write, and it is raised rather than dropped — an
+   * application that told a user it signed them out of their apps should be able
+   * to find out that it did not. The call can also fail the way any update call
+   * can, and that rejection is the caller's to decide about too.
+   */
+  async revoke(): Promise<void> {
+    unwrapSessionResult(await this.#service.app_revoke_session());
+  }
+
+  async #mintOnce(appPublicKey: DerEncodedPublicKey): Promise<DelegationChain> {
+    const prepared = unwrapSessionResult(
+      await this.#service.app_prepare_delegation({ session_key: appPublicKey }),
+    );
+
+    const signed = unwrapSessionResult(
+      await this.#service.app_get_delegation({
+        session_key: appPublicKey,
+        // Exactly what was prepared. A different value is a different signature.
+        expiration: prepared.expiration,
+      }),
+    );
+
+    return appDelegationChain(prepared.user_key, signed);
+  }
+}
+
+/**
+ * Assembles the one-hop chain an app signs its calls with, rooted at the
+ * account's own key.
+ */
+export function appDelegationChain(
+  userKey: Uint8Array,
+  signed: {
+    delegation: {
+      pubkey: Uint8Array;
+      expiration: bigint;
+      targets: [] | [Principal[]];
+      permissions: [] | [string];
+    };
+    signature: Uint8Array;
+  },
+): DelegationChain {
+  // The signature covers whatever fields the canister set, and a delegation
+  // carrying permissions cannot be represented by the chain type, so sending one
+  // without it would fail verification at the boundary node with nothing to point
+  // at. Read-only sessions are unsupported until the type carries the field.
+  if (signed.delegation.permissions.length > 0) {
+    throw new Error(
+      'This session is read-only, which @icp-sdk/auth cannot act for yet: its delegations carry permissions that a delegation chain has no room for',
+    );
+  }
+
+  return DelegationChain.fromDelegations(
+    [
+      {
+        delegation: new Delegation(
+          signed.delegation.pubkey,
+          signed.delegation.expiration,
+          signed.delegation.targets[0],
+        ),
+        signature: signed.signature as DelegationChain['delegations'][number]['signature'],
+      },
+    ],
+    userKey as DerEncodedPublicKey,
+  );
+}
+
+/**
+ * Refuses a chain that is not a session for `canisterId`.
+ *
+ * Targets restrict what the chain's final key may call, and the effective
+ * restriction is the intersection of the hops that name any: a hop with no
+ * targets imposes nothing, so one restricting hop is enough to confine the key.
+ * Internet Identity names the canister on both of its hops — on the one the
+ * canister signs to the provider's own key, and again on the provider's
+ * extension to the application's key — and the intersection is what is checked,
+ * so a hop that stopped naming it would still leave the chain confined by the
+ * other.
+ *
+ * So what is refused is a chain no hop restricts, which the session key would
+ * otherwise be able to sign any call with, and one whose restrictions do not
+ * come out as this canister alone.
+ */
+export function assertChainReaches(chain: DelegationChain, canisterId: Principal): void {
+  const hops = chain.delegations.map(({ delegation }) => delegation.targets);
+  const restricting = hops.filter(
+    (hopTargets): hopTargets is Principal[] => hopTargets !== undefined,
+  );
+
+  if (restricting.length === 0) {
+    throw new Error(
+      `A session chain must be restricted to ${canisterId.toText()}, but no hop of this one names any canister`,
+    );
+  }
+  // An empty list names nothing rather than naming this canister, and a chain
+  // that can call nothing is not a session either.
+  const namingNothing = restricting.some((hopTargets) => hopTargets.length === 0);
+  if (namingNothing) {
+    throw new Error(
+      `A session chain must be restricted to ${canisterId.toText()}, but a hop of this one names nothing`,
+    );
+  }
+  const elsewhere = restricting
+    .flat()
+    .filter((target) => target.compareTo(canisterId) !== 'eq')
+    .map((target) => target.toText());
+  if (elsewhere.length > 0) {
+    throw new Error(
+      `A session chain must be restricted to ${canisterId.toText()}, but this one also names ${[...new Set(elsewhere)].join(', ')}`,
+    );
+  }
+}

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

@@ -0,0 +1,303 @@
+import { DelegationChain, ECDSAKeyIdentity } from '@icp-sdk/core/identity';
+import type { Credential, CredentialStorage } from './credential-storage.js';
+
+/** The channel and lock prefix every instance agrees on by default. */
+export const DEFAULT_SHARED_MEMORY_NAME = 'ic-credentials';
+
+/** What one slot travels as: a key handle, and the chain as JSON. */
+interface WireCredential {
+  slot: string;
+  keyPair: CryptoKeyPair;
+  chain?: string;
+}
+
+/** A write, replicated to every tab as it happens. */
+interface Put extends WireCredential {
+  kind: 'put';
+}
+
+/** A removal, replicated the same way. */
+interface Drop {
+  kind: 'drop';
+  slot: string;
+}
+
+/** A starting instance asking whoever is already running for what it holds. */
+interface Ask {
+  kind: 'ask';
+}
+
+/** Everything one instance holds, in answer to an {@link Ask}. */
+interface Offer {
+  kind: 'offer';
+  entries: WireCredential[];
+}
+
+type Message = Put | Drop | Ask | Offer;
+
+// Narrowing, not protection. A channel reaches one origin, so a stranger on the
+// name is our own code through a deploy or an application posting on it, and what
+// keeps those harmless is elsewhere: the switch answers nothing it does not
+// recognise, and rebuilding a record catches its own failures. This is what gives
+// `data` a type, so the switch can read the fields it needs.
+const isMessage = (value: unknown): value is Message => {
+  if (typeof value !== 'object' || value === null || !('kind' in value)) return false;
+  const message = value as { kind: unknown; slot?: unknown; entries?: unknown };
+  switch (message.kind) {
+    case 'ask':
+      return true;
+    case 'drop':
+      return typeof message.slot === 'string';
+    case 'put':
+      return typeof message.slot === 'string' && 'keyPair' in message;
+    case 'offer':
+      return Array.isArray(message.entries);
+    default:
+      return false;
+  }
+};
+
+/**
+ * Credentials in memory, replicated to the other tabs of this origin.
+ *
+ * For an environment with no durable medium — a browser with IndexedDB and
+ * `localStorage` both unavailable, or an application that has decided nothing may
+ * reach disk — where every tab minting for itself is still worth avoiding.
+ *
+ * Every write is broadcast and every instance applies what it receives, so a
+ * steady-state read is local and immediate: the medium is a `Map`, and the channel
+ * is what keeps the Maps agreeing. A `CryptoKeyPair` survives a structured clone
+ * as a handle that signs and cannot be exported, so what crosses is usable
+ * without key material having been sent.
+ *
+ * Nothing survives the document, which is what `durable` says. What that costs is
+ * the last tab of an origin closing: the credentials go with it, and the next load
+ * signs in again.
+ * @see implements {@link CredentialStorage}
+ */
+export class SharedMemoryCredentialStorage implements CredentialStorage<ECDSAKeyIdentity> {
+  public readonly shared = true;
+  public readonly durable = false;
+
+  readonly #name: string;
+  readonly #channel: BroadcastChannel | undefined;
+
+  // On the instance and never on the module, so two clients on one page keep
+  // their own replicas and no state carries between tests in one process.
+  readonly #replica = new Map<string, Credential<ECDSAKeyIdentity>>();
+
+  // Held for this instance's life under a name only this instance uses, so a peer
+  // can wait for the grant that means this one is gone. The browser releases it
+  // when the document is torn down, which is the signal no message could carry.
+  readonly #id = crypto.randomUUID();
+  #releasePresence: (() => void) | undefined;
+
+  #announceOffer: (() => void) | undefined;
+
+  // Applying an incoming record is asynchronous, because a key handle and a chain
+  // have to be rebuilt from what crossed. Queued so they land in the order they
+  // arrived: a put applied after the drop that followed it would resurrect a slot
+  // its owner had already cleared.
+  #applying: Promise<void> = Promise.resolve();
+
+  /**
+   * Resolves once there is nothing left to wait for: a peer has answered, or
+   * every peer that existed when this instance started has gone.
+   *
+   * Reads await it, so the first one after a cold start sees what the other tabs
+   * hold rather than a miss. There is no deadline in it — waiting ends on a lock
+   * grant, and a lone instance waits not at all because there is no peer to hold
+   * one.
+   */
+  readonly #synced: Promise<void>;
+
+  /**
+   * @param options - The channel and lock prefix the tabs of this origin share.
+   */
+  constructor(options?: { name?: string }) {
+    this.#name = options?.name ?? DEFAULT_SHARED_MEMORY_NAME;
+    this.#channel =
+      typeof BroadcastChannel === 'undefined' ? undefined : new BroadcastChannel(this.#name);
+    this.#channel?.addEventListener('message', (event) => this.#receive(event.data));
+    this.#synced = this.#openReplica();
+  }
+
+  /**
+   * Stops replicating and lets go of the name a peer waits on.
+   *
+   * Only needed when you replace a store while the page lives; the document
+   * going away does the same thing.
+   */
+  public close(): void {
+    this.#channel?.close();
+    this.#releasePresence?.();
+    this.#releasePresence = undefined;
+  }
+
+  public create(): Promise<ECDSAKeyIdentity> {
+    return ECDSAKeyIdentity.generate({ extractable: false });
+  }
+
+  public async get(slot: string): Promise<Credential<ECDSAKeyIdentity> | null> {
+    await this.#synced;
+    // A read reflects everything received, not everything that has finished being
+    // rebuilt: applying is asynchronous, so a message already in hand would
+    // otherwise read as a miss and cost the caller a credential it had.
+    await this.#applying;
+    return this.#replica.get(slot) ?? null;
+  }
+
+  public async set(slot: string, credential: Credential<ECDSAKeyIdentity>): Promise<void> {
+    this.#replica.set(slot, credential);
+    this.#post({ kind: 'put', ...this.#toWire(slot, credential) });
+  }
+
+  public async remove(slot: string): Promise<void> {
+    this.#replica.delete(slot);
+    this.#post({ kind: 'drop', slot });
+  }
+
+  #presenceName(id: string): string {
+    return `${this.#name}:alive:${id}`;
+  }
+
+  /**
+   * Takes this instance's presence lock, then waits for the peers that already
+   * had one — asking them for what they hold.
+   */
+  async #openReplica(): Promise<void> {
+    const locks = globalThis.navigator?.locks;
+    if (locks === undefined || this.#channel === undefined) {
+      // Nothing can be enumerated and nothing can answer, so waiting could only
+      // cost a load. Every instance is alone, which is calls and not correctness.
+      return;
+    }
+
+    const peers = await this.#claimPresence(locks);
+    if (peers.length === 0) return;
+
+    const answered = new Promise<void>((resolve) => {
+      this.#announceOffer = resolve;
+    });
+
+    this.#post({ kind: 'ask' });
+
+    // A peer that answers ends the wait; a peer that dies without answering ends
+    // it too, because its lock is granted the moment the browser releases it. So
+    // the wait is bounded by the peers themselves rather than by a number.
+    const goneEverywhere = Promise.all(
+      peers.map((name) => locks.request(name, { mode: 'exclusive' }, () => undefined)),
+    );
+    await Promise.race([answered, goneEverywhere]);
+  }
+
+  /**
+   * Enumerates the peers holding a presence lock, then takes this instance's own.
+   *
+   * In that order: a snapshot taken after would include this instance, and it
+   * would then wait for a lock it holds itself and never be granted.
+   */
+  async #claimPresence(locks: LockManager): Promise<string[]> {
+    const mine = this.#presenceName(this.#id);
+    const prefix = `${this.#name}:alive:`;
+
+    let peers: string[] = [];
+    try {
+      const snapshot = await locks.query();
+      peers = (snapshot.held ?? [])
+        .map((lock) => lock.name)
+        .filter((name): name is string => name !== undefined && name !== mine)
+        .filter((name) => name.startsWith(prefix));
+    } catch {
+      // query() is not everywhere, and a caller cannot act on its absence. With
+      // no snapshot there is no peer to wait for, so this instance starts alone.
+    }
+
+    // Not awaited: the request resolves only when the lock is released, which is
+    // when this instance is done with it.
+    void locks
+      .request(mine, { mode: 'exclusive' }, () => {
+        return new Promise<void>((resolve) => {
+          this.#releasePresence = resolve;
+        });
+      })
+      .catch(() => undefined);
+
+    return peers;
+  }
+
+  #receive(data: unknown): void {
+    if (!isMessage(data)) return;
+
+    if (data.kind === 'ask') {
+      // Answered from what is queued as well as what has landed, so an instance
+      // asked while still applying an earlier message does not describe a state
+      // it is halfway out of.
+      this.#enqueue(() => {
+        const entries = [...this.#replica].map(([slot, credential]) =>
+          this.#toWire(slot, credential),
+        );
+        // Answered even when empty, because the asker is waiting on an answer and
+        // "I have nothing" is one. Staying silent would make it wait for this
+        // instance to close.
+        this.#post({ kind: 'offer', entries });
+      });
+      return;
+    }
+
+    this.#enqueue(async () => {
+      switch (data.kind) {
+        case 'offer':
+          for (const entry of data.entries) await this.#apply(entry, { overwrite: false });
+          // Last, so the answer is complete before anything waiting on it wakes.
+          this.#announceOffer?.();
+          this.#announceOffer = undefined;
+          return;
+        case 'put':
+          await this.#apply(data, { overwrite: true });
+          return;
+        case 'drop':
+          this.#replica.delete(data.slot);
+          return;
+      }
+    });
+  }
+
+  #enqueue(work: () => void | Promise<void>): void {
+    this.#applying = this.#applying.then(work).catch(() => undefined);
+  }
+
+  async #apply(entry: WireCredential, { overwrite }: { overwrite: boolean }): Promise<void> {
+    // An offer answers a question asked before anything local was written, so it
+    // fills gaps rather than replacing: a write that happened in the meantime is
+    // this instance's own and newer than the snapshot being described.
+    if (!overwrite && this.#replica.has(entry.slot)) return;
+
+    try {
+      const identity = await ECDSAKeyIdentity.fromKeyPair(entry.keyPair);
+      const chain = entry.chain === undefined ? undefined : DelegationChain.fromJSON(entry.chain);
+      this.#replica.set(entry.slot, { identity, chain });
+    } catch {
+      // A record from an incompatible version, or a handle this context cannot
+      // adopt. Holding nothing lets the reader acquire again.
+    }
+  }
+
+  #toWire(slot: string, credential: Credential<ECDSAKeyIdentity>): WireCredential {
+    return {
+      slot,
+      keyPair: credential.identity.getKeyPair(),
+      chain: credential.chain && JSON.stringify(credential.chain.toJSON()),
+    };
+  }
+
+  #post(message: Message): void {
+    try {
+      this.#channel?.postMessage(message);
+    } catch {
+      // A closed channel, or a payload this browser will not clone. The write has
+      // already landed in this instance's own replica, so the cost is a peer
+      // missing it and minting for itself.
+    }
+  }
+}

package/src/client/slots.ts

@@ -0,0 +1,78 @@
+/**
+ * Every name one client writes under, and the one thing that knows the whole set.
+ *
+ * Its own module rather than living beside the credential store or the state
+ * store, because it belongs to neither: the credentials and the state of a
+ * sign-in are named from one namespace, and a list that sat in either file would
+ * have to reach across to the other.
+ */
+
+/**
+ * The bare names, before a namespace is applied.
+ *
+ * One list, so a name cannot be added to some of the places that need it and
+ * missed in others. It was two lists and a hand-written mapping, and the state
+ * record was left out of the namespacing for exactly that reason.
+ */
+const SLOT_NAMES = {
+  /** The session's key and the chain issued to it. */
+  session: 'session',
+
+  /**
+   * Where a sign-in ceremony keeps its key until it returns.
+   *
+   * Its own name rather than {@link SLOT_NAMES.session}, so a ceremony that is
+   * cancelled or never comes back cannot take a working session with it.
+   */
+  sessionPending: 'session-pending',
+
+  /** The key an application signs with, and its delegation. */
+  app: 'app',
+
+  /**
+   * Where a ceremony keeps the credential it minted until its session is stored.
+   *
+   * The store reaches every tab of the origin, so writing to the app name during
+   * a ceremony — or clearing it first — would change what those tabs act with
+   * before the sign-in has succeeded. This is promoted instead, once there is a
+   * session behind it.
+   */
+  appPending: 'app-pending',
+
+  /**
+   * The record of who is signed in here and until when.
+   *
+   * Not a credential slot, and named here anyway: a namespace that moved the
+   * credentials and left this fixed would give two clients their own keys and one
+   * shared answer to who is signed in.
+   */
+  state: 'ic-session-state',
+} as const;
+
+/**
+ * What separates a namespace from the name it prefixes.
+ *
+ * A cross-origin contract rather than a detail: a sibling subdomain reads the
+ * state record by name, so both sides have to agree on this byte.
+ */
+const NAMESPACE_SEPARATOR = ':';
+
+/** Every name a client writes under, with its namespace already applied. */
+export type Slots = Record<keyof typeof SLOT_NAMES, string>;
+
+/**
+ * The names one client writes under, prefixed where a namespace is set.
+ *
+ * Assigned in one place rather than defaulted by each store: implementations
+ * choosing their own is what produced three colliding slots in the arrangement
+ * this replaces, and one assigner cannot collide with itself. A namespace moves
+ * all of them at once, so an application running two clients under one origin
+ * separates them with one string rather than renaming some and missing others.
+ * @param namespace - Prefix for every name, or `undefined` for the bare ones.
+ */
+export function slotsFor(namespace?: string): Slots {
+  const prefix = namespace === undefined ? '' : `${namespace}${NAMESPACE_SEPARATOR}`;
+  return Object.fromEntries(
+    Object.entries(SLOT_NAMES).map(([key, name]) => [key, `${prefix}${name}`]),
+  ) as Slots;
+}