@privos_ai/app-server 0.7.2 → 0.8.0

package/dist/relay/relay-client.js

@@ -5,12 +5,111 @@ import { buildHubUserTokenAuthOptions, extractRelayUserTokenCredential, } from '
 import { AppServerRuntime, DEFAULT_MAX_MESSAGE_BYTES, relayCallerAuthSurface, resolveCallerCredential, } from '../runtime.js';
 import { MessageTooLargeError, rawDataToText } from './message-adapter.js';
 import { isStandaloneControlMethod, } from './standalone-control.js';
-import { saveStandaloneIdentity, standaloneHubFingerprint, } from './standalone-identity.js';
+import { consumeStandalonePendingIdentity, loadStandaloneIdentity, loadStandalonePendingIdentity, resolveIdentityFilePath, saveStandaloneIdentity, saveStandalonePendingIdentity, standaloneHubFingerprint, standaloneIdentityFileExists, StandaloneIdentityError, } from './standalone-identity.js';
+import { lintManifest, sha256CanonicalJson } from '../manifest-tools.js';
 import { assertRuntimeDispatchTrustConfigurationV3, extractRuntimeDispatchRelayEnvelopeV3, verifyRuntimeDispatchAssertionV3, } from '../workload/dispatch-assertion.js';
 const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
 const DEFAULT_PAIRING_TIMEOUT_MS = 30_000;
 const DEFAULT_OAUTH_TIMEOUT_MS = 15_000;
 const DEFAULT_OPEN_HANDSHAKE_TIMEOUT_MS = 15_000;
+function sortedUniqueStrings(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item)) {
+        throw new Error(`Pairing response ${field} is invalid.`);
+    }
+    const result = [...value].sort();
+    if (new Set(result).size !== result.length)
+        throw new Error(`Pairing response ${field} contains duplicates.`);
+    return result;
+}
+function manifestDeclaredPermissionCeiling(manifest) {
+    if (!Array.isArray(manifest.permissions))
+        throw new Error('Published v3 manifest must declare permissions.');
+    return sortedUniqueStrings(manifest.permissions.map((permission) => permission && typeof permission === 'object' && !Array.isArray(permission)
+        ? permission.scope
+        : undefined), 'manifest permission ceiling');
+}
+async function persistCompletedPairing(input) {
+    assertRuntimeDispatchTrustConfigurationV3(input.wire.trust);
+    const trust = input.wire.trust;
+    const fingerprint = standaloneHubFingerprint(trust.hubKid);
+    if (input.wire.fingerprint !== undefined && input.wire.fingerprint !== fingerprint) {
+        throw new Error('Pairing response fingerprint does not match the pinned Hub key.');
+    }
+    if (trust.affinity.mcpAppId !== input.mcpAppId)
+        throw new Error('Pairing completion changed the app identity.');
+    if (input.wire.manifestDigest && input.wire.manifestDigest !== trust.affinity.manifestDigest) {
+        throw new Error('Pairing completion manifest digest does not match dispatch affinity.');
+    }
+    let approvedPermissionCeiling;
+    if (input.wire.approvedPermissionCeiling !== undefined) {
+        approvedPermissionCeiling = sortedUniqueStrings(input.wire.approvedPermissionCeiling, 'approvedPermissionCeiling');
+    }
+    if (input.pending) {
+        if (input.pending.clientId !== input.clientId ||
+            input.pending.oauthClientId !== input.wire.oauthClientId ||
+            input.pending.mcpAppId !== input.mcpAppId ||
+            input.pending.pairingId !== input.wire.pairingId ||
+            input.pending.manifestDigest !== trust.affinity.manifestDigest ||
+            input.pending.permissionContractHash !== input.wire.permissionContractHash ||
+            input.pending.hubKid !== trust.hubKid ||
+            input.pending.fingerprint !== fingerprint) {
+            throw new Error('Pairing completion does not match the durable pending identity.');
+        }
+        if (!approvedPermissionCeiling)
+            throw new Error('Pairing completion omitted the approved permission ceiling.');
+        const declared = new Set(input.pending.declaredPermissionCeiling);
+        if (approvedPermissionCeiling.some((scope) => !declared.has(scope))) {
+            throw new Error('Pairing completion widened the published permission ceiling.');
+        }
+    }
+    (input.options?.onFingerprint ?? ((line) => console.log(line)))(`PrivOS Hub fingerprint: ${fingerprint} — verify this out-of-band before trusting dispatch from this Hub.`);
+    let identityFilePath;
+    if (input.options?.persistIdentityFile ?? true) {
+        const identity = {
+            pairingVersion: 2,
+            relayUrl: input.privosUrl,
+            clientId: input.clientId,
+            clientSecret: input.clientSecret,
+            trust,
+            fingerprint,
+            mcpAppId: input.mcpAppId,
+            pairedAt: Date.now(),
+        };
+        try {
+            identityFilePath = await saveStandaloneIdentity(identity, { filePath: input.options?.identityFilePath });
+        }
+        catch (error) {
+            const existing = loadStandaloneIdentity({ filePath: input.options?.identityFilePath });
+            if (existing.identity.relayUrl !== identity.relayUrl ||
+                existing.identity.clientId !== identity.clientId ||
+                existing.identity.clientSecret !== identity.clientSecret ||
+                existing.identity.mcpAppId !== identity.mcpAppId ||
+                JSON.stringify(existing.identity.trust) !== JSON.stringify(identity.trust)) {
+                throw error;
+            }
+            identityFilePath = existing.filePath;
+        }
+        if (input.pending) {
+            await consumeStandalonePendingIdentity(input.pending, {
+                filePath: input.options?.pendingIdentityFilePath,
+                finalIdentityFilePath: input.options?.identityFilePath,
+            });
+        }
+    }
+    return {
+        state: 'complete',
+        privosUrl: input.privosUrl,
+        clientId: input.clientId,
+        clientSecret: input.clientSecret,
+        mcpAppId: input.mcpAppId,
+        pairingVersion: 2,
+        trust,
+        fingerprint,
+        manifestDigest: trust.affinity.manifestDigest,
+        ...(approvedPermissionCeiling ? { approvedPermissionCeiling } : {}),
+        ...(identityFilePath ? { identityFilePath } : {}),
+    };
+}
 /**
  * Pair with Privos using a one-time pairing URL.
  *
@@ -21,10 +120,27 @@ const DEFAULT_OPEN_HANDSHAKE_TIMEOUT_MS = 15_000;
  * create — same discipline as the Hub's own identity file), then prints the
  * Hub fingerprint for out-of-band operator verification. Set
  * `persistIdentityFile: false` to opt out and handle persistence yourself.
+ *
+ * If the socket closes after the Hub has persisted registration but before
+ * this function receives the result, the caller may explicitly invoke this
+ * function again with the same pairing URL and byte-semantically identical
+ * published manifest during the Hub's bounded recovery window. There is no
+ * automatic retry or polling loop: a changed URL, manifest, or authority must
+ * fail at the Hub rather than being hidden by client-side retry behavior.
  */
 export function pairOverWebSocket(pairUrl, appMeta, WebSocketImpl = WebSocket, options) {
     const timeoutMs = options?.timeoutMs ?? DEFAULT_PAIRING_TIMEOUT_MS;
     const persistIdentityFile = options?.persistIdentityFile ?? true;
+    // Fail fast BEFORE registering: an existing identity file makes the persist
+    // step (or the poll loop in pairAndAwaitApproval) throw at the very end, but
+    // only after the WebSocket handshake has already registered a fresh pending
+    // row on the Hub — every retry then churns a dead installation there. Refuse
+    // up front with the same error so re-pairing never touches the Hub until the
+    // operator has removed the stale file or chosen rotation.
+    if (persistIdentityFile && standaloneIdentityFileExists({ filePath: options?.identityFilePath })) {
+        const filePath = resolveIdentityFilePath(options?.identityFilePath);
+        return Promise.reject(new StandaloneIdentityError('IDENTITY_FILE_ALREADY_EXISTS', `Standalone identity file ${filePath} already exists. Remove it before re-pairing, or use rotation for an in-place credential change.`));
+    }
     return new Promise((resolve, reject) => {
         const ws = new WebSocketImpl(pairUrl);
         let settled = false;
@@ -47,26 +163,98 @@ export function pairOverWebSocket(pairUrl, appMeta, WebSocketImpl = WebSocket, o
             });
         }, timeoutMs);
         async function finishPairing(input) {
-            if (input.pairingVersion !== 2) {
-                // Either a v1 Hub, or a manifest-announced registration still awaiting
-                // approval: both hand back credentials and nothing to persist, because
+            if (input.wire.pairingVersion !== 2) {
+                // Either a v1 Hub, or a Hub generation that acknowledges a
+                // manifest-announced registration with only `awaitingApproval`:
+                // both hand back credentials and nothing to persist, because
                 // trust is minted with the generation an approved ceiling creates.
                 return {
+                    state: 'legacy-complete',
+                    privosUrl: input.privosUrl,
+                    clientId: input.clientId,
+                    clientSecret: input.clientSecret,
+                    mcpAppId: input.mcpAppId,
+                    ...(input.wire.awaitingApproval ? { awaitingApproval: true } : {}),
+                };
+            }
+            if (!input.mcpAppId)
+                throw new Error('Pairing v2 response missing app identity.');
+            if (input.wire.pairingState === 'pending-approval') {
+                if (!appMeta.manifest)
+                    throw new Error('Pending manifest pairing response was not requested with an exact manifest.');
+                const declaredPermissionCeiling = sortedUniqueStrings(input.wire.declaredPermissionCeiling, 'declaredPermissionCeiling');
+                const localDeclaredPermissionCeiling = manifestDeclaredPermissionCeiling(appMeta.manifest);
+                const manifestDigest = sha256CanonicalJson(appMeta.manifest);
+                if (input.wire.manifestDigest !== manifestDigest ||
+                    JSON.stringify(declaredPermissionCeiling) !== JSON.stringify(localDeclaredPermissionCeiling) ||
+                    !input.wire.pairingId ||
+                    !input.wire.oauthClientId ||
+                    input.wire.oauthClientId !== input.clientId ||
+                    !input.wire.permissionContractHash ||
+                    !input.wire.hubKid) {
+                    throw new Error('Pending pairing response does not match the exact published manifest or OAuth identity.');
+                }
+                const fingerprint = standaloneHubFingerprint(input.wire.hubKid);
+                if (input.wire.fingerprint !== fingerprint)
+                    throw new Error('Pending pairing Hub fingerprint is invalid.');
+                (options?.onFingerprint ?? ((line) => console.log(line)))(`PrivOS Hub fingerprint: ${fingerprint} — verify this out-of-band before approving this app.`);
+                const pending = {
+                    pairingVersion: 2,
+                    state: 'pending-approval',
+                    relayUrl: input.privosUrl,
+                    clientId: input.clientId,
+                    clientSecret: input.clientSecret,
+                    mcpAppId: input.mcpAppId,
+                    pairingId: input.wire.pairingId,
+                    oauthClientId: input.wire.oauthClientId,
+                    manifestDigest,
+                    permissionContractHash: input.wire.permissionContractHash,
+                    declaredPermissionCeiling,
+                    hubKid: input.wire.hubKid,
+                    fingerprint,
+                    createdAt: Date.now(),
+                };
+                const pendingIdentityFilePath = persistIdentityFile
+                    ? await saveStandalonePendingIdentity(pending, {
+                        filePath: options?.pendingIdentityFilePath,
+                        finalIdentityFilePath: options?.identityFilePath,
+                    })
+                    : undefined;
+                return {
+                    state: 'pending-approval',
                     privosUrl: input.privosUrl,
                     clientId: input.clientId,
                     clientSecret: input.clientSecret,
                     mcpAppId: input.mcpAppId,
-                    ...(input.awaitingApproval ? { awaitingApproval: true } : {}),
+                    pairingVersion: 2,
+                    pairingId: pending.pairingId,
+                    oauthClientId: pending.oauthClientId,
+                    manifestDigest,
+                    permissionContractHash: pending.permissionContractHash,
+                    declaredPermissionCeiling,
+                    hubKid: pending.hubKid,
+                    fingerprint,
+                    awaitingApproval: true,
+                    ...(pendingIdentityFilePath ? { pendingIdentityFilePath } : {}),
                 };
             }
-            return persistPairedV2Identity(input, {
-                onFingerprint: options?.onFingerprint,
-                persistIdentityFile,
-                identityFilePath: options?.identityFilePath,
+            return persistCompletedPairing({
+                wire: input.wire,
+                privosUrl: input.privosUrl,
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
+                mcpAppId: input.mcpAppId,
+                options,
             });
         }
         ws.on('open', () => {
             try {
+                if (appMeta.manifest) {
+                    const lint = lintManifest(appMeta.manifest);
+                    if (appMeta.manifest.schemaVersion !== 3 || !lint.valid) {
+                        throw new Error(`Exact standalone manifest is not a valid schema-v3 manifest: ${lint.errors.join('; ')}`);
+                    }
+                }
                 ws.send(JSON.stringify({
                     name: appMeta.name,
                     description: appMeta.description || '',
@@ -74,7 +262,7 @@ export function pairOverWebSocket(pairUrl, appMeta, WebSocketImpl = WebSocket, o
                     ...(appMeta.icon && { icon: appMeta.icon }),
                     ...(appMeta.scopes?.length && { scopes: appMeta.scopes }),
                     ...(appMeta.permissions?.length && { permissions: appMeta.permissions }),
-                    ...(appMeta.manifest !== undefined && { manifest: appMeta.manifest }),
+                    ...(appMeta.manifest ? { manifest: appMeta.manifest } : {}),
                 }));
             }
             catch (err) {
@@ -88,8 +276,8 @@ export function pairOverWebSocket(pairUrl, appMeta, WebSocketImpl = WebSocket, o
                     settle(() => reject(new Error(msg.error?.message || 'Pairing failed')));
                     return;
                 }
-                if (msg.result?.paired) {
-                    const { clientId, clientSecret, relayUrl, app, mcpAppId, appId, pairingVersion, trust, fingerprint, awaitingApproval } = msg.result;
+                if (msg.result && (msg.result.paired || msg.result.pairingState === 'pending-approval')) {
+                    const { clientId, clientSecret, relayUrl, app, mcpAppId, appId } = msg.result;
                     if (!clientId || !clientSecret || !relayUrl) {
                         settle(() => reject(new Error('Pairing response missing credentials')));
                         return;
@@ -101,14 +289,11 @@ export function pairOverWebSocket(pairUrl, appMeta, WebSocketImpl = WebSocket, o
                         undefined;
                     settle(() => {
                         void finishPairing({
+                            wire: msg.result,
                             privosUrl,
                             clientId,
                             clientSecret,
                             mcpAppId: resolvedAppId,
-                            pairingVersion,
-                            trust,
-                            fingerprint,
-                            awaitingApproval: awaitingApproval === true,
                         })
                             .then(resolve)
                             .catch(reject);
@@ -142,40 +327,6 @@ export function pairOverWebSocket(pairUrl, appMeta, WebSocketImpl = WebSocket, o
     });
 }
 const DEFAULT_APPROVAL_TIMEOUT_MS = 30 * 60_000;
-/** Validate a v2 trust payload, verify the fingerprint, and persist the identity file. */
-async function persistPairedV2Identity(input, options) {
-    assertRuntimeDispatchTrustConfigurationV3(input.trust);
-    const trust = input.trust;
-    const fingerprint = standaloneHubFingerprint(trust.hubKid);
-    if (input.fingerprint !== undefined && input.fingerprint !== fingerprint) {
-        throw new Error('Pairing response fingerprint does not match the pinned Hub key.');
-    }
-    (options.onFingerprint ?? ((line) => console.log(line)))(`PrivOS Hub fingerprint: ${fingerprint} — verify this out-of-band before trusting dispatch from this Hub.`);
-    let identityFilePath;
-    if (options.persistIdentityFile) {
-        const identity = {
-            pairingVersion: 2,
-            relayUrl: input.privosUrl,
-            clientId: input.clientId,
-            clientSecret: input.clientSecret,
-            trust,
-            fingerprint,
-            ...(input.mcpAppId ? { mcpAppId: input.mcpAppId } : {}),
-            pairedAt: Date.now(),
-        };
-        identityFilePath = await saveStandaloneIdentity(identity, { filePath: options.identityFilePath });
-    }
-    return {
-        privosUrl: input.privosUrl,
-        clientId: input.clientId,
-        clientSecret: input.clientSecret,
-        mcpAppId: input.mcpAppId,
-        pairingVersion: 2,
-        trust,
-        fingerprint,
-        ...(identityFilePath ? { identityFilePath } : {}),
-    };
-}
 /**
  * Normalize a Hub-supplied relay URL (`wss://host/api/v1/mcp-apps.relay`) to the
  * bare Hub HTTP origin the identity file stores as `relayUrl`/`privosUrl`. serveApp
@@ -196,8 +347,9 @@ function pairPollTarget(pairUrl) {
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * One-command pairing (device-authorization flow). Registers exactly like
- * {@link pairOverWebSocket}; if the Hub answers `awaitingApproval`, this then
- * POLLS the Hub with the SAME pairing token until an admin approves the
+ * {@link pairOverWebSocket}; while the registration awaits an admin's approval
+ * (`pending-approval` state, or a legacy-shaped `awaitingApproval` response),
+ * this POLLS the Hub with the SAME pairing token until the admin approves the
  * permission ceiling, receives the pairing-v2 trust payload, and writes the
  * standalone identity file — no second pairing URL. A Hub that returns trust
  * immediately (already-approved linked pairing, or a v1 Hub) is passed straight
@@ -206,8 +358,8 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  */
 export async function pairAndAwaitApproval(pairUrl, appMeta, WebSocketImpl = WebSocket, options) {
     const registered = await pairOverWebSocket(pairUrl, appMeta, WebSocketImpl, options);
-    // A Hub that already handed trust (linked pairing) or a v1 Hub: nothing to await.
-    if (registered.pairingVersion === 2 || !registered.awaitingApproval)
+    // Trust already delivered (linked pairing), or a v1 Hub with nothing pending: done.
+    if (registered.state === 'complete' || !registered.awaitingApproval)
         return registered;
     const { origin, pairToken } = pairPollTarget(pairUrl);
     if (!pairToken)
@@ -227,14 +379,36 @@ export async function pairAndAwaitApproval(pairUrl, appMeta, WebSocketImpl = Web
         if (body.success === false)
             throw new Error(body.error || 'Pairing poll was rejected');
         if (body.status === 'approved') {
-            return persistPairedV2Identity({
+            const mcpAppId = body.appId ?? registered.mcpAppId;
+            if (!mcpAppId)
+                throw new Error('Pairing approval response missing app identity.');
+            const completed = await persistCompletedPairing({
+                wire: { trust: body.trust, fingerprint: body.fingerprint },
                 privosUrl: body.relayUrl ? relayUrlToPrivosOrigin(body.relayUrl) : registered.privosUrl,
                 clientId: body.clientId ?? registered.clientId,
                 clientSecret: body.clientSecret ?? registered.clientSecret,
-                mcpAppId: body.appId ?? registered.mcpAppId,
-                trust: body.trust,
-                fingerprint: body.fingerprint,
-            }, { onFingerprint: options?.onFingerprint, persistIdentityFile, identityFilePath: options?.identityFilePath });
+                mcpAppId,
+                options,
+            });
+            // The pair-poll response carries no pending-contract echo to cross-check,
+            // so the durable pending half is consumed only after trust verification
+            // above — best-effort, the completed identity file is authoritative.
+            if (registered.state === 'pending-approval' && persistIdentityFile) {
+                try {
+                    const stalePending = loadStandalonePendingIdentity({
+                        filePath: options?.pendingIdentityFilePath,
+                        finalIdentityFilePath: options?.identityFilePath,
+                    });
+                    await consumeStandalonePendingIdentity(stalePending.identity, {
+                        filePath: options?.pendingIdentityFilePath,
+                        finalIdentityFilePath: options?.identityFilePath,
+                    });
+                }
+                catch {
+                    /* pending file already gone — nothing left to consume */
+                }
+            }
+            return completed;
         }
         if (body.status === 'rejected')
             throw new Error('Pairing was rejected — the app was removed. Re-pair from scratch.');
@@ -247,6 +421,125 @@ export async function pairAndAwaitApproval(pairUrl, appMeta, WebSocketImpl = Web
         delayMs = Math.min(Math.round(delayMs * 1.5), 10_000);
     }
 }
+/**
+ * Explicitly resumes one durable app-announced-manifest pairing. This is a
+ * single operator/app action, not a polling loop: a pending Hub replies
+ * pending; an approved Hub returns trust for the same OAuth/app/pairing
+ * identity and the SDK atomically promotes it to the production identity.
+ */
+export async function resumeStandalonePairing(options) {
+    const loaded = loadStandalonePendingIdentity({
+        filePath: options?.pendingIdentityFilePath,
+        finalIdentityFilePath: options?.identityFilePath,
+    });
+    const pending = loaded.identity;
+    const fetchImpl = options?.fetchImpl ?? fetch;
+    const WebSocketImpl = options?.WebSocketImpl ?? WebSocket;
+    const controller = new AbortController();
+    const oauthTimer = setTimeout(() => controller.abort(), options?.oauthTimeoutMs ?? DEFAULT_OAUTH_TIMEOUT_MS);
+    let accessToken;
+    try {
+        const response = await fetchImpl(`${pending.relayUrl}/oauth/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: `grant_type=client_credentials&client_id=${encodeURIComponent(pending.clientId)}&client_secret=${encodeURIComponent(pending.clientSecret)}`,
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`Pairing completion OAuth failed: ${response.status} ${response.statusText}`);
+        const token = (await response.json());
+        if (!token.access_token)
+            throw new Error('Pairing completion OAuth response omitted access_token.');
+        accessToken = token.access_token;
+    }
+    finally {
+        clearTimeout(oauthTimer);
+    }
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_PAIRING_TIMEOUT_MS;
+    const wire = await new Promise((resolve, reject) => {
+        const wsUrl = `${pending.relayUrl.replace(/^http/, 'ws')}/api/v1/mcp-apps.relay?pairingCompletion=1`;
+        const ws = new WebSocketImpl(wsUrl, { headers: { Authorization: `Bearer ${accessToken}` } });
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`Pairing completion timed out after ${timeoutMs}ms`)));
+            try {
+                ws.close();
+            }
+            catch { /* ignore */ }
+        }, timeoutMs);
+        ws.on('message', (raw) => {
+            try {
+                const message = JSON.parse(rawDataToText(raw));
+                if (message.error)
+                    return settle(() => reject(new Error(message.error?.message || 'Pairing completion failed')));
+                if (message.result?.pairingVersion !== 2)
+                    return settle(() => reject(new Error('Pairing completion response is not protocol v2.')));
+                settle(() => resolve(message.result));
+                try {
+                    ws.close();
+                }
+                catch { /* ignore */ }
+            }
+            catch (error) {
+                settle(() => reject(error instanceof Error ? error : new Error(String(error))));
+            }
+        });
+        ws.on('error', (error) => settle(() => reject(new Error(`Pairing completion failed: ${error.message}`))));
+        ws.on('close', (code, reason) => settle(() => reject(new Error(`Pairing completion closed: ${code} ${reason}`))));
+    });
+    if (wire.clientId !== pending.clientId ||
+        wire.oauthClientId !== pending.oauthClientId ||
+        wire.appId !== pending.mcpAppId ||
+        wire.pairingId !== pending.pairingId ||
+        wire.manifestDigest !== pending.manifestDigest ||
+        wire.permissionContractHash !== pending.permissionContractHash ||
+        wire.hubKid !== pending.hubKid ||
+        wire.fingerprint !== pending.fingerprint) {
+        throw new Error('Pairing resume response does not match the durable pending identity.');
+    }
+    if (wire.pairingState === 'pending-approval') {
+        const declaredPermissionCeiling = sortedUniqueStrings(wire.declaredPermissionCeiling, 'declaredPermissionCeiling');
+        if (JSON.stringify(declaredPermissionCeiling) !== JSON.stringify(pending.declaredPermissionCeiling)) {
+            throw new Error('Pairing resume changed the declared permission ceiling.');
+        }
+        return {
+            state: 'pending-approval',
+            privosUrl: pending.relayUrl,
+            clientId: pending.clientId,
+            clientSecret: pending.clientSecret,
+            mcpAppId: pending.mcpAppId,
+            pairingVersion: 2,
+            pairingId: pending.pairingId,
+            oauthClientId: pending.oauthClientId,
+            manifestDigest: pending.manifestDigest,
+            permissionContractHash: pending.permissionContractHash,
+            declaredPermissionCeiling: pending.declaredPermissionCeiling,
+            hubKid: pending.hubKid,
+            fingerprint: pending.fingerprint,
+            awaitingApproval: true,
+            pendingIdentityFilePath: loaded.filePath,
+        };
+    }
+    if (wire.pairingState !== 'complete' || !wire.clientSecret || wire.clientSecret !== pending.clientSecret) {
+        throw new Error('Pairing resume did not return an exact completed identity.');
+    }
+    return persistCompletedPairing({
+        wire,
+        privosUrl: pending.relayUrl,
+        clientId: pending.clientId,
+        clientSecret: pending.clientSecret,
+        mcpAppId: pending.mcpAppId,
+        options,
+        pending,
+    });
+}
 export async function pairFromDescriptor(pairUrl, descriptor, WebSocketImpl, options) {
     return pairOverWebSocket(pairUrl, buildPairingMetadata(descriptor), WebSocketImpl, options);
 }