@verentis/sdk 0.2.2 → 0.2.4

package/README.md

@@ -57,6 +57,30 @@ Release the 0.2 SDK before deploying apps that require `^0.2.0`, together with t
 Local sibling-repository development can link the built SDK; published applications must resolve
 the released SDK from npm.
 
+### WOPI editor launch
+
+Signed WOPI applications use `Bridge.requestWopiLaunch()` after `waitForInit()`.
+The authenticated workspace parent chooses the installed editor, document,
+branch and action; the child cannot request arbitrary document identities.
+The returned token is scoped to WOPI and is not a normal workspace API token.
+Submit it using a form POST to the validated discovery action, never a URL.
+
+`requestWopiSave(generation)`, `getWopiStatus()` and `closeWopiSession()` use the
+same exact-parent, origin/session/request-correlated bridge. A matching durable
+save receipt—not a CODE postMessage alone—is required before clearing dirty state.
+When status reports `continuationAvailable`, `requestWopiContinuation()` asks
+the parent to bind the target of a completed server-owned Save As operation.
+It accepts no document or acquisition IDs. Its `WopiContinuation` result contains
+only document metadata and the persisted target `accessTokenTtl`, not a token,
+action URL or private control credential. The parent obtains the exact existing
+control IDs from authenticated `/derived`; it does not reconstruct a launch,
+including after signing-key rotation. Keep the initial launch/form separate from
+active document metadata, retain CODE's iframe and existing token, and preserve
+unverified edits until a matching target save receipt arrives.
+These methods do not replace `requestBackendCredential()` or ordinary OAuth
+authentication for apps that need workspace APIs. WOPI-only packages need no
+per-editor OAuth client secret.
+
 ### Standalone mode (local development)
 
 ```ts

package/dist/index.cjs

@@ -30,6 +30,14 @@ var BridgeAuth = class {
   _refreshTimer = null;
   _pendingRefresh = null;
   _messageHandler;
+  _requestId = null;
+  _refreshReject = null;
+  _requestTimer = null;
+  _destroyed = false;
+  setHostOrigin(origin) {
+    if (!origin || origin === "*" || origin === "null") throw new Error("A trusted host origin is required.");
+    this.hostOrigin = origin;
+  }
   /** Set the initial token received from the host's `verentis:init` message */
   setToken(info) {
     this._token = info.accessToken;
@@ -44,7 +52,9 @@ var BridgeAuth = class {
     return `Bearer ${this._token}`;
   }
   destroy() {
+    this._destroyed = true;
     if (this._refreshTimer) clearTimeout(this._refreshTimer);
+    this.failRefresh("Authentication has been destroyed.");
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
     }
@@ -54,11 +64,16 @@ var BridgeAuth = class {
   }
   _refreshResolve = null;
   requestRefresh() {
+    if (this._destroyed || this.hostOrigin === "*")
+      return Promise.reject(new Error("Authentication is not initialized."));
     if (this._pendingRefresh) return this._pendingRefresh;
     const requestId = crypto.randomUUID();
-    this._pendingRefresh = new Promise((resolve) => {
+    this._requestId = requestId;
+    this._pendingRefresh = new Promise((resolve, reject) => {
       this._refreshResolve = resolve;
+      this._refreshReject = reject;
     });
+    this._requestTimer = setTimeout(() => this.failRefresh("Token refresh timed out."), 2e4);
     const message = {
       type: "verentis:token:refresh",
       version: 1,
@@ -68,21 +83,35 @@ var BridgeAuth = class {
     return this._pendingRefresh;
   }
   handleMessage(event) {
-    if (event.origin !== this.hostOrigin) return;
+    if (this._destroyed || event.origin !== this.hostOrigin || event.source !== window.parent) return;
     const data = event.data;
-    if (data?.type !== "verentis:token:refreshed") return;
+    if (data?.version !== 1 || data?.type !== "verentis:token:refreshed" || !this._requestId || data.requestId !== this._requestId || typeof data.token?.accessToken !== "string" || !Number.isFinite(Date.parse(data.token.expiresAt)) || Date.parse(data.token.expiresAt) <= Date.now() + SKEW_MS) return;
+    if (this._requestTimer) clearTimeout(this._requestTimer);
+    this._requestTimer = null;
+    this._requestId = null;
     this._token = data.token.accessToken;
     this._expiresAt = new Date(data.token.expiresAt).getTime();
     this._pendingRefresh = null;
     this._refreshResolve?.();
     this._refreshResolve = null;
+    this._refreshReject = null;
     this.scheduleRefresh();
   }
   scheduleRefresh() {
     if (this._refreshTimer) clearTimeout(this._refreshTimer);
     if (this._expiresAt === 0) return;
     const delay2 = Math.max(0, this._expiresAt - Date.now() - SKEW_MS);
-    this._refreshTimer = setTimeout(() => void this.requestRefresh(), delay2);
+    this._refreshTimer = setTimeout(() => void this.requestRefresh().catch(() => {
+    }), delay2);
+  }
+  failRefresh(message) {
+    if (this._requestTimer) clearTimeout(this._requestTimer);
+    this._requestTimer = null;
+    this._requestId = null;
+    this._pendingRefresh = null;
+    this._refreshReject?.(new Error(message));
+    this._refreshReject = null;
+    this._refreshResolve = null;
   }
 };
 
@@ -754,8 +783,24 @@ function isHeaderAction(value) {
 
 // src/transport/bridge.transport.ts
 var Bridge = class {
+  constructor(expectedHostOrigin) {
+    this.expectedHostOrigin = expectedHostOrigin;
+    this._initPromise = new Promise((resolve, reject) => {
+      this._initResolve = resolve;
+      this._initReject = reject;
+    });
+    void this._initPromise.catch(() => {
+    });
+    this._messageHandler = this.handleMessage.bind(this);
+    if (typeof window !== "undefined") {
+      window.addEventListener("message", this._messageHandler);
+    }
+  }
+  expectedHostOrigin;
   listeners = /* @__PURE__ */ new Map();
   _initResolve;
+  _initReject;
+  _initTimer;
   _initPromise;
   _hostOrigin = null;
   _messageHandler;
@@ -763,15 +808,8 @@ var Bridge = class {
   sessionId = null;
   actions = /* @__PURE__ */ new Map();
   requests = /* @__PURE__ */ new Set();
-  constructor() {
-    this._initPromise = new Promise((resolve) => {
-      this._initResolve = resolve;
-    });
-    this._messageHandler = this.handleMessage.bind(this);
-    if (typeof window !== "undefined") {
-      window.addEventListener("message", this._messageHandler);
-    }
-  }
+  backendRequests = /* @__PURE__ */ new Map();
+  wopiRequests = /* @__PURE__ */ new Map();
   /** Post `verentis:ready` to the host to start the handshake */
   sendReady(capabilities) {
     console.info("[Verentis SDK] Sending verentis:ready to host");
@@ -780,10 +818,16 @@ var Bridge = class {
       version: 1,
       capabilities
     };
-    window.parent.postMessage(message, "*");
+    window.parent.postMessage(message, this.expectedHostOrigin ?? "*");
   }
   /** Wait for the host to send `verentis:init` with context and token */
   waitForInit() {
+    if (!this._hostOrigin && !this._destroyed && !this._initTimer) {
+      this._initTimer = setTimeout(() => {
+        this._initReject(new Error("Workspace handshake timed out."));
+        this.destroy();
+      }, 2e4);
+    }
     return this._initPromise;
   }
   /** Get the host origin (available after init) */
@@ -827,6 +871,75 @@ var Bridge = class {
   setDirty(isDirty) {
     this.postToHost({ type: "verentis:dirty", version: 1, isDirty });
   }
+  /** The host, not the app, selects the installation, file, branch and permission ceiling. */
+  requestBackendCredential() {
+    if (this._destroyed || !this.sessionId || !this._hostOrigin)
+      return Promise.reject(new Error("An initialized workspace host is required."));
+    if (this.backendRequests.size >= 4)
+      return Promise.reject(new Error("A backend credential request is already pending."));
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.backendRequests.delete(requestId);
+        reject(new Error("Backend authorization timed out."));
+      }, 2e4);
+      this.backendRequests.set(requestId, { resolve, reject, timer });
+      try {
+        this.postToHost({ type: "verentis:backend:request", version: 1, requestId, sessionId: this.sessionId });
+      } catch {
+        clearTimeout(timer);
+        this.backendRequests.delete(requestId);
+        reject(new Error("The workspace host is unavailable."));
+      }
+    });
+  }
+  /** The trusted parent selects the approved installation, document and action. */
+  requestWopiLaunch() {
+    return this.requestWopi("launch");
+  }
+  /** Recover only the target selected by a completed server-owned derived operation. */
+  requestWopiContinuation() {
+    return this.requestWopi("continue");
+  }
+  getWopiStatus() {
+    return this.requestWopi("status");
+  }
+  requestWopiSave(generation) {
+    if (!Number.isSafeInteger(generation) || generation < 0)
+      return Promise.reject(new Error("Invalid edit generation."));
+    return this.requestWopi("save", generation);
+  }
+  closeWopiSession() {
+    return this.requestWopi("close");
+  }
+  requestWopi(operation, generation) {
+    if (this._destroyed || !this.sessionId || !this._hostOrigin)
+      return Promise.reject(new Error("An initialized workspace host is required."));
+    if (this.wopiRequests.size >= 4)
+      return Promise.reject(new Error("Too many collaboration requests."));
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.wopiRequests.delete(requestId);
+        reject(new Error("Collaboration authorization timed out."));
+      }, 3e4);
+      this.wopiRequests.set(requestId, { resolve, reject, timer });
+      try {
+        this.postToHost({
+          type: "verentis:wopi:request",
+          version: 1,
+          requestId,
+          sessionId: this.sessionId,
+          operation,
+          ...generation === void 0 ? {} : { generation }
+        });
+      } catch {
+        clearTimeout(timer);
+        this.wopiRequests.delete(requestId);
+        reject(new Error("The workspace host is unavailable."));
+      }
+    });
+  }
   registerAction(descriptor, handler) {
     if (!this.sessionId || this._destroyed) throw new Error("Header actions require an initialized workspace host.");
     if (!isHeaderAction(descriptor)) throw new Error("Invalid header action.");
@@ -903,9 +1016,22 @@ var Bridge = class {
   /** Clean up event listeners */
   destroy() {
     this._destroyed = true;
+    clearTimeout(this._initTimer);
+    this._initTimer = void 0;
+    if (!this._hostOrigin) this._initReject(new Error("Bridge has been destroyed."));
     this.actions.clear();
     this.requests.clear();
     this.listeners.clear();
+    for (const pending of this.backendRequests.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Bridge has been destroyed."));
+    }
+    this.backendRequests.clear();
+    for (const pending of this.wopiRequests.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Bridge has been destroyed."));
+    }
+    this.wopiRequests.clear();
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
     }
@@ -915,8 +1041,12 @@ var Bridge = class {
     const data = event.data;
     if (event.source !== window.parent || data?.version !== 1 || typeof data?.type !== "string" || !data.type.startsWith("verentis:")) return;
     if (this._hostOrigin && event.origin !== this._hostOrigin) return;
+    if (this.expectedHostOrigin && event.origin !== this.expectedHostOrigin) return;
     if (data.type === "verentis:init") {
       if (this._hostOrigin) return;
+      if (!data.context?.workspace?.id || !data.token || event.origin === "null") return;
+      clearTimeout(this._initTimer);
+      this._initTimer = void 0;
       this._hostOrigin = event.origin;
       this.sessionId = typeof data.sessionId === "string" ? data.sessionId : null;
       console.info("[Verentis SDK] Received verentis:init from host", {
@@ -927,6 +1057,29 @@ var Bridge = class {
       const initData = data;
       this._initResolve({ context: initData.context, token: initData.token });
     }
+    if (data.type === "verentis:backend:response") {
+      if (!this._hostOrigin || data.sessionId !== this.sessionId) return;
+      const pending = this.backendRequests.get(data.requestId);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      this.backendRequests.delete(data.requestId);
+      const value = data.credential;
+      if (data.error || !value || typeof value.launchCredential !== "string" || value.launchCredential.length > 512 || !value.launchCredential || typeof value.delegationId !== "string" || typeof value.backendClientId !== "string" || !Number.isFinite(Date.parse(value.expiresAt)) || Date.parse(value.expiresAt) <= Date.now())
+        pending.reject(new Error("Backend authorization was denied or is not configured."));
+      else pending.resolve(value);
+      return;
+    }
+    if (data.type === "verentis:wopi:response") {
+      if (!this._hostOrigin || data.sessionId !== this.sessionId) return;
+      const pending = this.wopiRequests.get(data.requestId);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      this.wopiRequests.delete(data.requestId);
+      if (data.error || !Object.hasOwn(data, "result"))
+        pending.reject(new Error("Collaboration authorization is unavailable."));
+      else pending.resolve(data.result);
+      return;
+    }
     if (data.type === "verentis:action:invoke") {
       void this.invokeAction(data);
       return;
@@ -1112,7 +1265,7 @@ var VerentisClient = class {
     this.bridge.sendReady();
     const { context, token } = await this.bridge.waitForInit();
     const hostOrigin = this.bridge.hostOrigin;
-    Object.assign(bridgeAuth, new BridgeAuth(hostOrigin));
+    bridgeAuth.setHostOrigin(hostOrigin);
     bridgeAuth.setToken(token);
     this.context.setFromAppContext(context);
     const http = new HttpTransport(