@mdbase-dev/connect 0.1.0-beta.94 → 0.1.0-beta.96

package/dist/session.js

@@ -1,3 +1,5 @@
+import { APPLICATION_CAPABILITY_DEFINITIONS, capabilityOperationsForContractVersion } from "@mdbase-dev/connect-protocol";
+import { retainedCapabilities, semanticContractVersion, validateAuthorizationSelection } from "./application-contract.js";
 import { authorizationCallbackState, authorizationReturnToFromProblem, isAuthorizationCallbackUrl } from "./authorization-url.js";
 import { MdbaseConnectError, connectProblem } from "./errors.js";
 import { DEFAULT_OPERATIONS } from "./internal-types.js";
@@ -221,9 +223,16 @@ export class MdbaseSession {
         const operation = this.beginLifecycleOperation(options);
         this.transactionDepth += 1;
         try {
+            const declaration = await this.connect.manifest?.(operation.options);
+            if (declaration && !declaration.ok)
+                return declaration;
+            if (!this.lifecycleCurrent(operation.generation))
+                return this.destroyedOutcome(connectSuccess(undefined));
+            const version = declaration ? semanticContractVersion(declaration.value.requirements) : 1;
             const outcome = await this.connect.authorize({
                 ...operation.options,
-                operations: this.operations,
+                ...(version === 1 && options.operations === undefined && options.capabilities === undefined
+                    ? { operations: this.operations } : {}),
                 target: targetCollectionId === null
                     ? { kind: "choose" }
                     : { kind: "collection", collectionId: targetCollectionId },
@@ -242,7 +251,13 @@ export class MdbaseSession {
             this.refresh();
         }
     }
-    async ensureOperations(requiredOperations, options) {
+    ensureOperations(requiredOperations, options) {
+        return this.ensureAuthorization({ operations: requiredOperations }, options);
+    }
+    ensureCapabilities(requiredCapabilities, options) {
+        return this.ensureAuthorization({ capabilities: requiredCapabilities }, options);
+    }
+    async ensureAuthorization(selection, options) {
         const lifecycle = this.lifecycleProblem();
         if (lifecycle)
             return connectFailure(lifecycle);
@@ -250,17 +265,30 @@ export class MdbaseSession {
         if (current.status !== "ready") {
             return connectFailure(connectProblem("collection_not_ready", "Choose an authorized collection first."));
         }
-        const required = uniqueOperations(requiredOperations);
-        const capabilities = current.connection.authorizationCapabilities(required);
-        if (capabilities.sufficient) {
-            return connectSuccess({ kind: "unchanged", connection: current.connection });
-        }
         const operation = this.beginLifecycleOperation(options);
         this.transactionDepth += 1;
         try {
+            const declaration = await this.connect.manifest?.(operation.options);
+            if (declaration && !declaration.ok)
+                return declaration;
+            if (!this.lifecycleCurrent(operation.generation))
+                return this.destroyedOutcome(connectSuccess(undefined));
+            // Custom advanced session adapters predating manifest() retain exact v1
+            // operations. The concrete SDK always supplies its declared manifest.
+            const requirements = declaration?.value.requirements ?? ("operations" in selection
+                ? { access: "full_collection", contracts: [] }
+                : { access: "full_collection", contracts: [], capabilities: { contract_version: 2, required: [], optional: Object.keys(APPLICATION_CAPABILITY_DEFINITIONS) } });
+            validateAuthorizationSelection(requirements, { ...options, ...selection });
+            const requiredOperations = "operations" in selection ? selection.operations : selection.capabilities.flatMap((id) => capabilityOperationsForContractVersion(semanticContractVersion(requirements), id) ?? []);
+            const authorization = current.connection.authorizationCapabilities(requiredOperations);
+            if (authorization.sufficient)
+                return connectSuccess({ kind: "unchanged", connection: current.connection });
+            const incremental = "operations" in selection || semanticContractVersion(requirements) === 1
+                ? { operations: uniqueOperations([...authorization.grantedOperations, ...requiredOperations]) }
+                : { capabilities: [...new Set([...retainedCapabilities(requirements, authorization.grantedOperations), ...selection.capabilities])] };
             const outcome = await this.connect.authorize({
                 ...operation.options,
-                operations: uniqueOperations([...capabilities.grantedOperations, ...capabilities.missingOperations]),
+                ...incremental,
                 target: { kind: "collection", collectionId: current.collectionId },
                 returnTo: this.selection.authorizationReturnTo()
             });
@@ -271,6 +299,11 @@ export class MdbaseSession {
             }
             return outcome;
         }
+        catch (error) {
+            if (error instanceof MdbaseConnectError)
+                return connectFailure(error.problem);
+            throw error;
+        }
         finally {
             operation.dispose();
             this.transactionDepth -= 1;

package/dist/structured-readiness.d.ts

@@ -0,0 +1,77 @@
+import type { ContractRequirement, FileAction, JsonObject } from "@mdbase-dev/connect-protocol";
+import type { MdbaseApplicationManifest } from "./application-contract.js";
+import type { MdbaseConnectionInfo } from "./connection-types.js";
+import { type MdbaseEffectiveCapabilities, type MdbaseCapabilityEvidence } from "./capabilities.js";
+import type { MdbaseConnection } from "./connection.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
+type ReadinessPublication = {
+    status: "authorization_required";
+} | {
+    status: "blocked";
+    problem: {
+        code: string;
+        message: string;
+    };
+};
+/** Live verification owns no session state; callers supply identity and cancellation guards. */
+export declare function verifyStructuredReadiness<Frontmatter extends JsonObject>(input: {
+    collectionId: string;
+    readiness: MdbaseStructuredReadiness;
+    contracts: ContractRequirement[];
+    connection: MdbaseConnection<Frontmatter>;
+    controller: AbortController;
+    options?: ConnectRequestOptions;
+    requestMs: number | null;
+    isCurrent: () => boolean;
+    publish: (result: ReadinessPublication) => void;
+}): Promise<boolean>;
+export declare function publishedStructuredReadiness(source: MdbaseStructuredReadiness, status: string, verification?: "cached" | "verified"): MdbaseStructuredReadiness;
+export interface ApplicationSessionContext {
+    collectionId: string;
+    info: MdbaseConnectionInfo;
+    capabilities: MdbaseEffectiveCapabilities;
+    /** Present only for semantic contract v2. */
+    readiness?: MdbaseStructuredReadiness;
+    connections: MdbaseConnectionInfo[];
+}
+export declare function applicationReadinessContext(manifest: MdbaseApplicationManifest, collectionId: string, info: MdbaseConnectionInfo, connections: MdbaseConnectionInfo[]): ApplicationSessionContext;
+export declare function verificationKey(manifest: MdbaseApplicationManifest, collectionId: string): string;
+export declare function verificationValue(manifest: MdbaseApplicationManifest): string;
+export declare function collectionSetupInput(manifest: MdbaseApplicationManifest, applicationId: string, declarationDigest: string, typePackAdoptions?: Record<string, Record<string, string>>): {
+    applicationId: string;
+    declarationDigest: string;
+    requirements: {
+        configuration: import("@mdbase-dev/connect-protocol").ConfigurationRequirement[];
+    };
+    provisions: {
+        configuration: import("@mdbase-dev/connect-protocol").ConfigurationProvision[];
+        typePacks: import("@mdbase-dev/connect-protocol").TypePackProvision[];
+    };
+    typePackAdoptions?: Record<string, Record<string, string>> | undefined;
+};
+/** Independent v2 declarations; never legacy capability aliases. */
+export interface MdbaseStructuredReadiness {
+    files: {
+        state: "not_required" | "available" | "requires_authorization";
+        missingRequiredActions: FileAction[];
+        missingOptionalActions: FileAction[];
+        scopeMatches: boolean;
+        evidence: MdbaseCapabilityEvidence[];
+    };
+    contracts: {
+        state: "not_required" | "checking" | "verified" | "requires_setup" | "requires_authorization" | "temporarily_unavailable";
+        missing: ContractRequirement[];
+        evidence: MdbaseCapabilityEvidence[];
+    };
+    setup: {
+        state: "not_required" | "checking" | "review_required" | "current" | "cached" | "blocked" | "requires_authorization";
+        evidence: MdbaseCapabilityEvidence[];
+    };
+    notifications: {
+        state: "not_required" | "requires_registration";
+        registration: "unverified";
+        evidence: MdbaseCapabilityEvidence[];
+    };
+}
+export declare function structuredReadiness(manifest: MdbaseApplicationManifest, info: MdbaseConnectionInfo): MdbaseStructuredReadiness;
+export {};

package/dist/structured-readiness.js

@@ -0,0 +1,126 @@
+/* The versioned protocol package is the sole capability-to-operation compiler. */
+import { effectiveCapabilities } from "./capabilities.js";
+import { MdbaseConnectError } from "./errors.js";
+import { withRequestBudget } from "./request-budget.js";
+/** Live verification owns no session state; callers supply identity and cancellation guards. */
+export async function verifyStructuredReadiness(input) {
+    const { collectionId, readiness, contracts, connection, controller, options, requestMs, isCurrent, publish } = input;
+    const abort = () => controller.abort(options?.signal?.reason);
+    if (options?.signal?.aborted)
+        abort();
+    else
+        options?.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const outcome = await withRequestBudget({ ...options, signal: controller.signal }, requestMs, request => connection.describe(request));
+        if (!isCurrent())
+            return false;
+        if (!outcome.ok) {
+            const authorizationRequired = ["access_denied", "collection_access_denied", "insufficient_access", "not_authorized", "authorization_expired", "application_declaration_mismatch"].includes(outcome.problem.code);
+            readiness.contracts = { state: authorizationRequired ? "requires_authorization" : "temporarily_unavailable", missing: [], evidence: [{ source: "runtime", fact: outcome.problem.message }] };
+            publish(authorizationRequired
+                ? { status: "authorization_required" }
+                : { status: "blocked", problem: outcome.problem });
+            return false;
+        }
+        if (outcome.value.collectionId !== collectionId) {
+            readiness.contracts = { state: "temporarily_unavailable", missing: [], evidence: [] };
+            publish({ status: "blocked", problem: { code: "collection_not_ready", message: "Description belongs to a different collection." } });
+            return false;
+        }
+        const missing = contracts.filter(required => !outcome.value.contracts.some(actual => actual.id === required.id && actual.version === required.version && actual.digest === required.digest));
+        readiness.contracts = { state: missing.length ? "requires_setup" : "verified", missing,
+            evidence: [{ source: "authority", fact: "Exact contract ID, version and digest checked by live describe for this collection." }] };
+        if (missing.length) {
+            publish({ status: "blocked", problem: { code: "collection_not_ready", message: "The collection is missing required exact contracts." } });
+            return false;
+        }
+    }
+    catch (error) {
+        if (!isCurrent())
+            return false;
+        if (!(error instanceof MdbaseConnectError))
+            throw error;
+        readiness.contracts = { state: "temporarily_unavailable", missing: [], evidence: [{ source: "runtime", fact: error.problem.message }] };
+        publish({ status: "blocked", problem: error.problem });
+        return false;
+    }
+    finally {
+        options?.signal?.removeEventListener("abort", abort);
+    }
+    return true;
+}
+export function publishedStructuredReadiness(source, status, verification) {
+    const readiness = structuredClone(source);
+    if (readiness.setup.state !== "not_required" && readiness.setup.state !== "current") {
+        readiness.setup.state = status === "ready" ? (verification === "cached" ? "cached" : "current")
+            : status === "setup_review_required" ? "review_required"
+                : status === "authorization_required" ? "requires_authorization"
+                    : status === "blocked" ? "blocked" : "checking";
+        readiness.setup.evidence = [{ source: status === "ready" && verification === "cached" ? "runtime" : "authority",
+                fact: `Collection setup verification: ${readiness.setup.state}.` }];
+    }
+    return readiness;
+}
+export function applicationReadinessContext(manifest, collectionId, info, connections) {
+    return {
+        collectionId, info,
+        capabilities: effectiveCapabilities(manifest.requirements.capabilities, manifest, info),
+        ...(manifest.requirements?.capabilities?.contract_version === 2
+            ? { readiness: structuredReadiness(manifest, info) } : {}),
+        connections
+    };
+}
+export function verificationKey(manifest, collectionId) {
+    return `mdbase-application-session:v1:${manifest.id}:${collectionId}`;
+}
+export function verificationValue(manifest) {
+    return JSON.stringify({
+        capabilities: manifest.requirements?.capabilities,
+        requirements: manifest.requirements?.configuration ?? [],
+        provisions: manifest.provisions ?? {}
+    });
+}
+export function collectionSetupInput(manifest, applicationId, declarationDigest, typePackAdoptions) {
+    return {
+        applicationId, declarationDigest,
+        requirements: { configuration: manifest.requirements?.configuration ?? [] },
+        provisions: {
+            configuration: manifest.provisions?.configuration ?? [],
+            typePacks: manifest.provisions?.type_packs ?? []
+        },
+        ...(typePackAdoptions ? { typePackAdoptions } : {})
+    };
+}
+function sameScope(left, right) {
+    if (!right || left.kind !== right.kind)
+        return false;
+    if (left.kind === "collection" || right.kind === "collection")
+        return true;
+    const a = [...new Set(left.folders)].sort();
+    const b = [...new Set(right.folders)].sort();
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export function structuredReadiness(manifest, info) {
+    const files = manifest.requirements?.files;
+    const requirement = files && "required" in files ? files : undefined;
+    const scopeMatches = !requirement || sameScope(requirement.scope, info.fileCapability?.scope);
+    const missing = (actions) => actions.filter(action => !scopeMatches || !info.fileCapability?.actions.includes(action));
+    const missingRequiredActions = missing(requirement?.required ?? []);
+    const missingOptionalActions = missing(requirement?.optional ?? []);
+    const contracts = manifest.requirements?.contracts ?? [];
+    const setup = (manifest.provisions?.type_packs.length ?? 0) > 0 || (manifest.provisions?.configuration?.length ?? 0) > 0;
+    return {
+        files: {
+            state: !requirement ? "not_required" : missingRequiredActions.length ? "requires_authorization" : "available",
+            missingRequiredActions, missingOptionalActions, scopeMatches,
+            evidence: [{ source: "authorization", fact: "Compared exact file actions and folder scope with connection.info().fileCapability." }]
+        },
+        contracts: { state: contracts.length ? "checking" : "not_required", missing: [], evidence: [] },
+        setup: { state: setup ? "checking" : "not_required", evidence: [] },
+        notifications: {
+            state: manifest.notifications?.criteria.length ? "requires_registration" : "not_required",
+            registration: "unverified",
+            evidence: [{ source: "runtime", fact: "The connection API exposes registration commands but no current delivery-registration query. Manifest criteria do not prove approval or delivery registration." }]
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect",
-  "version": "0.1.0-beta.94",
+  "version": "0.1.0-beta.96",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.94"
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.96"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",