@mdbase-dev/connect 0.1.0-beta.100

package/dist/advanced.d.ts

@@ -0,0 +1,9 @@
+/** Low-level construction and test seams. Ordinary applications use the root package. */
+export { MdbaseCollectionClient } from "./collection-client.js";
+export type { MdbaseCollectionTransport } from "./operation-types.js";
+export { createPkce } from "./runtime-utils.js";
+export { connectError, connectProblem, operationProblem } from "./errors.js";
+export { connectFailure, connectSuccess } from "./outcomes.js";
+export type { MdbaseApplicationVerificationStore, MdbaseApplicationSessionConnect } from "./application-session.js";
+export { MdbaseSession } from "./session.js";
+export type { MdbaseSessionConnect, MdbaseSessionOptions, MdbaseSessionSnapshot } from "./session.js";

package/dist/advanced.js

@@ -0,0 +1,6 @@
+/** Low-level construction and test seams. Ordinary applications use the root package. */
+export { MdbaseCollectionClient } from "./collection-client.js";
+export { createPkce } from "./runtime-utils.js";
+export { connectError, connectProblem, operationProblem } from "./errors.js";
+export { connectFailure, connectSuccess } from "./outcomes.js";
+export { MdbaseSession } from "./session.js";

package/dist/application-contract.d.ts

@@ -0,0 +1,22 @@
+import { type ApplicationCapabilityId, type ApplicationCapabilityRequirements, type LegacyApplicationCapabilityRequirements, type LegacyApplicationCapabilityId, type ApplicationRequirements, type LegacyApplicationRequirements, type MdbaseAppManifest, type LegacyMdbaseAppManifest, type CollectionOperation } from "@mdbase-dev/connect-protocol";
+export declare const DEFAULT_OPERATIONS: CollectionOperation[];
+/** SDK input compatibility boundary; protocol ApplicationRequirements remains v2-only. */
+export type MdbaseApplicationManifest = MdbaseAppManifest | LegacyMdbaseAppManifest;
+export type MdbaseApplicationRequirements = ApplicationRequirements | LegacyApplicationRequirements;
+export type MdbaseApplicationCapabilityRequirements = ApplicationCapabilityRequirements | LegacyApplicationCapabilityRequirements;
+export type MdbaseApplicationCapabilityId = ApplicationCapabilityId | LegacyApplicationCapabilityId;
+interface MdbaseAuthorizationSelection {
+    operations?: CollectionOperation[];
+    capabilities?: MdbaseApplicationCapabilityId[];
+}
+export declare function semanticContractVersion(requirements: MdbaseApplicationRequirements): 1 | 2;
+export declare function invalidAuthorizationSelection(message: string): never;
+export declare function validateAuthorizationSelection(requirements: MdbaseApplicationRequirements, options: MdbaseAuthorizationSelection): void;
+export declare function declaredOperations(requirements: MdbaseApplicationRequirements): CollectionOperation[];
+export declare function authorizationOperations(application: {
+    requirements: MdbaseApplicationRequirements;
+    provisions?: MdbaseApplicationManifest["provisions"];
+}, options: MdbaseAuthorizationSelection): CollectionOperation[];
+export declare function retainedCapabilities(requirements: MdbaseApplicationRequirements, operations: CollectionOperation[]): MdbaseApplicationCapabilityId[];
+export declare function authorizationFiles(requirements: MdbaseApplicationRequirements): import("@mdbase-dev/connect-protocol").ApplicationFileRequest | undefined;
+export {};

package/dist/application-contract.js

@@ -0,0 +1,75 @@
+import { APPLICATION_SETUP_OPERATIONS, applicationFileRequest, capabilityOperationsForContractVersion } from "@mdbase-dev/connect-protocol";
+import { connectError } from "./errors.js";
+export const DEFAULT_OPERATIONS = ["describe", "changes", "read", "query"];
+export function semanticContractVersion(requirements) {
+    const version = requirements.capabilities === undefined ? 1 : requirements.capabilities?.contract_version;
+    if (version !== 1 && version !== 2)
+        invalidAuthorizationSelection("Unsupported declared capability contract version.");
+    return version;
+}
+export function invalidAuthorizationSelection(message) {
+    throw connectError("invalid_application_manifest", message, {
+        details: { issues: [{ path: "/requirements/capabilities", keyword: "authorizationSelection", message, params: {} }] }
+    });
+}
+export function validateAuthorizationSelection(requirements, options) {
+    if (options.operations !== undefined && options.capabilities !== undefined) {
+        invalidAuthorizationSelection("Specify operations or capabilities, not both.");
+    }
+    if (options.operations !== undefined && semanticContractVersion(requirements) !== 1) {
+        invalidAuthorizationSelection("Exact operations authorization is only supported for legacy v1 declarations.");
+    }
+    if (options.capabilities !== undefined) {
+        const declared = new Set([
+            ...(requirements.capabilities?.required ?? []),
+            ...(requirements.capabilities?.optional ?? [])
+        ]);
+        if (options.capabilities.some((id) => !declared.has(id)
+            || capabilityOperationsForContractVersion(semanticContractVersion(requirements), id) === undefined)) {
+            invalidAuthorizationSelection("Authorization can only include capabilities declared by the application.");
+        }
+    }
+}
+export function declaredOperations(requirements) {
+    const capabilities = requirements.capabilities;
+    if (!capabilities)
+        return [...DEFAULT_OPERATIONS];
+    return [...new Set([...capabilities.required, ...(capabilities.optional ?? [])].flatMap((id) => capabilityOperationsForContractVersion(capabilities.contract_version, id) ?? []))];
+}
+export function authorizationOperations(application, options) {
+    const { requirements } = application;
+    validateAuthorizationSelection(requirements, options);
+    // Legacy callers selected independent exact operations, including subsets of declarations.
+    if (semanticContractVersion(requirements) === 1) {
+        if (options.operations !== undefined)
+            return [...new Set(options.operations)];
+        if (options.capabilities === undefined)
+            return [...DEFAULT_OPERATIONS];
+    }
+    const declared = requirements.capabilities;
+    const selected = [...(declared?.required ?? []), ...(options.capabilities ?? declared?.optional ?? [])];
+    const operations = selected.flatMap((id) => capabilityOperationsForContractVersion(semanticContractVersion(requirements), id) ?? []);
+    const hasSetup = (application.provisions?.type_packs.length ?? 0) > 0
+        || (application.provisions?.configuration?.length ?? 0) > 0;
+    return [...new Set([
+            ...operations,
+            ...(semanticContractVersion(requirements) === 2 && hasSetup ? APPLICATION_SETUP_OPERATIONS : [])
+        ])];
+}
+export function retainedCapabilities(requirements, operations) {
+    return [...(requirements.capabilities?.required ?? []), ...(requirements.capabilities?.optional ?? [])].filter((id) => (capabilityOperationsForContractVersion(semanticContractVersion(requirements), id) ?? []).every((operation) => operations.includes(operation)));
+}
+export function authorizationFiles(requirements) {
+    const files = requirements.files;
+    if (!files)
+        return undefined;
+    if (semanticContractVersion(requirements) === 1) {
+        if (!("actions" in files) || "required" in files || "optional" in files) {
+            invalidAuthorizationSelection("Legacy file declarations must use exact files.actions.");
+        }
+        return { actions: [...files.actions], scope: structuredClone(files.scope) };
+    }
+    if ("actions" in files)
+        invalidAuthorizationSelection("V2 file declarations must use required/optional file actions.");
+    return applicationFileRequest(files);
+}

package/dist/application-identity.d.ts

@@ -0,0 +1,34 @@
+import { authorizationSigningMessage, type ApplicationAuthorizationBinding, type ApplicationAuthorizationProof } from "@mdbase-dev/connect-protocol";
+import type { Application } from "./internal-types.js";
+export interface ApplicationIdentity {
+    handle: string;
+    signingPrivateKey: CryptoKey;
+    signingPublicKey: string;
+}
+export interface ApplicationIdentityStore {
+    create(handle: string): Promise<ApplicationIdentity>;
+    get(handle: string): Promise<ApplicationIdentity | null>;
+    delete(handle: string): Promise<void>;
+}
+/** Origin-scoped persistence for one non-extractable signing key per app/server installation. */
+export declare class IndexedDbApplicationIdentityStore implements ApplicationIdentityStore {
+    private database;
+    create(handle: string): Promise<ApplicationIdentity>;
+    get(handle: string): Promise<ApplicationIdentity | null>;
+    delete(handle: string): Promise<void>;
+    private open;
+}
+/** Process-local identity storage for portable applications, tests, and custom hosts. */
+export declare class MemoryApplicationIdentityStore implements ApplicationIdentityStore {
+    private readonly records;
+    create(handle: string): Promise<ApplicationIdentity>;
+    get(handle: string): Promise<ApplicationIdentity | null>;
+    delete(handle: string): Promise<void>;
+}
+export declare class ApplicationIdentityStoreError extends Error {
+    constructor(message: string);
+}
+export { authorizationSigningMessage };
+export declare function applicationInstallationId(identity: Pick<ApplicationIdentity, "signingPublicKey">): Promise<string>;
+export declare function signApplicationAuthorization(binding: ApplicationAuthorizationBinding, identity: Pick<ApplicationIdentity, "signingPrivateKey" | "signingPublicKey">): Promise<ApplicationAuthorizationProof>;
+export declare function applicationIdentity(store: ApplicationIdentityStore, serverUrl: string, application: Application): Promise<ApplicationIdentity>;

package/dist/application-identity.js

@@ -0,0 +1,148 @@
+import { applicationInstallationIdFromPublicKey, authorizationSigningMessage } from "@mdbase-dev/connect-protocol";
+const DATABASE_NAME = "mdbase-connect-identities";
+const STORE_NAME = "application-identities";
+const P256_ORDER = BigInt("0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
+const P256_HALF_ORDER = P256_ORDER / 2n;
+/** Origin-scoped persistence for one non-extractable signing key per app/server installation. */
+export class IndexedDbApplicationIdentityStore {
+    database = null;
+    async create(handle) {
+        const record = await generateApplicationIdentity(handle);
+        const database = await this.open();
+        await idbWrite(database, (store) => store.add(record));
+        return record;
+    }
+    async get(handle) {
+        const database = await this.open();
+        return await idbRequest(database.transaction(STORE_NAME).objectStore(STORE_NAME).get(handle)) ?? null;
+    }
+    async delete(handle) {
+        const database = await this.open();
+        await idbWrite(database, (store) => store.delete(handle));
+    }
+    open() {
+        if (typeof indexedDB === "undefined") {
+            throw new ApplicationIdentityStoreError("Persistent application identity requires browser IndexedDB or an injected identity store.");
+        }
+        if (!this.database) {
+            this.database = new Promise((resolve, reject) => {
+                const request = indexedDB.open(DATABASE_NAME, 1);
+                request.onupgradeneeded = () => {
+                    if (!request.result.objectStoreNames.contains(STORE_NAME)) {
+                        request.result.createObjectStore(STORE_NAME, { keyPath: "handle" });
+                    }
+                };
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => resolve(request.result);
+            });
+        }
+        return this.database;
+    }
+}
+/** Process-local identity storage for portable applications, tests, and custom hosts. */
+export class MemoryApplicationIdentityStore {
+    records = new Map();
+    async create(handle) {
+        if (this.records.has(handle))
+            throw new Error(`Application identity already exists: ${handle}`);
+        const record = await generateApplicationIdentity(handle);
+        this.records.set(handle, record);
+        return record;
+    }
+    async get(handle) {
+        return this.records.get(handle) ?? null;
+    }
+    async delete(handle) {
+        this.records.delete(handle);
+    }
+}
+export class ApplicationIdentityStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApplicationIdentityStoreError";
+    }
+}
+export { authorizationSigningMessage };
+export async function applicationInstallationId(identity) {
+    return applicationInstallationIdFromPublicKey(identity.signingPublicKey);
+}
+export async function signApplicationAuthorization(binding, identity) {
+    if (binding.installation_signing_public_key !== identity.signingPublicKey
+        || binding.application_installation_id !== await applicationInstallationId(identity)) {
+        throw new Error("Application authorization identity does not match its binding.");
+    }
+    const signature = canonicalSignature(new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, identity.signingPrivateKey, authorizationSigningMessage(binding))));
+    return { binding, signature: base64Url(signature) };
+}
+export async function applicationIdentity(store, serverUrl, application) {
+    const handle = `application-installation:v2:${serverUrl}:${application.id}`;
+    const existing = await store.get(handle);
+    if (existing)
+        return existing;
+    try {
+        return await store.create(handle);
+    }
+    catch (error) {
+        const raced = await store.get(handle);
+        if (raced)
+            return raced;
+        throw error;
+    }
+}
+async function generateApplicationIdentity(handle) {
+    const signing = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+    const signingPublicKey = base64Url(new Uint8Array(await crypto.subtle.exportKey("raw", signing.publicKey)));
+    const signingPkcs8 = await crypto.subtle.exportKey("pkcs8", signing.privateKey);
+    const signingPrivateKey = await crypto.subtle.importKey("pkcs8", signingPkcs8, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+    return { handle, signingPrivateKey, signingPublicKey };
+}
+function idbRequest(request) {
+    return new Promise((resolve, reject) => {
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+    });
+}
+function idbWrite(database, write) {
+    return new Promise((resolve, reject) => {
+        const transaction = database.transaction(STORE_NAME, "readwrite");
+        write(transaction.objectStore(STORE_NAME)).onerror = () => reject(transaction.error);
+        transaction.onerror = () => reject(transaction.error);
+        transaction.onabort = () => reject(transaction.error ?? new Error("Identity transaction aborted."));
+        transaction.oncomplete = () => resolve();
+    });
+}
+function concat(values) {
+    const output = new Uint8Array(values.reduce((length, value) => length + value.byteLength, 0));
+    let offset = 0;
+    for (const value of values) {
+        output.set(value, offset);
+        offset += value.byteLength;
+    }
+    return output;
+}
+function base64Url(value) {
+    return btoa(String.fromCharCode(...value))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/u, "");
+}
+function canonicalSignature(signature) {
+    if (signature.byteLength !== 64)
+        throw new Error("Application authorization signature is invalid.");
+    const s = bytesBigInt(signature.slice(32));
+    if (s === 0n || s >= P256_ORDER)
+        throw new Error("Application authorization signature is invalid.");
+    if (s <= P256_HALF_ORDER)
+        return signature;
+    return concat([signature.slice(0, 32), bigIntBytes(P256_ORDER - s, 32)]);
+}
+function bytesBigInt(value) {
+    return BigInt(`0x${hex(value)}`);
+}
+function bigIntBytes(value, length) {
+    const encoded = value.toString(16).padStart(length * 2, "0");
+    return Uint8Array.from({ length }, (_, index) => Number.parseInt(encoded.slice(index * 2, index * 2 + 2), 16));
+}
+function hex(value) {
+    return [...value].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/application-session.d.ts

@@ -0,0 +1,167 @@
+import { type ConnectProblem, type JsonObject, type CollectionOperation } from "@mdbase-dev/connect-protocol";
+import { type MdbaseApplicationManifest as MdbaseAppManifest, type MdbaseApplicationCapabilityId as ApplicationCapabilityId } from "./application-contract.js";
+import { type ApplicationSessionContext } from "./structured-readiness.js";
+import type { MdbaseAuthorizationOutcome, MdbaseAuthorizeOptions, MdbaseConnection } from "./connection.js";
+import type { MdbaseConnectionInfo } from "./connection-types.js";
+import { type ConnectOutcome, type CollectionTypeProblemCode, type RegistrationProblemCode, type SessionProblemCode } from "./outcomes.js";
+import type { MdbaseApplicationSelection, MdbaseSelectionHistory } from "./selection.js";
+import type { CollectionSetupAssessment, ConfigurationSetupAssessment, ConnectRequestOptions, TypePackAssessment } from "./operation-types.js";
+import { type ResolvedConnectTimeouts } from "./request-budget.js";
+import type { Application } from "./internal-types.js";
+import { type MdbaseSessionConnect, type MdbaseUnavailableReason } from "./session.js";
+export interface MdbaseApplicationSessionConnect<Frontmatter extends JsonObject = JsonObject> extends MdbaseSessionConnect<Frontmatter> {
+    register(options?: ConnectRequestOptions): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
+    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
+    connectionApplicationId(collectionId: string): string | null;
+}
+export interface MdbaseApplicationSessionOptions {
+    selection: MdbaseApplicationSelection;
+    autoSelect?: "only" | "never";
+    verificationStore?: MdbaseApplicationVerificationStore;
+}
+export interface MdbaseApplicationVerificationStore {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}
+export declare class MdbaseMemoryVerificationStore implements MdbaseApplicationVerificationStore {
+    private readonly values;
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}
+export interface MdbaseDefinitionUpdate {
+    id: string;
+    name: string;
+    status: TypePackAssessment["status"];
+    applicable: boolean;
+    assessmentDigest: string;
+    currentVersion?: string;
+    desiredVersion: string;
+    resources: TypePackAssessment["resources"];
+    contractSetups: TypePackAssessment["contractSetups"];
+    canApply: boolean;
+    reason: string;
+}
+export interface MdbaseCollectionSetupUpdate {
+    status: CollectionSetupAssessment["status"];
+    applicable: boolean;
+    assessmentDigest: string;
+    collectionRevision: string;
+    provisionDigest: string;
+    configuration: ConfigurationSetupAssessment[];
+    typePacks: MdbaseDefinitionUpdate[];
+    canApply: boolean;
+    reason: string;
+}
+export type MdbaseApplicationSessionSnapshot = {
+    status: "not_started";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "starting";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "start_failed";
+    problem: ConnectProblem<SessionProblemCode>;
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "destroyed";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "unselected";
+    connections: MdbaseConnectionInfo[];
+} | ({
+    status: "authorization_required";
+} & ApplicationSessionContext) | ({
+    status: "checking_setup";
+} & ApplicationSessionContext) | ({
+    status: "setup_review_required";
+    update: MdbaseCollectionSetupUpdate;
+} & ApplicationSessionContext) | ({
+    status: "ready";
+    verification: "cached" | "verified";
+} & ApplicationSessionContext) | {
+    status: "unavailable";
+    collectionId: string;
+    reason: MdbaseUnavailableReason;
+    connections: MdbaseConnectionInfo[];
+} | ({
+    status: "blocked";
+    problem: {
+        code: string;
+        message: string;
+        recovery?: string;
+    };
+} & ApplicationSessionContext);
+/**
+ * The application-level lifecycle boundary. It derives authorization from the
+ * bundled manifest, exposes semantic capabilities, and never mutates collection
+ * setup without an explicit `applyCollectionSetup` call.
+ */
+export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = JsonObject> {
+    private readonly connect;
+    private readonly options;
+    private readonly timeouts;
+    private readonly listeners;
+    private readonly verificationStore;
+    private snapshot;
+    private manifest;
+    private application;
+    private base;
+    private stopBase?;
+    private setupAssessment;
+    private setupTypePackAdoptions;
+    private verificationGeneration;
+    private readinessController?;
+    private lifecycleGeneration;
+    private readonly operationControllers;
+    private startOperation;
+    constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions, timeouts?: ResolvedConnectTimeouts);
+    start(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    private waitForStart;
+    private abandonStart;
+    private beginStart;
+    private startWithinBudget;
+    private performStartWithinBudget;
+    private startFailure;
+    destroy(): void;
+    private cleanupBase;
+    getSnapshot(): MdbaseApplicationSessionSnapshot;
+    subscribe(listener: () => void): () => void;
+    connection(): MdbaseConnection<Frontmatter> | null;
+    select(collectionId: string, options?: {
+        history?: MdbaseSelectionHistory;
+    }): ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>;
+    clearSelection(options?: {
+        history?: MdbaseSelectionHistory;
+    }): ConnectOutcome<void, SessionProblemCode>;
+    forget(collectionId: string): ConnectOutcome<void, SessionProblemCode>;
+    authorize(target: "choose" | "selected" | {
+        collectionId: string;
+    }, options?: Omit<MdbaseAuthorizeOptions, "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    handleAuthorizationCallback(callbackUrl: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>>;
+    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>>;
+    ensureCapabilities(capabilities: ApplicationCapabilityId[], options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
+        kind: "unchanged";
+        connection: MdbaseConnection<Frontmatter>;
+    }, SessionProblemCode>>;
+    ensureOperations(operations: CollectionOperation[], options?: ConnectRequestOptions): Promise<ConnectOutcome<{
+        kind: "unchanged";
+        connection: MdbaseConnection<Frontmatter>;
+    } | MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    applyCollectionSetup(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | SessionProblemCode>>;
+    private applyCollectionSetupStarted;
+    private refresh;
+    private verifySetup;
+    private publishReady;
+    private collectionSetupInput;
+    private context;
+    private publish;
+    private lifecycleBase;
+    private withLifecycleBase;
+    private beginLifecycleOperation;
+    private lifecycleCurrent;
+    private destroyedOutcome;
+    private requireManifest;
+    private requireApplication;
+}