@mdbase-dev/connect 0.1.0-beta.21

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdbase connect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# `@mdbase-dev/connect`
+
+Browser SDK for dynamically discovered mdbase connect applications.
+
+It also ships a dependency-free browser bundle for downloaded HTML
+applications. See the [portable application guide](../../docs/portable-apps.md)
+for the v1 manifest, device-code flow, version-pinned CDN URL, SRI metadata,
+and `file://` storage boundary.
+
+The complete developer guide covers
+[setup](https://mdbase.dev/sdk/quickstart/),
+[manifests and contracts](https://mdbase.dev/sdk/manifest/),
+[authorization](https://mdbase.dev/sdk/authorization/),
+[operations](https://mdbase.dev/sdk/operations/),
+[routing](https://mdbase.dev/sdk/routing/),
+[offline sync](https://mdbase.dev/sdk/offline-sync/), and
+[testing](https://mdbase.dev/sdk/testing/).
+
+```ts
+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"
+});
+const session = mdbase.createSession({
+  operations: ["describe", "changes", "read", "query", "update"],
+  selection: new MdbaseBrowserSelection()
+});
+
+await session.start();
+if (session.getSnapshot().status === "unselected") {
+  await session.authorize("choose");
+}
+
+const snapshot = session.getSnapshot();
+if (snapshot.status !== "ready") throw new Error("Choose an authorized collection.");
+const connection = snapshot.connection;
+const description = await connection.describe();
+const workouts = await connection.query({ types: ["workout"] });
+await connection.update({
+  path: "workouts/monday.md",
+  patch: { completed: true },
+  if_revision: workouts.result.results[0].revision
+});
+
+const preview = await connection.preflightRename({
+  from: "workouts/monday.md",
+  to: "archive/monday.md",
+  update_refs: true,
+  if_revision: workouts.result.results[0].revision
+});
+console.log(preview.result.references_affected);
+
+const controller = new AbortController();
+await connection.renameWithProgress({
+  from: "workouts/monday.md",
+  to: "archive/monday.md",
+  update_refs: true,
+  if_revision: workouts.result.results[0].revision
+}, {
+  preflight: preview.result,
+  signal: controller.signal,
+  onProgress: ({ state, estimate, cancellable }) => {
+    console.log(state, estimate?.affectedRecords, cancellable);
+  }
+});
+
+for await (const change of connection.watch()) {
+  console.log(change.type, change.payload.path);
+}
+```
+
+`MdbaseConnect` is the application-level authorization registry.
+`MdbaseSession` is the normal application boundary: it owns active collection
+selection, authorization callback completion, access capabilities, and one
+reactive snapshot. Use `getSnapshot()` and `subscribe()` directly or through
+your framework's external-store integration. A snapshot is `unselected`,
+`ready`, or `unavailable`; an unavailable bookmark includes the explicit
+collection ID and reason instead of collapsing every recovery state to `null`.
+
+`MdbaseBrowserSelection` keeps the stable collection ID in
+`?collection=<id>`, preserves unrelated path/query/hash and router state,
+restores authorization callbacks safely, and reports browser back/forward
+changes to the session. The session auto-selects only when exactly one saved
+connection exists. Switching is state-driven and must not reload the page:
+
+```ts
+session.select(collectionId, { history: "replace" });
+session.clearSelection();
+session.forget(collectionId);
+```
+
+Selection validates the saved authorization before changing the URL. Explicit
+unavailable IDs remain authoritative so applications can offer exact
+reauthorization or another collection:
+
+```ts
+await session.authorize("selected"); // exact bookmarked collection
+await session.authorize("choose");   // any compatible collection
+await session.authorize({ collectionId }); // exact adoption/migration target
+```
+
+Collection IDs are opaque non-secret locators that may appear in browser
+history and logs. Grants remain the authorization boundary, and names are
+display text that may change.
+
+Bundled v1 application manifests can declare runtime notification criteria.
+Register a service worker from a user gesture to receive standards-based Web
+Push while the app is closed:
+
+```ts
+const worker = await navigator.serviceWorker.register("/service-worker.js");
+await connection.registerNotifications({
+  serviceWorker: worker,
+  criteria: ["workout.reminder"]
+});
+```
+
+In the service worker:
+
+```ts
+import { showMdbasePushNotification } from "@mdbase-dev/connect";
+
+self.addEventListener("push", (event) => {
+  event.waitUntil(
+    showMdbasePushNotification(self.registration, event.data?.json())
+  );
+});
+```
+
+Pushes contain an opaque signal and cursor plus static declaration presentation,
+never record paths or content. Treat them as a wake-up hint and read current
+authorized state after opening. Registration atomically replaces the selected
+criteria for that installation. See the
+[runtime notifications guide](../../docs/notifications.md) for declaration and
+deployment examples.
+
+Native shells can use one FCM token for Android and iOS when the declaration
+declares `notifications.native_delivery.mode` as `managed_fcm`:
+
+```ts
+await connection.registerNativeNotifications({
+  token: await nativeMessaging.getToken(),
+  criteria: ["workout.reminder"]
+});
+```
+
+Re-register when Firebase rotates the token. Parse the string-valued
+notification data with `parseMdbaseNativeNotificationData()`, refresh current
+collection state, and call `unregisterNativeNotifications()` before deleting
+the token on opt-out. The public Firebase project ID is read from the
+application declaration; service credentials are never embedded in the app.
+
+Connect-managed FCM makes Connect a trusted sender for the application's
+Firebase project. It suits single-owner deployments; applications with a
+broader audience should normally declare signed webhook delivery and keep
+their Apple/Firebase credentials in their own backend. The notifications guide
+documents both threat models. New or changed declaration criteria never silently
+broaden an existing grant: handle `notification_reauthorization_required` by
+running authorization again before retrying registration.
+
+Before opening a feature, inspect its exact authorization gap instead of
+waiting for an operation to fail:
+
+```ts
+const required = ["read", "query", "update"] as const;
+const capabilities = connection.authorizationCapabilities([...required]);
+if (!capabilities.sufficient) {
+  console.log("Needs", capabilities.missingOperations);
+  await connection.requestOperations([...required]);
+}
+```
+
+`requestOperations()` is a no-op when the current grant is sufficient. When a
+replacement grant is needed, it requests the least-privilege union of the
+already granted operations and the missing requirements. An
+`insufficient_access` error carries the same `grantedOperations`,
+`missingOperations`, and `requiredOperations` metadata with a `reauthorize`
+recovery action.
+
+Applications that declare an `mdbase.runtime.timer.fired` notification criterion can keep
+one-shot reminders at the collection authority:
+
+```ts
+await connection.reconcileTimers({
+  namespace: "workout-reminders",
+  criterion_id: "workout.reminder",
+  timers: [{
+    id: "workout-42",
+    fire_at: new Date("2026-07-25T10:00:00Z").toISOString()
+  }]
+});
+```
+
+The SDK also exposes `listTimers()`, `putTimer()`, and `cancelTimer()`.
+Reconciliation is atomic and is normally the safest way to project a complete
+desired timer set. IDs and optional timer data stay at the local connector or
+hosted provider and are not included in notification signals.
+
+When the local connector definitively rejects an encrypted grant, the SDK does
+not bypass that decision through the relay. It classifies the error as requiring
+authorization, removes only the matching stale credential, and emits a `null`
+connection through `onConnectionChange()`. A subsequent
+`requestOperations()` call therefore starts authorization instead of trusting
+the stale cached capability list.
+
+Applications with full collection access can also register and maintain type
+definitions. Type source is returned with a revision token so updates cannot
+silently overwrite a definition changed by another application:
+
+```ts
+const created = await connection.createType({
+  document: `---
+kind: mdbase.type
+name: workout
+version: 1
+schema:
+  dialect: json-schema-2020-12
+  value:
+    type: object
+---
+`
+});
+
+const current = await connection.readType({ name: "workout" });
+await connection.updateType({
+  path: current.result.path,
+  document: current.result.document.replace("version: 1", "version: 2"),
+  if_revision: current.result.revision
+});
+```
+
+Request `read_type`, `create_type`, and `update_type` during authorization.
+Contract-scoped applications cannot manage collection-wide type definitions.
+
+To install a complete catalog pack without exposing its individual collection
+paths, request `install_type_pack`, fetch and verify the published provision,
+then pass it to the atomic collection operation:
+
+```ts
+const response = await fetch(pack.provisionUrl);
+const provision = await response.json();
+await connection.installTypePack(provision);
+```
+
+The caller remains responsible for verifying the catalog digest before sending
+the provision. Existing targets with different content are rejected.
+
+For a local collection, ask for same-computer access from a user gesture:
+
+```ts
+const status = await connection.checkDirectAccess();
+if (status === "permission_required") {
+  directButton.onclick = () => connection.requestDirectAccess();
+}
+
+connection.onConnectionChange((info) => {
+  console.log(info?.route); // "direct", "relay", or "remote"
+});
+```
+
+After permission is granted, all grantable operations prefer the fixed
+loopback connector automatically. If it is absent or unavailable, the SDK
+retries the exact encrypted envelope through the relay. Durable connector
+receipts prevent an ambiguous direct write from running twice. The SDK retains
+one unresolved encrypted mutation locally and requires that exact write to be
+retried before a later mutation can overtake it. Set
+`directAccess: "disabled"` only when an embedding environment cannot use
+loopback requests.
+
+The SDK loads the v1 manifest from the application's own bundle and
+posts it inline to Connect. Connect identifies the exact canonical declaration
+by its digest. The declared reverse-domain ID and name are presentation
+metadata, not proof of a publisher; grants remain bound to the authorization
+completed by that installation. No developer account, public manifest host, or
+manually issued client secret is required.
+
+Applications declare exact data-contract versions in their bundled manifest.
+Connect offers collections that already provide those contracts or can install
+the declared type pack safely. The developer helper computes every resource
+digest:
+
+```ts
+import { defineTypePack } from "@mdbase-dev/connect-dev";
+
+const contract = `---
+kind: mdbase.contract
+contract_type: record
+id: example.work-item
+version: 1.0.0
+record_schema:
+  dialect: json-schema-2020-12
+  value:
+    type: object
+    required: [title]
+    properties:
+      title: { type: string }
+---
+`;
+const type = `---
+kind: mdbase.type
+name: work-item
+version: 1
+schema:
+  dialect: json-schema-2020-12
+  value:
+    type: object
+implements:
+  - contract: example.work-item
+    version: 1.0.0
+    fields: { title: title }
+---
+`;
+
+export const manifest = {
+  manifest_version: 1,
+  id: "dev.mdbase.worklog",
+  name: "Worklog",
+  homepage: "https://worklog.example",
+  redirect_uris: ["https://worklog.example/auth/mdbase/callback"],
+  requirements: {
+    contracts: [{ id: "example.work-item", version: "1.0.0" }]
+  },
+  provisions: {
+    type_packs: [defineTypePack({
+      id: "example.work-items",
+      version: "1.0.0",
+      provides: [{ id: "example.work-item", version: "1.0.0" }],
+      resources: [
+        { kind: "contract", source: "_contracts/example.work-item.md", document: contract },
+        { kind: "type", source: "_types/work-item.md", document: type }
+      ]
+    })]
+  }
+};
+```
+
+Set `collection_kind` to `hosted` when the application needs a durable
+provider-backed collection and the offline sync transport returned by
+`sync()`. Connect then offers and accepts collections with replication capability.
+
+Access defaults to the record types supplied by `requirements.contracts`.
+Set `access` to `full_collection` when the application needs collection-level
+features such as saved views. Required contracts still determine compatibility
+and are provisioned during approval.
+
+`listViews()` returns each named view's selected result properties in display
+order. Property descriptors retain source labels for projected and computed
+values. `executeView()` returns their values on each result row.
+
+Provisioning is part of the approval flow. The connector validates and
+installs each missing type pack transactionally, verifies its exact contracts
+and implementations, and creates the scoped grant afterward. The application
+is not granted collection-wide type-management access.
+
+The SDK returns the mdbase operation envelope, carries revision tokens in typed
+record results, and accepts `if_revision` on mutations. `describe()` exposes
+JSON Schemas, portable type definitions, canonical collection settings, and
+first-class data contracts. `watch()` resumes from a local collection cursor;
+the Connect server does not store the change feed.
+`preflightRename()` and `preflightDelete()` run the canonical collection
+operation without changing records or advancing the change cursor, so an app
+can show authoritative reference impact before asking for confirmation.
+`renameWithProgress()` and `deleteWithProgress()` expose preflight, ready,
+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.
+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.
+
+Native shells can pass `navigate` to open the authorization URL in the system
+browser and list a reverse-domain callback such as
+`dev.mdbase.worklog://auth/mdbase/callback` in the bundled declaration. Its
+scheme must match the declaration ID. PKCE remains mandatory. Call
+`completeAuthorization(callbackUrl)` when the application receives the deep
+link.
+
+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.
+
+For a hosted collection, the same authorization exchange returns a short-lived,
+grant-bound provider capability. The SDK routes operations directly to the
+hosted Rust data plane, binds browser requests to the approved callback origin, and does
+not send record payloads through the Connect control plane. Refresh rotation,
+permission narrowing, and revocation keep the same public SDK behavior across
+local and hosted authorities.
+
+`sync()` exposes a provider-neutral sync transport without exposing the
+provider credential. It refreshes the grant-bound capability as needed and can
+be passed directly to `@mdbase-dev/connect-sync` for an offline application cache.
+
+Record-facing code can depend on `MdbaseCollectionClient` instead of the OAuth
+client. It accepts a small `MdbaseCollectionTransport`, which is the stable seam
+used by Connect, the developer sandbox, and future hosted providers. This keeps
+application logic independent of authorization and deployment topology.

package/dist/async.d.ts

@@ -0,0 +1 @@
+export declare function abortableDelay(milliseconds: number, signal?: AbortSignal): Promise<void>;

package/dist/async.js

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

package/dist/authorization-types.d.ts

@@ -0,0 +1,7 @@
+export interface MdbaseDeviceAuthorization {
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresAt: number;
+    intervalSeconds: number;
+}

package/dist/authorization-types.js

@@ -0,0 +1 @@
+export {};

package/dist/authorization-url.d.ts

@@ -0,0 +1,3 @@
+export declare function cleanAuthorizationParameters(url: URL): URL;
+export declare function isAuthorizationCallbackUrl(value: string): boolean;
+export declare function authorizationReturnToFromError(error: unknown): string | undefined;

package/dist/authorization-url.js

@@ -0,0 +1,27 @@
+import { MdbaseConnectError } from "./errors.js";
+export function cleanAuthorizationParameters(url) {
+    for (const parameter of ["code", "state", "error", "error_description"]) {
+        url.searchParams.delete(parameter);
+    }
+    return url;
+}
+export function isAuthorizationCallbackUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return url.searchParams.has("state")
+        && (url.searchParams.has("code") || url.searchParams.has("error"));
+}
+export function authorizationReturnToFromError(error) {
+    if (!(error instanceof MdbaseConnectError)
+        || !error.details
+        || typeof error.details !== "object"
+        || Array.isArray(error.details))
+        return undefined;
+    const returnTo = error.details.returnTo;
+    return typeof returnTo === "string" ? returnTo : undefined;
+}

package/dist/base64.d.ts

@@ -0,0 +1,3 @@
+export declare function randomBase64Url(size: number): string;
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+export declare function base64UrlBytes(value: string): Uint8Array<ArrayBuffer>;

package/dist/base64.js

@@ -0,0 +1,21 @@
+export function randomBase64Url(size) {
+    const bytes = new Uint8Array(size);
+    crypto.getRandomValues(bytes);
+    return bytesToBase64Url(bytes);
+}
+export function bytesToBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+export function base64UrlBytes(value) {
+    const padded = value.replaceAll("-", "+").replaceAll("_", "/")
+        .padEnd(Math.ceil(value.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}

package/dist/browser/integrity.json

@@ -0,0 +1,4 @@
+{
+  "file": "mdbase-connect.min.js",
+  "integrity": "sha384-u+z1WOpeMWPwuYV9kDMHHAqQEZKGn+NwX9tjAYtNztyMD7WJbsdj+Be++i43R9nY"
+}