dcp/identity

Identity is a newer session/login system for associating a Keystore with the running application, gradually superseding the parts of the Wallet API that deal with wallet.getId(). It layers OAuth-style login, session recovery across page loads, and reduced-privilege proxy keys on top of the same underlying Keystore objects.

Note

This module works on both browser and non-browser (Node.js, etc.) platforms, but login() behaves quite differently on each: in a browser it runs an OAuth-style redirect flow through the auth server; elsewhere, since there’s no UI to redirect through, it falls back to whatever setDefault() was given, a keystore file on disk, or a freshly-generated identity. See login() for the details.

Functions

• Functions
  • check
  • get
  • getActiveSession
  • login
  • logout
  • normalizePxRequest
  • requestProxyKey
  • set
  • setDefault
  • waitForSession

Classes

• Classes
  • KsCollection

Sessions and Contexts

Two internal classes do the heavy lifting behind the functions on this page; you won’t normally construct either one directly, but understanding them helps explain what login()/logout()/set() are actually doing.

• AuthContext represents everything this browser knows about one DCP identity, persisted in localStorage on the auth server’s own origin (“d9ve”). It’s created the first time a user authenticates (uploads a keystore, or completes an OAuth login), and can outlive any individual session – the keystore it holds may itself be a proxy (a reduced-privilege key obtained via requestProxyKey()) rather than a root key.

• DistributiveSession represents one login session in the current (usually third-party) origin: an opaque session id plus (once login completes) an IdKeystore. Sessions are exchanged between origins via a hidden iframe and postMessage, not by handing over the private key directly – the third-party origin ends up with a proxy key scoped to whatever permissions it originally requested (see login()).

The practical flow for a third-party application is: call login(), which either resolves quickly (an existing session was recovered from storage) or redirects the page through the auth origin’s authenticate/authorize pages and back. Either way, once it resolves, get()/check()/getActiveSession() reflect the logged-in identity.

Events

identity is itself an EventEmitter. Handlers are attached the usual way, for example, identity.on('set', (keystore) => { ... }).

• set - emitted with the new IdKeystore when an identity is first attached to the active session (from set(), login(), or session recovery).

• session - emitted with the active DistributiveSession whenever a session becomes active (see activateSession(), an internal building block used by login() and session recovery).

• clearSession - emitted with the (about-to-be-cleared) active session when logout() runs.

• busy / unbusy - UI hints, emitted around network requests made by login()/logout()/requestProxyKey().

Other exports

• IdKeystore, Address, PrivateKey - convenience re-exports of the same classes from dcp/wallet.

• KVIN - a KVIN instance pre-configured with Address/Keystore user constructors, used internally to (de)serialize sessions for postMessage/storage.

• interactive (boolean) - Whether the current process can prompt a human for input (always true in a browser or under PythonMonkey; on plain Node.js, true only if stdin is a TTY). Used internally to decide whether it’s reasonable to fall back to an interactive flow versus failing outright.

• pxa - a re-export of the dcp/pxa module, the canonical source of proxy-key operation names (identity.pxa.operations, etc.) used when building a pxRequest for login()/requestProxyKey().

• masquerade(uniqueString, pxRequest, options) / forceLogin(id) - lower-level, specialized session-activation helpers (generating a deterministic pseudo-identity from a base identity, and bypassing the login flow entirely with a known keystore, respectively). Most applications should use login()/set() instead.