@mdbase-dev/connect 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/operation-types.d.ts

@@ -1,5 +1,4 @@
-import type { CollectionOperation, JsonObject, QueryRecord, RecordDocument } from "@mdbase-dev/connect-protocol";
-import type { MdbaseConnectError } from "./errors.js";
+import type { CollectionOperation, ConnectProblem, JsonObject, QueryRecord, RecordDocument } from "@mdbase-dev/connect-protocol";
 export interface MdbaseDesiredTimer {
     /** Stable within the timer namespace. */
     id: string;
@@ -241,11 +240,11 @@ export type WatchStatus = {
     cursor?: number;
     attempt: number;
     retryInMs: number;
-    error: unknown;
+    problem: ConnectProblem;
 } | {
     state: "reset_required";
     cursor: number;
-    error: MdbaseConnectError;
+    problem: ConnectProblem<"change_cursor_reset">;
 };
 /** Provider-neutral operation transport used by the typed collection client. */
 export interface MdbaseCollectionTransport {

package/dist/outcomes.d.ts

@@ -0,0 +1,51 @@
+import type { ConnectProblem, ConnectProblemCode, MdbaseDiagnostic } from "@mdbase-dev/connect-protocol";
+export type ConnectSuccess<Value> = {
+    ok: true;
+    value: Value;
+    diagnostics: MdbaseDiagnostic[];
+};
+export type ConnectFailure<Code extends ConnectProblemCode = ConnectProblemCode> = {
+    ok: false;
+    problem: ConnectProblem<Code>;
+};
+/**
+ * Every expected failure from the public SDK is data. Exceptions are reserved
+ * for programming errors and broken SDK invariants.
+ */
+export type ConnectOutcome<Value, Code extends ConnectProblemCode = ConnectProblemCode> = ConnectSuccess<Value> | ConnectFailure<Code>;
+export type CommonOperationProblemCode = "access_denied" | "access_paused" | "authorization_expired" | "collection_access_denied" | "connector_identity_changed" | "connector_offline" | "connector_upgrade_required" | "direct_operation_rejected" | "operation_outcome_unknown" | "encryption_required" | "encrypted_relay_rejected" | "hosted_provider_unavailable" | "insufficient_access" | "invalid_encrypted_response" | "invalid_operation_response" | "invalid_request" | "missing_grant_key" | "not_authorized" | "operation_cancelled" | "operation_failed" | "rate_limited" | "relay_authorization_expired" | "relay_unavailable" | "temporarily_unavailable" | "timeout" | "unsupported_operation";
+export declare const COMMON_OPERATION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation"];
+export declare const ALL_CONNECT_PROBLEM_CODES: ConnectProblemCode[];
+export type RegistrationProblemCode = "discovery_failed" | "invalid_application_manifest" | "invalid_request" | "manifest_load_failed" | "rate_limited" | "temporarily_unavailable" | "timeout";
+export declare const REGISTRATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout"];
+export type AuthorizationProblemCode = RegistrationProblemCode | "access_denied" | "approval_window_blocked" | "authorization_cancelled" | "browser_required" | "collection_access_denied" | "collection_configuration_invalid" | "collection_contracts_missing" | "collection_incompatible" | "collection_invalid" | "collection_kind_unsupported" | "collection_mismatch" | "collection_not_found" | "collection_type_registry_invalid" | "collection_version_unsupported" | "connector_identity_changed" | "connector_offline" | "connector_upgrade_required" | "device_authorization_failed" | "encryption_required" | "expired_token" | "invalid_callback" | "invalid_device_authorization_response" | "invalid_token_response" | "scope_denied" | "token_exchange_failed";
+export declare const AUTHORIZATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "approval_window_blocked", "authorization_cancelled", "browser_required", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "encryption_required", "expired_token", "invalid_callback", "invalid_device_authorization_response", "invalid_token_response", "scope_denied", "token_exchange_failed"];
+export type NotificationProblemCode = RegistrationProblemCode | "authorization_expired" | "invalid_push_subscription" | "managed_fcm_not_declared" | "not_authorized" | "notification_criterion_not_declared" | "notification_reauthorization_required" | "notification_registration_failed" | "notification_unregistration_failed" | "notifications_not_declared" | "notifications_unavailable";
+export declare const NOTIFICATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "authorization_expired", "invalid_push_subscription", "managed_fcm_not_declared", "not_authorized", "notification_criterion_not_declared", "notification_reauthorization_required", "notification_registration_failed", "notification_unregistration_failed", "notifications_not_declared", "notifications_unavailable"];
+export type DirectAccessProblemCode = "connector_offline" | "connector_upgrade_required" | "invalid_operation_response" | "not_authorized" | "operation_failed" | "temporarily_unavailable" | "timeout";
+export declare const DIRECT_ACCESS_PROBLEM_CODES: readonly ["connector_offline", "connector_upgrade_required", "invalid_operation_response", "not_authorized", "operation_failed", "temporarily_unavailable", "timeout"];
+export type SessionProblemCode = AuthorizationProblemCode | "collection_not_ready" | "collection_not_selected" | "unknown_collection";
+export declare const SESSION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "approval_window_blocked", "authorization_cancelled", "browser_required", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "encryption_required", "expired_token", "invalid_callback", "invalid_device_authorization_response", "invalid_token_response", "scope_denied", "token_exchange_failed", "collection_not_ready", "collection_not_selected", "unknown_collection"];
+export type CollectionSetupProblemCode = "collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported";
+export type CollectionDescriptionProblemCode = CommonOperationProblemCode | CollectionSetupProblemCode;
+export type CollectionReadProblemCode = CollectionDescriptionProblemCode | "invalid_path" | "operation_invalid";
+export type CollectionQueryProblemCode = CollectionReadProblemCode | "query_snapshot_changed" | "sandbox_unsupported";
+export type CollectionMutationProblemCode = CollectionReadProblemCode | "concurrent_modification" | "invalid_preflight" | "pending_mutation_unresolved";
+export type CollectionChangesProblemCode = CollectionDescriptionProblemCode | "change_cursor_reset";
+export type CollectionTypeProblemCode = CollectionMutationProblemCode | "type_pack_provision_failed";
+export declare const COLLECTION_SETUP_PROBLEM_CODES: readonly ["collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported"];
+export declare const COLLECTION_DESCRIPTION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported"];
+export declare const COLLECTION_READ_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid"];
+export declare const COLLECTION_QUERY_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "query_snapshot_changed", "sandbox_unsupported"];
+export declare const COLLECTION_MUTATION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "concurrent_modification", "invalid_preflight", "pending_mutation_unresolved"];
+export declare const COLLECTION_CHANGES_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "change_cursor_reset"];
+export declare const COLLECTION_TYPE_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_expired", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "concurrent_modification", "invalid_preflight", "pending_mutation_unresolved", "type_pack_provision_failed"];
+export declare function connectSuccess<Value>(value: Value, diagnostics?: MdbaseDiagnostic[]): ConnectSuccess<Value>;
+export declare function connectFailure<Code extends ConnectProblemCode>(problem: ConnectProblem<Code>): ConnectFailure<Code>;
+export declare function captureConnectOutcome<Value, Code extends ConnectProblemCode>(operation: () => Promise<Value>, allowedCodes: readonly Code[]): Promise<ConnectOutcome<Value, Code>>;
+export declare class ConnectOutcomeError extends Error {
+    readonly problem: ConnectProblem;
+    constructor(problem: ConnectProblem);
+}
+/** Explicitly opt back into exception flow for scripts and narrow adapters. */
+export declare function unwrapConnectOutcome<Value>(outcome: ConnectOutcome<Value>): Value;

package/dist/outcomes.js

@@ -0,0 +1,168 @@
+import { CONNECT_PROBLEM_CATALOG } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError, unknownConnectProblem } from "./errors.js";
+export const COMMON_OPERATION_PROBLEM_CODES = [
+    "access_denied",
+    "access_paused",
+    "authorization_expired",
+    "collection_access_denied",
+    "connector_identity_changed",
+    "connector_offline",
+    "connector_upgrade_required",
+    "direct_operation_rejected",
+    "operation_outcome_unknown",
+    "encryption_required",
+    "encrypted_relay_rejected",
+    "hosted_provider_unavailable",
+    "insufficient_access",
+    "invalid_encrypted_response",
+    "invalid_operation_response",
+    "invalid_request",
+    "missing_grant_key",
+    "not_authorized",
+    "operation_cancelled",
+    "operation_failed",
+    "rate_limited",
+    "relay_authorization_expired",
+    "relay_unavailable",
+    "temporarily_unavailable",
+    "timeout",
+    "unsupported_operation"
+];
+export const ALL_CONNECT_PROBLEM_CODES = Object.keys(CONNECT_PROBLEM_CATALOG);
+export const REGISTRATION_PROBLEM_CODES = [
+    "discovery_failed",
+    "invalid_application_manifest",
+    "invalid_request",
+    "manifest_load_failed",
+    "rate_limited",
+    "temporarily_unavailable",
+    "timeout"
+];
+export const AUTHORIZATION_PROBLEM_CODES = [
+    ...REGISTRATION_PROBLEM_CODES,
+    "access_denied",
+    "approval_window_blocked",
+    "authorization_cancelled",
+    "browser_required",
+    "collection_access_denied",
+    "collection_configuration_invalid",
+    "collection_contracts_missing",
+    "collection_incompatible",
+    "collection_invalid",
+    "collection_kind_unsupported",
+    "collection_mismatch",
+    "collection_not_found",
+    "collection_type_registry_invalid",
+    "collection_version_unsupported",
+    "connector_identity_changed",
+    "connector_offline",
+    "connector_upgrade_required",
+    "device_authorization_failed",
+    "encryption_required",
+    "expired_token",
+    "invalid_callback",
+    "invalid_device_authorization_response",
+    "invalid_token_response",
+    "scope_denied",
+    "token_exchange_failed"
+];
+export const NOTIFICATION_PROBLEM_CODES = [
+    ...REGISTRATION_PROBLEM_CODES,
+    "authorization_expired",
+    "invalid_push_subscription",
+    "managed_fcm_not_declared",
+    "not_authorized",
+    "notification_criterion_not_declared",
+    "notification_reauthorization_required",
+    "notification_registration_failed",
+    "notification_unregistration_failed",
+    "notifications_not_declared",
+    "notifications_unavailable"
+];
+export const DIRECT_ACCESS_PROBLEM_CODES = [
+    "connector_offline",
+    "connector_upgrade_required",
+    "invalid_operation_response",
+    "not_authorized",
+    "operation_failed",
+    "temporarily_unavailable",
+    "timeout"
+];
+export const SESSION_PROBLEM_CODES = [
+    ...AUTHORIZATION_PROBLEM_CODES,
+    "collection_not_ready",
+    "collection_not_selected",
+    "unknown_collection"
+];
+export const COLLECTION_SETUP_PROBLEM_CODES = [
+    "collection_configuration_invalid",
+    "collection_invalid",
+    "collection_type_registry_invalid",
+    "collection_version_unsupported"
+];
+export const COLLECTION_DESCRIPTION_PROBLEM_CODES = [
+    ...COMMON_OPERATION_PROBLEM_CODES,
+    ...COLLECTION_SETUP_PROBLEM_CODES
+];
+export const COLLECTION_READ_PROBLEM_CODES = [
+    ...COLLECTION_DESCRIPTION_PROBLEM_CODES,
+    "invalid_path",
+    "operation_invalid"
+];
+export const COLLECTION_QUERY_PROBLEM_CODES = [
+    ...COLLECTION_READ_PROBLEM_CODES,
+    "query_snapshot_changed",
+    "sandbox_unsupported"
+];
+export const COLLECTION_MUTATION_PROBLEM_CODES = [
+    ...COLLECTION_READ_PROBLEM_CODES,
+    "concurrent_modification",
+    "invalid_preflight",
+    "pending_mutation_unresolved"
+];
+export const COLLECTION_CHANGES_PROBLEM_CODES = [
+    ...COLLECTION_DESCRIPTION_PROBLEM_CODES,
+    "change_cursor_reset"
+];
+export const COLLECTION_TYPE_PROBLEM_CODES = [
+    ...COLLECTION_MUTATION_PROBLEM_CODES,
+    "type_pack_provision_failed"
+];
+export function connectSuccess(value, diagnostics = []) {
+    return { ok: true, value, diagnostics };
+}
+export function connectFailure(problem) {
+    return { ok: false, problem };
+}
+export async function captureConnectOutcome(operation, allowedCodes) {
+    try {
+        return connectSuccess(await operation());
+    }
+    catch (error) {
+        if (!(error instanceof MdbaseConnectError))
+            throw error;
+        const problem = error.problem;
+        if (problem.code === "unknown" || allowedCodes.includes(problem.code)) {
+            return connectFailure(problem);
+        }
+        return connectFailure(unknownConnectProblem(problem.code, problem.message, {
+            details: problem.details,
+            operationOutcome: problem.operation_outcome,
+            traceId: problem.trace_id
+        }));
+    }
+}
+export class ConnectOutcomeError extends Error {
+    problem;
+    constructor(problem) {
+        super(problem.message);
+        this.problem = problem;
+        this.name = "ConnectOutcomeError";
+    }
+}
+/** Explicitly opt back into exception flow for scripts and narrow adapters. */
+export function unwrapConnectOutcome(outcome) {
+    if (!outcome.ok)
+        throw new ConnectOutcomeError(outcome.problem);
+    return outcome.value;
+}

package/dist/runtime-utils.d.ts

@@ -1,7 +1,10 @@
-import type { GrantEncryption, GrantScope, MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
+import type { FileCapability, GrantEncryption, GrantScope, MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import { MdbaseConnectError } from "./errors.js";
 import type { StoredToken } from "./internal-types.js";
 import type { MdbaseDeviceAuthorization } from "./authorization-types.js";
+type NetworkProblemCode = "notification_registration_failed" | "notification_unregistration_failed" | "notifications_unavailable" | "temporarily_unavailable";
+/** Normalize fetch rejection at the exact I/O boundary. */
+export declare function connectFetch(input: RequestInfo | URL, init: RequestInit | undefined, code: NetworkProblemCode, message: string): Promise<Response>;
 export declare function canonicalLoopbackUrl(value: string): string;
 export declare function createPkce(): Promise<{
     verifier: string;
@@ -11,6 +14,7 @@ export declare function apiError(body: any, fallbackCode: string, fallbackMessag
 export declare function oauthErrorCode(body: any): string | undefined;
 export declare function validAuthorityTokenResponse(value: unknown, collectionId: unknown): boolean;
 export declare function validStoredAuthority(authority: StoredToken["authority"], collectionId: string): boolean;
+export declare function validFileCapability(value: unknown): value is FileCapability;
 export declare function validStoredEncryption(encryption: StoredToken["encryption"], collectionId: string): encryption is GrantEncryption;
 export declare function parseDeviceAuthorization(body: any): MdbaseDeviceAuthorization;
 export declare function parseStored<T>(value: string | null): T | null;
@@ -31,3 +35,4 @@ export declare class MemoryStorage implements Storage {
 }
 export declare function isOpaquePortableManifest(manifest: MdbaseAppManifest | string): boolean;
 export declare function manifestStorageFingerprint(manifest: MdbaseAppManifest): string;
+export {};

package/dist/runtime-utils.js

@@ -1,7 +1,16 @@
 import { validateGrantEncryption } from "./crypto.js";
-import { MdbaseConnectError } from "./errors.js";
+import { connectError, serverConnectError } from "./errors.js";
 import { canonicalJson } from "./operation-helpers.js";
 import { bytesToBase64Url, randomBase64Url } from "./base64.js";
+/** Normalize fetch rejection at the exact I/O boundary. */
+export async function connectFetch(input, init, code, message) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (cause) {
+        throw connectError(code, message, { cause });
+    }
+}
 export function canonicalLoopbackUrl(value) {
     const url = new URL(value);
     if (url.protocol !== "http:"
@@ -11,7 +20,7 @@ export function canonicalLoopbackUrl(value) {
         || url.pathname !== "/"
         || url.search
         || url.hash) {
-        throw new MdbaseConnectError("invalid_loopback_url", "loopbackUrl must be an HTTP origin on 127.0.0.1 or ::1.");
+        throw connectError("invalid_loopback_url", "loopbackUrl must be an HTTP origin on 127.0.0.1 or ::1.");
     }
     return url.origin;
 }
@@ -21,7 +30,7 @@ export async function createPkce() {
     return { verifier, challenge: bytesToBase64Url(new Uint8Array(digest)) };
 }
 export function apiError(body, fallbackCode, fallbackMessage, status) {
-    return new MdbaseConnectError(oauthErrorCode(body) ?? body?.error?.code ?? fallbackCode, body?.error_description ?? body?.error?.message ?? fallbackMessage, { status, details: body?.error?.details });
+    return serverConnectError(oauthErrorCode(body) ?? body?.error?.code ?? fallbackCode, body?.error_description ?? body?.error?.message ?? fallbackMessage, { status, details: body?.error?.details });
 }
 export function oauthErrorCode(body) {
     return typeof body?.error === "string" ? body.error : undefined;
@@ -34,6 +43,7 @@ export function validAuthorityTokenResponse(value, collectionId) {
     const authority = value;
     if (typeof authority.operations_url !== "string"
         || typeof authority.sync_url !== "string"
+        || typeof authority.files_url !== "string"
         || typeof authority.replica_id !== "string"
         || authority.replica_id.length === 0
         || typeof authority.access_token !== "string"
@@ -45,7 +55,8 @@ export function validAuthorityTokenResponse(value, collectionId) {
     try {
         const operations = new URL(authority.operations_url);
         const sync = new URL(authority.sync_url);
-        return [operations, sync].every((url) => (url.protocol === "https:"
+        const files = new URL(authority.files_url);
+        return [operations, sync, files].every((url) => (url.protocol === "https:"
             || (url.protocol === "http:"
                 && ["localhost", "127.0.0.1", "[::1]", "::1"].includes(url.hostname)))
             && !url.username
@@ -54,9 +65,12 @@ export function validAuthorityTokenResponse(value, collectionId) {
             && !url.hash)
             && /^\/v1\/authorities\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/operations$/i.test(operations.pathname)
             && /^\/v1\/authorities\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/sync$/i.test(sync.pathname)
+            && /^\/v1\/authorities\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/files$/i.test(files.pathname)
             && operations.origin === sync.origin
+            && operations.origin === files.origin
             && operations.pathname.split("/")[3] === collectionId
-            && sync.pathname.split("/")[3] === collectionId;
+            && sync.pathname.split("/")[3] === collectionId
+            && files.pathname.split("/")[3] === collectionId;
     }
     catch {
         return false;
@@ -66,11 +80,76 @@ export function validStoredAuthority(authority, collectionId) {
     return validAuthorityTokenResponse({
         operations_url: authority?.operationsUrl,
         sync_url: authority?.syncUrl,
+        files_url: authority?.filesUrl,
         replica_id: authority?.replicaId,
         access_token: authority?.accessToken,
         proof_public_key: authority?.proofPublicKey
     }, collectionId);
 }
+export function validFileCapability(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const capability = value;
+    const actions = capability.actions;
+    if (capability.kind !== "files"
+        || capability.protocol_version !== 1
+        || !Array.isArray(actions)
+        || actions.length === 0
+        || actions.length > 6
+        || new Set(actions).size !== actions.length
+        || actions.some((action) => ![
+            "list",
+            "read",
+            "add",
+            "replace",
+            "move",
+            "delete"
+        ].includes(action)))
+        return false;
+    const scope = capability.scope;
+    if (!scope || typeof scope !== "object" || Array.isArray(scope))
+        return false;
+    if (scope.kind === "collection") {
+        return Object.keys(scope).length === 1;
+    }
+    return scope.kind === "selected_folders"
+        && Object.keys(scope).length === 2
+        && Array.isArray(scope.folders)
+        && scope.folders.length > 0
+        && scope.folders.length <= 100
+        && new Set(scope.folders).size === scope.folders.length
+        && scope.folders.every((folder) => typeof folder === "string"
+            && folder.length > 0
+            && folder.length <= 1_024
+            && validFileFolder(folder));
+}
+function validFileFolder(folder) {
+    const reserved = new Set([
+        ".mdbase",
+        ".git",
+        "node_modules",
+        "_contracts",
+        "_schemas",
+        "_types",
+        "_views"
+    ]);
+    return !folder.startsWith("/")
+        && !folder.endsWith("/")
+        && !folder.includes("\\")
+        && folder.split("/").every((component) => {
+            const stem = component.split(".")[0]?.toUpperCase() ?? "";
+            return component !== ""
+                && component !== "."
+                && component !== ".."
+                && !component.startsWith(".")
+                && !component.endsWith(" ")
+                && !component.endsWith(".")
+                && !/[<>:"|?*]/.test(component)
+                && !reserved.has(component.toLowerCase())
+                && !["CON", "PRN", "AUX", "NUL"].includes(stem)
+                && !/^(COM|LPT)[1-9]$/.test(stem);
+        });
+}
 export function validStoredEncryption(encryption, collectionId) {
     if (!encryption || typeof encryption !== "object" || Array.isArray(encryption)) {
         return false;
@@ -92,7 +171,7 @@ export function parseDeviceAuthorization(body) {
         || typeof body?.verification_uri_complete !== "string"
         || !Number.isFinite(body?.expires_in)
         || !Number.isFinite(body?.interval)) {
-        throw new MdbaseConnectError("invalid_device_authorization_response", "Connect returned an invalid downloaded application authorization response.");
+        throw connectError("invalid_device_authorization_response", "Connect returned an invalid downloaded application authorization response.");
     }
     return {
         userCode: body.user_code,
@@ -148,22 +227,22 @@ export function stripTrailingSlash(value) {
 }
 export function defaultManifestSource() {
     if (typeof location === "undefined") {
-        throw new MdbaseConnectError("manifest_required", "manifest is required outside a browser environment.");
+        throw connectError("manifest_required", "manifest is required outside a browser environment.");
     }
     if (location.origin === "null") {
-        throw new MdbaseConnectError("manifest_required", "Downloaded applications must provide their v1 portable manifest inline.");
+        throw connectError("manifest_required", "Downloaded applications must provide their v1 portable manifest inline.");
     }
     return new URL("/.well-known/mdbase-app.json", location.origin).href;
 }
 export function defaultRedirectUri() {
     if (typeof location === "undefined") {
-        throw new MdbaseConnectError("redirect_uri_required", "redirectUri is required outside a browser environment.");
+        throw connectError("redirect_uri_required", "redirectUri is required outside a browser environment.");
     }
     return location.href.split(/[?#]/)[0];
 }
 export function defaultCallbackUrl() {
     if (typeof location === "undefined") {
-        throw new MdbaseConnectError("callback_url_required", "callbackUrl is required outside a browser environment.");
+        throw connectError("callback_url_required", "callbackUrl is required outside a browser environment.");
     }
     return location.href;
 }
@@ -171,7 +250,7 @@ export function defaultStorage(memoryOnly) {
     if (memoryOnly)
         return new MemoryStorage();
     if (typeof localStorage === "undefined") {
-        throw new MdbaseConnectError("storage_required", "storage is required outside a browser environment.");
+        throw connectError("storage_required", "storage is required outside a browser environment.");
     }
     try {
         const probe = `mdbase-connect:probe:${randomBase64Url(8)}`;

package/dist/selection.js

@@ -1,5 +1,5 @@
 import { cleanAuthorizationParameters, isAuthorizationCallbackUrl } from "./authorization-url.js";
-import { MdbaseConnectError } from "./errors.js";
+import { connectError } from "./errors.js";
 /** URL-backed collection selection for browser and browser-shell applications. */
 export class MdbaseBrowserSelection {
     collectionParameter;
@@ -71,13 +71,13 @@ export class MdbaseBrowserSelection {
     }
     currentUrl() {
         if (typeof location === "undefined") {
-            throw new MdbaseConnectError("browser_required", "Browser selection requires a browser environment.");
+            throw connectError("browser_required", "Browser selection requires a browser environment.");
         }
         return new URL(location.href);
     }
     browserHistory() {
         if (typeof history === "undefined") {
-            throw new MdbaseConnectError("browser_required", "Browser selection requires a browser environment.");
+            throw connectError("browser_required", "Browser selection requires a browser environment.");
         }
         return history;
     }

package/dist/session.d.ts

@@ -1,10 +1,11 @@
 import type { CollectionOperation, JsonObject } from "@mdbase-dev/connect-protocol";
 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 { MdbaseSelectionHistory, MdbaseSessionSelection } from "./selection.js";
 export interface MdbaseSessionConnect<Frontmatter extends JsonObject> {
-    authorize(options?: MdbaseAuthorizeOptions): Promise<MdbaseAuthorizationOutcome<Frontmatter>>;
-    completeAuthorization(callbackUrl: string): Promise<MdbaseAuthorizationResult<Frontmatter>>;
+    authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
+    completeAuthorization(callbackUrl: string): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
     connections(): MdbaseConnectionInfo[];
     connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
     unavailableReason(collectionId: string): MdbaseUnavailableReason | null;
@@ -51,25 +52,25 @@ export declare class MdbaseSession<Frontmatter extends JsonObject = JsonObject>
     private transactionDepth;
     private callbackPromise;
     constructor(connect: MdbaseSessionConnect<Frontmatter>, options: MdbaseSessionOptions);
-    start(): Promise<MdbaseSessionSnapshot<Frontmatter>>;
+    start(): Promise<ConnectOutcome<MdbaseSessionSnapshot<Frontmatter>, SessionProblemCode>>;
     destroy(): void;
     getSnapshot(): MdbaseSessionSnapshot<Frontmatter>;
     subscribe(listener: () => void): () => void;
     select(collectionId: string, options?: {
         history?: MdbaseSelectionHistory;
-    }): MdbaseConnection<Frontmatter>;
+    }): ConnectOutcome<MdbaseConnection<Frontmatter>, "unknown_collection">;
     clearSelection(options?: {
         history?: MdbaseSelectionHistory;
     }): void;
     forget(collectionId: string): void;
     authorize(target: "choose" | "selected" | {
         collectionId: string;
-    }, options?: Omit<MdbaseAuthorizeOptions, "operations" | "returnTo" | "target">): Promise<MdbaseAuthorizationOutcome<Frontmatter>>;
-    ensureOperations(requiredOperations: CollectionOperation[]): Promise<MdbaseAuthorizationOutcome<Frontmatter> | {
+    }, options?: Omit<MdbaseAuthorizeOptions, "operations" | "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    ensureOperations(requiredOperations: CollectionOperation[]): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
         kind: "unchanged";
         connection: MdbaseConnection<Frontmatter>;
-    }>;
-    handleAuthorizationCallback(callbackUrl: string): Promise<MdbaseConnection<Frontmatter>>;
+    }, SessionProblemCode>>;
+    handleAuthorizationCallback(callbackUrl: string): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
     private autoSelectOnlyConnection;
     private refresh;
     private refreshOnce;