@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/dist/app-host/cloud-copy-host.d.ts

@@ -0,0 +1,248 @@
+import { AppLogPushChannel, type AppLogPushEvents } from "./log-push.js";
+import type { PeopleAuthority } from "../people.js";
+import type { AppLogHealth } from "./log-pump.js";
+import { type AppServerProblem } from "./cp-problem.js";
+import { type AppInitialSyncWait } from "./initial-sync.js";
+import { attachAppLocalFacade } from "./local-facade.js";
+import { type AppBundledReleaseTrust, type AppCloudCopyBootstrapMetadata, type AppCloudCopyAdoptionOptions } from "./cloud-copy-bootstrap.js";
+import type { AppReplicaScope } from "./owner.js";
+import type { AppSqlLifetime } from "./wasm-runtime.js";
+import type { AppProtectedInstallationSignIn, AppInstallationSignInView, AppInstallationTimerConsent } from "./installation-sign-in.js";
+import { type AppCpDeviceSession } from "./device-registration.js";
+import type { AppInstallationCustodyAuthority } from "./owner.js";
+import { type AppDeviceRegistrationReceipt } from "./wasm-runtime.js";
+/** Authenticated first-party selection, NOT caller/UI-selected grant authority.
+ * The installation ledger must establish explicit fresh/existing before this
+ * entry; missing/corrupt existing and interrupted initialization require recovery. */
+export interface AppCloudCopyHostSession extends AppCpDeviceSession {
+    readonly accountId: string;
+    readonly logOrigin: string;
+    readonly approvalMode: "password-ak1" | "strict";
+    /** Original protected CP receipt metadata; absent means no timer reference.
+     * Neither this snapshot nor its public IDs authorize a CP operation. */
+    timerConsent?(): AppInstallationTimerConsent | null;
+}
+/** SAME public bundled output of the shared BUILD verifier; never discover at
+ * runtime. Release context/tool authentication precedes host construction. */
+export type AppCloudCopyHostRelease = AppBundledReleaseTrust;
+export declare class AppCloudCopyHostError extends Error {
+    readonly reason: "binding" | "fenced" | "recovery_required" | "unavailable" | "sync_stalled";
+    constructor(reason: "binding" | "fenced" | "recovery_required" | "unavailable" | "sync_stalled");
+}
+/** Owns nonexported KEK and ciphertext handles for SAME original installation.
+ * Call close/terminate through openOwnedAppWorker; this object never unlocks.
+ * No raw key/KEK getter or generic store/sign/DH surface. */
+export declare class AppWebCloudCopyHost {
+    private readonly source;
+    private readonly installation;
+    private readonly originalRelease;
+    private readonly origin;
+    private readonly lifetime;
+    private closing;
+    private closeResult;
+    private provider;
+    private keys;
+    private noiseStore;
+    private key;
+    private noise;
+    private native;
+    private publicReceipt;
+    private signIn;
+    private originalCustody;
+    private collectionAttempted;
+    private collectionSignal;
+    private collectionCurrent;
+    private outcomeStore;
+    private outcome;
+    private bootstrap;
+    private bootstrapConfirmed;
+    private collectionScope;
+    private collectionSession;
+    private adoptedEndpoint;
+    private sqlAttempted;
+    private sqlClose;
+    private collectionSql;
+    private logRequest;
+    private logLoopback;
+    private logWork;
+    private authority;
+    private peopleMetadata;
+    private pump;
+    private readonly timerPorts;
+    private readWork;
+    private readAbort;
+    private readClient;
+    private readVerified;
+    /** One data facade per attached tab (the first, then any follower tabs). */
+    private readonly facades;
+    private logWorkListener;
+    private readonly selected;
+    private readonly currentCallback;
+    private readonly bearerCallback;
+    private readonly ownershipCallback;
+    private readonly trust;
+    private readonly pin;
+    private constructor();
+    private current;
+    private check;
+    private operationSignal;
+    /** Must run INSIDE owned Worker initialization, after installation acquisition.
+     * loadRuntime is the explicit authenticated immutable-artifact intake, not a
+     * MemStore/legacy/default module selector. No collection query/SQL/facade yet. */
+    static openOriginalDevice(options: {
+        session: AppCloudCopyHostSession;
+        installation: AppInstallationCustodyAuthority;
+        release: AppCloudCopyHostRelease;
+        origin: string;
+        mode: "fresh" | "existing";
+        signal: AbortSignal;
+        loadRuntime(options: {
+            signal: AbortSignal;
+        }): Promise<Uint8Array>;
+        fetch?: typeof fetch;
+        allowLoopbackHttp?: boolean;
+        allowNativeLoopbackHttp?: boolean;
+    }): Promise<AppWebCloudCopyHost>;
+    /** SAME protected installation flow -> SAME original native lifetime. No
+     * /devices registration, second open, seed re-loan or raw custody getter.
+     * User account confirmation and actual installation ownership precede the
+     * committed attempt; partial EXISTING state never authorizes fresh keys. */
+    static openInstallationDevice(options: {
+        signIn: AppProtectedInstallationSignIn;
+        installation: AppInstallationCustodyAuthority;
+        release: AppCloudCopyHostRelease;
+        origin: string;
+        signal: AbortSignal;
+        loadRuntime(options: {
+            signal: AbortSignal;
+        }): Promise<Uint8Array>;
+        allowLoopbackHttp?: boolean;
+        allowNativeLoopbackHttp?: boolean;
+    }): Promise<AppWebCloudCopyHost>;
+    /** ONE fixed enrol transcript with durable original proof. Lost replies
+     * retain this native owner; only explicit SAME-flow reconciliation retries. */
+    attestInstallation(): Promise<AppInstallationSignInView>;
+    /** Call only after explicit flow.exchange has protected the credential.
+     * Durable SAME Noise receipt precedes SAME native ACK and host readiness. */
+    completeInstallationSignIn(): Promise<AppDeviceRegistrationReceipt>;
+    /** Shared original-device intake for old controller qualification and actual
+     * installation sign-in. No mode inference or second custody implementation. */
+    private openOwnedDevice;
+    /** Called INSIDE the same owned collection Worker initialization. scope is
+     * the original scope supplied by openOwnedAppWorker, collectionCurrent is
+     * its trusted first-party lifetime fence (not a grant or SQL/readiness proof).
+     * SAME nonexported KEK and bundled environment; no caller outcome adapter.
+     * No SQL is opened here and completion is NOT readable/Saved authority. */
+    bootstrapCloudCopy(options: {
+        scope: Readonly<AppReplicaScope>;
+        collectionCurrent(): boolean;
+        purpose: "create" | "join";
+        outcomeMode: "fresh" | "existing";
+        signal: AbortSignal;
+        reconcile?: "explicit-unknown-outcome";
+        /** Explicit cleartext initial label, captured before asynchronous work. */
+        displayName?: string;
+        fetch?: typeof fetch;
+        allowLoopbackHttp?: boolean;
+        allowNativeLoopbackHttp?: boolean;
+    }): Promise<AppCloudCopyBootstrapMetadata>;
+    private checkCollection;
+    /** SQL is supplied only AFTER collection ownership and an internally
+     * confirmed protected completion. Native SAME-bundle adoption, not a fresh
+     * seed loan or caller root/genesis override. Verified read still required. */
+    adoptCloudCopy(options: AppCloudCopyAdoptionOptions, sql: AppSqlLifetime): void;
+    /** Trusted immutable storage intake callback: actual OPFS adapter in this
+     * Worker, exact owned scope, no MemStore/reset/missing-existing fallback.
+     * Callback cannot run until protected completion; root/genesis stay internal. */
+    openCollectionSql(options: {
+        signal: AbortSignal;
+        replicaId: string;
+        endpoint: number | bigint;
+        openSql(input: {
+            scope: Readonly<AppReplicaScope>;
+            signal: AbortSignal;
+        }): Promise<{
+            sql: AppSqlLifetime;
+            opened: AppCloudCopyAdoptionOptions["opened"];
+            sqliteVersion: number;
+            /** Close SQL/VFS ONLY after native shutdown or Worker termination. */
+            close(): Promise<void>;
+        }>;
+    }): Promise<void>;
+    /** Actual original-device CP credential -> native signed token -> fixed log
+     * transport. Missing/offline credentials never become trusted defaults. */
+    startCollectionLog(options: {
+        signal: AbortSignal;
+        fetch?: typeof fetch;
+        allowLoopbackHttp?: boolean;
+    }): Promise<void>;
+    /** Read-only metadata for this adopted collection. Uses the already pinned
+     * CP transport; no session, credential, key or readiness authority escapes.
+     * Compose with MdbasePeopleClient INSIDE the trusted owned Worker and send
+     * only public projections across its caller channel. */
+    peopleAuthority(): PeopleAuthority;
+    /** SAME Worker host/scope/child lifetime. Only the original chosen receipt
+     * selects a fixed native CP receiver; no session or bearer leaves Worker. */
+    openTimersPort(options: {
+        scope: Readonly<AppReplicaScope>;
+        generation: string;
+        signal: AbortSignal;
+    }): {
+        port: MessagePort;
+        close(): Promise<void>;
+    } | null;
+    /** The live log's latest specific server refusal, or null. Display only. */
+    serverProblem(): AppServerProblem | null;
+    /** Typed health of the path to the log from the latest failed call, or
+     * null once a reply was accepted. Display and retry pacing only. */
+    transportHealth(): AppLogHealth | null;
+    /** What the replica still waits for before it holds everything up to the
+     * known log head, or null once it does (native sync status). */
+    initialSync(): AppInitialSyncWait | null;
+    /** Diagnostics while waiting for a key (native sync status), else null. */
+    keyWaitDetail(): Record<string, string | number> | null;
+    /** Local writes not yet confirmed by the log (native sync status). */
+    pendingWrites(): number;
+    /** Feed one push frame to the native replica (current log session only). */
+    pushLog(frame: Uint8Array): boolean;
+    /** The log's push socket for this collection, or null when the runtime cannot
+     * sign its `hello` (older native asset): then the caller wakes on events only.
+     * Requires the started log. The socket never carries requests. */
+    openLogPush(events: AppLogPushEvents): AppLogPushChannel | null;
+    /** Ordinary foreground log drive. Quiet/head/ACK/status are NOT read/Saved. */
+    driveCollection(options: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    /** Foreground head wake. The HTTP log has no push channel and the native core
+     * queues a head only on open, failure or reconnect, so without this a running
+     * session never learns another device's entries. Runs only after a quiet pump;
+     * the native side refuses while a head fetch is already in flight. */
+    wakeCollectionLog(options: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    /** READ-only admission through the actual typed native Query gate. While
+     * the log pump runs, the budget bounds inactivity, so a warm replica far
+     * behind can finish its catch-up turn; without a pump it is fixed.
+     * No status-based admission, write retry, key override or private grant. */
+    waitForVerifiedRead(options: {
+        signal: AbortSignal;
+        timeoutMs?: number;
+        onProgress?: (progress: import("./opening-progress.js").AppOpeningProgress) => void;
+        /** SDK join ledger has never completed this local replica's first sync.
+         * The budget then bounds inactivity, not total collection catch-up. */
+        cold?: boolean;
+    }): Promise<void>;
+    private verifyRead;
+    /** A data-only Worker port per attached tab, only after a genuine native typed read passed.
+     * Every subsequent frame remains gated by native trust/applied/key/read.
+     * Host controls, SQL/custody/log tokens and owner unlock are never RPCs. */
+    /** Called when an app call may have queued log work (a write or file
+     * transfer), so the collection drive runs now rather than on its timer. */
+    onLogWork(listener: (() => void) | null): void;
+    attachDataFacade(channel: MessagePort): ReturnType<typeof attachAppLocalFacade>["resourceSetup"];
+    /** Close one tab's data facade (that tab left); the replica stays open. */
+    detachDataFacade(channel: MessagePort): void;
+    /** Public tuple copy only; no key loans and no readiness claim. */
+    registeredReceipt(): AppDeviceRegistrationReceipt;
+    close(): Promise<void>;
+}