@mdbase-dev/connect 0.1.0-beta.21

package/dist/runtime-utils.js

@@ -0,0 +1,224 @@
+import { validateGrantEncryption } from "./crypto.js";
+import { MdbaseConnectError } from "./errors.js";
+import { canonicalJson } from "./operation-helpers.js";
+import { bytesToBase64Url, randomBase64Url } from "./base64.js";
+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 new MdbaseConnectError("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 new MdbaseConnectError(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;
+}
+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.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);
+        return [operations, sync].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)
+            && operations.origin === sync.origin
+            && operations.pathname.split("/")[3] === collectionId
+            && sync.pathname.split("/")[3] === collectionId;
+    }
+    catch {
+        return false;
+    }
+}
+export function validStoredAuthority(authority, collectionId) {
+    return validAuthorityTokenResponse({
+        operations_url: authority?.operationsUrl,
+        sync_url: authority?.syncUrl,
+        replica_id: authority?.replicaId,
+        access_token: authority?.accessToken,
+        proof_public_key: authority?.proofPublicKey
+    }, collectionId);
+}
+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 new MdbaseConnectError("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;
+    }
+}
+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;
+}
+export function stripTrailingSlash(value) {
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+export function defaultManifestSource() {
+    if (typeof location === "undefined") {
+        throw new MdbaseConnectError("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.");
+    }
+    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.");
+    }
+    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.");
+    }
+    return location.href;
+}
+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.");
+    }
+    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/selection.d.ts

@@ -0,0 +1,48 @@
+export type MdbaseSelectionHistory = "push" | "replace";
+export interface MdbaseSessionSelection {
+    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 MdbaseSessionSelection {
+    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 MdbaseSessionSelection {
+    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 { MdbaseConnectError } 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 new MdbaseConnectError("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.");
+        }
+        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);
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,76 @@
+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 { MdbaseSelectionHistory, MdbaseSessionSelection } from "./selection.js";
+export interface MdbaseSessionConnect<Frontmatter extends JsonObject> {
+    authorize(options?: MdbaseAuthorizeOptions): Promise<MdbaseAuthorizationOutcome<Frontmatter>>;
+    completeAuthorization(callbackUrl: string): Promise<MdbaseAuthorizationResult<Frontmatter>>;
+    connections(): MdbaseConnectionInfo[];
+    connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
+    unavailableReason(collectionId: string): MdbaseUnavailableReason | null;
+    onConnectionsChange(listener: (connections: MdbaseConnectionInfo[]) => void): () => void;
+}
+export interface MdbaseSessionOptions {
+    selection: MdbaseSessionSelection;
+    operations?: CollectionOperation[];
+    autoSelect?: "only" | "never";
+}
+export type MdbaseUnavailableReason = "not_authorized" | "authorization_lost" | "invalid_stored_grant";
+export type MdbaseSessionSnapshot<Frontmatter extends JsonObject = JsonObject> = {
+    status: "unselected";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "ready";
+    collectionId: string;
+    connection: MdbaseConnection<Frontmatter>;
+    info: MdbaseConnectionInfo;
+    access: MdbaseAuthorizationCapabilities;
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "unavailable";
+    collectionId: string;
+    reason: MdbaseUnavailableReason;
+    connections: MdbaseConnectionInfo[];
+};
+export declare class MdbaseSession<Frontmatter extends JsonObject = JsonObject> {
+    private readonly connect;
+    private readonly operations;
+    private readonly selection;
+    private readonly autoSelect;
+    private readonly listeners;
+    private snapshot;
+    private snapshotKey;
+    private stopConnections?;
+    private stopSelection?;
+    private stopActiveConnection?;
+    private activeCollectionId;
+    private unavailableReason;
+    private started;
+    private refreshing;
+    private refreshQueued;
+    private transactionDepth;
+    private callbackPromise;
+    constructor(connect: MdbaseSessionConnect<Frontmatter>, options: MdbaseSessionOptions);
+    start(): Promise<MdbaseSessionSnapshot<Frontmatter>>;
+    destroy(): void;
+    getSnapshot(): MdbaseSessionSnapshot<Frontmatter>;
+    subscribe(listener: () => void): () => void;
+    select(collectionId: string, options?: {
+        history?: MdbaseSelectionHistory;
+    }): MdbaseConnection<Frontmatter>;
+    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> | {
+        kind: "unchanged";
+        connection: MdbaseConnection<Frontmatter>;
+    }>;
+    handleAuthorizationCallback(callbackUrl: string): Promise<MdbaseConnection<Frontmatter>>;
+    private autoSelectOnlyConnection;
+    private refresh;
+    private refreshOnce;
+}