@pryv/delegation 3.11.0

package/README.md

@@ -0,0 +1,166 @@
+# Account-delegation client helpers for `pryv`
+
+Account-delegation client-side helpers for the [Pryv JavaScript library](https://github.com/pryv/lib-js). Delegation lets one account (the **delegate**, "A") act on behalf of another (the **controlled** account, "B") through a delegate personal-access token (PAT) minted on B — for example a parent running a child's account, or a co-guardian added to an existing one. It is backed by the open-pryv.io `delegation` plugin (`delegations.*` API family).
+
+
+## Usage
+
+`@pryv/delegation` is a **sibling package** to `pryv` — imported separately, not attached to the `pryv` namespace. It uses a standard personal `pryv.Connection` to talk to the server.
+
+
+### Importing
+
+#### NPM
+
+`npm install --save pryv @pryv/delegation`, then in your code:
+
+```js
+const pryv = require('pryv');
+const { Delegation } = require('@pryv/delegation');
+```
+
+`@pryv/delegation` requires `pryv@^3.3.0` as a peer dependency.
+
+#### `<script>` tag
+
+`pryv-delegation.js` must be loaded **after** `pryv.js`. In browser bundles, pass the `pryv` module explicitly (needed by `openControlled`, which constructs a `Connection`):
+
+```js
+const delegation = Delegation.fromConnection(conn, { pryv: window.pryv });
+```
+
+
+## Concepts
+
+A delegation relationship has two sides:
+
+- **B — the controlled account.** Invites a delegate (`requestAttach`), lists its delegates (`listDelegates`), and is the **only** party that can authoritatively remove one (`detachDelegate`). Teardown requires a **genuine login** on B (see below).
+- **A — the delegate.** Accepts or refuses an invite (`acceptAttach` / `refuseAttach`), lists the accounts it controls (`listControlled`), mints a token for one (`getToken` / `openControlled`), and can create brand-new controlled accounts (`createAccount`).
+
+Every method maps to exactly one `delegations.*` API method, issued over the connection's batch call.
+
+
+## Surface
+
+Construct a client by wrapping a personal `pryv.Connection`:
+
+```js
+const delegation = Delegation.fromConnection(conn);
+```
+
+### B side (the controlled account)
+
+```js
+// Invite a delegate. Returns the pending invite record.
+const invite = await delegation.requestAttach('parent-b');
+// invite = { relId, delegate: { username }, status: 'invite', requestedAt, expiresAt }
+
+// List your delegates (status: 'invite' | 'active').
+const delegates = await delegation.listDelegates();
+// [ { relId, delegate: { username, hostSlug }, status, requestedAt, activatedAt?, lastTokenIssuedAt? } ]
+
+// Cancel a pending invite you issued (genuine-login-gated, see below).
+await delegation.cancelInvite('parent-b');
+
+// Remove a delegate — the authoritative teardown (genuine-login-gated).
+await delegation.detachDelegate('parent-b');
+```
+
+### A side (the delegate)
+
+```js
+// Accept / refuse an invite you received.
+const rel = await delegation.acceptAttach('kid-account');
+// rel = { relId, controlled: { username }, status: 'active', activatedAt }
+await delegation.refuseAttach('kid-account');
+
+// List the accounts you control (status: 'invite' | 'active' | 'stale').
+const controlled = await delegation.listControlled();
+// [ { relId, controlled: { username, hostSlug }, status, requestedAt, activatedAt? } ]
+
+// Dismiss a local 'stale' mirror (housekeeping — removes no authority).
+await delegation.dismissControlled('old-account');
+
+// Mint a delegate token for a controlled account.
+const { token, apiEndpoint } = await delegation.getToken('kid-account');
+
+// One-call "act as the controlled account": get a ready Connection onto B.
+const kidConn = await delegation.openControlled('kid-account');
+const events = await kidConn.apiOne('events.get', { limit: 20 }, 'events');
+
+// Create a brand-new controlled account, active at birth.
+const created = await delegation.createAccount({
+  username: 'kid-account',
+  email: 'guardian+kid@example.com', // optional
+  password: 'a-strong-password',     // optional (random if omitted)
+  core: 'core-2'                     // optional target core (default: your own)
+});
+// created = { delegation: { relId, controlled: { username, hostSlug }, status: 'active', activatedAt }, apiEndpoint? }
+```
+
+`createAccount` with **no** `email`/`password` yields an account reachable only through delegates until a delegate sets a password.
+
+
+## Detach requires a genuine login on B
+
+`detachDelegate` and `cancelInvite` remove a delegation relationship, so they require the account owner to be **genuinely logged in** to the controlled account — a delegate PAT or a control token is rejected. A delegated session therefore cannot walk away with, or tear down, the relationship on its own.
+
+The rejection surfaces as a typed [`DelegationError`](#typed-errors) with `id === delegationErrorIds.GENUINE_LOGIN_REQUIRED`. Surface it distinctly in your UI:
+
+```js
+const { errorIds: delegationErrorIds } = require('@pryv/delegation');
+
+try {
+  await delegation.detachDelegate('parent-b');
+} catch (err) {
+  if (err.id === delegationErrorIds.GENUINE_LOGIN_REQUIRED) {
+    // Prompt the account owner to sign in directly (not via a delegated
+    // session) before retrying the detach.
+  } else {
+    throw err;
+  }
+}
+```
+
+
+## Typed errors
+
+When a `delegations.*` call rejects with a `delegation-*` id, the method throws a `DelegationError` whose `.id` is one of `errorIds` (a stable, kebab-case mirror of the server-side catalogue). Match on the constant instead of parsing `error.message`. Non-delegation errors (transport, validation, auth) propagate unchanged.
+
+```js
+const { DelegationError, errorIds } = require('@pryv/delegation');
+```
+
+| Constant | String | When |
+|---|---|---|
+| `GENUINE_LOGIN_REQUIRED` | `delegation-genuine-login-required` | `detachDelegate` / `cancelInvite` called without a genuine B login. |
+| `NOT_ACTIVE` | `delegation-not-active` | `getToken` on a torn-down / non-active relationship (mirror flips to `stale`). |
+| `NOT_FOUND` | `delegation-not-found` | No relationship for the given username. |
+| `ALREADY_EXISTS` | `delegation-already-exists` | `requestAttach` duplicates an existing invite/relationship. |
+| `UNKNOWN_USERNAME` | `delegation-unknown-username` | The target username does not resolve to an account. |
+| `SELF_NOT_ALLOWED` | `delegation-self-not-allowed` | An account may not delegate to itself. |
+| `INVITE_EXPIRED` | `delegation-invite-expired` | `acceptAttach` on an expired invite. |
+| `USERNAME_TAKEN` | `delegation-username-taken` | `createAccount` username already claimed. |
+| `UNKNOWN_CORE` | `delegation-unknown-core` | `createAccount` target `core` not known to the platform. |
+| `CREATION_FAILED` | `delegation-creation-failed` | Account creation failed (rolled back). |
+| `DELIVERY_FAILED` | `delegation-delivery-failed` | Cross-core delivery to the counterparty core failed. |
+| `MIRROR_NOT_STALE` | `delegation-mirror-not-stale` | `dismissControlled` on a mirror that is not `stale`. |
+| `PERSONAL_TOKEN_REQUIRED` | `delegation-personal-token-required` | A personal token was required but an app/shared token was used. |
+| `DELEGATE_MISMATCH` | `delegation-delegate-mismatch` | Delegate identity does not match the recorded relationship. |
+
+The `STATUS` export mirrors the relationship-status enum used in list entries: `STATUS.INVITE`, `STATUS.ACTIVE`, `STATUS.STALE`.
+
+
+## Example
+
+See [`examples/delegation-usage.js`](examples/delegation-usage.js) for a runnable end-to-end sample (parent creates a child account, mints a token, acts as the child, then detaches).
+
+
+## Contributing
+
+See the [Pryv JavaScript library README](https://github.com/pryv/lib-js#contributing)
+
+
+## License
+
+[BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)

package/examples/delegation-usage.js

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * @pryv/delegation — end-to-end usage example.
+ *
+ * A guardian ("A") creates a controlled account for a child ("B"), acts on
+ * that account through a delegate token, then tears the relationship down.
+ * Run with a real personal API endpoint:
+ *
+ *   node delegation-usage.js 'https://<token>@<username>.pryv.me/'
+ *
+ * The token must be a PERSONAL access token on the guardian's account.
+ */
+
+const pryv = require('pryv');
+const { Delegation, errorIds } = require('@pryv/delegation');
+
+async function main () {
+  const guardianApiEndpoint = process.argv[2];
+  if (guardianApiEndpoint == null) {
+    console.error('Usage: node delegation-usage.js <guardian personal apiEndpoint>');
+    process.exit(1);
+  }
+
+  const guardianConn = new pryv.Connection(guardianApiEndpoint);
+  const delegation = Delegation.fromConnection(guardianConn);
+
+  // 1. Create a brand-new controlled account (active at birth). Omit the
+  //    password to make it reachable only through delegates.
+  const childUsername = 'kid-' + Date.now();
+  const created = await delegation.createAccount({ username: childUsername });
+  console.log('created controlled account:', created.delegation.controlled.username,
+    '(status:', created.delegation.status + ')');
+
+  // 2. List the accounts we control.
+  const controlled = await delegation.listControlled();
+  console.log('controlled accounts:', controlled.map((c) => c.controlled.username + ' [' + c.status + ']'));
+
+  // 3. Act as the child account in one call — a ready Connection onto B.
+  const childConn = await delegation.openControlled(childUsername);
+  const created2 = await childConn.apiOne('events.create', {
+    streamIds: ['diary'],
+    type: 'note/txt',
+    content: 'first note, written by the guardian on the child account'
+  }, 'event');
+  console.log('wrote event on the child account:', created2.id);
+
+  // 4. (Optional) Add a co-guardian by inviting another account as a delegate.
+  //    Uncomment with a real second username:
+  // const invite = await delegation.requestAttach('other-parent');
+  // console.log('invited co-guardian, invite expires at', invite.expiresAt);
+
+  // 5. Detach requires a GENUINE login on the controlled account. From this
+  //    guardian (delegate) connection it is refused — surface it distinctly.
+  try {
+    await delegation.detachDelegate('other-parent');
+  } catch (err) {
+    if (err.id === errorIds.GENUINE_LOGIN_REQUIRED) {
+      console.log('detach refused: the account owner must log in directly to remove a delegate');
+    } else if (err.id === errorIds.NOT_FOUND) {
+      console.log('detach: no such delegate (expected in this sample)');
+    } else {
+      throw err;
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('delegation example failed:', err.id || '', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@pryv/delegation",
+  "version": "3.11.0",
+  "description": "Account-delegation client helpers for Pryv.io",
+  "keywords": [
+    "Pryv",
+    "Pryv.io",
+    "Delegation",
+    "Account",
+    "Guardian"
+  ],
+  "homepage": "https://github.com/pryv/lib-js/tree/master/components/pryv-delegation#readme",
+  "bugs": {
+    "url": "https://github.com/pryv/lib-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/pryv/lib-js.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Pryv <info@pryv.com> (https://pryv.com)",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "pryv": "^3.3.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,149 @@
+declare module '@pryv/delegation' {
+  // --- Relationship status ---
+  export type RelationshipStatus = 'invite' | 'active' | 'stale';
+
+  export const STATUS: {
+    readonly INVITE: 'invite';
+    readonly ACTIVE: 'active';
+    readonly STALE: 'stale';
+  };
+
+  // --- Error catalogue ---
+  export type DelegationErrorId =
+    | 'delegation-clientdata-forbidden'
+    | 'delegation-managed-resource'
+    | 'delegation-reserved-stream'
+    | 'delegation-unknown-username'
+    | 'delegation-self-not-allowed'
+    | 'delegation-delegate-mismatch'
+    | 'delegation-already-exists'
+    | 'delegation-delivery-failed'
+    | 'delegation-genuine-login-required'
+    | 'delegation-not-found'
+    | 'delegation-invite-expired'
+    | 'delegation-not-active'
+    | 'delegation-username-taken'
+    | 'delegation-unknown-core'
+    | 'delegation-creation-failed'
+    | 'delegation-personal-token-required'
+    | 'delegation-mirror-not-stale';
+
+  export const errorIds: {
+    readonly CLIENTDATA_FORBIDDEN: 'delegation-clientdata-forbidden';
+    readonly MANAGED_RESOURCE: 'delegation-managed-resource';
+    readonly RESERVED_STREAM: 'delegation-reserved-stream';
+    readonly UNKNOWN_USERNAME: 'delegation-unknown-username';
+    readonly SELF_NOT_ALLOWED: 'delegation-self-not-allowed';
+    readonly DELEGATE_MISMATCH: 'delegation-delegate-mismatch';
+    readonly ALREADY_EXISTS: 'delegation-already-exists';
+    readonly DELIVERY_FAILED: 'delegation-delivery-failed';
+    readonly GENUINE_LOGIN_REQUIRED: 'delegation-genuine-login-required';
+    readonly NOT_FOUND: 'delegation-not-found';
+    readonly INVITE_EXPIRED: 'delegation-invite-expired';
+    readonly NOT_ACTIVE: 'delegation-not-active';
+    readonly USERNAME_TAKEN: 'delegation-username-taken';
+    readonly UNKNOWN_CORE: 'delegation-unknown-core';
+    readonly CREATION_FAILED: 'delegation-creation-failed';
+    readonly PERSONAL_TOKEN_REQUIRED: 'delegation-personal-token-required';
+    readonly MIRROR_NOT_STALE: 'delegation-mirror-not-stale';
+  };
+
+  /** Typed delegation failure surfaced by {@link Delegation} methods. */
+  export class DelegationError extends Error {
+    constructor(message: string, id: DelegationErrorId | string, cause?: any, data?: any);
+    readonly name: 'DelegationError';
+    readonly id: DelegationErrorId | string;
+    readonly cause?: any;
+    readonly data?: any;
+  }
+
+  // --- Records ---
+
+  export type DelegateIdentity = {
+    username: string;
+    /** Host with `.` replaced by `-`. */
+    hostSlug: string;
+  };
+
+  /** An entry of `listDelegates()` (B side). */
+  export type DelegateRecord = {
+    relId: string;
+    delegate: DelegateIdentity;
+    status: RelationshipStatus;
+    requestedAt: number;
+    activatedAt?: number | null;
+    lastTokenIssuedAt?: number | null;
+  };
+
+  /** An entry of `listControlled()` (A side). */
+  export type ControlledRecord = {
+    relId: string;
+    controlled: DelegateIdentity;
+    status: RelationshipStatus;
+    requestedAt: number;
+    activatedAt?: number | null;
+  };
+
+  /**
+   * The `delegation` record returned by `requestAttach` / `acceptAttach` /
+   * `createAccount`. Shape varies by call: an invite carries `delegate` +
+   * `expiresAt`; an activation carries `controlled` + `activatedAt`.
+   */
+  export type DelegationRecord = {
+    relId: string;
+    status: RelationshipStatus;
+    delegate?: { username: string; hostSlug?: string };
+    controlled?: { username: string; hostSlug?: string };
+    requestedAt?: number;
+    expiresAt?: number;
+    activatedAt?: number;
+  };
+
+  export type TokenResult = {
+    token: string;
+    apiEndpoint: string;
+  };
+
+  export type CreateAccountParams = {
+    username: string;
+    email?: string;
+    password?: string;
+    core?: string;
+    language?: string;
+  };
+
+  export type CreateAccountResult = {
+    delegation: DelegationRecord;
+    apiEndpoint?: string;
+  };
+
+  export type DelegationOptions = {
+    /** Explicit `pryv` module (needed by `openControlled` in browser bundles). */
+    pryv?: any;
+  };
+
+  /**
+   * Client for the `delegations.*` API family, bound to one personal
+   * `pryv.Connection`.
+   */
+  export class Delegation {
+    constructor(connection: any, opts?: DelegationOptions);
+    static fromConnection(connection: any, opts?: DelegationOptions): Delegation;
+    readonly connection: any;
+
+    // B side (the controlled account)
+    requestAttach(delegateUsername: string): Promise<DelegationRecord>;
+    cancelInvite(delegateUsername: string): Promise<void>;
+    listDelegates(): Promise<DelegateRecord[]>;
+    detachDelegate(delegateUsername: string): Promise<void>;
+
+    // A side (the delegate)
+    acceptAttach(controlledUsername: string): Promise<DelegationRecord>;
+    refuseAttach(controlledUsername: string): Promise<void>;
+    listControlled(): Promise<ControlledRecord[]>;
+    dismissControlled(controlledUsername: string): Promise<void>;
+    getToken(controlledUsername: string): Promise<TokenResult>;
+    openControlled(controlledUsername: string): Promise<any>;
+    createAccount(params: CreateAccountParams): Promise<CreateAccountResult>;
+  }
+}

package/src/index.js

@@ -0,0 +1,364 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * @pryv/delegation — account-delegation client helpers.
+ *
+ * Thin, typed wrapper over a personal `pryv.Connection` for the server-side
+ * `delegations.*` API family (open-pryv.io `delegation` plugin). Account
+ * delegation lets one account (the "delegate", A) act on behalf of another
+ * (the "controlled" account, B) through a delegate personal-access token (PAT)
+ * minted on B — e.g. a parent running a child's account, or a co-guardian
+ * added to an existing one.
+ *
+ * Two sides of one relationship:
+ *   - B (the controlled account) invites a delegate, and is the ONLY party
+ *     that can authoritatively detach one (genuine login required).
+ *   - A (the delegate) accepts/refuses the invite, lists the accounts it
+ *     controls, mints a token for one, and can create brand-new controlled
+ *     accounts.
+ *
+ * Every method here maps to exactly one `delegations.*` API method, issued
+ * through `connection.apiOne(...)` (batch call). Errors carrying a
+ * `delegation-*` id surface as a typed {@link DelegationError} whose `.id`
+ * matches one of {@link errorIds}, so callers branch on a stable constant
+ * instead of parsing English `error.message`.
+ *
+ * See server-side `open-pryv.io/components/delegation/` +
+ * `components/api-server/src/{routes,methods}/delegations.ts`.
+ */
+
+// --- Relationship status ---------------------------------------------------
+// Mirrors the server `STATUS` enum (components/delegation/src/constants.ts).
+// `listDelegates()` / `listControlled()` entries carry one of these.
+const STATUS = Object.freeze({
+  /** A pending invite: sent (B side) / received (A side), not yet accepted. */
+  INVITE: 'invite',
+  /** An active relationship: the delegate holds (or can mint) a live PAT. */
+  ACTIVE: 'active',
+  /**
+   * A's local mirror discovered the relationship was torn down on B (a token
+   * mint answered 401/403). Advisory only — carries no authority; the row is
+   * user-dismissable via `dismissControlled(...)`.
+   */
+  STALE: 'stale'
+});
+
+// --- Typed error catalogue -------------------------------------------------
+// Mirror of the server-side DelegationErrorIds
+// (components/delegation/src/errorIds.ts). Match on these constants when a
+// `delegations.*` call rejects, instead of parsing `error.message`.
+const errorIds = Object.freeze({
+  // Guard hooks (a generic accesses/events/streams write hit a plugin-owned
+  // namespace — should not occur through this client, surfaced for safety).
+  CLIENTDATA_FORBIDDEN: 'delegation-clientdata-forbidden',
+  MANAGED_RESOURCE: 'delegation-managed-resource',
+  RESERVED_STREAM: 'delegation-reserved-stream',
+  // Handshake / lifecycle.
+  UNKNOWN_USERNAME: 'delegation-unknown-username',
+  SELF_NOT_ALLOWED: 'delegation-self-not-allowed',
+  DELEGATE_MISMATCH: 'delegation-delegate-mismatch',
+  ALREADY_EXISTS: 'delegation-already-exists',
+  DELIVERY_FAILED: 'delegation-delivery-failed',
+  /**
+   * The operation (detach / cancel) requires a genuine, freshly-authenticated
+   * login on the controlled account — a delegate PAT or control token cannot
+   * remove a delegation relationship. The UI must prompt the account owner to
+   * log in directly before retrying.
+   */
+  GENUINE_LOGIN_REQUIRED: 'delegation-genuine-login-required',
+  NOT_FOUND: 'delegation-not-found',
+  INVITE_EXPIRED: 'delegation-invite-expired',
+  NOT_ACTIVE: 'delegation-not-active',
+  USERNAME_TAKEN: 'delegation-username-taken',
+  UNKNOWN_CORE: 'delegation-unknown-core',
+  CREATION_FAILED: 'delegation-creation-failed',
+  PERSONAL_TOKEN_REQUIRED: 'delegation-personal-token-required',
+  MIRROR_NOT_STALE: 'delegation-mirror-not-stale'
+});
+
+const DELEGATION_ID_VALUES = new Set(Object.values(errorIds));
+
+/**
+ * Typed error surfaced by {@link Delegation} methods when a `delegations.*`
+ * call rejects with a `delegation-*` id. `id` is the stable kebab-case string
+ * (one of {@link errorIds}); `cause` is the underlying `pryv` error; `data`
+ * is the server error's `data` payload when present.
+ */
+class DelegationError extends Error {
+  constructor (message, id, cause, data) {
+    super(message);
+    this.name = 'DelegationError';
+    this.id = id;
+    if (cause !== undefined) this.cause = cause;
+    if (data !== undefined) this.data = data;
+  }
+}
+
+/**
+ * Extract a Pryv API `error.id` from a thrown error, across the shapes the
+ * `pryv` client uses. `connection.apiOne` throws a `PryvError` whose
+ * `innerObject` is the batch call's `error` object (`{ id, message, data }`);
+ * `PryvError.fromApiResponse` sets `.id` / `.response` directly. Check all.
+ */
+function errorIdFrom (err) {
+  if (err == null) return null;
+  if (typeof err.id === 'string') return err.id;
+  const inner = err.innerObject;
+  if (inner != null) {
+    if (typeof inner.id === 'string') return inner.id;
+    if (inner.error != null && typeof inner.error.id === 'string') return inner.error.id;
+  }
+  const resp = err.response;
+  if (resp != null && resp.body != null && resp.body.error != null && typeof resp.body.error.id === 'string') {
+    return resp.body.error.id;
+  }
+  return null;
+}
+
+/** Pull the server error `data` payload from a thrown `pryv` error, if any. */
+function errorDataFrom (err) {
+  if (err == null) return undefined;
+  const inner = err.innerObject;
+  if (inner != null) {
+    if (inner.data !== undefined) return inner.data;
+    if (inner.error != null && inner.error.data !== undefined) return inner.error.data;
+  }
+  const resp = err.response;
+  if (resp != null && resp.body != null && resp.body.error != null) return resp.body.error.data;
+  return undefined;
+}
+
+/**
+ * Map a thrown `pryv` error to a {@link DelegationError} when it carries a
+ * `delegation-*` id; otherwise return it unchanged so transport / validation
+ * errors propagate as-is.
+ */
+function toDelegationError (err) {
+  const id = errorIdFrom(err);
+  if (id != null && (DELEGATION_ID_VALUES.has(id) || id.startsWith('delegation-'))) {
+    const message = (err && err.message) || id;
+    return new DelegationError(message, id, err, errorDataFrom(err));
+  }
+  return err;
+}
+
+/**
+ * Client for the `delegations.*` API family, bound to one personal
+ * `pryv.Connection`. Construct via {@link Delegation.fromConnection}.
+ */
+class Delegation {
+  /**
+   * @param {Object} connection  a personal `pryv.Connection`.
+   * @param {Object} [opts]
+   * @param {Object} [opts.pryv]  explicit `pryv` module (otherwise resolved
+   *   via `require('pryv')`; pass it in browser bundles where `require` is
+   *   unavailable — needed only by `openControlled`).
+   */
+  constructor (connection, opts) {
+    if (connection == null) throw new Error('Delegation: a pryv.Connection is required');
+    this.connection = connection;
+    this._pryvModule = (opts && opts.pryv) || null;
+  }
+
+  /**
+   * Wrap a personal `pryv.Connection` in a {@link Delegation} client.
+   * @param {Object} connection  a personal `pryv.Connection`.
+   * @param {Object} [opts]  see the constructor.
+   * @returns {Delegation}
+   */
+  static fromConnection (connection, opts) {
+    return new Delegation(connection, opts);
+  }
+
+  /** @private Resolve the `pryv` module (explicit opt or lazy require). */
+  _getPryv () {
+    if (this._pryvModule != null) return this._pryvModule;
+    this._pryvModule = require('pryv');
+    return this._pryvModule;
+  }
+
+  /** @private One batch call, remapping `delegation-*` errors to DelegationError. */
+  async _apiOne (method, params, expectedKey) {
+    try {
+      return await this.connection.apiOne(method, params || {}, expectedKey);
+    } catch (err) {
+      throw toDelegationError(err);
+    }
+  }
+
+  // ---- B side (the controlled account) ----------------------------------
+
+  /**
+   * B invites a delegate. `POST /delegations/attach-request`.
+   * A delegate PAT acting as B MAY call this (that is how a delegate adds a
+   * co-delegate).
+   *
+   * @param {string} delegateUsername  the account to invite as delegate.
+   * @returns {Promise<DelegationRecord>} the pending invite record
+   *   `{ relId, delegate:{username}, status:'invite', requestedAt, expiresAt }`.
+   */
+  async requestAttach (delegateUsername) {
+    return await this._apiOne('delegations.requestAttach', { delegateUsername }, 'delegation');
+  }
+
+  /**
+   * B cancels a pending invite it issued. `POST /delegations/delegates/{username}/cancel`.
+   * Genuine-login-gated on B (a delegate PAT cannot cancel B's invites) →
+   * may throw {@link DelegationError} `delegation-genuine-login-required`.
+   *
+   * @param {string} delegateUsername  the invited delegate to cancel.
+   * @returns {Promise<void>}
+   */
+  async cancelInvite (delegateUsername) {
+    await this._apiOne('delegations.cancelInvite', { username: delegateUsername });
+  }
+
+  /**
+   * List the delegates of the connected (B) account. `GET /delegations/delegates`.
+   *
+   * @returns {Promise<DelegateRecord[]>} each `{ relId, delegate:{username,
+   *   hostSlug}, status, requestedAt, activatedAt?, lastTokenIssuedAt? }`.
+   */
+  async listDelegates () {
+    return await this._apiOne('delegations.listDelegates', {}, 'delegates');
+  }
+
+  /**
+   * B detaches a delegate — THE authoritative teardown. `DELETE
+   * /delegations/delegates/{username}`. Removes the delegate's PAT + all
+   * marker accesses on B (active), or cancels the pending invite.
+   *
+   * **Requires a genuine login on B.** A delegate PAT or control token is
+   * rejected with {@link DelegationError} `delegation-genuine-login-required`
+   * — surface it distinctly so the UI can explain the account owner must log
+   * in directly (not through a delegated session) to remove a delegate.
+   *
+   * @param {string} delegateUsername  the delegate to detach.
+   * @returns {Promise<void>}
+   */
+  async detachDelegate (delegateUsername) {
+    await this._apiOne('delegations.detachDelegate', { username: delegateUsername });
+  }
+
+  // ---- A side (the delegate) --------------------------------------------
+
+  /**
+   * A accepts a pending invite from a controlled account.
+   * `POST /delegations/controlled/{username}/accept`.
+   *
+   * @param {string} controlledUsername  the inviting account.
+   * @returns {Promise<DelegationRecord>} `{ relId, controlled:{username},
+   *   status:'active', activatedAt }`.
+   */
+  async acceptAttach (controlledUsername) {
+    return await this._apiOne('delegations.acceptAttach', { username: controlledUsername }, 'delegation');
+  }
+
+  /**
+   * A refuses a pending invite. `POST /delegations/controlled/{username}/refuse`.
+   * A unilateral decline (not a detach) — gated on A's personal token.
+   *
+   * @param {string} controlledUsername  the inviting account.
+   * @returns {Promise<void>}
+   */
+  async refuseAttach (controlledUsername) {
+    await this._apiOne('delegations.refuseAttach', { username: controlledUsername });
+  }
+
+  /**
+   * List the accounts the connected (A) account controls.
+   * `GET /delegations/controlled`.
+   *
+   * @returns {Promise<ControlledRecord[]>} each `{ relId, controlled:{username,
+   *   hostSlug}, status, requestedAt, activatedAt? }`. `status` may be
+   *   `'stale'` — see {@link dismissControlled}.
+   */
+  async listControlled () {
+    return await this._apiOne('delegations.listControlled', {}, 'controlled');
+  }
+
+  /**
+   * A dismisses a local `stale` mirror row (housekeeping). `DELETE
+   * /delegations/controlled/{username}`. Removes no authority and never
+   * touches B; rejects a non-stale mirror with `delegation-mirror-not-stale`.
+   *
+   * @param {string} controlledUsername  the stale controlled account to drop.
+   * @returns {Promise<void>}
+   */
+  async dismissControlled (controlledUsername) {
+    await this._apiOne('delegations.dismissControlled', { username: controlledUsername });
+  }
+
+  /**
+   * A mints (or refreshes) a delegate PAT for an active controlled account.
+   * `POST /delegations/controlled/{username}/token`. On a torn-down
+   * relationship the mirror flips to `stale` and this throws
+   * {@link DelegationError} `delegation-not-active`.
+   *
+   * @param {string} controlledUsername  the controlled account.
+   * @returns {Promise<{token: string, apiEndpoint: string}>} the delegate PAT
+   *   and the controlled account's API base — use them to talk to B directly.
+   */
+  async getToken (controlledUsername) {
+    const res = await this._apiOne('delegations.getToken', { username: controlledUsername });
+    return { token: res.token, apiEndpoint: res.apiEndpoint };
+  }
+
+  /**
+   * One-call "act as the controlled account": mint a token and return a ready
+   * `pryv.Connection` onto the controlled account (B).
+   *
+   * Composes {@link getToken} + connection construction. Needs the `pryv`
+   * module — resolved via `require('pryv')` in Node, or the `opts.pryv` passed
+   * to {@link Delegation.fromConnection} in a browser bundle.
+   *
+   * @param {string} controlledUsername  the controlled account.
+   * @returns {Promise<Object>} a `pryv.Connection` authenticated as B.
+   */
+  async openControlled (controlledUsername) {
+    const { token, apiEndpoint } = await this.getToken(controlledUsername);
+    const pryv = this._getPryv();
+    // getToken returns the token + the controlled core's API base separately;
+    // fold them into one token-bearing apiEndpoint the Connection accepts.
+    const { endpoint } = pryv.utils.extractTokenAndAPIEndpoint(apiEndpoint);
+    const fullApiEndpoint = pryv.utils.buildAPIEndpoint({ endpoint, token });
+    return new pryv.Connection(fullApiEndpoint);
+  }
+
+  /**
+   * A creates a brand-new controlled account, active at birth.
+   * `POST /delegations/controlled`. `email` / `password` are optional — a
+   * password-less account is reachable only through delegates until one sets
+   * a password. `core` picks the target core (default = A's own).
+   *
+   * @param {Object} params
+   * @param {string} params.username   the new account's username.
+   * @param {string} [params.email]    optional email.
+   * @param {string} [params.password] optional password (random if omitted).
+   * @param {string} [params.core]     optional target core (id or URL).
+   * @param {string} [params.language] optional preferred language.
+   * @returns {Promise<{delegation: DelegationRecord, apiEndpoint?: string}>}
+   */
+  async createAccount (params) {
+    if (params == null || typeof params.username !== 'string' || params.username.length === 0) {
+      throw new Error('createAccount: params.username is required');
+    }
+    const body = { username: params.username };
+    if (params.email !== undefined) body.email = params.email;
+    if (params.password !== undefined) body.password = params.password;
+    if (params.core !== undefined) body.core = params.core;
+    if (params.language !== undefined) body.language = params.language;
+    const res = await this._apiOne('delegations.createAccount', body);
+    return { delegation: res.delegation, apiEndpoint: res.apiEndpoint };
+  }
+}
+
+module.exports = {
+  Delegation,
+  DelegationError,
+  errorIds,
+  STATUS
+};

package/test/delegation.test.js

@@ -0,0 +1,386 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, expect */
+
+const pryv = require('pryv');
+const delegation = require('../src');
+const { Delegation, DelegationError, errorIds, STATUS } = delegation;
+
+/**
+ * Stub Connection — records (method, params, expectedKey) calls and replays
+ * canned responses from a per-method handler. Mirrors enough of the real
+ * `pryv.Connection.apiOne` surface for unit tests:
+ *   apiOne(method, params, expectedKey) → result[expectedKey] (or full result)
+ *
+ * A handler may return `{ __error: { id, message, data } }` to simulate the
+ * real client's throw shape: `apiOne` rejects with a PryvError-like error
+ * whose `innerObject` is the batch call's `error` object.
+ */
+function makeStubConnection (options) {
+  options = options || {};
+  const handlers = options.handlers || {};
+  const calls = [];
+  return {
+    calls,
+    async apiOne (method, params, expectedKey) {
+      calls.push({ method, params, expectedKey });
+      const handler = handlers[method];
+      if (handler == null) {
+        throw new Error('stubConnection: no handler for method "' + method + '"');
+      }
+      const result = typeof handler === 'function' ? await handler(params, calls.length - 1) : handler;
+      if (result && result.__error) {
+        const e = new Error(result.__error.message || 'api error');
+        e.innerObject = result.__error;
+        throw e;
+      }
+      if (expectedKey != null) {
+        if (result == null || result[expectedKey] == null) {
+          throw new Error('stubConnection: missing expectedKey "' + expectedKey + '"');
+        }
+        return result[expectedKey];
+      }
+      return result;
+    }
+  };
+}
+
+describe('[DELX] @pryv/delegation Level-0 surface', function () {
+  describe('[DELXS] STATUS constants', function () {
+    it('[DELXSA] exposes the frozen relationship-status enum', function () {
+      expect(STATUS).to.be.frozen;
+      expect(STATUS.INVITE).to.equal('invite');
+      expect(STATUS.ACTIVE).to.equal('active');
+      expect(STATUS.STALE).to.equal('stale');
+    });
+  });
+
+  describe('[DELXE] errorIds catalogue', function () {
+    it('[DELXEA] is frozen + mirrors the server delegation-* ids', function () {
+      expect(errorIds).to.be.frozen;
+      expect(errorIds.GENUINE_LOGIN_REQUIRED).to.equal('delegation-genuine-login-required');
+      expect(errorIds.NOT_ACTIVE).to.equal('delegation-not-active');
+      expect(errorIds.ALREADY_EXISTS).to.equal('delegation-already-exists');
+      expect(errorIds.USERNAME_TAKEN).to.equal('delegation-username-taken');
+      expect(errorIds.UNKNOWN_CORE).to.equal('delegation-unknown-core');
+      expect(errorIds.INVITE_EXPIRED).to.equal('delegation-invite-expired');
+      expect(errorIds.UNKNOWN_USERNAME).to.equal('delegation-unknown-username');
+      expect(errorIds.SELF_NOT_ALLOWED).to.equal('delegation-self-not-allowed');
+      expect(errorIds.MIRROR_NOT_STALE).to.equal('delegation-mirror-not-stale');
+    });
+
+    it('[DELXEB] every id is kebab-case under the delegation- namespace', function () {
+      for (const id of Object.values(errorIds)) {
+        expect(id).to.match(/^delegation-[a-z-]+$/);
+      }
+    });
+  });
+
+  describe('[DELXC] DelegationError', function () {
+    it('[DELXCA] carries id + cause + data', function () {
+      const cause = new Error('boom');
+      const err = new DelegationError('nope', errorIds.NOT_ACTIVE, cause, { peerStatus: 410 });
+      expect(err).to.be.instanceOf(Error);
+      expect(err.name).to.equal('DelegationError');
+      expect(err.id).to.equal('delegation-not-active');
+      expect(err.cause).to.equal(cause);
+      expect(err.data).to.deep.equal({ peerStatus: 410 });
+    });
+  });
+
+  describe('[DELXF] fromConnection', function () {
+    it('[DELXFA] wraps a connection; requires one', function () {
+      const conn = makeStubConnection();
+      const d = Delegation.fromConnection(conn);
+      expect(d).to.be.instanceOf(Delegation);
+      expect(d.connection).to.equal(conn);
+      expect(() => Delegation.fromConnection(null)).to.throw();
+    });
+  });
+});
+
+describe('[DELM] @pryv/delegation method → endpoint mapping', function () {
+  describe('[DELMB] B-side (controlled account)', function () {
+    it('[DELMBA] requestAttach posts delegations.requestAttach with delegateUsername', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.requestAttach': function (params) {
+            return {
+              delegation: {
+                relId: 'rel-1',
+                delegate: { username: params.delegateUsername },
+                status: 'invite',
+                requestedAt: 1000,
+                expiresAt: 2000
+              }
+            };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      const rec = await d.requestAttach('bob');
+      expect(conn.calls).to.have.length(1);
+      expect(conn.calls[0].method).to.equal('delegations.requestAttach');
+      expect(conn.calls[0].params).to.deep.equal({ delegateUsername: 'bob' });
+      expect(conn.calls[0].expectedKey).to.equal('delegation');
+      expect(rec.relId).to.equal('rel-1');
+      expect(rec.status).to.equal(STATUS.INVITE);
+      expect(rec.delegate.username).to.equal('bob');
+    });
+
+    it('[DELMBB] cancelInvite posts delegations.cancelInvite with username', async function () {
+      const conn = makeStubConnection({ handlers: { 'delegations.cancelInvite': function () { return {}; } } });
+      const d = Delegation.fromConnection(conn);
+      await d.cancelInvite('bob');
+      expect(conn.calls[0].method).to.equal('delegations.cancelInvite');
+      expect(conn.calls[0].params).to.deep.equal({ username: 'bob' });
+    });
+
+    it('[DELMBC] listDelegates returns the delegates array incl. status', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.listDelegates': function () {
+            return {
+              delegates: [
+                { relId: 'r1', delegate: { username: 'a', hostSlug: 'pryv-me' }, status: 'active', requestedAt: 1, activatedAt: 2 },
+                { relId: 'r2', delegate: { username: 'b', hostSlug: 'pryv-me' }, status: 'invite', requestedAt: 3 }
+              ]
+            };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      const list = await d.listDelegates();
+      expect(conn.calls[0].method).to.equal('delegations.listDelegates');
+      expect(conn.calls[0].expectedKey).to.equal('delegates');
+      expect(list).to.have.length(2);
+      expect(list[0].status).to.equal(STATUS.ACTIVE);
+      expect(list[1].status).to.equal(STATUS.INVITE);
+    });
+
+    it('[DELMBD] detachDelegate posts delegations.detachDelegate with username', async function () {
+      const conn = makeStubConnection({ handlers: { 'delegations.detachDelegate': function () { return {}; } } });
+      const d = Delegation.fromConnection(conn);
+      await d.detachDelegate('bob');
+      expect(conn.calls[0].method).to.equal('delegations.detachDelegate');
+      expect(conn.calls[0].params).to.deep.equal({ username: 'bob' });
+    });
+  });
+
+  describe('[DELMA] A-side (delegate)', function () {
+    it('[DELMAA] acceptAttach posts delegations.acceptAttach with username', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.acceptAttach': function (params) {
+            return { delegation: { relId: 'rel-9', controlled: { username: params.username }, status: 'active', activatedAt: 5 } };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      const rec = await d.acceptAttach('kid');
+      expect(conn.calls[0].method).to.equal('delegations.acceptAttach');
+      expect(conn.calls[0].params).to.deep.equal({ username: 'kid' });
+      expect(conn.calls[0].expectedKey).to.equal('delegation');
+      expect(rec.status).to.equal(STATUS.ACTIVE);
+      expect(rec.controlled.username).to.equal('kid');
+    });
+
+    it('[DELMAB] refuseAttach posts delegations.refuseAttach with username', async function () {
+      const conn = makeStubConnection({ handlers: { 'delegations.refuseAttach': function () { return {}; } } });
+      const d = Delegation.fromConnection(conn);
+      await d.refuseAttach('kid');
+      expect(conn.calls[0].method).to.equal('delegations.refuseAttach');
+      expect(conn.calls[0].params).to.deep.equal({ username: 'kid' });
+    });
+
+    it('[DELMAC] listControlled returns the controlled array incl. stale status', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.listControlled': function () {
+            return {
+              controlled: [
+                { relId: 'r1', controlled: { username: 'kid', hostSlug: 'pryv-me' }, status: 'active', requestedAt: 1, activatedAt: 2 },
+                { relId: 'r2', controlled: { username: 'old', hostSlug: 'pryv-me' }, status: 'stale', requestedAt: 3 }
+              ]
+            };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      const list = await d.listControlled();
+      expect(conn.calls[0].method).to.equal('delegations.listControlled');
+      expect(conn.calls[0].expectedKey).to.equal('controlled');
+      expect(list).to.have.length(2);
+      expect(list[1].status).to.equal(STATUS.STALE);
+    });
+
+    it('[DELMAD] dismissControlled posts delegations.dismissControlled with username', async function () {
+      const conn = makeStubConnection({ handlers: { 'delegations.dismissControlled': function () { return {}; } } });
+      const d = Delegation.fromConnection(conn);
+      await d.dismissControlled('old');
+      expect(conn.calls[0].method).to.equal('delegations.dismissControlled');
+      expect(conn.calls[0].params).to.deep.equal({ username: 'old' });
+    });
+
+    it('[DELMAE] getToken returns { token, apiEndpoint }', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.getToken': function (params) {
+            expect(params).to.deep.equal({ username: 'kid' });
+            return { token: 'tok-abc', apiEndpoint: 'https://kid.pryv.me/', extra: 'ignored' };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      const res = await d.getToken('kid');
+      expect(res).to.deep.equal({ token: 'tok-abc', apiEndpoint: 'https://kid.pryv.me/' });
+    });
+
+    it('[DELMAF] createAccount posts delegations.createAccount + returns { delegation, apiEndpoint }', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.createAccount': function (params) {
+            return {
+              delegation: { relId: 'rel-new', controlled: { username: params.username, hostSlug: 'pryv-me' }, status: 'active', activatedAt: 9 },
+              apiEndpoint: 'https://new.pryv.me/'
+            };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      const res = await d.createAccount({ username: 'newkid', email: 'k@x.io', password: 'p', core: 'core-2' });
+      expect(conn.calls[0].method).to.equal('delegations.createAccount');
+      expect(conn.calls[0].params).to.deep.equal({ username: 'newkid', email: 'k@x.io', password: 'p', core: 'core-2' });
+      expect(res.delegation.status).to.equal(STATUS.ACTIVE);
+      expect(res.apiEndpoint).to.equal('https://new.pryv.me/');
+    });
+
+    it('[DELMAG] createAccount omits absent optional fields + requires username', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.createAccount': function () {
+            return { delegation: { relId: 'r', controlled: { username: 'x' }, status: 'active' } };
+          }
+        }
+      });
+      const d = Delegation.fromConnection(conn);
+      await d.createAccount({ username: 'x' });
+      expect(conn.calls[0].params).to.deep.equal({ username: 'x' });
+      let threw = false;
+      try { await d.createAccount({}); } catch (_e) { threw = true; }
+      expect(threw).to.equal(true);
+    });
+  });
+
+  describe('[DELMO] openControlled round-trip', function () {
+    it('[DELMOA] mints a token then builds a pryv.Connection onto the controlled account', async function () {
+      const conn = makeStubConnection({
+        handlers: {
+          'delegations.getToken': function () {
+            return { token: 'tok-xyz', apiEndpoint: 'https://kid.pryv.me/' };
+          }
+        }
+      });
+      // Use the real pryv module so the endpoint composition is exercised end-to-end.
+      const d = Delegation.fromConnection(conn, { pryv });
+      const controlledConn = await d.openControlled('kid');
+      expect(conn.calls[0].method).to.equal('delegations.getToken');
+      expect(controlledConn).to.be.instanceOf(pryv.Connection);
+      expect(controlledConn.token).to.equal('tok-xyz');
+      expect(controlledConn.endpoint).to.equal('https://kid.pryv.me/');
+    });
+  });
+});
+
+describe('[DELE] @pryv/delegation typed error surfacing', function () {
+  it('[DELEA] detachDelegate surfaces delegation-genuine-login-required distinctly', async function () {
+    const conn = makeStubConnection({
+      handlers: {
+        'delegations.detachDelegate': function () {
+          return { __error: { id: 'delegation-genuine-login-required', message: 'direct login required' } };
+        }
+      }
+    });
+    const d = Delegation.fromConnection(conn);
+    let err = null;
+    try { await d.detachDelegate('bob'); } catch (e) { err = e; }
+    expect(err).to.be.instanceOf(DelegationError);
+    expect(err.id).to.equal(errorIds.GENUINE_LOGIN_REQUIRED);
+  });
+
+  it('[DELEB] getToken surfaces delegation-not-active with data payload', async function () {
+    const conn = makeStubConnection({
+      handlers: {
+        'delegations.getToken': function () {
+          return { __error: { id: 'delegation-not-active', message: 'no longer active', data: { peerStatus: 403 } } };
+        }
+      }
+    });
+    const d = Delegation.fromConnection(conn);
+    let err = null;
+    try { await d.getToken('kid'); } catch (e) { err = e; }
+    expect(err).to.be.instanceOf(DelegationError);
+    expect(err.id).to.equal(errorIds.NOT_ACTIVE);
+    expect(err.data).to.deep.equal({ peerStatus: 403 });
+  });
+
+  it('[DELEC] requestAttach surfaces delegation-already-exists', async function () {
+    const conn = makeStubConnection({
+      handlers: {
+        'delegations.requestAttach': function () {
+          return { __error: { id: 'delegation-already-exists', message: 'dup' } };
+        }
+      }
+    });
+    const d = Delegation.fromConnection(conn);
+    let err = null;
+    try { await d.requestAttach('bob'); } catch (e) { err = e; }
+    expect(err).to.be.instanceOf(DelegationError);
+    expect(err.id).to.equal(errorIds.ALREADY_EXISTS);
+  });
+
+  it('[DELED] createAccount surfaces delegation-username-taken + delegation-unknown-core', async function () {
+    for (const id of ['delegation-username-taken', 'delegation-unknown-core']) {
+      const conn = makeStubConnection({
+        handlers: { 'delegations.createAccount': function () { return { __error: { id, message: id } }; } }
+      });
+      const d = Delegation.fromConnection(conn);
+      let err = null;
+      try { await d.createAccount({ username: 'x' }); } catch (e) { err = e; }
+      expect(err).to.be.instanceOf(DelegationError);
+      expect(err.id).to.equal(id);
+    }
+  });
+
+  it('[DELEE] acceptAttach surfaces delegation-invite-expired', async function () {
+    const conn = makeStubConnection({
+      handlers: {
+        'delegations.acceptAttach': function () {
+          return { __error: { id: 'delegation-invite-expired', message: 'gone' } };
+        }
+      }
+    });
+    const d = Delegation.fromConnection(conn);
+    let err = null;
+    try { await d.acceptAttach('kid'); } catch (e) { err = e; }
+    expect(err).to.be.instanceOf(DelegationError);
+    expect(err.id).to.equal(errorIds.INVITE_EXPIRED);
+  });
+
+  it('[DELEF] a non-delegation error passes through unchanged (not a DelegationError)', async function () {
+    const conn = makeStubConnection({
+      handlers: {
+        'delegations.listDelegates': function () {
+          return { __error: { id: 'invalid-access-token', message: 'bad token' } };
+        }
+      }
+    });
+    const d = Delegation.fromConnection(conn);
+    let err = null;
+    try { await d.listDelegates(); } catch (e) { err = e; }
+    expect(err).to.not.be.instanceOf(DelegationError);
+    expect(err.innerObject.id).to.equal('invalid-access-token');
+  });
+});