@lapis-notes/api 0.1.0 → 0.1.3

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

@@ -0,0 +1,285 @@
+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";
+export type SyncDeviceRole = "owner" | "member";
+export type SyncIdentityState = "setup-required" | "active" | "rotation-pending";
+export interface SyncIdentityHistoryEntry {
+    publicKey: string;
+    generation: number;
+    activatedMembershipGeneration: number;
+    retiredMembershipGeneration?: number;
+    cutoffHeads?: Record<string, string>;
+}
+export interface SyncIdentityPublicStatus {
+    state: SyncIdentityState;
+    publicKey?: string;
+    generation: number;
+    history: SyncIdentityHistoryEntry[];
+    pendingPublicKey?: string;
+    canRotate: boolean;
+}
+export interface SyncDeviceMembership {
+    publicKey: string;
+    alias: string;
+    role: SyncDeviceRole;
+    state: "active" | "revoked";
+    addedAt: number;
+    revokedAt?: number;
+    cutoffHead?: string;
+}
+export interface SyncMembershipSnapshot {
+    schemaVersion: 1 | 2;
+    vaultId: string;
+    ownerPublicKey: string;
+    generation: number;
+    currentEpoch: number;
+    previousEventId?: string;
+    devices: SyncDeviceMembership[];
+    /** NIP-44 sealed current-epoch material, keyed by active device public key. */
+    epochEnvelopes?: Record<string, string>;
+    /** Current-epoch material sealed to the recovery authority. */
+    recoveryEpochEnvelope?: string;
+    /** Stable remote-account identity and its root-authorised public lineage. */
+    syncIdentity?: {
+        publicKey: string;
+        generation: number;
+        history: SyncIdentityHistoryEntry[];
+    };
+    /** Active Sync Identity secret sealed independently to each active device. */
+    syncIdentityEnvelopes?: Record<string, string>;
+    /** Active Sync Identity secret sealed to the recovery authority. */
+    recoverySyncIdentityEnvelope?: string;
+    /** Final accepted legacy device-authored HEADs at Sync Identity activation. */
+    legacyTransportCutoffHeads?: Record<string, string>;
+    event?: NostrEvent;
+}
+export interface SyncCryptoStatus {
+    state: "unenrolled" | "locked" | "unlocked";
+    suite: "lapis-sync-v1-xchacha20poly1305-schnorr";
+    publicKey?: string;
+    /** Unambiguous replacement for the deprecated publicKey device-key alias. */
+    devicePublicKey?: string;
+    vaultId?: string;
+    deviceAlias?: string;
+    role?: SyncDeviceRole;
+    deviceState?: "active" | "revoked" | "recovery-pending";
+    currentEpoch?: number;
+    membershipGeneration?: number;
+    canManageDevices?: boolean;
+    syncIdentity?: SyncIdentityPublicStatus;
+}
+export interface SyncEncryptedObject {
+    bytes: Uint8Array;
+    objectHash: string;
+}
+export interface UnsignedSyncEvent {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+export interface SyncCryptoCapability {
+    status(): Promise<SyncCryptoStatus>;
+    /** Explicitly create a new sync vault through a host-owned enrollment flow. */
+    enrollNewVault(input: {
+        deviceAlias: string;
+    }): Promise<SyncCryptoStatus>;
+    /** Ask the owning host to perform its user-verification unlock flow. */
+    requestUnlock(): Promise<SyncCryptoStatus>;
+    getDevicePublicKey(): Promise<string>;
+    encryptObject(input: {
+        epoch: number;
+        type: SyncCryptoObjectType;
+        plaintext: Uint8Array;
+    }): Promise<SyncEncryptedObject>;
+    decryptObject(input: {
+        epoch: number;
+        type: SyncCryptoObjectType;
+        envelope: Uint8Array;
+    }): Promise<Uint8Array>;
+    calculateContentId(input: {
+        epoch: number;
+        plaintext: Uint8Array;
+    }): Promise<string>;
+    signEvent(event: UnsignedSyncEvent): Promise<NostrEvent>;
+    /** Sign a bounded inner revision or HEAD attestation with this device. */
+    signDeviceEvent(event: UnsignedSyncEvent): Promise<NostrEvent>;
+}
+export type SyncIdentitySigningPurpose = "transport" | "relay-auth" | "blossom-auth" | "connection-probe";
+export interface SyncIdentityCapability {
+    status(): Promise<SyncIdentityPublicStatus>;
+    initialize(input: {
+        cutoffHeads: Record<string, string>;
+    }): Promise<{
+        status: SyncIdentityPublicStatus;
+        membershipEvent: NostrEvent;
+    }>;
+    signEvent(input: {
+        purpose: SyncIdentitySigningPurpose;
+        identity?: "active" | "pending";
+        event: UnsignedSyncEvent;
+    }): Promise<NostrEvent>;
+    beginRotation(): Promise<SyncIdentityPublicStatus>;
+    commitRotation(input: {
+        pendingPublicKey: string;
+        cutoffHeads: Record<string, string>;
+    }): Promise<{
+        status: SyncIdentityPublicStatus;
+        membershipEvent: NostrEvent;
+    }>;
+    cancelRotation(): Promise<SyncIdentityPublicStatus>;
+}
+export interface SyncPairingSessionSnapshot {
+    sessionId: string;
+    role: "owner" | "joining";
+    state: "waiting-for-peer" | "waiting-for-sas" | "waiting-for-confirmation" | "ready-to-enroll" | "transferring" | "complete" | "cancelled" | "expired" | "error";
+    expiresAt: number;
+    sas?: string;
+    peerPublicKey?: string;
+    peerAlias?: string;
+    error?: string;
+}
+export interface SyncPairingActionResult {
+    session: SyncPairingSessionSnapshot;
+    outboundEvents: NostrEvent[];
+    /** Public transport endpoints for this bounded pairing session. */
+    relayUrls: string[];
+    invitationUri?: string;
+    membershipEvent?: NostrEvent;
+    /** Bounded plugin data recovered only from the encrypted pairing transfer. */
+    metadata?: unknown;
+}
+export interface SyncPairingCapability {
+    beginOwner(input: {
+        relayUrls: string[];
+        cutoffHeads?: Record<string, string>;
+        metadata?: unknown;
+    }): Promise<SyncPairingActionResult>;
+    acceptInvite(input: {
+        invitationUri: string;
+        deviceAlias: string;
+    }): Promise<SyncPairingActionResult>;
+    ingest(input: {
+        sessionId: string;
+        event: NostrEvent;
+    }): Promise<SyncPairingActionResult>;
+    confirm(sessionId: string, sas?: string): Promise<SyncPairingActionResult>;
+    cancel(sessionId: string): Promise<SyncPairingSessionSnapshot>;
+    /** Create a disposable kind-24134 event for relay policy probing. */
+    createRelayProbe(): Promise<NostrEvent>;
+}
+export interface SyncMembershipCapability {
+    getSnapshot(): Promise<SyncMembershipSnapshot>;
+    ingest(event: NostrEvent): Promise<SyncMembershipSnapshot>;
+    renameDevice(input: {
+        publicKey: string;
+        alias: string;
+    }): Promise<SyncMembershipSnapshot>;
+    revokeDevice(input: {
+        publicKey: string;
+        cutoffHeads: Record<string, string>;
+    }): Promise<SyncMembershipSnapshot>;
+    recoverOwner(input: {
+        cutoffHeads: Record<string, string>;
+    }): Promise<SyncMembershipSnapshot>;
+}
+export interface SyncRecoveryCapability {
+    exportBundle(input?: {
+        metadata?: unknown;
+    }): Promise<Uint8Array>;
+    importBundle(input: {
+        bundle: Uint8Array;
+        replaceExisting?: boolean;
+    }): Promise<{
+        status: SyncCryptoStatus;
+        metadata?: unknown;
+    }>;
+}
+export interface SyncCryptoEnrollmentRequest {
+    mode: "new-vault" | "paired-device" | "recovery";
+    deviceAlias?: string;
+    sessionId?: string;
+}
+export interface PluginNetworkRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: BodyInit | ReadableStream<Uint8Array> | null;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface PluginNetworkResponse {
+    url: string;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: ReadableStream<Uint8Array> | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+export interface PluginWebSocket {
+    readonly url: string;
+    readonly ready: Promise<void>;
+    readonly readyState: number;
+    addEventListener(type: "open" | "message" | "error" | "close", listener: EventListenerOrEventListenerObject): void;
+    removeEventListener(type: "open" | "message" | "error" | "close", listener: EventListenerOrEventListenerObject): void;
+    send(data: string | ArrayBuffer | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+}
+export interface PluginNetworkCapability {
+    /** Ask the host to approve and persist an exact origin grant. */
+    requestOriginGrant(origin: string, options?: {
+        allowPrivateNetwork?: boolean;
+    }): Promise<void>;
+    request(request: PluginNetworkRequest): Promise<PluginNetworkResponse>;
+    connectWebSocket(url: string, protocols?: string | string[]): Promise<PluginWebSocket>;
+}
+export type SyncWrappingKeyDescriptor = {
+    name: "argon2id";
+    timeCost: number;
+    memoryKiB: number;
+    parallelism: number;
+    dkLen: 32;
+    saltHex: string;
+} | {
+    name: "external";
+    provider: "webauthn-prf" | "os-credential-store";
+    keyId: string;
+};
+export interface SyncHostSecurityOptions {
+    fetch?: typeof fetch;
+    WebSocket?: typeof WebSocket;
+    argon2?: {
+        timeCost?: number;
+        memoryKiB?: number;
+        parallelism?: number;
+    };
+}
+export declare class SyncHostSecurityService {
+    #private;
+    readonly database: AppDatabase;
+    readonly assertRuntime: (pluginId: string, runtimeId: string) => void;
+    constructor(database: AppDatabase, 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";
+    }>, request?: SyncCryptoEnrollmentRequest): Promise<SyncCryptoStatus>;
+    unlock(pluginId: string, passphrase: string): Promise<SyncCryptoStatus>;
+    unlockWithWrappingKey(pluginId: string, wrappingKey: Uint8Array): Promise<SyncCryptoStatus>;
+    lock(pluginId: string): void;
+    status(pluginId: string): Promise<SyncCryptoStatus>;
+    crypto(pluginId: string, runtimeId: string, assertGranted?: () => void, requestUnlock?: () => Promise<SyncCryptoStatus>, requestEnrollment?: (input: SyncCryptoEnrollmentRequest) => Promise<SyncCryptoStatus>): SyncCryptoCapability;
+    syncIdentity(pluginId: string, runtimeId: string, assertGranted?: () => void): SyncIdentityCapability;
+    pairing(pluginId: string, runtimeId: string, assertGranted?: () => void, requestEnrollment?: (input: SyncCryptoEnrollmentRequest) => Promise<SyncCryptoStatus>): SyncPairingCapability;
+    membership(pluginId: string, runtimeId: string, assertGranted?: () => void): SyncMembershipCapability;
+    recovery(pluginId: string, runtimeId: string, assertGranted?: () => void, requestPassphrase?: (mode: "export" | "import") => Promise<string | null>, requestEnrollment?: (input: SyncCryptoEnrollmentRequest) => Promise<SyncCryptoStatus>): SyncRecoveryCapability;
+    grantNetworkOrigin(pluginId: string, origin: string, options?: {
+        allowPrivateNetwork?: boolean;
+    }): Promise<void>;
+    hasNetworkOriginGrant(pluginId: string, origin: string): Promise<boolean>;
+    revokeNetworkOrigin(pluginId: string, origin: string): Promise<void>;
+    revokePlugin(pluginId: string): void;
+    network(pluginId: string, runtimeId: string, assertGranted?: () => void, requestOriginGrant?: (origin: string, options?: {
+        allowPrivateNetwork?: boolean;
+    }) => Promise<void>): PluginNetworkCapability;
+}