@mdbase-dev/connect 0.1.0-beta.100

package/dist/runtime-utils.js

@@ -0,0 +1,368 @@
+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 {
+        return await fetch(input, init);
+    }
+    catch (cause) {
+        throw connectError(code, message, { cause });
+    }
+}
+/** Decode JSON without allowing native syntax/body errors across the SDK boundary. */
+export async function decodeJsonResponse(response, code, message) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (cause) {
+        throw serverConnectError(code, message, { status: response.status, cause });
+    }
+    if (text.trim() === "") {
+        throw serverConnectError(code, message, { status: response.status });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw serverConnectError(code, message, { status: response.status, cause });
+    }
+}
+export function canonicalLoopbackUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:"
+        || !["127.0.0.1", "[::1]"].includes(url.hostname)
+        || url.username
+        || url.password
+        || url.pathname !== "/"
+        || url.search
+        || url.hash) {
+        throw connectError("invalid_loopback_url", "loopbackUrl must be an HTTP origin on 127.0.0.1 or ::1.");
+    }
+    return url.origin;
+}
+export async function createPkce() {
+    const verifier = randomBase64Url(32);
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return { verifier, challenge: bytesToBase64Url(new Uint8Array(digest)) };
+}
+export function apiError(body, fallbackCode, fallbackMessage, status) {
+    return serverConnectError(oauthErrorCode(body) ?? body?.error?.code ?? fallbackCode, body?.error_description ?? body?.error?.message ?? fallbackMessage, {
+        status,
+        details: body?.error?.details,
+        operationOutcome: body?.error?.operation_outcome,
+        traceId: body?.error?.trace_id
+    });
+}
+export function oauthErrorCode(body) {
+    return typeof body?.error === "string" ? body.error : undefined;
+}
+export function validAuthorityTokenResponse(value, collectionId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    if (typeof collectionId !== "string")
+        return false;
+    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"
+        || authority.access_token.length === 0
+        || (authority.proof_public_key !== undefined
+            && (typeof authority.proof_public_key !== "string"
+                || authority.proof_public_key.length === 0)))
+        return false;
+    try {
+        const operations = new URL(authority.operations_url);
+        const sync = new URL(authority.sync_url);
+        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
+            && !url.password
+            && !url.search
+            && !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
+            && files.pathname.split("/")[3] === collectionId;
+    }
+    catch {
+        return false;
+    }
+}
+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;
+    }
+    if (encryption.collection_id !== collectionId)
+        return false;
+    try {
+        validateGrantEncryption(encryption);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseDeviceAuthorization(body) {
+    if (typeof body?.device_code !== "string"
+        || typeof body?.user_code !== "string"
+        || typeof body?.verification_uri !== "string"
+        || typeof body?.verification_uri_complete !== "string"
+        || !Number.isFinite(body?.expires_in)
+        || !Number.isFinite(body?.interval)) {
+        throw connectError("invalid_device_authorization_response", "Connect returned an invalid downloaded application authorization response.");
+    }
+    return {
+        userCode: body.user_code,
+        verificationUri: body.verification_uri,
+        verificationUriComplete: body.verification_uri_complete,
+        expiresAt: Date.now() + Math.max(1, body.expires_in) * 1_000,
+        intervalSeconds: Math.max(1, body.interval)
+    };
+}
+export function parseStored(value) {
+    if (!value)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        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;
+    const scope = value;
+    if (scope.access !== "contract" && scope.access !== "full_collection")
+        return null;
+    if (!Array.isArray(scope.contracts))
+        return null;
+    if (scope.contracts.some((contract) => !contract
+        || typeof contract !== "object"
+        || contract.contract_type !== "record"
+        || typeof contract.id !== "string"
+        || typeof contract.version !== "string"
+        || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(contract.version)
+        || !/^sha256:[0-9a-f]{64}$/.test(contract.digest)
+        || !contract.schema
+        || typeof contract.schema !== "object"
+        || Array.isArray(contract.schema)
+        || !Array.isArray(contract.implementations)
+        || contract.implementations.some((implementation) => !implementation
+            || typeof implementation !== "object"
+            || typeof implementation.type_name !== "string"
+            || !Number.isInteger(implementation.type_version)
+            || !/^sha256:[0-9a-f]{64}$/.test(implementation.digest)
+            || !implementation.fields
+            || typeof implementation.fields !== "object"
+            || Array.isArray(implementation.fields)
+            || Object.values(implementation.fields).some((field) => typeof field !== "string"))))
+        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;
+}
+export function defaultManifestSource() {
+    if (typeof location === "undefined") {
+        throw connectError("manifest_required", "manifest is required outside a browser environment.");
+    }
+    if (location.origin === "null") {
+        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 connectError("redirect_uri_required", "redirectUri is required outside a browser environment.");
+    }
+    return location.href.split(/[?#]/)[0];
+}
+export function applicationStorageOrigin(manifest, manifestSource, redirectUri, registeredPortable) {
+    if ((typeof manifest !== "string" && manifest.distribution === "portable")
+        || registeredPortable)
+        return "null";
+    const redirect = new URL(redirectUri);
+    if (["http:", "https:"].includes(redirect.protocol))
+        return redirect.origin;
+    if (typeof location !== "undefined")
+        return location.origin;
+    if (typeof manifest !== "string")
+        return new URL(manifest.homepage).origin;
+    try {
+        return new URL(manifestSource).origin;
+    }
+    catch {
+        return "";
+    }
+}
+export function collectionIdFromTokenKey(key) {
+    const marker = ":token:";
+    const index = key.lastIndexOf(marker);
+    return index < 0 ? "" : key.slice(index + marker.length);
+}
+export function defaultCallbackUrl() {
+    if (typeof location === "undefined") {
+        throw connectError("callback_url_required", "callbackUrl is required outside a browser environment.");
+    }
+    return location.href;
+}
+export function defaultStorage(memoryOnly) {
+    if (memoryOnly)
+        return new MemoryStorage();
+    if (typeof localStorage === "undefined") {
+        throw connectError("storage_required", "storage is required outside a browser environment.");
+    }
+    try {
+        const probe = `mdbase-connect:probe:${randomBase64Url(8)}`;
+        localStorage.setItem(probe, "1");
+        localStorage.removeItem(probe);
+        return localStorage;
+    }
+    catch {
+        return new MemoryStorage();
+    }
+}
+export class MemoryStorage {
+    values = new Map();
+    get length() {
+        return this.values.size;
+    }
+    clear() {
+        this.values.clear();
+    }
+    getItem(key) {
+        return this.values.get(key) ?? null;
+    }
+    key(index) {
+        return [...this.values.keys()][index] ?? null;
+    }
+    removeItem(key) {
+        this.values.delete(key);
+    }
+    setItem(key, value) {
+        this.values.set(String(key), String(value));
+    }
+}
+export function isOpaquePortableManifest(manifest) {
+    if (typeof manifest === "string" || manifest.distribution !== "portable")
+        return false;
+    return typeof location === "undefined"
+        || location.origin === "null"
+        || !["http:", "https:"].includes(location.protocol);
+}
+export function manifestStorageFingerprint(manifest) {
+    const canonical = canonicalJson(manifest);
+    let first = 0x811c9dc5;
+    let second = 0x9e3779b9;
+    for (let index = 0; index < canonical.length; index += 1) {
+        const code = canonical.charCodeAt(index);
+        first = Math.imul(first ^ code, 0x01000193);
+        second = Math.imul(second ^ code, 0x85ebca6b);
+    }
+    return `${(first >>> 0).toString(16).padStart(8, "0")}${(second >>> 0).toString(16).padStart(8, "0")}`;
+}

package/dist/saved-view-pagination.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import { type CollectionReadProblemCode, type ConnectOutcome } from "./outcomes.js";
+import type { ConnectRequestOptions, ExecuteViewInput, SavedViewExecution, SavedViewPage, SavedViewPagesOptions } from "./operation-types.js";
+type SavedViewOperation<Frontmatter extends JsonObject> = (input: ExecuteViewInput, options?: ConnectRequestOptions) => Promise<ConnectOutcome<SavedViewExecution<Frontmatter>, CollectionReadProblemCode>>;
+export declare function coordinatedSavedViewPages<Frontmatter extends JsonObject>(executeView: SavedViewOperation<Frontmatter>, releaseQueryCursor: (cursor: string) => Promise<void>, input: ExecuteViewInput, options?: SavedViewPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<SavedViewPage<Frontmatter>, CollectionReadProblemCode>>;
+export {};

package/dist/saved-view-pagination.js

@@ -0,0 +1,76 @@
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+export async function* coordinatedSavedViewPages(executeView, releaseQueryCursor, input, options = {}) {
+    const { offset: requestedOffset, limit: requestedLimit, cursor: requestedCursor, ...criteria } = input;
+    let offset = nonNegativeInteger(requestedOffset, 0);
+    const firstPageSize = positiveInteger(options.firstPageSize ?? requestedLimit, 200);
+    const pageSize = positiveInteger(options.pageSize ?? requestedLimit, 1_000);
+    let cursor = requestedCursor;
+    let cursorMode = requestedCursor !== undefined;
+    let cursorToRelease = requestedCursor;
+    let loaded = 0;
+    let pageNumber = 0;
+    try {
+        while (!options.signal?.aborted) {
+            const pageCursor = cursor;
+            const outcome = await executeView({
+                ...criteria,
+                limit: pageNumber === 0 ? firstPageSize : pageSize,
+                ...(cursorMode && pageCursor ? { cursor: pageCursor } : { offset })
+            }, {
+                signal: options.signal,
+                timeoutMs: options.pageTimeoutMs,
+                coordination: { ...options.coordination, coalesce: false }
+            });
+            if (!outcome.ok) {
+                yield outcome;
+                return;
+            }
+            const result = outcome.value;
+            const returnedCursor = result.meta.cursor;
+            if (returnedCursor) {
+                cursorMode = true;
+                cursor = returnedCursor;
+                cursorToRelease = returnedCursor;
+            }
+            else if (cursorMode) {
+                cursor = undefined;
+                cursorToRelease = pageCursor;
+            }
+            if (cursorMode && result.meta.hasMore && !returnedCursor) {
+                yield connectFailure(connectProblem("invalid_operation_response", "The collection authority omitted the cursor required for the next saved-view page."));
+                return;
+            }
+            loaded += result.results.length;
+            const complete = !result.meta.hasMore || result.results.length === 0;
+            const page = {
+                ...result,
+                page: pageNumber,
+                offset,
+                loaded,
+                complete,
+                ...(returnedCursor ? { cursor: returnedCursor } : {})
+            };
+            options.onProgress?.(page);
+            yield connectSuccess(page, outcome.diagnostics);
+            if (complete)
+                return;
+            offset += result.results.length;
+            pageNumber += 1;
+        }
+    }
+    finally {
+        if (cursorMode && cursorToRelease)
+            await releaseQueryCursor(cursorToRelease);
+    }
+}
+function nonNegativeInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : fallback;
+}
+function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}

package/dist/selection.d.ts

@@ -0,0 +1,48 @@
+export type MdbaseSelectionHistory = "push" | "replace";
+export interface MdbaseApplicationSelection {
+    selectedCollectionId(): string | null;
+    select(collectionId: string | null, options?: {
+        history?: MdbaseSelectionHistory;
+    }): void;
+    authorizationReturnTo(): string | undefined;
+    authorizationCallback(): string | null;
+    finishAuthorization(returnTo: string | undefined, collectionId: string): void;
+    clearAuthorizationCallback(returnTo?: string): void;
+    subscribe(listener: () => void): () => void;
+}
+export interface MdbaseBrowserSelectionOptions {
+    collectionParameter?: string;
+    fallbackPath?: string;
+}
+/** URL-backed collection selection for browser and browser-shell applications. */
+export declare class MdbaseBrowserSelection implements MdbaseApplicationSelection {
+    private readonly collectionParameter;
+    private readonly fallbackPath;
+    private readonly listeners;
+    private readonly handlePopState;
+    constructor(options?: MdbaseBrowserSelectionOptions);
+    selectedCollectionId(): string | null;
+    select(collectionId: string | null, options?: {
+        history?: MdbaseSelectionHistory;
+    }): void;
+    authorizationReturnTo(): string;
+    authorizationCallback(): string | null;
+    finishAuthorization(returnTo: string | undefined, collectionId: string): void;
+    clearAuthorizationCallback(returnTo?: string): void;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    private safeAppUrl;
+    private currentUrl;
+    private browserHistory;
+}
+export declare class MdbaseMemorySelection implements MdbaseApplicationSelection {
+    private collectionId;
+    private readonly listeners;
+    selectedCollectionId(): string | null;
+    select(collectionId: string | null): void;
+    authorizationReturnTo(): undefined;
+    authorizationCallback(): null;
+    finishAuthorization(_returnTo: string | undefined, collectionId: string): void;
+    clearAuthorizationCallback(): void;
+    subscribe(listener: () => void): () => void;
+}

package/dist/selection.js

@@ -0,0 +1,112 @@
+import { cleanAuthorizationParameters, isAuthorizationCallbackUrl } from "./authorization-url.js";
+import { connectError } from "./errors.js";
+/** URL-backed collection selection for browser and browser-shell applications. */
+export class MdbaseBrowserSelection {
+    collectionParameter;
+    fallbackPath;
+    listeners = new Set();
+    handlePopState = () => this.emit();
+    constructor(options = {}) {
+        this.collectionParameter = options.collectionParameter ?? "collection";
+        this.fallbackPath = options.fallbackPath ?? "/";
+    }
+    selectedCollectionId() {
+        return this.currentUrl().searchParams.get(this.collectionParameter);
+    }
+    select(collectionId, options = {}) {
+        const url = cleanAuthorizationParameters(this.currentUrl());
+        if (collectionId)
+            url.searchParams.set(this.collectionParameter, collectionId);
+        else
+            url.searchParams.delete(this.collectionParameter);
+        const browserHistory = this.browserHistory();
+        browserHistory[options.history === "push" ? "pushState" : "replaceState"](browserHistory.state, "", url);
+        this.emit();
+    }
+    authorizationReturnTo() {
+        const url = cleanAuthorizationParameters(this.currentUrl());
+        return `${url.pathname}${url.search}${url.hash}`;
+    }
+    authorizationCallback() {
+        const value = this.currentUrl().href;
+        return isAuthorizationCallbackUrl(value) ? value : null;
+    }
+    finishAuthorization(returnTo, collectionId) {
+        const url = this.safeAppUrl(returnTo ?? this.fallbackPath);
+        cleanAuthorizationParameters(url);
+        url.searchParams.set(this.collectionParameter, collectionId);
+        const browserHistory = this.browserHistory();
+        browserHistory.replaceState(null, "", url);
+        this.emit();
+    }
+    clearAuthorizationCallback(returnTo) {
+        const url = returnTo ? this.safeAppUrl(returnTo) : this.currentUrl();
+        const browserHistory = this.browserHistory();
+        browserHistory.replaceState(browserHistory.state, "", cleanAuthorizationParameters(url));
+        this.emit();
+    }
+    subscribe(listener) {
+        const first = this.listeners.size === 0;
+        this.listeners.add(listener);
+        if (first && typeof window !== "undefined") {
+            window.addEventListener("popstate", this.handlePopState);
+        }
+        return () => {
+            this.listeners.delete(listener);
+            if (this.listeners.size === 0 && typeof window !== "undefined") {
+                window.removeEventListener("popstate", this.handlePopState);
+            }
+        };
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    safeAppUrl(value) {
+        const current = this.currentUrl();
+        const candidate = new URL(value, current.origin);
+        return candidate.origin === current.origin
+            ? candidate
+            : new URL(this.fallbackPath, current.origin);
+    }
+    currentUrl() {
+        if (typeof location === "undefined") {
+            throw connectError("browser_required", "Browser selection requires a browser environment.");
+        }
+        return new URL(location.href);
+    }
+    browserHistory() {
+        if (typeof history === "undefined") {
+            throw connectError("browser_required", "Browser selection requires a browser environment.");
+        }
+        return history;
+    }
+}
+export class MdbaseMemorySelection {
+    collectionId = null;
+    listeners = new Set();
+    selectedCollectionId() {
+        return this.collectionId;
+    }
+    select(collectionId) {
+        if (collectionId === this.collectionId)
+            return;
+        this.collectionId = collectionId;
+        for (const listener of this.listeners)
+            listener();
+    }
+    authorizationReturnTo() {
+        return undefined;
+    }
+    authorizationCallback() {
+        return null;
+    }
+    finishAuthorization(_returnTo, collectionId) {
+        this.select(collectionId);
+    }
+    clearAuthorizationCallback() { }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}