@mdbase-dev/connect 0.1.0-beta.93 → 0.1.0-beta.95

package/dist/runtime-utils.js

@@ -2,6 +2,19 @@ import { validateGrantEncryption } from "./crypto.js";
 import { connectError, serverConnectError } from "./errors.js";
 import { canonicalJson } from "./operation-helpers.js";
 import { bytesToBase64Url, randomBase64Url } from "./base64.js";
+/** Resolve bundled declarations and their stable storage identity without loading URLs. */
+export function resolveManifestSource(input, redirect) {
+    const manifest = input instanceof URL ? input.href : input ?? defaultManifestSource();
+    const manifestSource = typeof manifest === "string"
+        ? manifest
+        : manifest.distribution === "portable"
+            ? `bundle:${manifest.id}:${manifestStorageFingerprint(manifest)}`
+            : `bundle:${manifest.id}`;
+    const redirectUri = redirect === undefined ? (typeof manifest !== "string" && manifest.distribution === "portable"
+        ? ""
+        : defaultRedirectUri()) : String(redirect);
+    return { manifest, manifestSource, redirectUri };
+}
 /** Normalize fetch rejection at the exact I/O boundary. */
 export async function connectFetch(input, init, code, message) {
     try {
@@ -215,6 +228,7 @@ export function parseStored(value) {
         return null;
     }
 }
+/** Parse both canonical and N-1 grant shapes so callers can diagnose legacy grants. */
 export function parseGrantScope(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -246,6 +260,10 @@ export function parseGrantScope(value) {
         return null;
     return scope;
 }
+/** Only this scope authorizes application data access. */
+export function isCanonicalGrantScope(scope) {
+    return scope.access === "full_collection" && scope.contracts.length === 0;
+}
 export function stripTrailingSlash(value) {
     return value.endsWith("/") ? value.slice(0, -1) : value;
 }

package/dist/session.d.ts

@@ -1,10 +1,12 @@
 import type { CollectionOperation, ConnectProblem, JsonObject } from "@mdbase-dev/connect-protocol";
+import { type MdbaseApplicationManifest, type MdbaseApplicationCapabilityId as ApplicationCapabilityId } from "./application-contract.js";
 import { MdbaseConnection, type MdbaseAuthorizationOutcome, type MdbaseAuthorizationResult, type MdbaseAuthorizeOptions } from "./connection.js";
 import type { MdbaseAuthorizationCapabilities, MdbaseConnectionInfo } from "./connection-types.js";
-import { type AuthorizationProblemCode, type ConnectOutcome, type SessionProblemCode } from "./outcomes.js";
+import { type AuthorizationProblemCode, type RegistrationProblemCode, type ConnectOutcome, type SessionProblemCode } from "./outcomes.js";
 import type { MdbaseSelectionHistory, MdbaseApplicationSelection } from "./selection.js";
 import type { ConnectRequestOptions } from "./operation-types.js";
 export interface MdbaseSessionConnect<Frontmatter extends JsonObject> {
+    manifest?(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationManifest, RegistrationProblemCode>>;
     authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
     completeAuthorization(callbackUrl: string, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
     connections(): MdbaseConnectionInfo[];
@@ -17,7 +19,7 @@ export interface MdbaseSessionOptions {
     operations?: CollectionOperation[];
     autoSelect?: "only" | "never";
 }
-export type MdbaseUnavailableReason = "not_authorized" | "authorization_lost" | "invalid_stored_grant";
+export type MdbaseUnavailableReason = "not_authorized" | "authorization_lost" | "invalid_stored_grant" | "legacy_scope_reauthorization_required";
 export type MdbaseSessionSnapshot<Frontmatter extends JsonObject = JsonObject> = {
     status: "not_started";
     connections: MdbaseConnectionInfo[];
@@ -87,11 +89,16 @@ export declare class MdbaseSession<Frontmatter extends JsonObject = JsonObject>
     forget(collectionId: string): ConnectOutcome<void, SessionProblemCode>;
     authorize(target: "choose" | "selected" | {
         collectionId: string;
-    }, options?: Omit<MdbaseAuthorizeOptions, "operations" | "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
-    ensureOperations(requiredOperations: CollectionOperation[], options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
+    }, options?: Omit<MdbaseAuthorizeOptions, "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    ensureOperations(requiredOperations: CollectionOperation[], options?: ConnectRequestOptions): Promise<ConnectOutcome<{
         kind: "unchanged";
         connection: MdbaseConnection<Frontmatter>;
-    }, SessionProblemCode>>;
+    } | MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    ensureCapabilities(requiredCapabilities: ApplicationCapabilityId[], options?: ConnectRequestOptions): Promise<ConnectOutcome<{
+        kind: "unchanged";
+        connection: MdbaseConnection<Frontmatter>;
+    } | MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    private ensureAuthorization;
     handleAuthorizationCallback(callbackUrl: string, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>>;
     private completeAuthorizationCallback;
     private beginCallbackCompletion;

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/stored-token.d.ts

@@ -3,7 +3,7 @@ interface ReadStoredTokenOptions {
     stored: string | null;
     collectionId: string;
     relayEncryption: "required" | "disabled";
-    invalidate(keyHandle?: string): void;
+    invalidate(keyHandle?: string, reason?: "invalid_stored_grant" | "legacy_scope_reauthorization_required"): void;
     directCapable(token: StoredToken): boolean;
 }
 export declare function readStoredToken({ stored, collectionId, relayEncryption, invalidate, directCapable }: ReadStoredTokenOptions): StoredToken | null;

package/dist/stored-token.js

@@ -1,8 +1,8 @@
-import { parseGrantScope, parseStored, validFileCapability, validStoredAuthority, validStoredEncryption } from "./runtime-utils.js";
+import { isCanonicalGrantScope, parseGrantScope, parseStored, validFileCapability, validStoredAuthority, validStoredEncryption } from "./runtime-utils.js";
 export function readStoredToken({ stored, collectionId, relayEncryption, invalidate, directCapable }) {
     const token = parseStored(stored);
-    const reject = (keyHandle) => {
-        invalidate(typeof keyHandle === "string" ? keyHandle : undefined);
+    const reject = (keyHandle, reason = "invalid_stored_grant") => {
+        invalidate(typeof keyHandle === "string" ? keyHandle : undefined, reason);
         return null;
     };
     if (!token) {
@@ -27,8 +27,12 @@ export function readStoredToken({ stored, collectionId, relayEncryption, invalid
         || (token.refreshExpiresAt !== undefined
             && (typeof token.refreshExpiresAt !== "number" || !Number.isFinite(token.refreshExpiresAt))))
         return reject(token.keyHandle);
-    if (!parseGrantScope(token.scope))
+    const scope = parseGrantScope(token.scope);
+    if (!scope)
         return reject(token.keyHandle);
+    if (!isCanonicalGrantScope(scope)) {
+        return reject(token.keyHandle, "legacy_scope_reauthorization_required");
+    }
     if (token.fileCapability && !validFileCapability(token.fileCapability)) {
         return reject(token.keyHandle);
     }

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/dist/token-response.js

@@ -1,6 +1,6 @@
 import { validateGrantEncryption } from "./crypto.js";
 import { connectError } from "./errors.js";
-import { parseGrantScope, validAuthorityTokenResponse, validFileCapability } from "./runtime-utils.js";
+import { isCanonicalGrantScope, parseGrantScope, validAuthorityTokenResponse, validFileCapability } from "./runtime-utils.js";
 export function storedTokenFromResponse({ body, clientId, keyHandle, previous, retiredKeyHandles, defaultApplicationOrigin, pinConnectorIdentity }) {
     const collectionId = body.collection_id;
     if (typeof collectionId !== "string") {
@@ -10,6 +10,9 @@ export function storedTokenFromResponse({ body, clientId, keyHandle, previous, r
     if (!scope) {
         throw connectError("invalid_token_response", "Authorization returned no valid collection scope.");
     }
+    if (!isCanonicalGrantScope(scope)) {
+        throw connectError("legacy_scope_reauthorization_required", "Authorization returned a legacy contract-scoped grant. Reauthorize for the entire collection.");
+    }
     if (body.authority && !validAuthorityTokenResponse(body.authority, collectionId)) {
         throw connectError("invalid_token_response", "Authorization returned an invalid remote authority capability.");
     }

package/package.json

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