dropspace 0.0.0-stage → 0.1.0

package/dist/client/peer-selection.d.ts

@@ -0,0 +1,70 @@
+import type { PeerPresence, PermissionScope } from "../protocol/index.js";
+export interface PeerConnectionQualityMetrics {
+    rttMs?: number;
+    recentSuccessCount: number;
+    recentFailureCount: number;
+    lastConnectedAt?: number;
+}
+export interface PeerCandidateInput {
+    presence: PeerPresence;
+    spaceMember: boolean;
+    revoked?: boolean;
+    hasHealthyActiveConnection: boolean;
+    quality?: PeerConnectionQualityMetrics;
+}
+export interface PeerSelectionQuery {
+    spaceId: string;
+    requiredPermissions: PermissionScope[];
+    requiredCapabilities: string[];
+    preferredDeviceId?: string;
+    requireOnline?: boolean;
+}
+export interface PeerScoreBreakdown {
+    deviceId: string;
+    totalScore: number;
+    preferredDeviceBonus: number;
+    healthyConnectionBonus: number;
+    qualityScore: number;
+    reasons: string[];
+}
+export interface PeerRejectionReason {
+    deviceId: string;
+    code: "REVOKED" | "NOT_SPACE_MEMBER" | "MISSING_PERMISSION" | "MISSING_CAPABILITY" | "OFFLINE";
+    detail: string;
+}
+export interface PeerSelectionDecision {
+    spaceId: string;
+    selectedDeviceId: string | null;
+    selectedPermissions: PermissionScope[];
+    explanation: string;
+    hysteresisApplied: boolean;
+    switchedFromDeviceId: string | null;
+    rankedCandidates: PeerScoreBreakdown[];
+    rejectedCandidates: PeerRejectionReason[];
+    evaluatedAt: number;
+}
+export interface SmartPeerSelectorOptions {
+    /** Minimum score improvement required to switch away from an eligible active selection */
+    hysteresisDelta?: number;
+    /** Minimum cooldown period (ms) before switching between eligible peers */
+    switchCooldownMs?: number;
+    now?: () => number;
+}
+/**
+ * Deterministic policy engine for smart peer selection (Section 8).
+ *
+ * Security Invariants:
+ * 1. Self-declared capabilities or deviceHints (e.g. "desktop", "alwaysOnHint") are NEVER treated as authorization.
+ * 2. Verified space membership and server-authorized permissions are mandatory gates before scoring.
+ * 3. Failover/switching to an alternative peer restricts operations strictly to that peer's granted permissions.
+ */
+export declare class SmartPeerSelector {
+    private readonly hysteresisDelta;
+    private readonly switchCooldownMs;
+    private readonly now;
+    private readonly lastSelectedBySpace;
+    constructor(options?: SmartPeerSelectorOptions);
+    selectPeer(query: PeerSelectionQuery, candidates: readonly PeerCandidateInput[]): PeerSelectionDecision;
+    clearHistory(spaceId?: string): void;
+}
+//# sourceMappingURL=peer-selection.d.ts.map

package/dist/client/peer-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-selection.d.ts","sourceRoot":"","sources":["../../src/client/peer-selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0BAA0B,EAAE,OAAO,CAAC;IACpC,OAAO,CAAC,EAAE,4BAA4B,CAAC;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,eAAe,EAAE,CAAC;IACvC,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EACA,SAAS,GACT,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,SAAS,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mBAAmB,EAAE,eAAe,EAAE,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,0FAA0F;IAC1F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAGhC;gBAEQ,OAAO,GAAE,wBAA6B;IAM3C,UAAU,CACf,KAAK,EAAE,kBAAkB,EACzB,UAAU,EAAE,SAAS,kBAAkB,EAAE,GACxC,qBAAqB;IA+LjB,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;CAO5C"}

package/dist/client/peer-selection.js

@@ -0,0 +1,193 @@
+/**
+ * Deterministic policy engine for smart peer selection (Section 8).
+ *
+ * Security Invariants:
+ * 1. Self-declared capabilities or deviceHints (e.g. "desktop", "alwaysOnHint") are NEVER treated as authorization.
+ * 2. Verified space membership and server-authorized permissions are mandatory gates before scoring.
+ * 3. Failover/switching to an alternative peer restricts operations strictly to that peer's granted permissions.
+ */
+export class SmartPeerSelector {
+    hysteresisDelta;
+    switchCooldownMs;
+    now;
+    lastSelectedBySpace = new Map();
+    constructor(options = {}) {
+        this.hysteresisDelta = options.hysteresisDelta ?? 25;
+        this.switchCooldownMs = options.switchCooldownMs ?? 10_000;
+        this.now = options.now ?? (() => Date.now());
+    }
+    selectPeer(query, candidates) {
+        const nowMs = this.now();
+        const requireOnline = query.requireOnline ?? true;
+        const ranked = [];
+        const rejected = [];
+        for (let i = 0; i < candidates.length; i++) {
+            const candidate = candidates[i];
+            const { presence } = candidate;
+            // 1. Revocation & Space membership gate
+            if (candidate.revoked) {
+                rejected.push({
+                    deviceId: presence.deviceId,
+                    code: "REVOKED",
+                    detail: "Device access has been revoked",
+                });
+                continue;
+            }
+            if (!candidate.spaceMember) {
+                rejected.push({
+                    deviceId: presence.deviceId,
+                    code: "NOT_SPACE_MEMBER",
+                    detail: `Device is not an authorized member of space '${query.spaceId}'`,
+                });
+                continue;
+            }
+            // 2. Permission gate (Capability != Permission; must check server-verified permissions)
+            const grantedSet = new Set(presence.permissions);
+            const missingPermission = query.requiredPermissions.find((p) => !grantedSet.has(p));
+            if (missingPermission) {
+                rejected.push({
+                    deviceId: presence.deviceId,
+                    code: "MISSING_PERMISSION",
+                    detail: `Missing required permission '${missingPermission}'`,
+                });
+                continue;
+            }
+            // 3. Capability gate
+            const capSet = new Set(presence.capabilities);
+            const missingCapability = query.requiredCapabilities.find((c) => !capSet.has(c));
+            if (missingCapability) {
+                rejected.push({
+                    deviceId: presence.deviceId,
+                    code: "MISSING_CAPABILITY",
+                    detail: `Peer does not advertise capability '${missingCapability}'`,
+                });
+                continue;
+            }
+            // 4. Online / reachable gate
+            if (requireOnline && !presence.online) {
+                rejected.push({
+                    deviceId: presence.deviceId,
+                    code: "OFFLINE",
+                    detail: "Peer is currently offline",
+                });
+                continue;
+            }
+            // Eligible candidate scoring (deterministic)
+            const reasons = [
+                `Authorized in space '${query.spaceId}' with permissions [${query.requiredPermissions.join(", ")}]`,
+            ];
+            let preferredDeviceBonus = 0;
+            if (query.preferredDeviceId && presence.deviceId === query.preferredDeviceId) {
+                preferredDeviceBonus = 100;
+                reasons.push("Matches user-preferred device (+100)");
+            }
+            let healthyConnectionBonus = 0;
+            if (candidate.hasHealthyActiveConnection) {
+                healthyConnectionBonus = 60;
+                reasons.push("Has existing healthy WebRTC connection (+60)");
+            }
+            let qualityScore = 0;
+            if (candidate.quality) {
+                const { rttMs, recentSuccessCount, recentFailureCount } = candidate.quality;
+                if (typeof rttMs === "number" && Number.isFinite(rttMs) && rttMs >= 0) {
+                    // Up to +25 points for low latency
+                    const rttPoints = Math.max(0, Math.round(25 - Math.min(250, rttMs) / 10));
+                    qualityScore += rttPoints;
+                    reasons.push(`RTT ${Math.round(rttMs)}ms (+${rttPoints})`);
+                }
+                const reliabilityPoints = Math.max(-30, Math.min(20, recentSuccessCount * 4 - recentFailureCount * 10));
+                if (reliabilityPoints !== 0) {
+                    qualityScore += reliabilityPoints;
+                    reasons.push(`Historical reliability (${recentSuccessCount} ok / ${recentFailureCount} fail: ${reliabilityPoints >= 0 ? "+" : ""}${reliabilityPoints})`);
+                }
+            }
+            const totalScore = 100 + preferredDeviceBonus + healthyConnectionBonus + qualityScore;
+            ranked.push({
+                deviceId: presence.deviceId,
+                totalScore,
+                preferredDeviceBonus,
+                healthyConnectionBonus,
+                qualityScore,
+                reasons,
+            });
+        }
+        // Deterministic sort: highest totalScore first; tie-break by lexicographical deviceId ascending
+        ranked.sort((a, b) => {
+            if (b.totalScore !== a.totalScore) {
+                return b.totalScore - a.totalScore;
+            }
+            return a.deviceId.localeCompare(b.deviceId);
+        });
+        if (ranked.length === 0) {
+            return {
+                spaceId: query.spaceId,
+                selectedDeviceId: null,
+                selectedPermissions: [],
+                explanation: "No eligible peer met space membership, permission, capability, and reachability criteria",
+                hysteresisApplied: false,
+                switchedFromDeviceId: null,
+                rankedCandidates: [],
+                rejectedCandidates: rejected,
+                evaluatedAt: nowMs,
+            };
+        }
+        const topCandidate = ranked[0];
+        const prev = this.lastSelectedBySpace.get(query.spaceId);
+        let chosen = topCandidate;
+        let hysteresisApplied = false;
+        let switchedFromDeviceId = null;
+        if (prev && prev.deviceId !== topCandidate.deviceId) {
+            const prevStillEligible = ranked.find((r) => r.deviceId === prev.deviceId);
+            if (prevStillEligible) {
+                const scoreDiff = topCandidate.totalScore - prevStillEligible.totalScore;
+                const withinCooldown = nowMs - prev.selectedAt < this.switchCooldownMs;
+                // Do not flip-flop unless user explicitly changed preferredDeviceId to the new top candidate
+                const isExplicitUserPreference = query.preferredDeviceId === topCandidate.deviceId;
+                if (!isExplicitUserPreference &&
+                    (scoreDiff < this.hysteresisDelta || withinCooldown)) {
+                    chosen = prevStillEligible;
+                    hysteresisApplied = true;
+                }
+                else {
+                    switchedFromDeviceId = prev.deviceId;
+                }
+            }
+            else {
+                switchedFromDeviceId = prev.deviceId;
+            }
+        }
+        if (!hysteresisApplied) {
+            this.lastSelectedBySpace.set(query.spaceId, {
+                deviceId: chosen.deviceId,
+                score: chosen.totalScore,
+                selectedAt: nowMs,
+            });
+        }
+        const chosenInput = candidates.find((c) => c.presence.deviceId === chosen.deviceId);
+        // Never expand permissions beyond what the selected peer actually holds
+        const selectedPermissions = [...chosenInput.presence.permissions];
+        const explanation = hysteresisApplied
+            ? `Retained active peer '${chosen.deviceId}' (score ${chosen.totalScore}) due to hysteresis/cooldown over '${topCandidate.deviceId}' (score ${topCandidate.totalScore})`
+            : `Selected peer '${chosen.deviceId}' (score ${chosen.totalScore}): ${chosen.reasons.join("; ")}`;
+        return {
+            spaceId: query.spaceId,
+            selectedDeviceId: chosen.deviceId,
+            selectedPermissions,
+            explanation,
+            hysteresisApplied,
+            switchedFromDeviceId,
+            rankedCandidates: ranked,
+            rejectedCandidates: rejected,
+            evaluatedAt: nowMs,
+        };
+    }
+    clearHistory(spaceId) {
+        if (spaceId) {
+            this.lastSelectedBySpace.delete(spaceId);
+        }
+        else {
+            this.lastSelectedBySpace.clear();
+        }
+    }
+}
+//# sourceMappingURL=peer-selection.js.map

package/dist/client/peer-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-selection.js","sourceRoot":"","sources":["../../src/client/peer-selection.ts"],"names":[],"mappings":"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"}

package/dist/client/storage.d.ts

@@ -0,0 +1,118 @@
+export type StorageErrorCode = "QUOTA_EXCEEDED" | "PERMISSION_DENIED" | "NOT_SUPPORTED" | "NOT_FOUND" | "PATH_TRAVERSAL_BLOCKED" | "OVERWRITE_BLOCKED" | "IO_ERROR";
+export declare class DropspaceStorageError extends Error {
+    readonly code: StorageErrorCode;
+    readonly causeError?: unknown | undefined;
+    constructor(message: string, code: StorageErrorCode, causeError?: unknown | undefined);
+}
+export interface StorageCapabilities {
+    indexedDb: boolean;
+    opfs: boolean;
+    fileSystemAccess: boolean;
+    storageEstimate: boolean;
+    persistentStorageRequest: boolean;
+}
+export interface StorageQuotaInfo {
+    usageBytes: number;
+    quotaBytes: number;
+    usageRatio: number;
+    persisted: boolean | null;
+    supported: boolean;
+}
+/**
+ * Runtime feature detection for browser storage APIs.
+ * Never accesses browser globals at module import time (SSR safe).
+ */
+export declare function detectStorageCapabilities(): StorageCapabilities;
+export declare function getStorageQuotaEstimate(): Promise<StorageQuotaInfo>;
+export declare function requestPersistentStorage(): Promise<boolean>;
+export declare function normalizeStorageError(err: unknown): DropspaceStorageError;
+/**
+ * Sanitizes an untrusted remote filename to prevent path traversal, null bytes,
+ * reserved OS device names, and hidden dot-files.
+ */
+export declare function sanitizeFileName(rawName: string): string;
+export interface BinaryStagingStorageAdapter {
+    readonly kind: "opfs" | "indexeddb" | "memory";
+    writeChunk(transferId: string, chunkIndex: number, data: Uint8Array): Promise<void>;
+    readChunk(transferId: string, chunkIndex: number): Promise<Uint8Array | null>;
+    listWrittenChunks(transferId: string): Promise<number[]>;
+    finalizeTransfer(transferId: string, safeFileName: string, totalChunks: number, options?: {
+        allowOverwrite?: boolean;
+    }): Promise<{
+        finalKey: string;
+        byteLength: number;
+    }>;
+    readCompletedFile(finalKey: string): Promise<Uint8Array | null>;
+    deleteTransferStaging(transferId: string): Promise<void>;
+    exportBackup(): Promise<Record<string, string>>;
+    importBackup(snapshot: Record<string, string>): Promise<void>;
+}
+/**
+ * In-memory staging & file storage adapter with configurable quota limit (for deterministic quota testing and SSR).
+ */
+export declare class InMemoryBinaryStagingAdapter implements BinaryStagingStorageAdapter {
+    private maxQuotaBytes;
+    readonly kind: "memory";
+    private readonly stagingChunks;
+    private readonly completedFiles;
+    private currentBytes;
+    constructor(maxQuotaBytes?: number);
+    setMaxQuotaBytes(bytes: number): void;
+    getUsedBytes(): number;
+    writeChunk(transferId: string, chunkIndex: number, data: Uint8Array): Promise<void>;
+    readChunk(transferId: string, chunkIndex: number): Promise<Uint8Array | null>;
+    listWrittenChunks(transferId: string): Promise<number[]>;
+    finalizeTransfer(transferId: string, rawFileName: string, totalChunks: number, options?: {
+        allowOverwrite?: boolean;
+    }): Promise<{
+        finalKey: string;
+        byteLength: number;
+    }>;
+    readCompletedFile(finalKey: string): Promise<Uint8Array | null>;
+    deleteTransferStaging(transferId: string): Promise<void>;
+    exportBackup(): Promise<Record<string, string>>;
+    importBackup(snapshot: Record<string, string>): Promise<void>;
+}
+/**
+ * Origin Private File System (OPFS) adapter for large binary staging and completed files.
+ * Keeps incomplete transfers in `.staging/<transferId>/chunk_<idx>.part` and promotes to `completed/<safeFileName>`.
+ */
+export declare class OpfsBinaryStagingAdapter implements BinaryStagingStorageAdapter {
+    readonly kind: "opfs";
+    private getRootDir;
+    private getTransferStagingDir;
+    private getCompletedDir;
+    writeChunk(transferId: string, chunkIndex: number, data: Uint8Array): Promise<void>;
+    readChunk(transferId: string, chunkIndex: number): Promise<Uint8Array | null>;
+    listWrittenChunks(transferId: string): Promise<number[]>;
+    finalizeTransfer(transferId: string, rawFileName: string, totalChunks: number, options?: {
+        allowOverwrite?: boolean;
+    }): Promise<{
+        finalKey: string;
+        byteLength: number;
+    }>;
+    readCompletedFile(finalKey: string): Promise<Uint8Array | null>;
+    deleteTransferStaging(transferId: string): Promise<void>;
+    exportBackup(): Promise<Record<string, string>>;
+    importBackup(snapshot: Record<string, string>): Promise<void>;
+}
+/**
+ * Real user directory adapter using File System Access API (`FileSystemDirectoryHandle`),
+ * strictly distinct from Origin-Private Storage (OPFS).
+ * Handles permission re-prompting on stored handles and download fallback when unsupported.
+ */
+export declare class UserDirectoryStorageAdapter {
+    private directoryHandle;
+    constructor(directoryHandle?: FileSystemDirectoryHandle | null);
+    setDirectoryHandle(handle: FileSystemDirectoryHandle): void;
+    getDirectoryHandle(): FileSystemDirectoryHandle | null;
+    verifyOrRequestPermission(mode?: "read" | "readwrite"): Promise<boolean>;
+    saveFileToUserDirectory(rawFileName: string, content: Uint8Array, options?: {
+        allowOverwrite?: boolean;
+    }): Promise<void>;
+    /**
+     * Browser download fallback when File System Access API is unavailable.
+     */
+    triggerBrowserDownloadFallback(rawFileName: string, content: Uint8Array, mimeType?: string): void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/client/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/client/storage.ts"],"names":[],"mappings":"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"}