@mdbase-dev/connect 0.1.0-beta.27 → 0.1.0-beta.29

package/dist/application-session.js

@@ -0,0 +1,302 @@
+import { capabilityOperations, operationsForApplicationCapabilities } from "@mdbase-dev/connect-protocol";
+/* The versioned protocol package is the sole capability-to-operation compiler. */
+import { effectiveCapabilities } from "./capabilities.js";
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+import { MdbaseSession } from "./session.js";
+export class MdbaseMemoryVerificationStore {
+    values = new Map();
+    read(key) {
+        return this.values.get(key) ?? null;
+    }
+    write(key, value) {
+        this.values.set(key, value);
+    }
+    remove(key) {
+        this.values.delete(key);
+    }
+}
+/**
+ * The application-level lifecycle boundary. It derives authorization from the
+ * bundled manifest, exposes semantic capabilities, and never mutates collection
+ * definitions without an explicit `applyDefinitionUpdates` call.
+ */
+export class MdbaseApplicationSession {
+    connect;
+    options;
+    listeners = new Set();
+    verificationStore;
+    snapshot = { status: "opening", connections: [] };
+    manifest = null;
+    base = null;
+    stopBase;
+    reviewEntries = [];
+    verificationGeneration = 0;
+    constructor(connect, options) {
+        this.connect = connect;
+        this.options = options;
+        this.verificationStore = options.verificationStore ?? defaultVerificationStore();
+    }
+    async start() {
+        const manifest = await this.connect.manifest();
+        if (!manifest.ok)
+            return manifest;
+        const capabilities = manifest.value.requirements?.capabilities;
+        if (!capabilities) {
+            return connectFailure(connectProblem("invalid_application_manifest", "Application sessions require a versioned semantic capability contract.", {
+                details: {
+                    issues: [{
+                            path: "/requirements/capabilities",
+                            keyword: "required",
+                            message: "is required for application sessions",
+                            params: {}
+                        }]
+                }
+            }));
+        }
+        this.manifest = manifest.value;
+        this.base = new MdbaseSession(this.connect, {
+            selection: this.options.selection,
+            autoSelect: this.options.autoSelect,
+            operations: operationsForSession(capabilities)
+        });
+        this.stopBase = this.base.subscribe(() => this.refresh());
+        const started = await this.base.start();
+        if (!started.ok)
+            return started;
+        await this.refresh(true);
+        return connectSuccess(this.snapshot);
+    }
+    destroy() {
+        this.verificationGeneration += 1;
+        this.stopBase?.();
+        this.stopBase = undefined;
+        this.base?.destroy();
+        this.base = null;
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    connection() {
+        const current = this.base?.getSnapshot();
+        return current?.status === "ready" ? current.connection : null;
+    }
+    select(collectionId, options = {}) {
+        return this.requireBase().select(collectionId, options);
+    }
+    clearSelection(options = {}) {
+        this.requireBase().clearSelection(options);
+    }
+    forget(collectionId) {
+        this.requireBase().forget(collectionId);
+    }
+    authorize(target, options = {}) {
+        return this.requireBase().authorize(target, options);
+    }
+    handleAuthorizationCallback(callbackUrl) {
+        return this.requireBase().handleAuthorizationCallback(callbackUrl);
+    }
+    ensureCapabilities(capabilities) {
+        const manifestRequirements = this.requireManifest().requirements?.capabilities;
+        const declared = new Set([
+            ...(manifestRequirements?.required ?? []),
+            ...(manifestRequirements?.optional ?? [])
+        ]);
+        if (capabilities.some((capability) => !declared.has(capability))) {
+            return Promise.resolve(connectFailure(connectProblem("invalid_application_manifest", "Applications may only request capabilities declared in their manifest.", {
+                details: {
+                    issues: [{
+                            path: "/requirements/capabilities",
+                            keyword: "undeclaredCapability",
+                            message: "must declare every capability requested by the application",
+                            params: {
+                                requested: capabilities,
+                                declared: [...declared]
+                            }
+                        }]
+                }
+            })));
+        }
+        return this.requireBase().ensureOperations(operationsForIds(capabilities));
+    }
+    async applyDefinitionUpdates() {
+        if (this.snapshot.status !== "definition_review_required" || this.reviewEntries.length === 0) {
+            return connectFailure(connectProblem("collection_not_ready", "There are no reviewed definition updates to apply."));
+        }
+        if (this.reviewEntries.some(({ assessment }) => !assessment.applicable)) {
+            return connectFailure(connectProblem("collection_not_ready", "Resolve the definition conflicts before applying this update."));
+        }
+        const connection = this.connection();
+        if (!connection) {
+            return connectFailure(connectProblem("collection_not_ready", "The collection is not ready."));
+        }
+        for (const { provision, assessment } of this.reviewEntries) {
+            const applied = await connection.applyTypePack({
+                provision,
+                installed_by: this.requireManifest().id,
+                expected_assessment_digest: assessment.assessment_digest,
+                ...(assessment.status === "downgrade" ? { allow_downgrade: true } : {})
+            });
+            if (!applied.ok)
+                return applied;
+        }
+        this.reviewEntries = [];
+        await this.verifyDefinitions(this.context(connection), ++this.verificationGeneration);
+        return connectSuccess(this.snapshot);
+    }
+    async refresh(awaitVerification = false) {
+        if (!this.base || !this.manifest)
+            return;
+        const current = this.base.getSnapshot();
+        this.verificationGeneration += 1;
+        const generation = this.verificationGeneration;
+        this.reviewEntries = [];
+        if (current.status === "unselected") {
+            this.publish({ status: "unselected", connections: current.connections });
+            return;
+        }
+        if (current.status === "unavailable") {
+            this.publish(current);
+            return;
+        }
+        const context = this.context(current.connection);
+        if (!context.capabilities.requiredAvailable) {
+            this.publish({ status: "authorization_required", ...context });
+            return;
+        }
+        const managesDefinitions = this.manifest.requirements?.capabilities?.required
+            .includes("definitions.type-pack.apply") ?? false;
+        const provisions = managesDefinitions
+            ? this.manifest.provisions?.type_packs ?? []
+            : [];
+        if (provisions.length === 0) {
+            this.publish({ status: "ready", verification: "verified", ...context });
+            return;
+        }
+        const key = verificationKey(this.manifest, current.collectionId);
+        if (this.verificationStore.read(key) === verificationValue(this.manifest)) {
+            this.publish({ status: "ready", verification: "cached", ...context });
+        }
+        else {
+            this.publish({ status: "checking_definitions", ...context });
+        }
+        const verification = this.verifyDefinitions(context, generation);
+        if (awaitVerification)
+            await verification;
+    }
+    async verifyDefinitions(context, generation) {
+        const connection = this.connection();
+        const manifest = this.requireManifest();
+        if (!connection || connection.collectionId !== context.collectionId)
+            return;
+        const entries = [];
+        const managesDefinitions = manifest.requirements?.capabilities?.required
+            .includes("definitions.type-pack.apply") ?? false;
+        for (const provision of managesDefinitions ? manifest.provisions?.type_packs ?? [] : []) {
+            const outcome = await connection.assessTypePack({
+                provision,
+                installed_by: manifest.id
+            });
+            if (generation !== this.verificationGeneration)
+                return;
+            if (!outcome.ok) {
+                this.publish({ status: "blocked", problem: outcome.problem, ...context });
+                return;
+            }
+            if (outcome.value.status !== "current") {
+                entries.push({ provision, assessment: outcome.value });
+            }
+        }
+        if (generation !== this.verificationGeneration)
+            return;
+        if (entries.length > 0) {
+            this.reviewEntries = entries;
+            this.verificationStore.remove(verificationKey(manifest, context.collectionId));
+            this.publish({
+                status: "definition_review_required",
+                updates: entries.map(definitionUpdate),
+                ...context
+            });
+            return;
+        }
+        this.verificationStore.write(verificationKey(manifest, context.collectionId), verificationValue(manifest));
+        this.publish({ status: "ready", verification: "verified", ...context });
+    }
+    context(connection) {
+        const info = connection.info();
+        return {
+            collectionId: connection.collectionId,
+            info,
+            capabilities: effectiveCapabilities(this.requireManifest().requirements.capabilities, this.requireManifest(), info),
+            connections: this.connect.connections()
+        };
+    }
+    publish(snapshot) {
+        if (JSON.stringify(this.snapshot) === JSON.stringify(snapshot))
+            return;
+        this.snapshot = snapshot;
+        for (const listener of this.listeners)
+            listener();
+    }
+    requireBase() {
+        if (!this.base)
+            throw new Error("Start the application session before using it.");
+        return this.base;
+    }
+    requireManifest() {
+        if (!this.manifest)
+            throw new Error("Start the application session before using it.");
+        return this.manifest;
+    }
+}
+function operationsForSession(requirements) {
+    return operationsForApplicationCapabilities(requirements);
+}
+function operationsForIds(capabilities) {
+    const definitions = capabilities.flatMap((id) => capabilityOperations(id));
+    return [...new Set(definitions)];
+}
+function definitionUpdate(entry) {
+    const { assessment } = entry;
+    const statusReason = assessment.status === "conflict"
+        ? "Existing user-owned resources conflict with this application definition pack."
+        : assessment.status === "install"
+            ? "This collection needs the application definitions installed."
+            : `This collection has a ${assessment.status} definition change to review.`;
+    return {
+        id: assessment.desired.id,
+        name: entry.provision.manifest.name ?? assessment.desired.id,
+        status: assessment.status,
+        applicable: assessment.applicable,
+        assessmentDigest: assessment.assessment_digest,
+        ...(assessment.current ? { currentVersion: assessment.current.version } : {}),
+        desiredVersion: assessment.desired.version,
+        resources: assessment.resources,
+        contractSetups: assessment.contract_setups,
+        canApply: assessment.applicable,
+        reason: statusReason
+    };
+}
+function verificationKey(manifest, collectionId) {
+    return `mdbase-application-session:v1:${manifest.id}:${collectionId}`;
+}
+function verificationValue(manifest) {
+    return JSON.stringify({
+        capabilities: manifest.requirements?.capabilities,
+        provisions: manifest.provisions?.type_packs ?? []
+    });
+}
+function defaultVerificationStore() {
+    if (typeof localStorage !== "undefined") {
+        return {
+            read: (key) => localStorage.getItem(key),
+            write: (key, value) => localStorage.setItem(key, value),
+            remove: (key) => localStorage.removeItem(key)
+        };
+    }
+    return new MdbaseMemoryVerificationStore();
+}

package/dist/browser/integrity.json

@@ -1,4 +1,4 @@
 {
   "file": "mdbase-connect.min.js",
-  "integrity": "sha384-DjJkmk65xgvpJONlTzVuGLRLNCDOhbOdcG4xoq+le2zjOf+cYDEiN4Ctdl+HyrCL"
+  "integrity": "sha384-Cw/OpEwBlbmIBjDZ/JDyh1HiQoKqitRwVSPaYpNCg33rNDYZr/EdSxv5oRa4jP+I"
 }