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

package/dist/app-host/wasm-runtime.d.ts

@@ -0,0 +1,302 @@
+import { WasmRuntime, type OpenConfig } from "../runtime/wasm.js";
+import { type ConfirmedHead, type SyncStatus } from "../wire.js";
+import { AppLogPump, type AppLogCall, type AppLogRuntime, type AppLogTransport } from "./log-pump.js";
+import type { AppLogHttpProof } from "./http-log.js";
+import { type AppResourceAssessment, type AppResourceDecisions } from "./collection-control.js";
+import type { ModelResourcePlan } from "./collection-setup-types.js";
+export interface AppSqlMemory {
+    memory: WebAssembly.Memory;
+    alloc(length: number): number;
+}
+/** Bind the existing AppBinaryIndexHost/appSqlHost in the SAME Worker. */
+export interface AppSqlLifetime {
+    import(exports: () => AppSqlMemory): (ptr: number, len: number) => bigint;
+    /** Fence the connection/clean marker on a trap or malformed ABI observation. */
+    fence(): void;
+    readonly needsRecovery: boolean;
+}
+/** Supplied ONLY by authenticated host selection after async protected key unwrap. */
+export interface AppBootstrap {
+    collection: string;
+    replicaId: string;
+    deviceId: string;
+    endpoint: number | bigint;
+    trustedRoots: readonly Uint8Array[];
+    /** Canonical public PolicyPins from the shared BUILD-time signed environment
+     * trust-asset verifier, bundled in the release. Never CP/log/UI-derived.
+     * Native validates IDs/strong keys/root binding and warm consistency. */
+    policyPins: Uint8Array;
+    trustedSigners: readonly string[];
+    expectedGenesis: string;
+    state: "e2e" | "cloud_copy";
+    cloudCopyOptIn: boolean;
+    /** Owned transient buffers: openAppConsuming wipes both on ordinary return. */
+    signSecretKey: Uint8Array;
+    kemSecretKey: Uint8Array;
+    opened: "fresh" | "existing" | "unclean";
+    sqliteVersion: number;
+}
+/** Trusted authenticated host bootstrap only, never a grant/app RPC. */
+export interface AppCpConnectorPin {
+    readonly connectorId: string;
+    readonly deviceId: string;
+    readonly collection: string;
+    isCurrent(): boolean;
+}
+/** Authenticating-host per-installation identity BEFORE any collection.
+ * Dedicated connector/device, never application grant or daemon identity. */
+export interface AppDeviceIdentityPin {
+    readonly connectorId: string;
+    readonly deviceId: string;
+    readonly installationId: string;
+    isCurrent(): boolean;
+}
+export interface AppDeviceBootstrap {
+    pin: AppDeviceIdentityPin;
+    /** Protected transient loans, consumed/wiped; NEVER a Noise secret. */
+    signSecretKey: Uint8Array;
+    kemSecretKey: Uint8Array;
+    opened: {
+        mode: "fresh";
+    } | {
+        mode: "existing";
+        envelope: Uint8Array;
+    };
+}
+export type AppCollectionBootstrap = Omit<AppBootstrap, "signSecretKey" | "kemSecretKey">;
+/** Actual authenticated registration response, or protected stored receipt for
+ * offline reopen. Ciphertext possession is NOT registration completion. */
+export interface AppDeviceRegistrationReceipt extends AppDevicePublicIdentity {
+    readonly connectorId: string;
+    readonly deviceId: string;
+    readonly installationId: string;
+}
+export interface AppDevicePublicIdentity {
+    readonly signPublicKey: Uint8Array;
+    readonly kemPublicKey: Uint8Array;
+    readonly noisePublicKey: Uint8Array;
+}
+export interface AppNoiseCustodyResult extends AppDevicePublicIdentity {
+    readonly envelope: Uint8Array;
+}
+export interface AppCpEnrolProof extends AppDevicePublicIdentity {
+    readonly signature: Uint8Array;
+}
+/** Authenticated host prospective collection decision, not a grant/readiness. */
+export interface AppCloudCopyCollectionPin extends AppDeviceIdentityPin {
+    readonly collection: string;
+    readonly purpose: "create" | "join";
+    readonly approvalMode: "password-ak1" | "strict";
+}
+export interface AppPrivateCollectionPin extends AppDeviceIdentityPin {
+    readonly collection: string;
+    readonly purpose: "create" | "enrol";
+    readonly approvalMode: "password-ak1" | "strict";
+}
+export interface AppPrivateDeviceEnrolProof {
+    readonly signature: Uint8Array;
+    readonly sasCommitment: Uint8Array;
+}
+/** PUBLIC exact-tuple operation marker, authenticated platform-protected.
+ * r is NEVER stored. Acknowledgement is actual CP response, NOT approval/keyed. */
+export interface AppPrivateEnrolOperationMarker extends AppDeviceRegistrationReceipt {
+    readonly collection: string;
+    readonly sasCommitment: Uint8Array;
+    readonly acknowledged: boolean;
+}
+export type AppPrivateCollectionOpen = {
+    readonly mode: "fresh";
+} | {
+    readonly mode: "existing";
+    readonly marker: AppPrivateEnrolOperationMarker;
+};
+export interface AppAccountKeyPin extends AppDeviceIdentityPin {
+    readonly collection: string;
+    readonly approvalMode: "password-ak1" | "strict";
+}
+export type AppAccountKeyRefusal = "not_private" | "not_ready" | "not_enrolled" | "not_authorized" | "device_missing" | "enrolment_mismatch" | "not_keyed" | "no_wrap" | "inconsistent" | "failed" | "outcome_unknown";
+export type AppAccountKeyState = {
+    readonly state: "pending" | "keyed";
+} | {
+    readonly state: "refused";
+    readonly reason: AppAccountKeyRefusal;
+};
+export type AppAccountKeyDeviceSetupState = {
+    readonly state: "recovery_pending" | "recovery_keyed";
+} | {
+    readonly state: "refused";
+    readonly reason: AppAccountKeyRefusal;
+};
+export declare class AppStrictDeviceApprovalError extends Error {
+    readonly reason = "strict_device_approval";
+    constructor();
+}
+/** Captured from the actual authenticated hosted session, not witness/hello
+ * self-claims, NoisePK or guessed CP fields. No signing key supplied by JS. */
+export interface AppHandoverSource {
+    readonly collection: string;
+    readonly deviceId: string;
+    isCurrent(): boolean;
+}
+export interface AppRuntimeObservations {
+    status: SyncStatus;
+    keyringRebuilding: boolean;
+    keyringRebuildFailed: boolean;
+    snapshotInstallAvailable: boolean;
+    requiresReopen: boolean;
+}
+/** One module/database lifetime. Call pump.close() before shutdown/SQL close;
+ * terminate Worker before releasing its lease if drain/disposal fails. */
+export declare class AppWasmRuntime extends WasmRuntime implements AppLogRuntime {
+    private readonly sqlBinding;
+    private attempted;
+    private active;
+    private retired;
+    private collection;
+    private deviceId;
+    private connectorId;
+    private cpPin;
+    private deviceAttempted;
+    private deviceActive;
+    private deviceRegistered;
+    private devicePin;
+    private installationId;
+    private publicIdentity;
+    private noiseEnvelope;
+    private cloudSource;
+    private cloudCallback;
+    private cloudCollection;
+    private cloudPurpose;
+    private cloudIssued;
+    private privateAttempted;
+    private privateSource;
+    private prospectiveCollection;
+    private privatePurpose;
+    private sasCommitment;
+    private privateEnrolAcknowledged;
+    private endpoint;
+    private logGeneration;
+    private pump;
+    private transport;
+    private constructor();
+    private get sql();
+    private get app();
+    static create(bytes: BufferSource, sql: AppSqlLifetime): Promise<AppWasmRuntime>;
+    /** Device-only module with DENYING SQL import. Collection trust/database is
+     * deliberately not required/created while registering a fresh installation. */
+    static createDevice(bytes: BufferSource): Promise<AppWasmRuntime>;
+    private static instantiateApp;
+    /** The app artifact never uses a legacy/config-default MemStore path. */
+    open(_config: OpenConfig): never;
+    private fail;
+    private guard;
+    /** One attempt. The caller must unwrap keys before this SYNCHRONOUS operation. */
+    openAppConsuming(c: AppBootstrap): void;
+    tick(): void;
+    connect(options?: Parameters<WasmRuntime["connect"]>[0]): ReturnType<WasmRuntime["connect"]>;
+    /** Trusted host READ on its actual held port. Native admission/publication
+     * remains authoritative. There is no caller-selected session or MemStore path. */
+    executeBases(port: ReturnType<WasmRuntime["connect"]>, request: Uint8Array): Uint8Array;
+    /** Separate native metadata READ exports; never caller sessions or Query RPC. */
+    discoverBases(port: ReturnType<WasmRuntime["connect"]>, operation: "list-views" | "read-view-source", request: Uint8Array): Uint8Array;
+    private readBases;
+    /** Private resource-only planner, bound to the already held facade session.
+     * Native owns inventory and authority checks; no caller IDs or state loans. */
+    setupResources(port: ReturnType<WasmRuntime["connect"]>, operation: "assess", manifest: unknown, expectedDigest?: undefined, decisions?: AppResourceDecisions): AppResourceAssessment;
+    setupResources(port: ReturnType<WasmRuntime["connect"]>, operation: "apply", manifest: unknown, expectedDigest: string, decisions?: AppResourceDecisions): ModelResourcePlan;
+    /** True only when native holds a FINAL rejected receipt for exactly this
+     * mutation on the port's own session. Anything else, including errors, is false. */
+    resourceRejected(port: ReturnType<WasmRuntime["connect"]>, mutationId: string): boolean;
+    /** Positive ONLY from native verified-policy signature + retained prefix and
+     * live READ session. Ordinary unavailable stays hosted; no saved implication. */
+    verifyHandover(port: ReturnType<WasmRuntime["connect"]>, source: AppHandoverSource, witness: Uint8Array): ConfirmedHead | null;
+    /** One authenticated connector bootstrap pin before any LS binding. */
+    bindCpConnector(pin: AppCpConnectorPin): void;
+    private deviceCurrent;
+    private publicResult;
+    /** Phase1 ONLY; no roots/genesis/Core/SQL/LS/RPC. Async protected outer
+     * unwrap precedes this sync native operation. Exactly one fresh/restore
+     * attempt, consuming BOTH sign/KEM loans; no caller Noise secret. */
+    openDeviceConsuming(c: AppDeviceBootstrap): AppNoiseCustodyResult;
+    /** Public binding check for this exact DEVICE-only custody result. Not an
+     * account/app grant, collection readiness or independent key attestation. */
+    deviceCustodyCurrent(pin: AppDeviceIdentityPin, custody: AppNoiseCustodyResult): boolean;
+    /** HOST ONLY actual authenticated response/protected stored receipt. Never
+     * inferred from ciphertext, same account, persistence or zero pending. */
+    acknowledgeDeviceRegistration(receipt: AppDeviceRegistrationReceipt): void;
+    /** Once-pinned CLOUD COPY purpose. Requires actual original registration,
+     * no private/SAS context and no seed re-loan, roots or SQL effects. */
+    prepareCloudCopyCollection(pin: AppCloudCopyCollectionPin): void;
+    cloudCopyCollectionCurrent(source?: AppCloudCopyCollectionPin): boolean;
+    /** Fixed native create domain; no configurable digest/subject/signer. */
+    signCloudCopyCreate(challenge: Uint8Array): Uint8Array;
+    /** Fixed native join domain; no private enrol/SAS state. */
+    signCloudCopyJoin(challenge: Uint8Array): Uint8Array;
+    private signCloudCopy;
+    /** Host-only ONCE, registered DEVICE phase. No Core/SQL/readiness; no caller
+     * fresh JS commit/secret. Existing must come from exact platform-protected
+     * public marker; never regenerate after uncertain enrolment. */
+    preparePrivateCollection(pin: AppPrivateCollectionPin, opened: AppPrivateCollectionOpen): void;
+    /** Actual acknowledged device public receipt, copied; no new authority. */
+    registeredDeviceReceipt(): AppDeviceRegistrationReceipt;
+    /** Public native-generated/restored marker to protect BEFORE any enrol POST. */
+    privateEnrolMarker(): AppPrivateEnrolOperationMarker;
+    privateCollectionCurrent(source?: AppPrivateCollectionPin): boolean;
+    /** Dedicated private-create signature only, no configurable purpose/PK/digest. */
+    signPrivateCreate(challenge: Uint8Array): Uint8Array;
+    /** Native public SAS commitment + dedicated enrol signature. No r/state or
+     * caller commit; strict approval/Noise handshake is not implemented in v1. */
+    signPrivateDeviceEnrol(challenge: Uint8Array): AppPrivateDeviceEnrolProof;
+    /** Phase2 consumes SAME native owners with genuine collection trust metadata.
+     * NO seed re-export/loan/recreation/rebind; device-phase v1 is unchanged. */
+    adoptDevice(c: AppCollectionBootstrap, sql?: AppSqlLifetime): void;
+    /** Separate fixed cp-enrol transcript over internally protected public keys.
+     * Borrowed nonce is independently copied; no key/identity/domain/digest inputs. */
+    signCpEnrol(challenge: Uint8Array): AppCpEnrolProof;
+    /** Fixed CP purpose; no method/route/domain/digest or identity override. */
+    signCpLogToken(challenge: Uint8Array): Uint8Array;
+    /** Host supplies a genuinely authenticated immutable transport, not a true flag. */
+    bindLogTransport(transport: AppLogTransport): AppLogPump;
+    /** HOST ONLY quiet foreground wake: asks the native replica to fetch the log
+     * head over the CURRENT authenticated session so remote entries are learned.
+     * No token, reconnect, status or readiness change; false when unsupported,
+     * not bound, already in flight, or unhealthy. Never retires the log; a trap
+     * fails the runtime exactly like tick(). */
+    requestLogHead(): boolean;
+    /** True when this runtime can sign the push socket's `hello`. */
+    get supportsLogPush(): boolean;
+    /** Fixed ls-hello proof for the push socket of the CURRENT log generation
+     * (`nonce32 ‖ token`). Null when unsupported or refused; never a generic signer. */
+    signLogHello(nonce: Uint8Array, token: string): Uint8Array | null;
+    /** HOST ONLY wake AFTER fresh authenticated authority admission: drain/abort
+     * original pump before SAME-owner native session/generation replacement. May
+     * hang: owner must terminate Worker before releasing lease. Not readiness. */
+    reconnectLogTransport(transport: AppLogTransport): Promise<AppLogPump>;
+    /** Protected fixed-domain authority callback. Rust checks the original exact
+     * frame or its associated same-address commit; JS digest is NOT signing input. */
+    signLogHttp(proof: AppLogHttpProof): Uint8Array;
+    takeLogCalls(): readonly AppLogCall[];
+    acceptLogReply(id: bigint, bytes: Uint8Array): boolean;
+    logNoResponse(id: bigint): void;
+    retireLog(): void;
+    /** Current authenticated service push only; transport fences its generation. */
+    pushLog(bytes: Uint8Array): boolean;
+    private accountKeyCurrent;
+    private accountKeyState;
+    /** Protected transient R32 loan, consumed/wiped even when refused/trapped.
+     * Native derives only this collection; pending/queued is NOT keyed. */
+    unlockAccountKeyConsuming(pin: AppAccountKeyPin, secret: Uint8Array): AppAccountKeyState;
+    /** Protected R32 setup loan, consumed even when refused/trapped. Only an
+     * existing CP-enrolled EXACT recovery device; queued != recovery_keyed, and
+     * recovery_keyed != this app keyed/Saved. Ordinary native KEY_GRANT only. */
+    setupAccountKeyDeviceConsuming(pin: AppAccountKeyPin, secret: Uint8Array): AppAccountKeyDeviceSetupState;
+    /** Actual native applied-policy/trust status; not zero-pending/readback/Saved. */
+    accountKeyStatus(pin: AppAccountKeyPin): AppAccountKeyState;
+    observations(): AppRuntimeObservations;
+    /** Drain/abort current generation BEFORE key/runtime/SQL shutdown. May hang;
+     * owner must terminate the Worker before releasing its lease in that case. */
+    close(): Promise<boolean>;
+    /** Synchronous clean shutdown only with no undrained pump. Not a saved claim. */
+    shutdown(): boolean;
+    dispose(): void;
+}