@lapis-notes/api 0.1.3 → 0.2.0

package/dist/sync-host-local.js

@@ -0,0 +1,228 @@
+import { snapshotSyncFileMutation } from "./sync-repository";
+const FILE_GRANTS = [
+    "crypto:nostr-sync",
+    "vault:stream",
+    "metadata:identity",
+];
+const STORE_GRANTS = ["crypto:nostr-sync", "plugin:generated-state"];
+/** Grant-checked lifetime boundary; providers retain all platform-specific authority. */
+export class ScopedSyncLocalRuntime {
+    options;
+    #active = true;
+    #provider;
+    #capabilities;
+    #selectionError;
+    #selected = false;
+    #closing;
+    #flights = new Set();
+    #streams = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    capabilities = {
+        list: () => this.#invoke(FILE_GRANTS, async (local) => {
+            const files = await local.list();
+            return files.map((file) => ({
+                path: file.path,
+                fileId: file.fileId,
+                hostFileId: file.hostFileId,
+                contentGeneration: file.contentGeneration,
+                openRead: () => this.#invoke(FILE_GRANTS, async () => (await this.#stream(await file.openRead(), FILE_GRANTS)).stream),
+            }));
+        }),
+        repository: {
+            readState: () => this.#invoke(STORE_GRANTS, (local) => local.repository.readState()),
+            compareAndSwap: (expectedVersion, next, authority) => {
+                const captured = structuredClone(next);
+                const fence = authority ? structuredClone(authority) : undefined;
+                return this.#invoke(STORE_GRANTS, (local) => fence
+                    ? local.repository.compareAndSwap(expectedVersion, captured, fence)
+                    : local.repository.compareAndSwap(expectedVersion, captured));
+            },
+            blobs: {
+                has: (hash) => this.#invoke(STORE_GRANTS, (local) => local.repository.blobs.has(hash)),
+                get: (hash) => this.#invoke(STORE_GRANTS, (local) => local.repository.blobs.get(hash)),
+                put: (bytes) => {
+                    const captured = Uint8Array.from(bytes);
+                    return this.#invoke(STORE_GRANTS, (local) => local.repository.blobs.put(captured));
+                },
+            },
+        },
+        apply: {
+            receipt: (id, authority) => {
+                const fence = authority ? structuredClone(authority) : undefined;
+                return this.#apply(undefined, (local) => fence ? local.apply.receipt(id, fence) : local.apply.receipt(id));
+            },
+            mutate: (operation, source, authority) => {
+                return this.#track((async () => {
+                    let guarded;
+                    try {
+                        const captured = snapshotSyncFileMutation(operation);
+                        const fence = authority ? structuredClone(authority) : undefined;
+                        guarded = source
+                            ? await this.#stream(source, FILE_GRANTS)
+                            : undefined;
+                        return await this.#apply(captured.path, async (local) => {
+                            try {
+                                this.#assert([...FILE_GRANTS, "plugin:generated-state"]);
+                                return await (fence
+                                    ? local.apply.mutate(captured, guarded?.stream, fence)
+                                    : local.apply.mutate(captured, guarded?.stream));
+                            }
+                            finally {
+                                await guarded?.close();
+                            }
+                        });
+                    }
+                    finally {
+                        if (guarded)
+                            await guarded.close();
+                        else if (source && !source.locked)
+                            await source.cancel();
+                    }
+                })());
+            },
+        },
+    };
+    #assert(grants) {
+        if (!this.#active)
+            throw new Error("Local Sync runtime is revoked");
+        for (const grant of grants)
+            this.options.assertGranted(grant);
+    }
+    #local() {
+        if (!this.#selected) {
+            this.#selected = true;
+            try {
+                const provider = this.options.selectProvider();
+                if (!provider)
+                    throw new Error("Local Sync host capability is unavailable");
+                if (typeof provider.forRuntime !== "function" ||
+                    typeof provider.revokeRuntime !== "function")
+                    throw new Error("Invalid local Sync provider");
+                this.#provider = provider;
+                this.#capabilities = provider.forRuntime(this.options.runtimeId);
+                if (!this.#capabilities || typeof this.#capabilities !== "object")
+                    throw new Error("Invalid local Sync provider capabilities");
+            }
+            catch (error) {
+                this.#selectionError =
+                    error instanceof Error
+                        ? error
+                        : new Error("Local Sync provider selection failed");
+            }
+        }
+        if (this.#selectionError)
+            throw this.#selectionError;
+        return this.#capabilities;
+    }
+    #invoke(grants, operation) {
+        const flight = (async () => {
+            this.#assert(grants);
+            const result = await operation(this.#local());
+            this.#assert(grants);
+            return result;
+        })();
+        return this.#track(flight);
+    }
+    #track(flight) {
+        this.#flights.add(flight);
+        void flight.then(() => this.#flights.delete(flight), () => this.#flights.delete(flight));
+        return flight;
+    }
+    async #apply(path, operation) {
+        this.#assert([...FILE_GRANTS, "plugin:generated-state"]);
+        const guard = this.options.guardApply;
+        if (!guard)
+            throw new Error("Local Sync host apply guard is unavailable");
+        return this.#invoke([...FILE_GRANTS, "plugin:generated-state"], async (local) => {
+            return guard(path, async () => {
+                this.#assert([...FILE_GRANTS, "plugin:generated-state"]);
+                return operation(local);
+            });
+        });
+    }
+    async #stream(source, grants) {
+        try {
+            this.#assert(grants);
+        }
+        catch (error) {
+            await source.cancel(error);
+            throw error;
+        }
+        const reader = source.getReader();
+        let terminal = false;
+        let stopping;
+        let controller;
+        const release = () => {
+            this.#streams.delete(stop);
+            reader.releaseLock();
+        };
+        const cancel = (reason) => {
+            if (stopping)
+                return stopping;
+            if (terminal)
+                return Promise.resolve();
+            terminal = true;
+            stopping = reader.cancel(reason).finally(release);
+            return stopping;
+        };
+        const stop = (reason = new Error("Local Sync runtime is revoked")) => {
+            if (!terminal)
+                controller.error(reason);
+            return cancel(reason);
+        };
+        this.#streams.add(stop);
+        const stream = new ReadableStream({
+            start(value) {
+                controller = value;
+            },
+            pull: async () => {
+                if (terminal)
+                    return;
+                try {
+                    this.#assert(grants);
+                    const result = await reader.read();
+                    this.#assert(grants);
+                    if (terminal)
+                        return;
+                    if (result.done) {
+                        terminal = true;
+                        release();
+                        controller.close();
+                    }
+                    else {
+                        if (!(result.value instanceof Uint8Array))
+                            throw new Error("Invalid local Sync stream chunk");
+                        controller.enqueue(result.value);
+                    }
+                }
+                catch (error) {
+                    if (!terminal)
+                        controller.error(error);
+                    await cancel(error);
+                }
+            },
+            cancel,
+        }, { highWaterMark: 0 });
+        return {
+            stream,
+            close: () => stop(new Error("Local Sync operation has completed")),
+        };
+    }
+    revoke() {
+        if (this.#closing)
+            return this.#closing;
+        this.#active = false;
+        this.#closing = (async () => {
+            const streams = await Promise.allSettled([...this.#streams].map((stop) => stop()));
+            await Promise.allSettled([...this.#flights]);
+            // Even failed cancellation must release the platform provider.
+            await this.#provider?.revokeRuntime(this.options.runtimeId);
+            const failure = streams.find((result) => result.status === "rejected");
+            if (failure?.status === "rejected")
+                throw failure.reason;
+        })();
+        return this.#closing;
+    }
+}

package/dist/sync-host-security.d.ts

@@ -1,6 +1,8 @@
 import { type Event as NostrEvent } from "nostr-tools/pure";
-import type { AppDatabase } from "./storage/app-database";
-export type SyncCryptoObjectType = "file-content" | "file-manifest" | "tree-manifest" | "revision-payload" | "revision-archive" | "head-payload" | "membership-payload";
+import type { HostMetadataStore } from "./metadata-store";
+/** Host-owned persistence for wrapped keys and network grants, outside disposable indexes. */
+export type SyncSecurityStore = HostMetadataStore;
+export type SyncCryptoObjectType = "file-content" | "file-manifest" | "tree-manifest" | "revision-payload" | "revision-archive" | "head-payload" | "membership-payload" | "local-state";
 export type SyncDeviceRole = "owner" | "member";
 export type SyncIdentityState = "setup-required" | "active" | "rotation-pending";
 export interface SyncIdentityHistoryEntry {
@@ -64,6 +66,8 @@ export interface SyncCryptoStatus {
     role?: SyncDeviceRole;
     deviceState?: "active" | "revoked" | "recovery-pending";
     currentEpoch?: number;
+    /** Installed content-key epoch numbers, sorted and copied; present only while unlocked. */
+    installedEpochs?: number[];
     membershipGeneration?: number;
     canManageDevices?: boolean;
     syncIdentity?: SyncIdentityPublicStatus;
@@ -144,20 +148,31 @@ export interface SyncPairingActionResult {
     outboundEvents: NostrEvent[];
     /** Public transport endpoints for this bounded pairing session. */
     relayUrls: string[];
+    /** Omitted by older hosts, whose invitations use relay delivery. */
+    delivery?: SyncPairingDelivery;
     invitationUri?: string;
     membershipEvent?: NostrEvent;
     /** Bounded plugin data recovered only from the encrypted pairing transfer. */
     metadata?: unknown;
 }
+export type SyncPairingDelivery = "relay" | "host";
+export type SyncPairingOwnerRequest = {
+    cutoffHeads?: Record<string, string>;
+    metadata?: unknown;
+} & ({
+    delivery?: "relay";
+    relayUrls: string[];
+} | {
+    delivery: "host";
+    relayUrls?: never;
+});
 export interface SyncPairingCapability {
-    beginOwner(input: {
-        relayUrls: string[];
-        cutoffHeads?: Record<string, string>;
-        metadata?: unknown;
-    }): Promise<SyncPairingActionResult>;
+    beginOwner(input: SyncPairingOwnerRequest): Promise<SyncPairingActionResult>;
     acceptInvite(input: {
         invitationUri: string;
         deviceAlias: string;
+        /** Host delivery must be selected explicitly for an invitation with no relay addresses. */
+        delivery?: SyncPairingDelivery;
     }): Promise<SyncPairingActionResult>;
     ingest(input: {
         sessionId: string;
@@ -257,9 +272,9 @@ export interface SyncHostSecurityOptions {
 }
 export declare class SyncHostSecurityService {
     #private;
-    readonly database: AppDatabase;
+    readonly database: SyncSecurityStore;
     readonly assertRuntime: (pluginId: string, runtimeId: string) => void;
-    constructor(database: AppDatabase, assertRuntime: (pluginId: string, runtimeId: string) => void, options?: SyncHostSecurityOptions);
+    constructor(database: SyncSecurityStore, assertRuntime: (pluginId: string, runtimeId: string) => void, options?: SyncHostSecurityOptions);
     enroll(pluginId: string, passphrase: string, request?: SyncCryptoEnrollmentRequest): Promise<SyncCryptoStatus>;
     enrollWithWrappingKey(pluginId: string, wrappingKey: Uint8Array, descriptor: Extract<SyncWrappingKeyDescriptor, {
         name: "external";

package/dist/sync-host-security.js

@@ -28,6 +28,7 @@ function typeTag(type) {
         "revision-archive": 5,
         "head-payload": 6,
         "membership-payload": 7,
+        "local-state": 8,
     }[type];
 }
 function requireCryptoSize(bytes) {
@@ -98,12 +99,21 @@ function requirePublicKey(value, label = "Device public key") {
     }
     return value;
 }
+function requirePairingDelivery(value) {
+    if (value === undefined)
+        return "relay";
+    if (value === "relay" || value === "host")
+        return value;
+    throw new Error("Unsupported pairing delivery mode");
+}
 function requireRelayUrls(values) {
-    if (values.length < 1 || values.length > 8) {
+    if (!Array.isArray(values) || values.length < 1 || values.length > 8) {
         throw new Error("Pairing requires between one and eight relay URLs");
     }
     const result = [];
     for (const value of values) {
+        if (typeof value !== "string")
+            throw new Error("Pairing relay URLs must be strings");
         const url = new URL(value);
         if (!["wss:", "ws:"].includes(url.protocol)) {
             throw new Error("Pairing relays must use wss or loopback ws");
@@ -286,6 +296,9 @@ export class SyncHostSecurityService {
     constructor(database, assertRuntime, options = {}) {
         this.database = database;
         this.assertRuntime = assertRuntime;
+        if (!database ||
+            ["getMeta", "setMeta", "transactMeta"].some((name) => typeof database[name] !== "function"))
+            throw new Error("Invalid Sync security store");
         this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.#WebSocket = options.WebSocket ?? globalThis.WebSocket;
         this.#argon2 = {
@@ -387,12 +400,19 @@ export class SyncHostSecurityService {
         const keys = pending?.material
             ? this.#materialToUnlocked(pending.material, wrappingKey, descriptor)
             : this.#createOwnerKeys(requireAlias(request.deviceAlias ?? "This device"), wrappingKey, descriptor);
-        const envelope = this.#sealEnvelope(pluginId, keys);
-        const stored = await this.database.transactMeta({
-            checks: [{ key: envelopeKey(pluginId), exists: false }],
-            mutations: [{ key: envelopeKey(pluginId), value: envelope }],
-        });
-        if (!stored.applied) {
+        let applied;
+        try {
+            const envelope = this.#sealEnvelope(pluginId, keys);
+            applied = (await this.database.transactMeta({
+                checks: [{ key: envelopeKey(pluginId), exists: false }],
+                mutations: [{ key: envelopeKey(pluginId), value: envelope }],
+            })).applied;
+        }
+        catch (error) {
+            this.#destroyKeys(keys);
+            throw error;
+        }
+        if (!applied) {
             this.#destroyKeys(keys);
             throw new Error(`Sync crypto enrollment changed concurrently for ${pluginId}`);
         }
@@ -708,6 +728,7 @@ export class SyncHostSecurityService {
                 role: unlocked.role,
                 deviceState: this.#deviceState(unlocked),
                 currentEpoch: unlocked.currentEpoch,
+                installedEpochs: [...unlocked.vaultKeys.keys()].sort((left, right) => left - right),
                 membershipGeneration: unlocked.membershipGeneration,
                 canManageDevices: unlocked.role === "owner",
                 syncIdentity: this.#syncIdentityStatus(unlocked),
@@ -1059,20 +1080,24 @@ export class SyncHostSecurityService {
             session: this.#pairingSnapshot(session),
             outboundEvents,
             relayUrls: [...session.relays],
+            delivery: session.delivery,
             ...extras,
         });
         return {
-            beginOwner: async ({ relayUrls, cutoffHeads = {}, metadata }) => {
+            beginOwner: async ({ relayUrls, delivery, cutoffHeads = {}, metadata, }) => {
                 assertActive();
                 const keys = this.#requireUnlocked(pluginId);
                 if (keys.role !== "owner" || !keys.ownerSecret) {
                     throw new Error("Only the owner device may begin pairing");
                 }
+                const selectedDelivery = requirePairingDelivery(delivery);
+                if (selectedDelivery === "host" && relayUrls !== undefined)
+                    throw new Error("Host-delivered pairing must not specify relay URLs");
+                const relays = selectedDelivery === "host" ? [] : requireRelayUrls(relayUrls);
                 const ephemeralSecret = randomBytes(KEY_LENGTH);
                 const sessionSecret = toBase64Url(randomBytes(KEY_LENGTH));
                 const sessionId = pairingSessionId(sessionSecret);
                 const expiresAt = Date.now() + PAIRING_TTL_MS;
-                const relays = requireRelayUrls(relayUrls);
                 const session = {
                     pluginId,
                     sessionId,
@@ -1083,6 +1108,7 @@ export class SyncHostSecurityService {
                     ephemeralPublicKey: getPublicKey(ephemeralSecret),
                     sessionSecret,
                     relays,
+                    delivery: selectedDelivery,
                     sequence: 0,
                     lastReceivedSequence: 0,
                     localConfirmed: false,
@@ -1107,12 +1133,13 @@ export class SyncHostSecurityService {
                 }
                 return result(session, [], { invitationUri });
             },
-            acceptInvite: async ({ invitationUri, deviceAlias }) => {
+            acceptInvite: async ({ invitationUri, deviceAlias, delivery }) => {
                 assertActive();
                 if ((await this.status(pluginId)).state !== "unenrolled") {
                     throw new Error("Pairing import requires an unenrolled sync identity");
                 }
-                const invitation = this.#parsePairingInvitation(invitationUri);
+                const selectedDelivery = requirePairingDelivery(delivery);
+                const invitation = this.#parsePairingInvitation(invitationUri, selectedDelivery);
                 if (Date.now() >= invitation.e)
                     throw new Error("Pairing invitation expired");
                 const ephemeralSecret = randomBytes(KEY_LENGTH);
@@ -1127,7 +1154,8 @@ export class SyncHostSecurityService {
                     ephemeralSecret,
                     ephemeralPublicKey: getPublicKey(ephemeralSecret),
                     sessionSecret: invitation.s,
-                    relays: requireRelayUrls(invitation.r),
+                    relays: [...invitation.r],
+                    delivery: selectedDelivery,
                     sequence: 0,
                     lastReceivedSequence: 0,
                     peerEphemeralPublicKey: requirePublicKey(invitation.p, "Pairing public key"),
@@ -1717,7 +1745,7 @@ export class SyncHostSecurityService {
         session.pendingDeviceSecret?.fill(0);
         session.pendingDeviceSecret = undefined;
     }
-    #parsePairingInvitation(invitationUri) {
+    #parsePairingInvitation(invitationUri, delivery) {
         if (invitationUri.length > 2_048) {
             throw new Error("Pairing invitation exceeds the app URL limit");
         }
@@ -1752,7 +1780,12 @@ export class SyncHostSecurityService {
             throw new Error("Pairing invitation data is invalid");
         }
         requirePublicKey(invitation.p, "Pairing public key");
-        requireRelayUrls(invitation.r);
+        if (delivery === "host") {
+            if (invitation.r.length !== 0)
+                throw new Error("Host-delivered pairing invitations must not contain relay URLs");
+        }
+        else
+            invitation.r = requireRelayUrls(invitation.r);
         return invitation;
     }
     #createPairingEvent(session, input) {

package/dist/sync-host.d.ts

@@ -3,7 +3,9 @@ import { TFile } from "./storage/fs";
 import type { VaultReadHandle } from "./storage/fs";
 import type { Vault } from "./storage/vault.svelte";
 import type { HostedPluginCapability } from "./plugin-capability-facade";
-import { type PluginNetworkCapability, type SyncCryptoCapability, type SyncCryptoEnrollmentRequest, type SyncCryptoStatus, type SyncIdentityCapability, type SyncHostSecurityOptions, type SyncMembershipCapability, type SyncPairingCapability, type SyncRecoveryCapability, type SyncWrappingKeyDescriptor } from "./sync-host-security";
+import type { SyncHostLocalProvider, SyncLocalApplyGuard, SyncLocalHostCapabilities } from "./sync-repository";
+export type { SyncHostLocalProvider, SyncLocalApplyGuard, SyncLocalHostCapabilities, } from "./sync-repository";
+import { type PluginNetworkCapability, type SyncCryptoCapability, type SyncCryptoEnrollmentRequest, type SyncCryptoStatus, type SyncIdentityCapability, type SyncHostSecurityOptions, type SyncMembershipCapability, type SyncPairingCapability, type SyncRecoveryCapability, type SyncSecurityStore, type SyncWrappingKeyDescriptor } from "./sync-host-security";
 export type HostFileIdentityState = "present" | "tombstoned";
 export type HostFileChangeKind = "create" | "modify" | "rename" | "delete";
 export interface HostFileIdentity {
@@ -92,6 +94,8 @@ export interface PluginGeneratedState {
     clear(): Promise<void>;
 }
 export interface SyncHostCapabilities {
+    /** Omitted by hosts without durable guarded local Sync support. */
+    readonly local?: SyncLocalHostCapabilities;
     readonly files: {
         getIdentity(path: string): Promise<HostFileIdentity | null>;
         resolveIdentity(fileId: string): Promise<HostFileIdentity | null>;
@@ -133,7 +137,27 @@ export interface SyncHostCapabilities {
     readonly recovery: SyncRecoveryCapability;
     readonly generatedState: PluginGeneratedState;
 }
+export type SyncEndpointSecurityCapabilities = Pick<SyncHostCapabilities, "crypto" | "syncIdentity" | "pairing" | "membership" | "recovery">;
+/** Trusted host custody. This controller is never included in plugin facades. */
+export interface SyncHostSecurityProvider {
+    forRuntime(runtimeId: string): SyncEndpointSecurityCapabilities;
+    /**
+     * Must stop admission synchronously, then drain and destroy this runtime's
+     * keys.
+     */
+    revokeRuntime(runtimeId: string): void | Promise<void>;
+}
 export interface SyncHostServiceOptions {
+    localProvider?: (pluginId: string) => SyncHostLocalProvider | undefined;
+    /** Required before local mutations or receipt recovery can enter a provider. */
+    guardLocalApply?: SyncLocalApplyGuard;
+    /**
+     * Select custody per plugin; returning undefined explicitly retains legacy
+     * custody.
+     */
+    securityProvider?: (pluginId: string) => SyncHostSecurityProvider | undefined;
+    /** Dedicated host custody; omitted only for legacy AppDatabase-backed callers. */
+    securityStore?: SyncSecurityStore;
     flushOpenEditor?: (path?: string) => Promise<{
         flushed: boolean;
         path?: string;
@@ -155,12 +179,17 @@ export declare class SyncHostService {
     readonly database: AppDatabase;
     readonly vault: Vault;
     readonly clock: () => number;
-    readonly options: SyncHostServiceOptions;
+    readonly options: Omit<SyncHostServiceOptions, "securityStore" | "securityProvider" | "localProvider" | "guardLocalApply">;
     constructor(database: AppDatabase, vault: Vault, clock?: () => number, options?: SyncHostServiceOptions);
     ready(): Promise<void>;
     forPlugin(pluginId: string, grantedCapabilities?: readonly HostedPluginCapability[]): SyncHostCapabilities;
-    revokePlugin(pluginId: string): void;
-    /** Host-controlled enrollment; this operation is intentionally absent from plugin facades. */
+    revokePlugin(pluginId: string): Promise<void>;
+    /** Invalidate first, then wait for every admitted host cleanup and file event. */
+    dispose(): Promise<void>;
+    /**
+     * Host-controlled enrollment; this operation is intentionally absent from
+     * plugin facades.
+     */
     enrollPluginCrypto(pluginId: string, passphrase: string, request?: SyncCryptoEnrollmentRequest): Promise<SyncCryptoStatus>;
     /** Host-controlled unlock; plugins can only observe locked state. */
     unlockPluginCrypto(pluginId: string, passphrase: string): Promise<SyncCryptoStatus>;