Authority routes

Automatic route selection

A collection has one write authority: either a local connector for a filesystem folder or a hosted provider. For a local authority, the SDK prefers the fixed same-computer endpoint and falls back to the encrypted relay. The user chooses the collection authority. The SDK selects the network route for each request.

Routing state belongs to a collection-bound MdbaseConnection. Different saved collections can be remote, direct, or relayed at the same time.

const mdbase = new MdbaseConnect({
  serverUrl: "https://connect.mdbase.dev",
  manifest,
  redirectUri,
  directAccess: "auto",
  relayEncryption: "required"
});

Request same-computer browser access from a user gesture

const status = await connection.checkDirectAccess();

if (status === "permission_required") {
  directAccessButton.onclick = async () => {
    await connection.requestDirectAccess();
  };
}

connection.onConnectionChange((info) => {
  // "direct", "relay", or "remote"
  renderRoute(info?.route);
});

Browser local-network permission must be requested from a user action. Once available, grantable operations prefer http://127.0.0.1:28485/v1/operations. The connector checks the exact approved web origin, or the exact opaque null origin for a portable grant. It also checks the Host header, protocol version, grant, and application-key proof.

Set directAccess: "disabled" for embedding environments that cannot make loopback requests.

Encrypted relay fallback

Protocol 1 uses a non-extractable P-256 key and atomic message counter in IndexedDB for a web application. An opaque portable file keeps both in process memory. The SDK encrypts operation inputs for the local connector and decrypts results in the application. The control plane receives opaque bodies plus operation and delivery metadata.

New authorizations require encrypted relay by default. Encrypted grants use encrypted relay exclusively. The relayEncryption: "disabled" option supports development stacks that intentionally lack end-to-end relay encryption.

Remote-authority route

Authorization may return a short-lived, grant-bound remote-authority capability. The SDK sends operations directly to that authority, binds browser requests to the approved callback origin, and refreshes the capability as needed.

An mdbase hosted provider is one remote-authority deployment. Its operations go directly from the application to the provider. The provider decrypts records to execute canonical mdbase operations and acts as a trusted data processor.

Portable files use the same route-neutral connection

A downloaded file can use direct, encrypted-relay, or remote-authority access after its short-code approval. For remote access, its short-lived capability is bound to the exact grant, collection, scope, operations, expiry, and opaque Origin: null, and remains in process memory. The consuming operation API is identical across all three routes.

Native shells

Supply navigate to open authorization in the system browser, list a private-use callback scheme in the bundled manifest, and provide the received deep link to completeAuthorization(callbackUrl). Native shells may also supply custom authorization storage and grant key stores.