@peers-app/peers-sdk 0.30.0 → 0.30.1

package/dist/data/files/chunk-store.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Where a device keeps file chunks, by hash. Each host supplies one store per account
+ * ({@link setChunkStore}): an encrypted SQLite database on Node hosts, IndexedDB in the browser.
+ * Chunks are deduplicated across the account's contexts: a chunk three groups list is stored once.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryChunkStore = exports.CHUNK_LIST_PAGE = void 0;
+exports.setChunkStore = setChunkStore;
+exports.getChunkStore = getChunkStore;
+exports.setChunkDownloader = setChunkDownloader;
+exports.downloadChunk = downloadChunk;
+exports.resetChunkStore = resetChunkStore;
+/** Most chunks one {@link ChunkStore.list} page returns by default. */
+exports.CHUNK_LIST_PAGE = 1000;
+/** A {@link ChunkStore} in memory, for tests and ephemeral hosts. */
+class MemoryChunkStore {
+    now;
+    chunks = new Map();
+    /** @param now - The clock `storedAt` comes from. */
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    async has(hash) {
+        return this.chunks.has(hash);
+    }
+    async get(hash) {
+        return this.chunks.get(hash)?.bytes;
+    }
+    async put(hash, bytes) {
+        const stored = this.chunks.get(hash);
+        this.chunks.set(hash, { bytes: stored?.bytes ?? new Uint8Array(bytes), storedAt: this.now() });
+    }
+    async delete(hashes, storedBefore) {
+        let deleted = 0;
+        for (const hash of hashes) {
+            const stored = this.chunks.get(hash);
+            if (stored && stored.storedAt < storedBefore) {
+                this.chunks.delete(hash);
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+    async list(opts) {
+        const limit = opts?.limit ?? exports.CHUNK_LIST_PAGE;
+        return [...this.chunks.keys()]
+            .filter((hash) => opts?.after === undefined || hash > opts.after)
+            .sort()
+            .slice(0, limit)
+            .map((hash) => {
+            const { bytes, storedAt } = this.chunks.get(hash);
+            return { hash, size: bytes.length, storedAt };
+        });
+    }
+    async stats() {
+        let bytes = 0;
+        for (const chunk of this.chunks.values())
+            bytes += chunk.bytes.length;
+        return { count: this.chunks.size, bytes };
+    }
+}
+exports.MemoryChunkStore = MemoryChunkStore;
+let chunkStore = null;
+let chunkStoreWaiters = [];
+/**
+ * Set this process's chunk store. Reads and writes waiting for one continue.
+ *
+ * @param store - The account's chunk store.
+ */
+function setChunkStore(store) {
+    chunkStore = store;
+    const waiters = chunkStoreWaiters;
+    chunkStoreWaiters = [];
+    for (const resolve of waiters)
+        resolve(store);
+}
+/** This process's chunk store, once {@link setChunkStore} has set it. */
+function getChunkStore() {
+    if (chunkStore)
+        return Promise.resolve(chunkStore);
+    return new Promise((resolve) => chunkStoreWaiters.push(resolve));
+}
+let chunkDownloader = null;
+/**
+ * Set how chunks this device lacks are fetched. peers-device installs the connection manager's.
+ *
+ * @param downloader - The downloader, or null for none.
+ */
+function setChunkDownloader(downloader) {
+    chunkDownloader = downloader;
+}
+/**
+ * Fetch a chunk this device lacks from a connected device; the downloader stores it.
+ *
+ * @param hash - The chunk's hash.
+ * @returns The bytes, or null when no device has it or there's no downloader.
+ */
+async function downloadChunk(hash) {
+    return chunkDownloader ? chunkDownloader(hash) : null;
+}
+/** Forget the chunk store and downloader (for tests). */
+function resetChunkStore() {
+    chunkStore = null;
+    chunkStoreWaiters = [];
+    chunkDownloader = null;
+}

package/dist/data/files/file-read-stream.d.ts

@@ -1,8 +1,11 @@
 import { type IFile } from "./file.types";
-import type { FilesTable } from "./files";
+/**
+ * Reads one file's bytes chunk by chunk, from this device's chunks or, for a chunk it lacks, from
+ * a connected device. Each chunk is checked against its hash unless verification is skipped.
+ * Open one with {@link FilesTable.openReadStream}.
+ */
 export declare class FileReadStream {
     private fileRecord;
-    private fileTable;
     private preloadChunksCount;
     private skipVerification;
     private chunkHashes;
@@ -12,17 +15,43 @@ export declare class FileReadStream {
     private positionInChunk;
     private totalPosition;
     private eof;
-    constructor(fileRecord: IFile, fileTable: FilesTable, preloadChunksCount?: number, skipVerification?: boolean);
+    /**
+     * @param fileRecord - The file's row.
+     * @param preloadChunksCount - Chunks to fetch ahead of the reader, counting the current one.
+     * @param skipVerification - Skip hash checks (only for trusted local data).
+     */
+    constructor(fileRecord: IFile, preloadChunksCount?: number, skipVerification?: boolean);
     private loadChunkHashes;
     private loadChunkByIndex;
     private preloadChunks;
     private loadCurrentChunk;
+    /**
+     * Read the next bytes.
+     *
+     * @param size - Most bytes to read; one chunk's worth when omitted.
+     * @returns The bytes, or null at the end of the file.
+     */
     read(size?: number): Promise<Uint8Array | null>;
+    /**
+     * Move to a byte position; the next read starts there.
+     *
+     * @param position - From 0 to the file's size.
+     */
     seek(position: number): Promise<void>;
+    /** A copy of the file's row. */
     getMetadata(): IFile;
+    /** The byte position the next read starts at. */
     getPosition(): number;
+    /** The whole file's size in bytes. */
     getFileSize(): number;
+    /** Whether the stream is at the end of the file. */
     isEOF(): boolean;
+    /** Bytes between the position and the end of the file. */
     getBytesRemaining(): number;
+    /**
+     * Read the whole file from the start.
+     *
+     * @returns The bytes, or null when a chunk is missing everywhere or fails its hash check.
+     */
     readAll(): Promise<Uint8Array | null>;
 }

package/dist/data/files/file-read-stream.js

@@ -2,10 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileReadStream = void 0;
 const keys_1 = require("../../keys");
+const chunk_store_1 = require("./chunk-store");
 const file_types_1 = require("./file.types");
+/**
+ * Reads one file's bytes chunk by chunk, from this device's chunks or, for a chunk it lacks, from
+ * a connected device. Each chunk is checked against its hash unless verification is skipped.
+ * Open one with {@link FilesTable.openReadStream}.
+ */
 class FileReadStream {
     fileRecord;
-    fileTable;
     preloadChunksCount;
     skipVerification;
     chunkHashes = null;
@@ -15,9 +20,13 @@ class FileReadStream {
     positionInChunk = 0;
     totalPosition = 0;
     eof = false;
-    constructor(fileRecord, fileTable, preloadChunksCount = 2, skipVerification = false) {
+    /**
+     * @param fileRecord - The file's row.
+     * @param preloadChunksCount - Chunks to fetch ahead of the reader, counting the current one.
+     * @param skipVerification - Skip hash checks (only for trusted local data).
+     */
+    constructor(fileRecord, preloadChunksCount = 2, skipVerification = false) {
         this.fileRecord = fileRecord;
-        this.fileTable = fileTable;
         this.preloadChunksCount = preloadChunksCount;
         this.skipVerification = skipVerification;
     }
@@ -25,24 +34,19 @@ class FileReadStream {
         if (this.chunkHashes !== null) {
             return; // Already loaded
         }
-        if (this.fileRecord.chunkHashes) {
-            // Small file: chunk hashes stored directly in database
-            this.chunkHashes = this.fileRecord.chunkHashes;
-        }
-        else if (this.fileRecord.indexFileId) {
-            // Large file: chunk hashes stored in separate index file (recursively)
-            this.chunkHashes = await this.fileTable.loadChunkHashesRecursively(this.fileRecord.indexFileId);
-        }
-        else {
-            throw new Error(`File ${this.fileRecord.fileId} has neither chunkHashes nor indexFileId`);
+        const chunkHashes = this.fileRecord.chunkHashes ?? [];
+        if (chunkHashes.length === 0 && this.fileRecord.fileSize > 0) {
+            // Older builds kept a file over 1,000 chunks in index files, which are no longer read.
+            throw new Error(`File ${this.fileRecord.fileId} has no chunk list`);
         }
         if (!this.skipVerification) {
-            const computedFileHash = (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(this.chunkHashes)));
+            const computedFileHash = (0, file_types_1.fileHashOf)(chunkHashes);
             if (computedFileHash !== this.fileRecord.fileHash) {
                 throw new Error(`File integrity check failed for ${this.fileRecord.fileId}: ` +
                     `chunk hashes produce ${computedFileHash}, expected ${this.fileRecord.fileHash}`);
             }
         }
+        this.chunkHashes = chunkHashes;
     }
     async loadChunkByIndex(chunkIndex) {
         await this.loadChunkHashes();
@@ -51,19 +55,11 @@ class FileReadStream {
             throw new Error(`Chunk index ${chunkIndex} out of bounds`);
         }
         const chunkHash = chunkHashes[chunkIndex];
-        const ops = await (0, file_types_1.getFileOps)();
-        const chunkPath = `${file_types_1.CHUNKS_DIR}/${chunkHash}`;
-        let chunk;
-        if (await ops.fileExists(chunkPath)) {
-            // Read from local storage
-            chunk = await ops.readFile(chunkPath);
-        }
-        else {
-            // Download from peer by hash
-            chunk = (await ops.downloadFileChunk(chunkHash));
-            if (!chunk) {
-                throw new Error(`Chunk ${chunkHash} not found in storage or peers`);
-            }
+        const store = await (0, chunk_store_1.getChunkStore)();
+        // Stored here, or downloaded from a connected device (which stores it).
+        const chunk = (await store.get(chunkHash)) ?? (await (0, chunk_store_1.downloadChunk)(chunkHash));
+        if (!chunk) {
+            throw new Error(`Chunk ${chunkHash} not found in storage or peers`);
         }
         // Verify chunk integrity (skip for trusted local reads)
         if (!this.skipVerification) {
@@ -109,6 +105,12 @@ class FileReadStream {
         this.currentChunkBuffer = await chunkPromise;
         this.chunkPromises.delete(this.currentChunkIndex);
     }
+    /**
+     * Read the next bytes.
+     *
+     * @param size - Most bytes to read; one chunk's worth when omitted.
+     * @returns The bytes, or null at the end of the file.
+     */
     async read(size) {
         if (this.eof) {
             return null;
@@ -146,6 +148,11 @@ class FileReadStream {
         await this.preloadChunks();
         return chunks.length > 0 ? new Uint8Array(Buffer.concat(chunks)) : null;
     }
+    /**
+     * Move to a byte position; the next read starts there.
+     *
+     * @param position - From 0 to the file's size.
+     */
     async seek(position) {
         if (position < 0) {
             throw new Error("Seek position cannot be negative");
@@ -167,22 +174,31 @@ class FileReadStream {
         this.chunkPromises.clear();
         await this.preloadChunks();
     }
+    /** A copy of the file's row. */
     getMetadata() {
         return { ...this.fileRecord };
     }
+    /** The byte position the next read starts at. */
     getPosition() {
         return this.totalPosition;
     }
+    /** The whole file's size in bytes. */
     getFileSize() {
         return this.fileRecord.fileSize;
     }
+    /** Whether the stream is at the end of the file. */
     isEOF() {
         return this.eof;
     }
+    /** Bytes between the position and the end of the file. */
     getBytesRemaining() {
         return this.fileRecord.fileSize - this.totalPosition;
     }
-    // Read the entire file (for compatibility with existing getFile API)
+    /**
+     * Read the whole file from the start.
+     *
+     * @returns The bytes, or null when a chunk is missing everywhere or fails its hash check.
+     */
     async readAll() {
         await this.seek(0); // Start from beginning
         const chunks = [];
@@ -199,7 +215,6 @@ class FileReadStream {
         }
         catch (error) {
             // Only return null for chunk-specific errors (not found, download failed)
-            // Rethrow other errors like index file issues
             if (error instanceof Error &&
                 error.message.includes("Chunk") &&
                 (error.message.includes("not found") || error.message.includes("integrity check failed"))) {

package/dist/data/files/file-rows.d.ts

@@ -0,0 +1,68 @@
+import { type IFile } from "./file.types";
+/** What a file's id is derived from. */
+export interface IFileIdentity {
+    fileHash: string;
+    fileSize: number;
+    name: string;
+    /** Empty when unknown; omitted counts as empty. */
+    mimeType?: string;
+    keep: boolean;
+}
+/**
+ * The id of a file: derived from its hash, size, name, MIME type and `keep`, so saving the same
+ * content with the same description gives the same file on every device. Give the name and MIME
+ * type as storage keeps them (`FileWriteStream` normalizes them), or other devices, which
+ * rederive the id from the stored row, refuse it.
+ *
+ * @param file - The file's hash, size, name, MIME type and `keep`.
+ */
+export declare function fileIdFor(file: IFileIdentity): string;
+/**
+ * Whether a row is a legacy file: one saved under a random id, before ids were derived from
+ * content. Legacy rows are admitted as they are, never change, and are always kept.
+ *
+ * @param fileId - The row's id.
+ */
+export declare function isLegacyFileId(fileId: string): boolean;
+/**
+ * Whether a legacy row is a package bundle the installer saved. The runtime owns these, so they
+ * are collected once nothing references them, and their rows may be deleted.
+ *
+ * @param file - The row's id and name.
+ */
+export declare function isLegacyBundleFile(file: Pick<IFile, "fileId" | "name">): boolean;
+/**
+ * Whether a file is kept: never collected, even with nothing referencing it. A legacy row always
+ * is. A row relayed by a build that predates `keep` arrives without it; its id, derived from
+ * `keep`, then decides, and a row whose id says neither is kept.
+ *
+ * @param file - The row.
+ */
+export declare function isKeptFile(file: IFile): boolean;
+/**
+ * Whether two rows describe the same file, ignoring how an older build stored it (no `keep`, no
+ * MIME type).
+ *
+ * @param a - One row.
+ * @param b - The other.
+ */
+export declare function isSameFile(a: IFile, b: IFile): boolean;
+/**
+ * Why `file` can't be stored as a new row under `recordId`, or undefined when it can. A legacy
+ * row needs only a size within the limit. Any other must have its derived id, a chunk list of
+ * well-formed hashes, one per started MiB, and the `fileHash` of that list.
+ *
+ * @param file - The candidate row.
+ * @param recordId - The record id it's written under.
+ */
+export declare function fileRowProblem(file: IFile, recordId: string): string | undefined;
+/**
+ * The `Files` write check: a new row must pass {@link fileRowProblem}; a stored row never
+ * changes (rewriting the same file is allowed); and only a legacy bundle row may be deleted.
+ *
+ * @param existing - The row as stored, if any.
+ * @param candidate - The row to store, or undefined for a delete.
+ * @param recordId - The record written.
+ * @throws A {@link writeNotAuthorized} refusal.
+ */
+export declare function checkFileWrite(existing: IFile | undefined, candidate: IFile | undefined, recordId: string): void;

package/dist/data/files/file-rows.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileIdFor = fileIdFor;
+exports.isLegacyFileId = isLegacyFileId;
+exports.isLegacyBundleFile = isLegacyBundleFile;
+exports.isKeptFile = isKeptFile;
+exports.isSameFile = isSameFile;
+exports.fileRowProblem = fileRowProblem;
+exports.checkFileWrite = checkFileWrite;
+/**
+ * The rules every `Files` row meets, on every device: ids derived from the content, rows that
+ * never change, and deletes only of runtime-owned legacy bundle rows. Each device checks an
+ * incoming row in full, so no member can put other content under a file's id.
+ */
+const derived_row_id_1 = require("../derived-row-id");
+const write_checks_1 = require("../orm/write-checks");
+const file_types_1 = require("./file.types");
+/** A chunk hash: SHA-256 as unpadded base64url. */
+const CHUNK_HASH = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * Names the package installer gives bundle files: `<packageId>-<kind>.bundle.js`, and the older
+ * `<name>.<kind>.<packageId>.js`.
+ */
+const BUNDLE_FILE_NAME = /^[0-9a-z]{25}-(package|routes|uis)\.bundle\.js$|^.+\.(package|routes|uis)\.[0-9a-z]{25}\.js$/;
+/**
+ * The id of a file: derived from its hash, size, name, MIME type and `keep`, so saving the same
+ * content with the same description gives the same file on every device. Give the name and MIME
+ * type as storage keeps them (`FileWriteStream` normalizes them), or other devices, which
+ * rederive the id from the stored row, refuse it.
+ *
+ * @param file - The file's hash, size, name, MIME type and `keep`.
+ */
+function fileIdFor(file) {
+    return (0, derived_row_id_1.derivedRowId)("Files", [
+        file.fileHash,
+        file.fileSize,
+        file.name,
+        file.mimeType ?? "",
+        file.keep,
+    ]);
+}
+/**
+ * Whether a row is a legacy file: one saved under a random id, before ids were derived from
+ * content. Legacy rows are admitted as they are, never change, and are always kept.
+ *
+ * @param fileId - The row's id.
+ */
+function isLegacyFileId(fileId) {
+    return !(0, derived_row_id_1.isDerivedRowId)(fileId);
+}
+/**
+ * Whether a legacy row is a package bundle the installer saved. The runtime owns these, so they
+ * are collected once nothing references them, and their rows may be deleted.
+ *
+ * @param file - The row's id and name.
+ */
+function isLegacyBundleFile(file) {
+    return isLegacyFileId(file.fileId) && BUNDLE_FILE_NAME.test(file.name);
+}
+/**
+ * Whether a file is kept: never collected, even with nothing referencing it. A legacy row always
+ * is. A row relayed by a build that predates `keep` arrives without it; its id, derived from
+ * `keep`, then decides, and a row whose id says neither is kept.
+ *
+ * @param file - The row.
+ */
+function isKeptFile(file) {
+    if (isLegacyFileId(file.fileId))
+        return true;
+    if (typeof file.keep === "boolean")
+        return file.keep;
+    return fileIdFor({ ...file, keep: false }) !== file.fileId;
+}
+/**
+ * Whether two rows describe the same file, ignoring how an older build stored it (no `keep`, no
+ * MIME type).
+ *
+ * @param a - One row.
+ * @param b - The other.
+ */
+function isSameFile(a, b) {
+    return (a.fileId === b.fileId &&
+        a.name === b.name &&
+        a.fileSize === b.fileSize &&
+        a.fileHash === b.fileHash &&
+        (a.mimeType ?? "") === (b.mimeType ?? "") &&
+        isKeptFile(a) === isKeptFile(b) &&
+        JSON.stringify(a.chunkHashes ?? []) === JSON.stringify(b.chunkHashes ?? []));
+}
+/**
+ * Why `file` can't be stored as a new row under `recordId`, or undefined when it can. A legacy
+ * row needs only a size within the limit. Any other must have its derived id, a chunk list of
+ * well-formed hashes, one per started MiB, and the `fileHash` of that list.
+ *
+ * @param file - The candidate row.
+ * @param recordId - The record id it's written under.
+ */
+function fileRowProblem(file, recordId) {
+    if (file.fileId !== recordId)
+        return "the row's id isn't its record id";
+    if (!Number.isSafeInteger(file.fileSize) || file.fileSize < 0) {
+        return "its size isn't a whole number of bytes";
+    }
+    if (file.fileSize > file_types_1.FILE_MAX_SIZE) {
+        return `it's over the ${file_types_1.FILE_MAX_SIZE / (1024 * 1024)} MiB limit`;
+    }
+    if (isLegacyFileId(file.fileId))
+        return undefined;
+    if (typeof file.name !== "string")
+        return "its name isn't text";
+    // Storage may return an absent value as null.
+    if (file.mimeType != null && typeof file.mimeType !== "string") {
+        return "its MIME type isn't text";
+    }
+    if (file.keep != null && typeof file.keep !== "boolean")
+        return "keep isn't a boolean";
+    const chunkHashes = file.chunkHashes ?? [];
+    if (!Array.isArray(chunkHashes) ||
+        !chunkHashes.every((hash) => typeof hash === "string" && CHUNK_HASH.test(hash))) {
+        return "its chunk list isn't a list of chunk hashes";
+    }
+    if (chunkHashes.length !== Math.ceil(file.fileSize / file_types_1.FILE_CHUNK_SIZE)) {
+        return "its chunk count doesn't match its size";
+    }
+    if (file.fileHash !== (0, file_types_1.fileHashOf)(chunkHashes))
+        return "its hash doesn't match its chunk list";
+    // A build that predates `keep` relays the row without it.
+    const keeps = typeof file.keep === "boolean" ? [file.keep] : [false, true];
+    if (!keeps.some((keep) => fileIdFor({ ...file, keep }) === file.fileId)) {
+        return "its id isn't derived from its content";
+    }
+    return undefined;
+}
+/**
+ * The `Files` write check: a new row must pass {@link fileRowProblem}; a stored row never
+ * changes (rewriting the same file is allowed); and only a legacy bundle row may be deleted.
+ *
+ * @param existing - The row as stored, if any.
+ * @param candidate - The row to store, or undefined for a delete.
+ * @param recordId - The record written.
+ * @throws A {@link writeNotAuthorized} refusal.
+ */
+function checkFileWrite(existing, candidate, recordId) {
+    if (!candidate) {
+        if (isLegacyFileId(recordId) && (!existing || isLegacyBundleFile(existing)))
+            return;
+        throw (0, write_checks_1.writeNotAuthorized)("Files", "a file can't be deleted");
+    }
+    if (existing) {
+        if (!isSameFile(existing, candidate))
+            throw (0, write_checks_1.writeNotAuthorized)("Files", "a file can't change");
+        return;
+    }
+    const problem = fileRowProblem(candidate, recordId);
+    if (problem)
+        throw (0, write_checks_1.writeNotAuthorized)("Files", `the file is refused: ${problem}`);
+}
+(0, write_checks_1.registerTableWriteCheck)("Files", (existing, candidate, { recordId }) => checkFileWrite(existing, candidate, recordId));

package/dist/data/files/file-write-stream.d.ts

@@ -1,5 +1,9 @@
 import { type IFile, type IFileInput } from "./file.types";
 import type { FilesTable } from "./files";
+/**
+ * Writes one file in pieces: each full chunk is stored as it arrives, and `finalize` saves the
+ * row under the id derived from the content. Open one with {@link FilesTable.createWriteStream}.
+ */
 export declare class FileWriteStream {
     private metadata;
     private fileTable;
@@ -8,13 +12,35 @@ export declare class FileWriteStream {
     private bytesWritten;
     private finalized;
     private aborted;
+    /**
+     * @param metadata - The file's name, MIME type and `keep`.
+     * @param fileTable - The Files table the row is saved to.
+     */
     constructor(metadata: IFileInput, fileTable: FilesTable);
+    /**
+     * Append bytes. Full chunks are stored as they complete.
+     *
+     * @param chunk - The next bytes, of any length.
+     * @throws When the file would exceed {@link FILE_MAX_SIZE}, or the stream has ended.
+     */
     write(chunk: Uint8Array): Promise<void>;
     private processCompleteChunks;
+    private storeChunk;
+    /**
+     * Store the last chunk and save the file's row. Saving content that already has a row (the
+     * same bytes, name, MIME type and `keep`) writes no row and returns the stored one.
+     *
+     * @returns The file's row.
+     */
     finalize(): Promise<IFile>;
+    /** Stop without saving a row. Stored chunks stay until collection frees them. */
     abort(): Promise<void>;
+    /** Bytes written so far. */
     getBytesWritten(): number;
+    /** Chunks stored so far. */
     getChunkCount(): number;
+    /** Whether `finalize` has saved the row. */
     isFinalized(): boolean;
+    /** Whether `abort` was called. */
     isAborted(): boolean;
 }