@mdbase-dev/connect 0.1.0-beta.31 → 0.1.0-beta.32

package/README.md

@@ -20,11 +20,18 @@ The complete developer guide covers
 const mdbase = new MdbaseConnect({
   serverUrl: "https://connect.mdbase.dev",
   manifest: new URL(".well-known/mdbase-app.json", location.href).href,
-  redirectUri: "https://workouts.example/auth/mdbase/callback"
+  redirectUri: "https://workouts.example/auth/mdbase/callback",
+  timeouts: {
+    requestMs: 15_000,
+    watchStartMs: 20_000,
+    uploadMs: 120_000,
+    syncMs: 60_000
+  }
 });
-const session = mdbase.createApplicationSession({
+const session = mdbase.application({
   selection: new MdbaseBrowserSelection()
 });
+const unsubscribeSession = session.subscribe(() => render(session.getSnapshot()));
 
 const started = await session.start();
 if (!started.ok) {
@@ -56,12 +63,20 @@ const updated = await connection.update({
 });
 if (!updated.ok) renderProblem(updated.problem);
 
-for await (const change of connection.watch()) {
-  if (!change.ok) {
-    renderProblem(change.problem);
-    break;
-  }
-  console.log(change.value.type, change.value.payload.path);
+const pageLifetime = new AbortController();
+const watch = await connection.watch(
+  { lifetimeSignal: pageLifetime.signal },
+  { timeoutMs: 20_000 }
+);
+if (!watch.ok) {
+  renderProblem(watch.problem);
+} else {
+  const unsubscribeWatch = watch.value.subscribe(
+    (change) => console.log(change.type, change.payload.path),
+    renderWatchStatus,
+    renderProblem
+  );
+  // On navigation: unsubscribeWatch(); watch.value.close();
 }
 ```
 
@@ -70,6 +85,45 @@ reserved for programming errors and broken SDK invariants. See
 [typed outcomes and recovery](../../docs/sdk-outcomes.md) for the complete
 problem model, setup failures, mutation uncertainty, and UI guidance.
 
+React applications can use the same session without introducing another state
+owner:
+
+```ts
+const store = externalStore(session);
+
+function useMdbaseSession() {
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  );
+}
+```
+
+Browser and native callbacks share the same typed completion boundary:
+
+```ts
+const browserResult = await session.completeAuthorization(location.href, {
+  timeoutMs: 15_000
+});
+const nativeResult = await session.completeAuthorization(deepLinkUrl, {
+  signal: appForeground.signal,
+  timeoutMs: 15_000
+});
+```
+
+Unknown writes are recovered through their durable handles, never by calling
+the original mutation again with reconstructed input:
+
+```ts
+for (const pending of connection.pendingMutations()) {
+  showRecoveryAction(pending.requestId, async () => {
+    const recovered = await pending.recover({ timeoutMs: 30_000 });
+    if (!recovered.ok) renderProblem(recovered.problem);
+  });
+}
+```
+
 `MdbaseConnect` is the application-level authorization registry.
 `MdbaseApplicationSession` is the normal application boundary: it owns active
 collection selection, authorization completion, semantic capabilities,
@@ -424,10 +478,11 @@ can show authoritative reference impact before asking for confirmation.
 applying, completed, and cancelled phases with an impact estimate. Cancellation
 remains available during an encrypted local/relay mutation because the SDK
 persists its exact encrypted request before dispatch. If waiting is cancelled
-after dispatch, `pendingMutation()` reports the interruption and
-`resumePendingMutation()` safely recovers the connector's durable receipt using
-the exact same input. Other providers are cancellable until apply begins and
-then run to a definitive response.
+after dispatch, `pendingMutations()` exposes durable handles. A handle's
+`recover()` method resends the exact stored request identity and bytes; callers
+never reconstruct or resupply mutation input. Multiple interrupted writes are
+independently recoverable. Other providers are cancellable until apply begins
+and then run to a definitive response.
 Authorization is retained in `localStorage` by default. Access tokens are
 renewed with rotating refresh tokens; passing a custom `Storage` implementation
 allows a host to choose another persistence boundary.
@@ -441,13 +496,14 @@ and the shell passes that URL to `completeAuthorization()`. PKCE prevents the
 callback code from being exchanged without the pending application state and
 verifier.
 
-New authorizations require encrypted relay protocol 1 by default. The SDK keeps
-independent non-extractable P-256 ECDH agreement and ECDSA signing keys plus an
-atomic message counter in IndexedDB. It encrypts operation inputs for the
-connector, decrypts connector results locally, and signs hosted authority
-requests with the independent signing key. Set `relayEncryption: "disabled"`
-only for development where end-to-end relay encryption is intentionally
-unavailable; an encrypted grant never falls back to plaintext.
+New authorizations require operation transport v2 and grant encryption profile
+v1 by default. The SDK keeps independent non-extractable P-256 ECDH agreement
+and ECDSA signing keys plus an atomic message counter in IndexedDB. It encrypts
+operation inputs for the connector, decrypts connector results locally, and
+signs hosted authority requests with the independent signing key. Set
+`relayEncryption: "disabled"` only for development where end-to-end relay
+encryption is intentionally unavailable; an encrypted grant never falls back
+to plaintext.
 
 For a hosted collection, the same authorization exchange returns a short-lived,
 grant-bound provider capability. The SDK routes operations directly to the

package/dist/advanced.d.ts

@@ -0,0 +1,7 @@
+/** 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 type { MdbaseApplicationVerificationStore, MdbaseApplicationSessionConnect } from "./application-session.js";
+export { MdbaseSession } from "./session.js";
+export type { MdbaseSessionConnect, MdbaseSessionOptions } from "./session.js";

package/dist/advanced.js

@@ -0,0 +1,4 @@
+/** 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 { MdbaseSession } from "./session.js";

package/dist/application-session.d.ts

@@ -4,9 +4,11 @@ import type { MdbaseAuthorizationOutcome, MdbaseAuthorizeOptions, MdbaseConnecti
 import type { MdbaseConnectionInfo } from "./connection-types.js";
 import { type ConnectOutcome, type CollectionTypeProblemCode, type AuthorizationProblemCode, type RegistrationProblemCode, type SessionProblemCode } from "./outcomes.js";
 import type { MdbaseApplicationSelection, MdbaseSelectionHistory } from "./selection.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
+import { type ResolvedConnectTimeouts } from "./request-budget.js";
 import { type MdbaseSessionConnect, type MdbaseUnavailableReason } from "./session.js";
 export interface MdbaseApplicationSessionConnect<Frontmatter extends JsonObject = JsonObject> extends MdbaseSessionConnect<Frontmatter> {
-    manifest(): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
+    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
 }
 export interface MdbaseApplicationSessionOptions {
     selection: MdbaseApplicationSelection;
@@ -80,6 +82,7 @@ export type MdbaseApplicationSessionSnapshot = {
 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;
@@ -88,8 +91,9 @@ export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = J
     private stopBase?;
     private reviewEntries;
     private verificationGeneration;
-    constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions);
-    start(): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions, timeouts?: ResolvedConnectTimeouts);
+    start(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    private startWithinBudget;
     destroy(): void;
     getSnapshot(): MdbaseApplicationSessionSnapshot;
     subscribe(listener: () => void): () => void;
@@ -104,12 +108,13 @@ export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = J
     authorize(target: "choose" | "selected" | {
         collectionId: string;
     }, options?: Omit<MdbaseAuthorizeOptions, "operations" | "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
-    handleAuthorizationCallback(callbackUrl: string): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
+    handleAuthorizationCallback(callbackUrl: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
+    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
     ensureCapabilities(capabilities: ApplicationCapabilityId[]): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
         kind: "unchanged";
         connection: MdbaseConnection<Frontmatter>;
     }, SessionProblemCode>>;
-    applyDefinitionUpdates(): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | "collection_not_ready">>;
+    applyDefinitionUpdates(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | "collection_not_ready">>;
     private refresh;
     private verifyDefinitions;
     private context;

package/dist/application-session.js

@@ -3,6 +3,8 @@ import { capabilityOperations, operationsForApplicationCapabilities } from "@mdb
 import { effectiveCapabilities } from "./capabilities.js";
 import { connectProblem } from "./errors.js";
 import { connectFailure, connectSuccess } from "./outcomes.js";
+import { resolveConnectTimeouts, withRequestBudget } from "./request-budget.js";
+import { defaultCallbackUrl } from "./runtime-utils.js";
 import { MdbaseSession } from "./session.js";
 export class MdbaseMemoryVerificationStore {
     values = new Map();
@@ -24,6 +26,7 @@ export class MdbaseMemoryVerificationStore {
 export class MdbaseApplicationSession {
     connect;
     options;
+    timeouts;
     listeners = new Set();
     verificationStore;
     snapshot = { status: "opening", connections: [] };
@@ -32,13 +35,17 @@ export class MdbaseApplicationSession {
     stopBase;
     reviewEntries = [];
     verificationGeneration = 0;
-    constructor(connect, options) {
+    constructor(connect, options, timeouts = resolveConnectTimeouts()) {
         this.connect = connect;
         this.options = options;
+        this.timeouts = timeouts;
         this.verificationStore = options.verificationStore ?? defaultVerificationStore();
     }
-    async start() {
-        const manifest = await this.connect.manifest();
+    start(options) {
+        return withRequestBudget(options, this.timeouts.watchStartMs, (budget) => this.startWithinBudget({ signal: budget.signal, timeoutMs: null }));
+    }
+    async startWithinBudget(options) {
+        const manifest = await this.connect.manifest(options);
         if (!manifest.ok)
             return manifest;
         const capabilities = manifest.value.requirements?.capabilities;
@@ -61,10 +68,10 @@ export class MdbaseApplicationSession {
             operations: operationsForSession(capabilities)
         });
         this.stopBase = this.base.subscribe(() => this.refresh());
-        const started = await this.base.start();
+        const started = await this.base.start(options);
         if (!started.ok)
             return started;
-        await this.refresh(true);
+        await this.refresh(true, options);
         return connectSuccess(this.snapshot);
     }
     destroy() {
@@ -97,8 +104,11 @@ export class MdbaseApplicationSession {
     authorize(target, options = {}) {
         return this.requireBase().authorize(target, options);
     }
-    handleAuthorizationCallback(callbackUrl) {
-        return this.requireBase().handleAuthorizationCallback(callbackUrl);
+    handleAuthorizationCallback(callbackUrl, options) {
+        return this.requireBase().handleAuthorizationCallback(String(callbackUrl), options);
+    }
+    completeAuthorization(callbackUrl, options) {
+        return this.requireBase().handleAuthorizationCallback(callbackUrl === undefined ? defaultCallbackUrl() : String(callbackUrl), options);
     }
     ensureCapabilities(capabilities) {
         const manifestRequirements = this.requireManifest().requirements?.capabilities;
@@ -123,7 +133,7 @@ export class MdbaseApplicationSession {
         }
         return this.requireBase().ensureOperations(operationsForIds(capabilities));
     }
-    async applyDefinitionUpdates() {
+    async applyDefinitionUpdates(options) {
         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."));
         }
@@ -135,20 +145,23 @@ export class MdbaseApplicationSession {
             return connectFailure(connectProblem("collection_not_ready", "The collection is not ready."));
         }
         for (const { provision, assessment } of this.reviewEntries) {
-            const applied = await connection.applyTypePack({
+            const input = {
                 provision,
                 installed_by: this.requireManifest().id,
                 expected_assessment_digest: assessment.assessment_digest,
                 ...(assessment.status === "downgrade" ? { allow_downgrade: true } : {})
-            });
+            };
+            const applied = options
+                ? await connection.applyTypePack(input, options)
+                : await connection.applyTypePack(input);
             if (!applied.ok)
                 return applied;
         }
         this.reviewEntries = [];
-        await this.verifyDefinitions(this.context(connection), ++this.verificationGeneration);
+        await this.verifyDefinitions(this.context(connection), ++this.verificationGeneration, options);
         return connectSuccess(this.snapshot);
     }
-    async refresh(awaitVerification = false) {
+    async refresh(awaitVerification = false, options) {
         if (!this.base || !this.manifest)
             return;
         const current = this.base.getSnapshot();
@@ -184,11 +197,11 @@ export class MdbaseApplicationSession {
         else {
             this.publish({ status: "checking_definitions", ...context });
         }
-        const verification = this.verifyDefinitions(context, generation);
+        const verification = this.verifyDefinitions(context, generation, options);
         if (awaitVerification)
             await verification;
     }
-    async verifyDefinitions(context, generation) {
+    async verifyDefinitions(context, generation, options) {
         const connection = this.connection();
         const manifest = this.requireManifest();
         if (!connection || connection.collectionId !== context.collectionId)
@@ -197,10 +210,13 @@ export class MdbaseApplicationSession {
         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({
+            const input = {
                 provision,
                 installed_by: manifest.id
-            });
+            };
+            const outcome = options
+                ? await connection.assessTypePack(input, options)
+                : await connection.assessTypePack(input);
             if (generation !== this.verificationGeneration)
                 return;
             if (!outcome.ok) {

package/dist/async.js

@@ -1,13 +1,19 @@
 export function abortableDelay(milliseconds, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
-            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+            reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
             return;
         }
-        const timeout = setTimeout(resolve, milliseconds);
-        signal?.addEventListener("abort", () => {
+        const cleanup = () => signal?.removeEventListener("abort", abort);
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, milliseconds);
+        const abort = () => {
             clearTimeout(timeout);
-            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
-        }, { once: true });
+            cleanup();
+            reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
     });
 }

package/dist/authority-proof.d.ts

@@ -0,0 +1,3 @@
+import { type GrantKeyStore } from "./crypto.js";
+import type { StoredToken } from "./internal-types.js";
+export declare function authorityProofHeaders(keyStore: GrantKeyStore, token: StoredToken, method: string, url: string, body: string | undefined, credential: string): Promise<Record<string, string>>;

package/dist/authority-proof.js

@@ -0,0 +1,24 @@
+import { RelayCryptoError, signAuthorityRequest } from "./crypto.js";
+import { connectError, serverConnectError } from "./errors.js";
+export async function authorityProofHeaders(keyStore, token, method, url, body, credential) {
+    if (!token.authority?.proofPublicKey)
+        return {};
+    if (!token.keyHandle) {
+        throw connectError("missing_grant_key", "Reconnect this application to restore remote authority request signing.");
+    }
+    try {
+        const target = new URL(url);
+        return await signAuthorityRequest(keyStore, token.keyHandle, token.authority.proofPublicKey, {
+            method,
+            target: `${target.pathname}${target.search}`,
+            body,
+            credential
+        });
+    }
+    catch (error) {
+        if (error instanceof RelayCryptoError) {
+            throw serverConnectError(error.code, error.message);
+        }
+        throw error;
+    }
+}

package/dist/browser/integrity.json

@@ -1,4 +1,4 @@
 {
   "file": "mdbase-connect.min.js",
-  "integrity": "sha384-Cw/OpEwBlbmIBjDZ/JDyh1HiQoKqitRwVSPaYpNCg33rNDYZr/EdSxv5oRa4jP+I"
+  "integrity": "sha384-HYIXh8E0r6OVNVpvmRcFYSjLi278951j0TbDZeZGQQ/jcLhe/Ih1TvTZVdqJGqY7"
 }