@calimero-network/mero-js 27.0.1 → 27.1.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,11 +46,14 @@ __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,
@@ -64,6 +68,8 @@ __export(index_exports, {
   checkOwner: () => checkOwner,
   claimedRelease: () => claimedRelease,
   cloudNodeReleaseUrl: () => cloudNodeReleaseUrl,
+  compareVersions: () => compareVersions,
+  consentReturn: () => consentReturn,
   createQuoteVerifier: () => createQuoteVerifier,
   createSealedFetch: () => createSealedFetch,
   createSignedReleaseVerifier: () => createSignedReleaseVerifier,
@@ -75,15 +81,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);
 
@@ -1355,6 +1371,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);
@@ -1408,6 +1438,10 @@ function errorFrom(status, body, retryAfterHeader) {
       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 +1518,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);
@@ -1829,8 +1970,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`;
@@ -2003,8 +2147,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 +2162,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 +2173,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 +2363,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 +2372,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) {