@mdbase-dev/connect 0.1.0-beta.26 → 0.1.0-beta.28

package/README.md

@@ -22,8 +22,7 @@ const mdbase = new MdbaseConnect({
   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"],
+const session = mdbase.createApplicationSession({
   selection: new MdbaseBrowserSelection()
 });
 
@@ -33,14 +32,7 @@ if (!started.ok) {
   return;
 }
 if (session.getSnapshot().status === "unselected") {
-  const authorized = await session.authorize("choose", {
-    onFirstContact: ({ authenticationString }) => {
-      showPersistentSecurityPrompt({
-        title: "Compare with mdbase connect",
-        code: authenticationString
-      });
-    }
-  });
+  const authorized = await session.authorize("choose");
   if (!authorized.ok) {
     renderProblem(authorized.problem);
     return;
@@ -49,7 +41,8 @@ if (session.getSnapshot().status === "unselected") {
 
 const snapshot = session.getSnapshot();
 if (snapshot.status !== "ready") throw new Error("Choose an authorized collection.");
-const connection = snapshot.connection;
+const connection = session.connection();
+if (!connection) throw new Error("The ready session has no active connection.");
 const queried = await connection.query({ types: ["workout"] });
 if (!queried.ok) {
   renderProblem(queried.problem);
@@ -78,12 +71,32 @@ reserved for programming errors and broken SDK invariants. See
 problem model, setup failures, mutation uncertainty, and UI guidance.
 
 `MdbaseConnect` is the application-level authorization registry.
-`MdbaseSession` is the normal application boundary: it owns active collection
-selection, authorization 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`.
+`MdbaseApplicationSession` is the normal application boundary: it owns active
+collection selection, authorization completion, semantic capabilities,
+definition compatibility, and one reactive snapshot. Applications declare
+versioned capabilities in their manifest; they never maintain a parallel array
+of protocol operations. Use `getSnapshot()` and `subscribe()` directly or
+through your framework's external-store integration.
+
+The session distinguishes `authorization_required`, `checking_definitions`,
+`definition_review_required`, `ready`, `unavailable`, and `blocked`. Definition
+inspection is read-only. If an update is needed, render the supplied plan and
+apply the exact assessment the user reviewed:
+
+```ts
+const snapshot = session.getSnapshot();
+if (snapshot.status === "definition_review_required") {
+  renderDefinitionChanges(snapshot.updates);
+  const applied = await session.applyDefinitionUpdates();
+  if (!applied.ok) renderProblem(applied.problem);
+}
+```
+
+A `ready` snapshot may be `cached` for immediate startup and is then reverified
+in the background. Route details remain diagnostics; feature UI should read
+`snapshot.capabilities`, whose values explain whether a capability is available,
+needs authorization/setup, is temporarily unavailable, or is unsupported by the
+selected authority.
 
 `MdbaseBrowserSelection` keeps the stable collection ID in
 `?collection=<id>`, preserves unrelated path/query/hash and router state, and
@@ -111,15 +124,14 @@ 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.
 
-When the chosen collection is owned by a computer that has not seen this
-application installation before, `onFirstContact` is required. The SDK derives
-the eight-character value locally from the application's non-extractable
-installation key and the connector key; it never accepts a value supplied by
-the control plane. Keep the value visible while the user compares and accepts
-the exact same value in mdbase connect. Headless operators use
-`mdbase connect trust list`, `trust show <id>`, and
-`trust accept <id> --code XXXX-XXXX`. Hosted-only authorization does not invoke
-this callback.
+The SDK keeps one non-extractable P-256 installation signing identity per
+server/application and signs every authorization ceiling with it. Grant
+agreement and signing keys remain disposable and are replaced on
+reauthorization. For local collections, the SDK also pins the connector public
+key after the first successful authorization and rejects silent replacement as
+`connector_identity_changed`, even after the grant is forgotten. Only call
+`forgetConnectorIdentity(connectorId)` after independently verifying an
+intentional connector replacement.
 
 Bundled v1 application manifests can declare runtime notification criteria.
 Register a service worker from a user gesture to receive standards-based Web
@@ -254,17 +266,31 @@ 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:
+paths, request `assess_type_pack` and `apply_type_pack`, fetch and verify the
+published provision, then review and apply the authority's exact plan:
 
 ```ts
 const response = await fetch(pack.provisionUrl);
 const provision = await response.json();
-await connection.installTypePack(provision);
+const installedBy = "dev.example.catalog";
+const assessment = await connection.assessTypePack({
+  provision,
+  installed_by: installedBy
+});
+if (!assessment.ok) return renderProblem(assessment.problem);
+
+renderDefinitionChanges(assessment.value);
+const applied = await connection.applyTypePack({
+  provision,
+  installed_by: installedBy,
+  expected_assessment_digest: assessment.value.assessment_digest
+});
+if (!applied.ok) return renderProblem(applied.problem);
 ```
 
 The caller remains responsible for verifying the catalog digest before sending
-the provision. Existing targets with different content are rejected.
+the provision. Apply rechecks the reviewed assessment inside the transaction;
+stale plans and locally modified targets fail without partial writes.
 
 For a local collection, ask for same-computer access from a user gesture:
 
@@ -333,6 +359,25 @@ implements:
 ---
 `;
 
+const workItemPack = defineTypePack({
+  id: "example.work-items",
+  version: "1.0.0",
+  resources: [
+    {
+      kind: "contract",
+      mode: "managed",
+      source: "_contracts/example.work-item.md",
+      document: contract
+    },
+    {
+      kind: "type",
+      mode: "seed",
+      source: "_types/work-item.md",
+      document: type
+    }
+  ]
+});
+
 export const manifest = {
   manifest_version: 1,
   id: "dev.mdbase.worklog",
@@ -340,18 +385,10 @@ export const manifest = {
   homepage: "https://worklog.example",
   redirect_uris: ["https://worklog.example/auth/mdbase/callback"],
   requirements: {
-    contracts: [{ id: "example.work-item", version: "1.0.0" }]
+    contracts: workItemPack.provides
   },
   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 }
-      ]
-    })]
+    type_packs: [workItemPack]
   }
 };
 ```
@@ -398,10 +435,11 @@ allows a host to choose another persistence boundary.
 Native shells can pass `navigate` to open the approval 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. The application remains alive, polls the
-PKCE-bound status endpoint, displays first contact when required, and receives
-the completed connection directly from `authorize()`; the browser does not
-carry credentials back through a deep link.
+scheme must match the declaration ID. `authorize()` returns `redirecting`; the
+browser redirects to the declared callback with a short-lived code and state,
+and the shell passes that URL to `completeAuthorization()`. PKCE prevents the
+callback code from being exchanged without the pending application state and
+verifier.
 
 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

package/dist/application-identity.d.ts

@@ -1,5 +1,34 @@
 import { authorizationSigningMessage, type ApplicationAuthorizationBinding, type ApplicationAuthorizationProof } from "@mdbase-dev/connect-protocol";
-import type { GrantKeyRecord } from "./crypto.js";
+import type { Application } from "./internal-types.js";
+export interface ApplicationIdentity {
+    handle: string;
+    signingPrivateKey: CryptoKey;
+    signingPublicKey: string;
+}
+export interface ApplicationIdentityStore {
+    create(handle: string): Promise<ApplicationIdentity>;
+    get(handle: string): Promise<ApplicationIdentity | null>;
+    delete(handle: string): Promise<void>;
+}
+/** Origin-scoped persistence for one non-extractable signing key per app/server installation. */
+export declare class IndexedDbApplicationIdentityStore implements ApplicationIdentityStore {
+    private database;
+    create(handle: string): Promise<ApplicationIdentity>;
+    get(handle: string): Promise<ApplicationIdentity | null>;
+    delete(handle: string): Promise<void>;
+    private open;
+}
+/** Process-local identity storage for portable applications, tests, and custom hosts. */
+export declare class MemoryApplicationIdentityStore implements ApplicationIdentityStore {
+    private readonly records;
+    create(handle: string): Promise<ApplicationIdentity>;
+    get(handle: string): Promise<ApplicationIdentity | null>;
+    delete(handle: string): Promise<void>;
+}
+export declare class ApplicationIdentityStoreError extends Error {
+    constructor(message: string);
+}
 export { authorizationSigningMessage };
-export declare function applicationInstallationId(identity: Pick<GrantKeyRecord, "agreementPublicKey" | "signingPublicKey">): Promise<string>;
-export declare function signApplicationAuthorization(binding: ApplicationAuthorizationBinding, identity: Pick<GrantKeyRecord, "signingPrivateKey" | "agreementPublicKey" | "signingPublicKey">): Promise<ApplicationAuthorizationProof>;
+export declare function applicationInstallationId(identity: Pick<ApplicationIdentity, "signingPublicKey">): Promise<string>;
+export declare function signApplicationAuthorization(binding: ApplicationAuthorizationBinding, identity: Pick<ApplicationIdentity, "signingPrivateKey" | "signingPublicKey">): Promise<ApplicationAuthorizationProof>;
+export declare function applicationIdentity(store: ApplicationIdentityStore, serverUrl: string, application: Application): Promise<ApplicationIdentity>;

package/dist/application-identity.js

@@ -1,21 +1,115 @@
-import { applicationInstallationIdFromPublicKeys, authorizationSigningMessage } from "@mdbase-dev/connect-protocol";
+import { applicationInstallationIdFromPublicKey, authorizationSigningMessage } from "@mdbase-dev/connect-protocol";
+const DATABASE_NAME = "mdbase-connect-identities";
+const STORE_NAME = "application-identities";
 const P256_ORDER = BigInt("0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
 const P256_HALF_ORDER = P256_ORDER / 2n;
+/** Origin-scoped persistence for one non-extractable signing key per app/server installation. */
+export class IndexedDbApplicationIdentityStore {
+    database = null;
+    async create(handle) {
+        const record = await generateApplicationIdentity(handle);
+        const database = await this.open();
+        await idbWrite(database, (store) => store.add(record));
+        return record;
+    }
+    async get(handle) {
+        const database = await this.open();
+        return await idbRequest(database.transaction(STORE_NAME).objectStore(STORE_NAME).get(handle)) ?? null;
+    }
+    async delete(handle) {
+        const database = await this.open();
+        await idbWrite(database, (store) => store.delete(handle));
+    }
+    open() {
+        if (typeof indexedDB === "undefined") {
+            throw new ApplicationIdentityStoreError("Persistent application identity requires browser IndexedDB or an injected identity store.");
+        }
+        if (!this.database) {
+            this.database = new Promise((resolve, reject) => {
+                const request = indexedDB.open(DATABASE_NAME, 1);
+                request.onupgradeneeded = () => {
+                    if (!request.result.objectStoreNames.contains(STORE_NAME)) {
+                        request.result.createObjectStore(STORE_NAME, { keyPath: "handle" });
+                    }
+                };
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => resolve(request.result);
+            });
+        }
+        return this.database;
+    }
+}
+/** Process-local identity storage for portable applications, tests, and custom hosts. */
+export class MemoryApplicationIdentityStore {
+    records = new Map();
+    async create(handle) {
+        if (this.records.has(handle))
+            throw new Error(`Application identity already exists: ${handle}`);
+        const record = await generateApplicationIdentity(handle);
+        this.records.set(handle, record);
+        return record;
+    }
+    async get(handle) {
+        return this.records.get(handle) ?? null;
+    }
+    async delete(handle) {
+        this.records.delete(handle);
+    }
+}
+export class ApplicationIdentityStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApplicationIdentityStoreError";
+    }
+}
 export { authorizationSigningMessage };
 export async function applicationInstallationId(identity) {
-    return applicationInstallationIdFromPublicKeys(identity.agreementPublicKey, identity.signingPublicKey);
+    return applicationInstallationIdFromPublicKey(identity.signingPublicKey);
 }
 export async function signApplicationAuthorization(binding, identity) {
-    if (binding.installation_agreement_public_key !== identity.agreementPublicKey
-        || binding.installation_signing_public_key !== identity.signingPublicKey
+    if (binding.installation_signing_public_key !== identity.signingPublicKey
         || binding.application_installation_id !== await applicationInstallationId(identity)) {
         throw new Error("Application authorization identity does not match its binding.");
     }
     const signature = canonicalSignature(new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, identity.signingPrivateKey, authorizationSigningMessage(binding))));
-    return {
-        binding,
-        signature: base64Url(signature)
-    };
+    return { binding, signature: base64Url(signature) };
+}
+export async function applicationIdentity(store, serverUrl, application) {
+    const handle = `application-installation:v2:${serverUrl}:${application.id}`;
+    const existing = await store.get(handle);
+    if (existing)
+        return existing;
+    try {
+        return await store.create(handle);
+    }
+    catch (error) {
+        const raced = await store.get(handle);
+        if (raced)
+            return raced;
+        throw error;
+    }
+}
+async function generateApplicationIdentity(handle) {
+    const signing = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+    const signingPublicKey = base64Url(new Uint8Array(await crypto.subtle.exportKey("raw", signing.publicKey)));
+    const signingPkcs8 = await crypto.subtle.exportKey("pkcs8", signing.privateKey);
+    const signingPrivateKey = await crypto.subtle.importKey("pkcs8", signingPkcs8, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+    return { handle, signingPrivateKey, signingPublicKey };
+}
+function idbRequest(request) {
+    return new Promise((resolve, reject) => {
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+    });
+}
+function idbWrite(database, write) {
+    return new Promise((resolve, reject) => {
+        const transaction = database.transaction(STORE_NAME, "readwrite");
+        write(transaction.objectStore(STORE_NAME)).onerror = () => reject(transaction.error);
+        transaction.onerror = () => reject(transaction.error);
+        transaction.onabort = () => reject(transaction.error ?? new Error("Identity transaction aborted."));
+        transaction.oncomplete = () => resolve();
+    });
 }
 function concat(values) {
     const output = new Uint8Array(values.reduce((length, value) => length + value.byteLength, 0));
@@ -33,13 +127,11 @@ function base64Url(value) {
         .replace(/=+$/u, "");
 }
 function canonicalSignature(signature) {
-    if (signature.byteLength !== 64) {
+    if (signature.byteLength !== 64)
         throw new Error("Application authorization signature is invalid.");
-    }
     const s = bytesBigInt(signature.slice(32));
-    if (s === 0n || s >= P256_ORDER) {
+    if (s === 0n || s >= P256_ORDER)
         throw new Error("Application authorization signature is invalid.");
-    }
     if (s <= P256_HALF_ORDER)
         return signature;
     return concat([signature.slice(0, 32), bigIntBytes(P256_ORDER - s, 32)]);

package/dist/application-session.d.ts

@@ -0,0 +1,120 @@
+import { type ApplicationCapabilityId, type JsonObject, type MdbaseAppManifest, type TypePackAssessment } from "@mdbase-dev/connect-protocol";
+import { type MdbaseEffectiveCapabilities } from "./capabilities.js";
+import type { MdbaseAuthorizationOutcome, MdbaseAuthorizeOptions, MdbaseConnection } from "./connection.js";
+import type { MdbaseConnectionInfo } from "./connection-types.js";
+import { type ConnectOutcome, type CollectionTypeProblemCode, type AuthorizationProblemCode, type RegistrationProblemCode, type SessionProblemCode } from "./outcomes.js";
+import type { MdbaseApplicationSelection, MdbaseSelectionHistory } from "./selection.js";
+import { type MdbaseSessionConnect, type MdbaseUnavailableReason } from "./session.js";
+export interface MdbaseApplicationSessionConnect<Frontmatter extends JsonObject = JsonObject> extends MdbaseSessionConnect<Frontmatter> {
+    manifest(): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
+}
+export interface MdbaseApplicationSessionOptions {
+    selection: MdbaseApplicationSelection;
+    autoSelect?: "only" | "never";
+    verificationStore?: MdbaseApplicationVerificationStore;
+}
+export interface MdbaseApplicationVerificationStore {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}
+export declare class MdbaseMemoryVerificationStore implements MdbaseApplicationVerificationStore {
+    private readonly values;
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}
+export interface MdbaseDefinitionUpdate {
+    id: string;
+    name: string;
+    status: TypePackAssessment["status"];
+    applicable: boolean;
+    assessmentDigest: string;
+    currentVersion?: string;
+    desiredVersion: string;
+    resources: TypePackAssessment["resources"];
+    contractSetups: TypePackAssessment["contract_setups"];
+    canApply: boolean;
+    reason: string;
+}
+interface ApplicationSessionContext {
+    collectionId: string;
+    info: MdbaseConnectionInfo;
+    capabilities: MdbaseEffectiveCapabilities;
+    connections: MdbaseConnectionInfo[];
+}
+export type MdbaseApplicationSessionSnapshot = {
+    status: "opening";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "unselected";
+    connections: MdbaseConnectionInfo[];
+} | ({
+    status: "authorization_required";
+} & ApplicationSessionContext) | ({
+    status: "checking_definitions";
+} & ApplicationSessionContext) | ({
+    status: "definition_review_required";
+    updates: MdbaseDefinitionUpdate[];
+} & ApplicationSessionContext) | ({
+    status: "ready";
+    verification: "cached" | "verified";
+} & ApplicationSessionContext) | {
+    status: "unavailable";
+    collectionId: string;
+    reason: MdbaseUnavailableReason;
+    connections: MdbaseConnectionInfo[];
+} | ({
+    status: "blocked";
+    problem: {
+        code: string;
+        message: string;
+        recovery?: string;
+    };
+} & ApplicationSessionContext);
+/**
+ * The application-level lifecycle boundary. It derives authorization from the
+ * bundled manifest, exposes semantic capabilities, and never mutates collection
+ * definitions without an explicit `applyDefinitionUpdates` call.
+ */
+export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = JsonObject> {
+    private readonly connect;
+    private readonly options;
+    private readonly listeners;
+    private readonly verificationStore;
+    private snapshot;
+    private manifest;
+    private base;
+    private stopBase?;
+    private reviewEntries;
+    private verificationGeneration;
+    constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions);
+    start(): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    destroy(): void;
+    getSnapshot(): MdbaseApplicationSessionSnapshot;
+    subscribe(listener: () => void): () => void;
+    connection(): MdbaseConnection<Frontmatter> | null;
+    select(collectionId: string, options?: {
+        history?: MdbaseSelectionHistory;
+    }): 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<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
+    handleAuthorizationCallback(callbackUrl: string): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
+    ensureCapabilities(capabilities: ApplicationCapabilityId[]): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
+        kind: "unchanged";
+        connection: MdbaseConnection<Frontmatter>;
+    }, SessionProblemCode>>;
+    applyDefinitionUpdates(): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | "collection_not_ready">>;
+    private refresh;
+    private verifyDefinitions;
+    private context;
+    private publish;
+    private requireBase;
+    private requireManifest;
+}
+export {};