@lapis-notes/api 0.1.0 → 0.1.2

package/dist/sync-host.d.ts

@@ -0,0 +1,179 @@
+import type { AppDatabase } from "./storage/app-database";
+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";
+export type HostFileIdentityState = "present" | "tombstoned";
+export type HostFileChangeKind = "create" | "modify" | "rename" | "delete";
+export interface HostFileIdentity {
+    fileId: string;
+    currentPath: string;
+    state: HostFileIdentityState;
+    createdAt: number;
+    updatedAt: number;
+    tombstonedAt?: number;
+    lastObservedMtime?: number;
+    lastObservedSize?: number;
+    contentGeneration: number;
+    lastChangeSequence: number;
+    contentFingerprint?: string;
+}
+export interface HostFilePathAlias {
+    fileId: string;
+    path: string;
+    firstSeenAt: number;
+    lastSeenAt?: number;
+    reason: "create" | "rename" | "move" | "scan-reconciliation" | "restore";
+}
+export interface HostChangeCursor {
+    databaseGenerationId: string;
+    sequence: number;
+}
+export interface HostFileChange {
+    file: HostFileIdentity;
+    kind: HostFileChangeKind;
+    previousPath?: string;
+    selfOriginated: boolean;
+}
+export interface HostChangedFileBatch {
+    status: "ok" | "reset-required";
+    databaseGenerationId: string;
+    changes: HostFileChange[];
+    nextCursor: HostChangeCursor;
+    hasMore: boolean;
+}
+export interface ExternalFileIdentityBinding {
+    namespace: string;
+    externalFileId: string;
+    localFileId: string;
+    boundAt: number;
+    updatedAt: number;
+}
+export interface OperationOrigin {
+    readonly token: string;
+}
+export interface GeneratedStateRecord<T = unknown> {
+    key: string;
+    value: T;
+    version: number;
+    updatedAt: number;
+}
+export interface GeneratedStateMutation {
+    type: "set" | "delete";
+    key: string;
+    value?: unknown;
+}
+export interface GeneratedStateTransaction {
+    expectedRevision?: number;
+    expectedSchemaVersion?: number;
+    schemaVersion?: number;
+    mutations: GeneratedStateMutation[];
+}
+export interface GeneratedStateTransactionResult {
+    applied: boolean;
+    revision: number;
+    schemaVersion: number;
+}
+export interface GeneratedStatePage<T = unknown> {
+    records: GeneratedStateRecord<T>[];
+    nextCursor?: string;
+}
+export interface PluginGeneratedState {
+    get<T = unknown>(key: string): Promise<GeneratedStateRecord<T> | null>;
+    scan<T = unknown>(options?: {
+        prefix?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<GeneratedStatePage<T>>;
+    getRevision(): Promise<number>;
+    getSchemaVersion(): Promise<number>;
+    transact(transaction: GeneratedStateTransaction): Promise<GeneratedStateTransactionResult>;
+    clear(): Promise<void>;
+}
+export interface SyncHostCapabilities {
+    readonly files: {
+        getIdentity(path: string): Promise<HostFileIdentity | null>;
+        resolveIdentity(fileId: string): Promise<HostFileIdentity | null>;
+        listChangedSince(cursor?: HostChangeCursor, options?: {
+            limit?: number;
+        }): Promise<HostChangedFileBatch>;
+        getExternalBinding(externalFileId: string): Promise<ExternalFileIdentityBinding | null>;
+        bindExternalIdentity(localFileId: string, externalFileId: string): Promise<ExternalFileIdentityBinding>;
+    };
+    readonly origins: {
+        create(): Promise<OperationOrigin>;
+    };
+    readonly vault: {
+        flushOpenEditor(path?: string): Promise<{
+            flushed: boolean;
+            path?: string;
+        }>;
+        openRead(path: string): Promise<VaultReadHandle & {
+            fileId: string;
+            contentGeneration: number;
+        }>;
+        atomicWrite(path: string, source: ReadableStream<Uint8Array>, options?: {
+            origin?: OperationOrigin;
+            expectedFileId?: string;
+            expectedContentGeneration?: number;
+            signal?: AbortSignal;
+        }): Promise<HostFileIdentity>;
+        remove(path: string, options?: {
+            origin?: OperationOrigin;
+            expectedFileId?: string;
+            expectedContentGeneration?: number;
+        }): Promise<HostFileIdentity>;
+    };
+    readonly network: PluginNetworkCapability;
+    readonly crypto: SyncCryptoCapability;
+    readonly syncIdentity: SyncIdentityCapability;
+    readonly pairing: SyncPairingCapability;
+    readonly membership: SyncMembershipCapability;
+    readonly recovery: SyncRecoveryCapability;
+    readonly generatedState: PluginGeneratedState;
+}
+export interface SyncHostServiceOptions {
+    flushOpenEditor?: (path?: string) => Promise<{
+        flushed: boolean;
+        path?: string;
+    }>;
+    security?: SyncHostSecurityOptions;
+    /** Host UI/native adapter callback. It never becomes part of a plugin facade. */
+    requestCryptoUnlock?: (pluginId: string, status: SyncCryptoStatus, enrollment?: SyncCryptoEnrollmentRequest) => Promise<void>;
+    /** Host-owned passphrase or equivalent recovery-bundle interaction. */
+    requestRecoveryPassphrase?: (pluginId: string, mode: "export" | "import") => Promise<string | null>;
+    /** Host consent callback for an exact plugin network origin. */
+    requestNetworkOriginGrant?: (request: {
+        pluginId: string;
+        origin: string;
+        allowPrivateNetwork: boolean;
+    }) => Promise<boolean>;
+}
+export declare class SyncHostService {
+    #private;
+    readonly database: AppDatabase;
+    readonly vault: Vault;
+    readonly clock: () => number;
+    readonly options: SyncHostServiceOptions;
+    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. */
+    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>;
+    /** Host-controlled passkey or OS-credential enrollment. */
+    enrollPluginCryptoWithWrappingKey(pluginId: string, wrappingKey: Uint8Array, descriptor: Extract<SyncWrappingKeyDescriptor, {
+        name: "external";
+    }>, request?: SyncCryptoEnrollmentRequest): Promise<SyncCryptoStatus>;
+    /** Host-controlled passkey or OS-credential unlock. */
+    unlockPluginCryptoWithWrappingKey(pluginId: string, wrappingKey: Uint8Array): Promise<SyncCryptoStatus>;
+    lockPluginCrypto(pluginId: string): void;
+    grantPluginNetworkOrigin(pluginId: string, origin: string, options?: {
+        allowPrivateNetwork?: boolean;
+    }): Promise<void>;
+    revokePluginNetworkOrigin(pluginId: string, origin: string): Promise<void>;
+    recordOriginatedChange(pluginId: string, origin: OperationOrigin, kind: HostFileChangeKind, file: TFile, previousPath?: string): Promise<void>;
+}