@calimero-network/mero-js 27.0.2 → 27.2.0

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   CalimeroError: () => CalimeroError,
   ConfirmCancelled: () => ConfirmCancelled,
   ConfirmRequired: () => ConfirmRequired,
+  ConsentStale: () => ConsentStale,
   DEFAULT_ORG_CAPABILITIES: () => DEFAULT_ORG_CAPABILITIES,
   DEFAULT_RELEASE_MIRROR: () => DEFAULT_RELEASE_MIRROR,
   GITHUB_RELEASES: () => GITHUB_RELEASES,
@@ -45,17 +46,21 @@ __export(index_exports, {
   IdempotencyMismatch: () => IdempotencyMismatch,
   KMS_RELEASE_SIGNER: () => KMS_RELEASE_SIGNER,
   LoginRequired: () => LoginRequired,
+  MAX_REPORT_PAGE: () => MAX_REPORT_PAGE,
   MOCK_QUOTE_HEADER: () => MOCK_QUOTE_HEADER,
   NODE_RELEASE_SIGNER: () => NODE_RELEASE_SIGNER,
   NotFound: () => NotFound,
   ORG_CAPABILITIES: () => ORG_CAPABILITIES,
   PRODUCTION_PROFILE: () => PRODUCTION_PROFILE,
+  RELEASE_VERIFIER: () => RELEASE_VERIFIER,
+  ReleaseDeadlineError: () => ReleaseDeadlineError,
   SEALED_CONTENT_TYPE: () => SEALED_CONTENT_TYPE,
   SEALED_PATH: () => SEALED_PATH,
   SealedTransportError: () => SealedTransportError,
   StaleTransportKeyError: () => StaleTransportKeyError,
   TrapError: () => TrapError,
   UnavailableError: () => UnavailableError,
+  WrongNode: () => WrongNode,
   agentKeyBinding: () => agentKeyBinding,
   agentQuoteVerifier: () => agentQuoteVerifier,
   attestAgent: () => attestAgent,
@@ -64,6 +69,8 @@ __export(index_exports, {
   checkOwner: () => checkOwner,
   claimedRelease: () => claimedRelease,
   cloudNodeReleaseUrl: () => cloudNodeReleaseUrl,
+  compareVersions: () => compareVersions,
+  consentReturn: () => consentReturn,
   createQuoteVerifier: () => createQuoteVerifier,
   createSealedFetch: () => createSealedFetch,
   createSignedReleaseVerifier: () => createSignedReleaseVerifier,
@@ -75,15 +82,25 @@ __export(index_exports, {
   generateOwnerKey: () => generateOwnerKey,
   orgCapabilities: () => orgCapabilities,
   ownerPublicKey: () => ownerPublicKey,
+  pageQuery: () => pageQuery,
+  pendingApprovalsFrom: () => pendingApprovalsFrom,
   provisionAgent: () => provisionAgent,
   provisionInfo: () => provisionInfo,
+  publisherBindingBytes: () => publisherBindingBytes,
+  publisherBindingMessage: () => publisherBindingMessage,
   releaseAgent: () => releaseAgent,
+  releaseConsent: () => releaseConsent,
+  releaseNotesUrl: () => releaseNotesUrl,
+  stalledBy: () => stalledBy,
   transportKeyBinding: () => transportKeyBinding,
   trustSignedRelease: () => trustSignedRelease,
   trustedMeasurementsFromReleases: () => trustedMeasurementsFromReleases,
+  upgradeConsent: () => upgradeConsent,
   validateAgentId: () => validateAgentId,
+  verifyReleaseUrl: () => verifyReleaseUrl,
   verifySignedAgentPolicy: () => verifySignedAgentPolicy,
-  verifySignedNodeRelease: () => verifySignedNodeRelease
+  verifySignedNodeRelease: () => verifySignedNodeRelease,
+  withdrawConsent: () => withdrawConsent
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1324,6 +1341,12 @@ var LoginRequired = class extends CalimeroError {
     this.name = "LoginRequired";
   }
 };
+var WrongNode = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(421, "WRONG_NODE", message, details);
+    this.name = "WrongNode";
+  }
+};
 var NotFound = class extends CalimeroError {
   constructor(message, details = {}) {
     super(404, "NOT_FOUND", message, details);
@@ -1355,6 +1378,20 @@ var IdempotencyMismatch = class extends CalimeroError {
     this.name = "IdempotencyMismatch";
   }
 };
+var ReleaseDeadlineError = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(409, "RELEASE_DEADLINE", message, details);
+    this.name = "ReleaseDeadlineError";
+    this.release = typeof details.release === "string" ? details.release : "";
+    this.after = typeof details.after === "string" ? details.after : "";
+  }
+};
+var ConsentStale = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(409, "CONSENT_STALE", message, details);
+    this.name = "ConsentStale";
+  }
+};
 var AppError = class extends CalimeroError {
   constructor(message, details = {}) {
     super(422, "APP_ERROR", message, details);
@@ -1404,10 +1441,16 @@ function errorFrom(status, body, retryAfterHeader) {
   switch (`${status} ${code}`) {
     case "401 UNAUTHENTICATED":
       return new LoginRequired(message, details);
+    case "421 WRONG_NODE":
+      return new WrongNode(message, details);
     case "404 NOT_FOUND":
       return new NotFound(message, details);
     case "409 IDEMPOTENCY_MISMATCH":
       return new IdempotencyMismatch(message, details);
+    case "409 RELEASE_DEADLINE":
+      return new ReleaseDeadlineError(message, details);
+    case "409 CONSENT_STALE":
+      return new ConsentStale(message, details);
     case "412 CONFIRM_REQUIRED":
       return new ConfirmRequired(message, details);
     case "413 ARGS_TOO_LARGE":
@@ -1484,6 +1527,113 @@ function browserPasskey() {
   };
 }
 
+// src/cloud-v2/approvals.ts
+var MAX_REPORT_PAGE = 100;
+function pageQuery(page = {}) {
+  const q = new URLSearchParams();
+  if (page.after !== void 0) q.set("after", page.after);
+  if (page.limit !== void 0) {
+    if (!Number.isInteger(page.limit) || page.limit < 1 || page.limit > MAX_REPORT_PAGE) {
+      throw new RangeError(`limit is 1 to ${MAX_REPORT_PAGE}`);
+    }
+    q.set("limit", String(page.limit));
+  }
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+function compareVersions(a, b) {
+  try {
+    return compareReleaseVersions(a, b);
+  } catch {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+}
+function stalledBy(approved, deadlines, now = Date.now() / 1e3) {
+  if (approved === null || approved.length === 0) return null;
+  const newest = approved.reduce((a, b) => compareVersions(a, b) >= 0 ? a : b);
+  let stall = null;
+  for (const d of deadlines) {
+    if (d.afterSecs <= now && compareVersions(newest, d.version) < 0) {
+      if (stall === null || compareVersions(d.version, stall.version) > 0) stall = d;
+    }
+  }
+  return stall;
+}
+function publisherBindingMessage(cluster, org, signerId, generation) {
+  return `calimero-publisher-binding/v1
+${cluster}
+${org}
+${signerId}
+${generation}`;
+}
+function publisherBindingBytes(cluster, org, signerId, generation) {
+  return new TextEncoder().encode(publisherBindingMessage(cluster, org, signerId, generation));
+}
+function consentReturn(href) {
+  const url2 = typeof href === "string" ? new URL(href) : href;
+  const requestId = url2.searchParams.get("request_id");
+  const result = url2.searchParams.get("result");
+  if (!requestId || result !== "approved" && result !== "declined") return null;
+  return { requestId, result };
+}
+var RELEASE_VERIFIER = "https://mero-tee.vercel.app";
+function releaseNotesUrl(version) {
+  return `https://github.com/calimero-network/mero-tee/releases/tag/mero-tee-v${encodeURIComponent(version)}`;
+}
+function verifyReleaseUrl(version) {
+  return `${RELEASE_VERIFIER}/mero-tee?release_tag=${encodeURIComponent(`mero-tee-v${version}`)}`;
+}
+function pendingApprovalsFrom(report, rules, now = Date.now() / 1e3) {
+  const deadlineOf = (v) => rules.deadlines.find((d) => d.version === v) ?? null;
+  const releasesActionable = report.governance.releases === "owner";
+  const upgradesActionable = report.governance.appUpgrades === "owner";
+  const releases = report.clusterReleases.filter((r) => !r.approved).sort((a, b) => compareVersions(b.release, a.release)).map((r) => ({
+    version: r.release,
+    nodes: r.nodes,
+    actionable: releasesActionable,
+    releaseNotesUrl: releaseNotesUrl(r.release),
+    verifyUrl: verifyReleaseUrl(r.release),
+    deadline: deadlineOf(r.release)
+  }));
+  const upgrades = [];
+  for (const a of report.apps) {
+    const available = a.availableVersions ?? [];
+    if (a.package === null || available.length === 0) continue;
+    upgrades.push({
+      app: a.app,
+      name: a.name ?? null,
+      package: a.package.package,
+      from: a.package.version,
+      to: available[available.length - 1],
+      available,
+      actionable: upgradesActionable
+    });
+  }
+  return {
+    scope: report.scope,
+    governance: report.governance,
+    approvedReleases: report.approvedReleases,
+    releases,
+    upgrades,
+    stalledBy: stalledBy(report.approvedReleases, rules.deadlines, now),
+    actionable: releases.some((r) => r.actionable) || upgrades.some((u) => u.actionable)
+  };
+}
+function releaseConsent(scope, version, returnTo, options = {}) {
+  return {
+    kind: "release",
+    scope: scope.kind === "org" ? { org: scope.org } : "account",
+    subject: options.withdraw ? { version, withdraw: true } : { version },
+    returnTo
+  };
+}
+function withdrawConsent(scope, version, returnTo) {
+  return releaseConsent(scope, version, returnTo, { withdraw: true });
+}
+function upgradeConsent(app, toVersion, returnTo) {
+  return { kind: "upgrade", subject: { app, toVersion }, returnTo };
+}
+
 // src/cloud-v2/client.ts
 function seg(value) {
   return encodeURIComponent(value);
@@ -1547,11 +1697,20 @@ var DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2e3 };
 function retryDelayMs(retry, options) {
   return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
 }
+function ceremony(path) {
+  return path === "auth/refresh" || path.startsWith("auth/passkey/");
+}
 var CalimeroClient = class {
   constructor(options) {
+    /** The one in use: an index into {@link nodeUrls}. */
+    this.at = 0;
+    /** A sealed fetch per node, each attesting its own node on first use. */
+    this.channels = /* @__PURE__ */ new Map();
     /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
     this.networkFailures = /* @__PURE__ */ new WeakSet();
-    this.base = options.baseUrl.replace(/\/+$/, "");
+    const trim = (url2) => url2.replace(/\/+$/, "");
+    this.nodeUrls = [...new Set([options.baseUrl, ...options.nodes ?? []].map(trim))];
+    this.policy = options.policy;
     this.retry = { ...DEFAULT_RETRY, ...options.retry };
     const given = options.fetch ?? ((input, init) => fetch(input, init));
     const raw = async (input, init) => {
@@ -1563,11 +1722,33 @@ var CalimeroClient = class {
       }
     };
     this.raw = raw;
-    this.sealed = createSealedFetch({
-      baseUrl: this.base,
-      transportPublicKey: () => fetchAttestedKey(this.base, options.policy, raw),
-      fetch: raw
-    });
+  }
+  /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+  get nodeUrl() {
+    return this.nodeUrls[this.at];
+  }
+  /** The sealed channel to `url`, attested under the client's policy before its first request. */
+  channel(url2) {
+    let sealed = this.channels.get(url2);
+    if (!sealed) {
+      sealed = createSealedFetch({
+        baseUrl: url2,
+        transportPublicKey: () => fetchAttestedKey(url2, this.policy, this.raw),
+        fetch: this.raw
+      });
+      this.channels.set(url2, sealed);
+    }
+    return sealed;
+  }
+  /**
+   * Move on from node `from` (the one that answered `421 WRONG_NODE`) to the
+   * next one. False when there is no other. A request that saw the same node
+   * refuse after another request moved on already does not move again.
+   */
+  moveOn(from) {
+    if (this.nodeUrls.length < 2) return false;
+    if (this.at === from) this.at = (from + 1) % this.nodeUrls.length;
+    return true;
   }
   /** Authenticate every request with an API key. */
   useApiKey(key) {
@@ -1581,7 +1762,11 @@ var CalimeroClient = class {
   get session() {
     return this.current;
   }
-  async request(method, path, body, raw, contentType = "application/wasm") {
+  /**
+   * Send one request to the node in use, with the credential held now, and
+   * answer the response, whatever its status. {@link send} judges it.
+   */
+  async request(method, path, body, raw, contentType = "application/wasm", signal) {
     const headers = {};
     if (this.auth) headers.authorization = `Bearer ${this.auth}`;
     let payload;
@@ -1592,15 +1777,66 @@ var CalimeroClient = class {
       headers["content-type"] = "application/json";
       payload = JSON.stringify(body);
     }
+    const url2 = this.nodeUrl;
     try {
-      return await this.sealed(`${this.base}/${path}`, { method, headers, body: payload });
+      return await this.channel(url2)(`${url2}/${path}`, { method, headers, body: payload, signal });
     } catch (error) {
       throw sealedError(error);
     }
   }
+  /**
+   * {@link request}, answering what a lost issuing node or a node on the
+   * wrong release does to a session: a successful response, or the refusal as a
+   * typed error ({@link errorFrom}).
+   *
+   * - `401 UNAUTHENTICATED` to a request that carried a session: the node that
+   *   signed the session may be gone, replaced, or out of reach of the node
+   *   asked, which any node of the cluster answers with a refresh. The client
+   *   refreshes once, shared by every request that needs it at the same time
+   *   ({@link refresh}), and repeats the request once. A refresh that is
+   *   refused surfaces as {@link LoginRequired}.
+   * - `421 WRONG_NODE`: this node's release may not serve the account. The
+   *   client moves to the next node it knows and repeats the request once; with
+   *   none, the {@link WrongNode} reaches the caller.
+   *
+   * Repeating is safe even for a request that is not idempotent: the node
+   * answers `401` and `421` when it judges the credential, before it reads what
+   * the request asks, so the first attempt ran nothing. The exceptions are the
+   * ceremonies that mint a session ({@link ceremony}), never repeated here.
+   */
+  async send(method, path, body, raw, contentType, signal) {
+    let refreshed = false;
+    let moved = false;
+    for (; ; ) {
+      const [token, at] = [this.auth, this.at];
+      const response = await this.request(method, path, body, raw, contentType, signal);
+      if (response.ok) return response;
+      const error = await refusal(response);
+      if (error instanceof WrongNode && !moved) {
+        moved = true;
+        if (this.moveOn(at) && !ceremony(path)) continue;
+      } else if (error instanceof LoginRequired && !refreshed && this.mayRefresh(token, path)) {
+        refreshed = true;
+        await this.renew(token);
+        continue;
+      }
+      throw error;
+    }
+  }
+  /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
+  mayRefresh(token, path) {
+    return token !== void 0 && this.current !== void 0 && !ceremony(path);
+  }
+  /**
+   * A fresh session in place of the one `token` belonged to: by the refresh
+   * another request already made, or by one this request starts.
+   */
+  async renew(token) {
+    if (this.auth !== token) return;
+    await this.refresh();
+  }
   async json(method, path, body, raw, contentType) {
-    const response = await this.request(method, path, body, raw, contentType);
-    if (!response.ok) throw await refusal(response);
+    const response = await this.send(method, path, body, raw, contentType);
     const text = await response.text();
     return text ? JSON.parse(text) : {};
   }
@@ -1669,11 +1905,35 @@ var CalimeroClient = class {
     this.useSession(session);
     return session;
   }
-  /** Swap the refresh token for a new session. */
-  async refresh() {
-    if (!this.current) throw new Error("no session to refresh");
-    const session = await this.post("auth/refresh", { refreshToken: this.current.refreshToken });
-    this.useSession(session);
+  /**
+   * Swap the refresh token for a new session, on whichever node the client
+   * uses: any node of the cluster takes it. A refresh token is used once, so
+   * calls made while one refresh is under way share it rather than sending the
+   * same token again (which would revoke the session).
+   */
+  refresh() {
+    if (!this.refreshing) {
+      const pending = this.exchangeRefresh();
+      this.refreshing = pending;
+      const clear = () => {
+        if (this.refreshing === pending) this.refreshing = void 0;
+      };
+      pending.then(clear, clear);
+    }
+    return this.refreshing;
+  }
+  async exchangeRefresh() {
+    const current = this.current;
+    if (!current) throw new Error("no session to refresh");
+    let session;
+    for (let tried = 1; session === void 0; tried++) {
+      try {
+        session = await this.post("auth/refresh", { refreshToken: current.refreshToken });
+      } catch (error) {
+        if (!(error instanceof WrongNode) || tried >= this.nodeUrls.length) throw error;
+      }
+    }
+    if (this.current === current) this.useSession(session);
     return session;
   }
   async signOut() {
@@ -1718,7 +1978,7 @@ var CalimeroClient = class {
    */
   async attestation() {
     const nonce2 = toHex(crypto.getRandomValues(new Uint8Array(32)));
-    const response = await this.raw(`${this.base}/attestation?nonce=${nonce2}`);
+    const response = await this.raw(`${this.nodeUrl}/attestation?nonce=${nonce2}`);
     if (!response.ok) throw await refusal(response);
     return await response.json();
   }
@@ -1746,8 +2006,7 @@ var CalimeroClient = class {
   }
   /** One of `app`'s blobs, by id (base58 or hex). */
   async downloadBlob(app, id) {
-    const response = await this.request("GET", `apps/${seg(app)}/blobs/${seg(id)}`);
-    if (!response.ok) throw await refusal(response);
+    const response = await this.send("GET", `apps/${seg(app)}/blobs/${seg(id)}`);
     return new Uint8Array(await response.arrayBuffer());
   }
   /** `app`'s blobs. */
@@ -1829,8 +2088,11 @@ var CalimeroClient = class {
    * Move an app to another release of its package (`{ version }`), another
    * package, or a bundle hash, running its migration. Answers the upgrade's
    * entry; a failed migration rejects with code `UPGRADE_FAILED` (422).
-   * Where the owner holds app upgrades, the node asks for the owner's approval
-   * (`412 CONFIRM_REQUIRED`), which `passkey` gives.
+   * Where owners hold app upgrades, the node asks for the approval of
+   * whoever the package's manifest names (`412 CONFIRM_REQUIRED`), which
+   * `passkey` gives. Refused (`403`) to a session opened on an app's
+   * frontend: an app asks its user with {@link requestConsent} instead. Past
+   * a release deadline its approver has not met: {@link ReleaseDeadlineError}.
    */
   upgradeApp(app, target, passkey) {
     const path = `apps/${seg(app)}/upgrade`;
@@ -1913,10 +2175,7 @@ var CalimeroClient = class {
   }
   /** A server-sent event stream on `path`, sealed like every other answer. */
   async *stream(path, signal) {
-    const headers = {};
-    if (this.auth) headers.authorization = `Bearer ${this.auth}`;
-    const response = await this.sealed(`${this.base}/${path}`, { headers, signal });
-    if (!response.ok) throw await refusal(response);
+    const response = await this.send("GET", path, void 0, void 0, void 0, signal);
     if (!response.body) throw new CalimeroError(response.status, "EVENTS", "the event stream has no body");
     yield* sseFrames(response.body);
   }
@@ -2003,8 +2262,11 @@ var CalimeroClient = class {
   /**
    * Approve a mero-tee release to hold the apps of `org`, or of this account
    * outside any organization (`org` `null`); `approved: false` withdraws it.
-   * Until then, nodes on that release get none of those apps' data. The owner
-   * approves with `passkey`.
+   * Until then, nodes on that release get none of those apps' data. For an
+   * organization, a member holding `APPROVE_RELEASES` approves with `passkey`;
+   * the node binds the release's measurements itself. Refused (`403`) to a
+   * session opened on an app's frontend: an app asks its user with
+   * {@link requestConsent} instead.
    */
   async approveRelease(org, version, passkey, approved = true) {
     const path = org === null ? "auth/releases" : `orgs/${seg(org)}/releases`;
@@ -2015,7 +2277,8 @@ var CalimeroClient = class {
    * `org`'s apps or this account's own (`org` `null`). `prefixes` `'manifest'`
    * (the default) approves every prefix the package's latest release declares;
    * `replace` sets exactly `prefixes`, which is how one is revoked. Approved
-   * with `passkey`.
+   * with `passkey`. Refused (`403`) to a session opened on an app's frontend:
+   * an app asks with {@link requestConsent} (`kind: 'outbound'`) instead.
    */
   async approveOutbound(org, pkg, passkey, options = {}) {
     const path = org === null ? "auth/outbound" : `orgs/${seg(org)}/outbound`;
@@ -2025,6 +2288,137 @@ var CalimeroClient = class {
       passkey
     );
   }
+  // ---------------------------------------------------------------- approvals
+  /**
+   * One page of the report of a scope's apps: an organization's (any member;
+   * `404` to anyone else) or, with `org` `null`, the account's own outside any
+   * organization (a session bound to an app's frontend: that package's apps).
+   * The governance, the scope's approved releases, the releases the cluster's
+   * nodes run and whether each is approved, and per app its release, newer
+   * releases it may move to, last upgrade and replicas.
+   */
+  appsReport(org, page = {}) {
+    const path = org === null ? "auth/apps" : `orgs/${seg(org)}/apps`;
+    return this.get(`${path}${pageQuery(page)}`);
+  }
+  /** {@link appsReport}, every page, with the apps of all of them in `apps`. */
+  async appsReportAll(org) {
+    const first = await this.appsReport(org);
+    const apps = [...first.apps];
+    let next = first.next;
+    while (next !== null) {
+      const page = await this.appsReport(org, { after: next });
+      apps.push(...page.apps);
+      next = page.next;
+    }
+    return { ...first, apps, next: null };
+  }
+  /** `GET /releases`: the cluster's governance and every release deadline. Public. */
+  releaseRules() {
+    return this.get("releases");
+  }
+  /**
+   * What waits for a decision in a scope (`org`, or the account's own apps
+   * with `null`): mero-tee releases the cluster's nodes run that the scope has
+   * not approved, apps with newer releases of their package, and whether a
+   * passed deadline stops new work. Read over the sealed channel; act on an
+   * item by sending the user to the consent page ({@link requestConsent},
+   * `releaseConsent`, `upgradeConsent`).
+   */
+  async pendingApprovals(org = null) {
+    const [report, rules] = await Promise.all([this.appsReportAll(org), this.releaseRules()]);
+    return pendingApprovalsFrom(report, rules);
+  }
+  /**
+   * Ask the node to ask the user: a release, upgrade or outbound approval
+   * that only the account holder may make, decided on the node's own consent
+   * page, never in the app. Needs a passkey session (a session bound to the
+   * app's frontend is fine). Send the person to the answer's `url`; the page
+   * sends them back to `returnTo?request_id=…&result=approved|declined`
+   * (`consentReturn`), and {@link consentResult} confirms the decision.
+   */
+  requestConsent(request) {
+    return this.post("consent/requests", request);
+  }
+  /**
+   * {@link requestConsent}, then send the browser to the consent page
+   * (`navigate`, by default `window.location.assign`). Answers the request
+   * once `navigate` returns: with a popup (`url => window.open(url)`), poll it
+   * with {@link waitForConsent}.
+   */
+  async openConsentPage(request, navigate = (url2) => {
+    const w = globalThis.window;
+    if (!w) throw new Error("no window to open the consent page in; pass `navigate`");
+    w.location.assign(url2);
+  }) {
+    const started = await this.requestConsent(request);
+    navigate(started.url);
+    return started;
+  }
+  /** The decision on a consent request (any node answers, for the account that asked). */
+  consentResult(requestId) {
+    return this.get(`consent/${seg(requestId)}/result`);
+  }
+  /**
+   * Poll {@link consentResult} until the request is decided, every
+   * `intervalMs` (2 s), until `signal` aborts or `expiresAt` (Unix seconds)
+   * passes, when it answers the last `pending` result.
+   */
+  async waitForConsent(requestId, options = {}) {
+    const interval = options.intervalMs ?? 2e3;
+    for (; ; ) {
+      const result = await this.consentResult(requestId);
+      if (result.status !== "pending") return result;
+      if (options.signal?.aborted) return result;
+      if (options.expiresAt !== void 0 && Date.now() / 1e3 >= options.expiresAt) return result;
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+  /** `GET /publishers/{signerId}`: the cluster name and binding generation a key signs to bind it next. */
+  publisherBinding(signerId) {
+    return this.get(`publishers/${seg(signerId)}`);
+  }
+  /**
+   * Bind a package signing key to `org`, which then approves the node images
+   * every instance of the key's packages runs on, and upgrades those whose
+   * package declares `upgrades: publisher`. `proof` is the key's signature
+   * over `publisherBindingMessage(cluster, org, signerId, generation)`; a
+   * member holding `APPROVE_RELEASES` sends it with `passkey`.
+   */
+  bindPublisher(org, proof, passkey) {
+    return this.postConfirmed(`orgs/${seg(org)}/publishers`, { ...proof }, passkey);
+  }
+  /**
+   * Upgrade every instance of `pkg` whose release declares `upgrades:
+   * publisher`, whoever owns it, as its publisher `org` (a
+   * `MANAGE_APPLICATION` holder there), with one passkey approval. Answers
+   * the run, kept on the publisher.
+   */
+  upgradePublished(org, pkg, target, passkey) {
+    return this.postConfirmed(`orgs/${seg(org)}/packages/${seg(pkg)}/upgrade`, { ...target }, passkey);
+  }
+  // ---------------------------------------------------------------- operator
+  /** `GET /ops/apps`: what every app runs, without names or accounts. Operator token (`useApiKey`). */
+  opsApps(page = {}) {
+    return this.get(`ops/apps${pageQuery(page)}`);
+  }
+  /** `GET /ops/orgs`: each organization's approved releases. Operator token. */
+  opsOrgs(page = {}) {
+    return this.get(`ops/orgs${pageQuery(page)}`);
+  }
+  /**
+   * Announce when work on images older than `version` ends: from `after` on,
+   * a scope that has not approved it (or newer) starts no new work. Operator
+   * token.
+   */
+  async setReleaseDeadline(version, after) {
+    const at = typeof after === "string" ? after : after.toISOString();
+    await this.post(`ops/releases/${seg(version)}/deadline`, { after: at });
+  }
+  /** Lift a release's deadline. Operator token. */
+  async liftReleaseDeadline(version) {
+    await this.delete(`ops/releases/${seg(version)}/deadline`);
+  }
   /** Add a member, or change their role. */
   async setMember(org, account, role) {
     await this.post(`orgs/${seg(org)}/members`, { account, role });
@@ -2084,7 +2478,7 @@ var ORG_CAPABILITIES = {
   JOIN_OPEN_TEAMS: 1 << 2,
   /** Add and remove a team's members. */
   MANAGE_MEMBERS: 1 << 3,
-  /** Upgrade the organization's apps, start org upgrade runs, approve outbound hosts (org-wide). */
+  /** Upgrade the organization's apps (and, as a publisher, every instance of its `publisher` packages), start org upgrade runs, approve outbound hosts (org-wide). */
   MANAGE_APPLICATION: 1 << 4,
   /** Create a top-level team without being an admin. */
   CREATE_TEAM: 1 << 5,
@@ -2093,7 +2487,14 @@ var ORG_CAPABILITIES = {
   /** Change who may join a team (open or invite-only). */
   MANAGE_VISIBILITY: 1 << 7,
   /** Set the organization's and its teams' metadata. */
-  MANAGE_METADATA: 1 << 8
+  MANAGE_METADATA: 1 << 8,
+  /**
+   * Approve (or withdraw) the mero-tee releases that hold the apps the
+   * organization governs (those of the packages it publishes, and its own of
+   * unbound packages), and bind a package signing key to it
+   * (`bindPublisher`). Organization-wide only. Bit 9 is left unused.
+   */
+  APPROVE_RELEASES: 1 << 10
 };
 var DEFAULT_ORG_CAPABILITIES = ORG_CAPABILITIES.JOIN_OPEN_TEAMS;
 function orgCapabilities(...names) {