@peers-app/peers-sdk 0.18.6 → 0.19.0

package/README.md

@@ -1 +1,74 @@
-Common types, zod schemas, functions, and classes that are used internally in Peers and for building packages.  
+# @peers-app/peers-sdk
+
+The core SDK for building [Peers](https://peers.app) packages.
+
+## What is Peers?
+
+Peers is a local-first personal computing platform. Your data lives on your devices, syncs peer-to-peer, and is end-to-end encrypted — no servers in the middle. You own your data and your identity. Build apps with the SDK or use AI coding tools to create them; either way, the platform handles sync, encryption, and persistence automatically.
+
+## What this package provides
+
+### Package System
+
+`definePackage()` and the contract builder API let you declare tables, tools, assistants, screens, and navigation entries. The runtime installs, loads, and hot-reloads your package across all devices.
+
+### ORM
+
+Table definitions with Zod schemas, data queries with a Mongo-style filter syntax, and async cursors. Tables sync across devices and encrypt automatically — you just define the schema.
+
+### Observables and Persistent Variables
+
+Lightweight reactive primitives (`observable()`, `computed()`) with `.subscribe()`. Persistent variables (`deviceVar`, `userVar`, `groupVar`) are observables backed by the database — write once, subscribe everywhere, synced across devices.
+
+### Types and Schemas
+
+Zod schemas and TypeScript types for the entire Peers data model: users, groups, devices, packages, tools, assistants, workflows, messages, channels, and more.
+
+### Encryption
+
+NaCl-based key management, message signing and verification, box encryption, and deterministic hashing. Identity is a cryptographic key pair — no passwords, no email.
+
+### Tools Framework
+
+Define AI-callable tools with `ITool` and `IToolInstance`. Tools are registered at runtime and available to built-in and user-defined AI assistants and workflows.
+
+### Identity and Groups
+
+User, group, and permission management types. Group-scoped data contexts for multi-tenant data isolation. Invite flows and trust levels.
+
+## Quick Start
+
+```bash
+npm install @peers-app/peers-sdk
+```
+
+The fastest way to build a Peers package is to start from the template:
+
+**[peers-package-template](https://github.com/peers-app/peers-package-template)** — scaffold, build, and install a custom package into the Peers runtime.  This will be setup automatically when you create a new package in the desktop app.  
+
+## Key Interfaces
+
+
+| Export                               | Purpose                                                                 |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| `definePackage()`                    | Entry point for declaring a package's contracts, tools, tables, and nav |
+| `Table`                              | ORM table with CRUD, Zod validation, and `dataChanged` events           |
+| `DataQuery` / `DataFilter`           | Mongo-style query filters translated to SQL                             |
+| `observable()` / `computed()`        | Reactive state primitives                                               |
+| `deviceVar` / `userVar` / `groupVar` | Persistent variables — observables backed by the database               |
+| `ITool` / `IToolInstance`            | AI-callable tool definitions                                            |
+| `IPeersUI` / `IPeersUIRoute`         | Screen and route declarations for package UIs                           |
+| `newid()`                            | Generate 25-character time-sortable peer IDs                            |
+| `newKeys()` / `hydrateKeys()`        | Cryptographic key pair generation and hydration                         |
+| `UserContext` / `DataContext`        | Multi-group data scoping and package loading                            |
+
+
+## Links
+
+- [peers.app](https://peers.app) — try Peers in your browser or download the desktop app
+- [Documentation](https://peers-app.github.io) — architecture, package development, and API reference
+- [GitHub](https://github.com/peers-app) — source repositories and package template
+
+## License
+
+MIT

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

@@ -36,6 +36,13 @@ class FileReadStream {
         else {
             throw new Error(`File ${this.fileRecord.fileId} has neither chunkHashes nor indexFileId`);
         }
+        if (!this.skipVerification) {
+            const computedFileHash = (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(this.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}`);
+            }
+        }
     }
     async loadChunkByIndex(chunkIndex) {
         await this.loadChunkHashes();

package/dist/data/files/file.types.d.ts

@@ -35,6 +35,12 @@ export declare const FILE_CHUNK_SIZE: number;
 export declare const CHUNKS_DIR = "file_chunks";
 export declare let CHUNK_INDEX_THRESHOLD: number;
 export declare function setChunkIndexThreshold(threshold: number): void;
+/**
+ * Compute the file-system hash for content without saving it.
+ * Mirrors the chunking + hashing logic of FileWriteStream so the result
+ * matches `IFile.fileHash` for the same bytes.
+ */
+export declare function computeFileHash(content: string | Uint8Array): string;
 export interface FileOps {
     downloadFileChunk(chunkHash: string): Promise<Uint8Array | null>;
     fileExists(path: string): Promise<boolean>;

package/dist/data/files/file.types.js

@@ -2,10 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CHUNK_INDEX_THRESHOLD = exports.CHUNKS_DIR = exports.FILE_CHUNK_SIZE = exports.filesMetaData = exports.fileSchema = void 0;
 exports.setChunkIndexThreshold = setChunkIndexThreshold;
+exports.computeFileHash = computeFileHash;
 exports.setFileOps = setFileOps;
 exports.getFileOps = getFileOps;
 exports.resetFileOps = resetFileOps;
 const zod_1 = require("zod");
+const keys_1 = require("../../keys");
 const zod_types_1 = require("../../types/zod-types");
 const types_1 = require("../orm/types");
 exports.fileSchema = zod_1.z.object({
@@ -38,6 +40,22 @@ exports.CHUNK_INDEX_THRESHOLD = 1000; // Use chunk index file for files with >10
 function setChunkIndexThreshold(threshold) {
     exports.CHUNK_INDEX_THRESHOLD = threshold;
 }
+/**
+ * Compute the file-system hash for content without saving it.
+ * Mirrors the chunking + hashing logic of FileWriteStream so the result
+ * matches `IFile.fileHash` for the same bytes.
+ */
+function computeFileHash(content) {
+    const data = typeof content === "string" ? new Uint8Array(Buffer.from(content, "utf8")) : content;
+    const chunkHashes = [];
+    let offset = 0;
+    while (offset < data.length) {
+        const end = Math.min(offset + exports.FILE_CHUNK_SIZE, data.length);
+        chunkHashes.push((0, keys_1.hashBytes)(data.subarray(offset, end)));
+        offset = end;
+    }
+    return (0, keys_1.hashBytes)(new Uint8Array(Buffer.from(JSON.stringify(chunkHashes), "utf8")));
+}
 let fileOps = null;
 let fileOpsReady = null;
 function setFileOps(ops) {

package/dist/data/files/files.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const keys_1 = require("../../keys");
 const field_type_1 = require("../../types/field-type");
 const utils_1 = require("../../utils");
 const file_types_1 = require("./file.types");
@@ -201,7 +202,7 @@ describe("FileTable", () => {
             const result = await fileTable.getFileContents("non-existent");
             expect(result).toBeNull();
         });
-        it("should return null when chunk is missing", async () => {
+        it("should throw integrity error when fileHash doesn't match chunk hashes", async () => {
             const fileId = (0, utils_1.newid)();
             const metadata = {
                 fileId,
@@ -210,10 +211,9 @@ describe("FileTable", () => {
                 fileHash: "hash123",
                 chunkHashes: ["hash1", "hash2"],
             };
-            // Insert metadata directly without saving chunks
+            // Insert metadata directly with mismatched fileHash
             await fileTable.dataSource.insert(metadata);
-            const result = await fileTable.getFileContents(fileId);
-            expect(result).toBeNull();
+            await expect(fileTable.getFileContents(fileId)).rejects.toThrow("File integrity check failed");
         });
         it("should return null when chunk is missing during read", async () => {
             const result = await fileTable.getFileContents("non-existent");
@@ -674,20 +674,63 @@ describe("FileTable", () => {
             });
             it("should return null when chunk is unavailable", async () => {
                 const fileId = (0, utils_1.newid)();
+                const chunkHashes = ["missing_chunk_hash"];
+                const fileHash = (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(chunkHashes)));
                 const metadata = {
                     fileId,
                     name: "missing-chunk.txt",
                     fileSize: 50,
-                    fileHash: "hash123",
-                    chunkHashes: ["missing_chunk_hash"],
+                    fileHash,
+                    chunkHashes,
                 };
                 // Insert file metadata without storing the actual chunk
                 await fileTable.dataSource.insert(metadata);
                 // This should return null when the chunk can't be found
-                // instead of throwing an error or hanging
                 const result = await fileTable.getFileContents(fileId);
                 expect(result).toBeNull();
             });
+            it("should throw when fileHash does not match chunk hashes", async () => {
+                const fileId = (0, utils_1.newid)();
+                const data = new Uint8Array(Buffer.from("Valid content", "utf8"));
+                const metadata = {
+                    fileId,
+                    name: "tampered.txt",
+                    fileSize: data.length,
+                    mimeType: "text/plain",
+                };
+                // Save file normally to get valid chunks on disk
+                const saved = await fileTable.saveFile(metadata, data);
+                // Tamper with the fileHash in the database record
+                const tamperedRecord = {
+                    ...saved,
+                    fileHash: "tampered-hash-value",
+                };
+                await fileTable.dataSource.save(tamperedRecord);
+                // Reading should throw a file integrity error
+                await expect(fileTable.getFileContents(fileId)).rejects.toThrow("File integrity check failed");
+            });
+            it("should skip fileHash verification when skipVerification is true", async () => {
+                const fileId = (0, utils_1.newid)();
+                const data = new Uint8Array(Buffer.from("Valid content", "utf8"));
+                const metadata = {
+                    fileId,
+                    name: "skip-verify.txt",
+                    fileSize: data.length,
+                    mimeType: "text/plain",
+                };
+                // Save file normally to get valid chunks on disk
+                const saved = await fileTable.saveFile(metadata, data);
+                // Tamper with the fileHash in the database record
+                const tamperedRecord = {
+                    ...saved,
+                    fileHash: "tampered-hash-value",
+                };
+                await fileTable.dataSource.save(tamperedRecord);
+                // Reading with skipVerification should succeed
+                const result = await fileTable.getFileContents(fileId, { skipVerification: true });
+                expect(result).not.toBeNull();
+                expect(new Uint8Array(result)).toEqual(data);
+            });
         });
         describe("Round-trip streaming", () => {
             it("should write and read back identical data using streams", async () => {

package/dist/data/package-version-resolver.test.js

@@ -72,6 +72,7 @@ function makePkg(overrides = {}) {
         name: "test-package",
         description: "test",
         createdBy: testUserId,
+        publishPublicKey: "",
         signature: "",
         ...overrides,
     };

package/dist/data/package-versions.d.ts

@@ -30,6 +30,7 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }>, "many">>;
+    packageAuthorSignature: z.ZodOptional<z.ZodString>;
     history: z.ZodOptional<z.ZodArray<z.ZodObject<{
         action: z.ZodString;
         by: z.ZodString;
@@ -76,6 +77,7 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }[] | undefined;
+    packageAuthorSignature?: string | undefined;
 }, {
     version: string;
     signature: string;
@@ -103,6 +105,7 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }[] | undefined;
+    packageAuthorSignature?: string | undefined;
 }>;
 export type IPackageVersion = z.infer<typeof schema>;
 export declare class PackageVersionsTable extends Table<IPackageVersion> {

package/dist/data/package-versions.js

@@ -66,6 +66,11 @@ const schema = zod_1.z.object({
         .array()
         .optional()
         .describe("The app navigation items that this version provides"),
+    packageAuthorSignature: zod_1.z
+        .string()
+        .optional()
+        .describe("Publisher's Ed25519 detached signature over the author-signed payload. " +
+        "Enables cross-group trust verification without needing the original source."),
     history: zod_1.z
         .array(zod_1.z.object({
         action: zod_1.z.string().describe("created | promoted:beta | promoted:stable | activated"),

package/dist/data/packages.d.ts

@@ -29,6 +29,8 @@ declare const schema: z.ZodObject<{
     activePackageVersionId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     versionFollowRange: z.ZodOptional<z.ZodEnum<["pinned", "patch", "minor", "latest"]>>;
     followVersionTags: z.ZodOptional<z.ZodString>;
+    updateUrl: z.ZodOptional<z.ZodString>;
+    publishPublicKey: z.ZodString;
     signature: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     name: string;
@@ -36,6 +38,7 @@ declare const schema: z.ZodObject<{
     signature: string;
     packageId: string;
     createdBy: string;
+    publishPublicKey: string;
     disabled?: boolean | undefined;
     appNavs?: {
         name: string;
@@ -47,12 +50,14 @@ declare const schema: z.ZodObject<{
     activePackageVersionId?: string | undefined;
     versionFollowRange?: "pinned" | "patch" | "minor" | "latest" | undefined;
     followVersionTags?: string | undefined;
+    updateUrl?: string | undefined;
 }, {
     name: string;
     description: string;
     signature: string;
     packageId: string;
     createdBy: string;
+    publishPublicKey: string;
     disabled?: boolean | undefined;
     appNavs?: {
         name: string;
@@ -64,6 +69,7 @@ declare const schema: z.ZodObject<{
     activePackageVersionId?: string | undefined;
     versionFollowRange?: "pinned" | "patch" | "minor" | "latest" | undefined;
     followVersionTags?: string | undefined;
+    updateUrl?: string | undefined;
 }>;
 export type IPackage = z.infer<typeof schema>;
 export declare class PackagesTable extends Table<IPackage> {

package/dist/data/packages.js

@@ -72,6 +72,14 @@ const schema = zod_1.z.object({
         .string()
         .optional()
         .describe('Tag policy: undefined="current" (follow active tag), "*"=any tag, or CSV like "stable,prod"'),
+    updateUrl: zod_1.z
+        .string()
+        .optional()
+        .describe("Base URL for remote package seeding. Admin devices check <updateUrl>/latest-<tag>.json on startup."),
+    publishPublicKey: zod_1.z
+        .string()
+        .describe("Ed25519 public key (base64url) of the package publisher. " +
+        "Set at package creation; used as TOFU anchor for verifying packageAuthorSignature on versions."),
     signature: zod_1.z.string().describe("The signed hash of this data excluding the signature itself"),
 });
 const metaData = {

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./keys";
 export * from "./logging";
 export * from "./mentions";
 export * from "./observable";
+export * from "./package-installer";
 export * from "./package-loader";
 export * from "./peers-ui/peers-ui";
 export * from "./peers-ui/peers-ui.types";

package/dist/index.js

@@ -40,6 +40,7 @@ __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./mentions"), exports);
 __exportStar(require("./observable"), exports);
+__exportStar(require("./package-installer"), exports);
 __exportStar(require("./package-loader"), exports);
 __exportStar(require("./peers-ui/peers-ui"), exports);
 __exportStar(require("./peers-ui/peers-ui.types"), exports);

package/dist/package-installer/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./package-author-signing";
+export * from "./package-cloner";
+export * from "./package-creator";
+export * from "./package-installer";
+export * from "./package-propagation";
+export * from "./package-publisher";
+export * from "./package-remote-checker";
+export * from "./package-seed-installer";
+export * from "./package-tarball";
+export * from "./types";

package/dist/package-installer/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./package-author-signing"), exports);
+__exportStar(require("./package-cloner"), exports);
+__exportStar(require("./package-creator"), exports);
+__exportStar(require("./package-installer"), exports);
+__exportStar(require("./package-propagation"), exports);
+__exportStar(require("./package-publisher"), exports);
+__exportStar(require("./package-remote-checker"), exports);
+__exportStar(require("./package-seed-installer"), exports);
+__exportStar(require("./package-tarball"), exports);
+__exportStar(require("./types"), exports);

package/dist/package-installer/package-author-signing.d.ts

@@ -0,0 +1,48 @@
+import type { IPackageVersion } from "../data/package-versions";
+/** Prefix for the persistent variable name that stores a package's signing secret key. */
+export declare const PACKAGE_SIGNING_KEY_PREFIX = "packageSigningKey_";
+/**
+ * The subset of PackageVersion fields that the publisher signs.
+ * The `publicKey` field is included so verifiers know which key to check against.
+ */
+export interface IAuthorSignedPayload {
+    packageId: string;
+    packageVersionId: string;
+    version: string;
+    versionTag: string;
+    packageBundleFileHash: string;
+    routesBundleFileHash?: string;
+    uiBundleFileHash?: string;
+    publicKey: string;
+}
+/**
+ * Extracts the signable payload from a PackageVersion record.
+ * Only includes optional hash fields when they have a value (undefined fields are omitted
+ * entirely so `stableStringify` produces a consistent output).
+ */
+export declare function buildAuthorSignedPayload(pv: Pick<IPackageVersion, "packageId" | "packageVersionId" | "version" | "versionTag" | "packageBundleFileHash" | "routesBundleFileHash" | "uiBundleFileHash">, publicKey: string): IAuthorSignedPayload;
+/**
+ * Signs a PackageVersion with the publisher's Ed25519 secret key.
+ * @returns A base64url-encoded detached Ed25519 signature over `stableStringify(payload)`.
+ */
+export declare function signPackageAuthor(pv: Pick<IPackageVersion, "packageId" | "packageVersionId" | "version" | "versionTag" | "packageBundleFileHash" | "routesBundleFileHash" | "uiBundleFileHash">, secretKey: string): string;
+/**
+ * Result of verifying a packageAuthorSignature.
+ * `publicKey` is the key embedded in the payload (extracted from the signature verification process).
+ */
+export interface IVerifyAuthorSignatureResult {
+    valid: boolean;
+    publicKey: string;
+}
+/**
+ * Verifies the `packageAuthorSignature` on a PackageVersion record.
+ *
+ * The signature format is a raw base64url detached Ed25519 signature. The public key
+ * is NOT in the signature itself — it must be provided via `expectedPublicKey` (TOFU check)
+ * to reconstruct the payload and verify.
+ *
+ * @param pv - The PackageVersion record with `packageAuthorSignature` set
+ * @param expectedPublicKey - The public key to verify against (from Package.publishPublicKey)
+ * @returns `{ valid, publicKey }` — valid is true if signature verifies and key matches
+ */
+export declare function verifyPackageAuthorSignature(pv: Pick<IPackageVersion, "packageId" | "packageVersionId" | "version" | "versionTag" | "packageBundleFileHash" | "routesBundleFileHash" | "uiBundleFileHash" | "packageAuthorSignature">, expectedPublicKey: string): IVerifyAuthorSignatureResult;

package/dist/package-installer/package-author-signing.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_SIGNING_KEY_PREFIX = void 0;
+exports.buildAuthorSignedPayload = buildAuthorSignedPayload;
+exports.signPackageAuthor = signPackageAuthor;
+exports.verifyPackageAuthorSignature = verifyPackageAuthorSignature;
+const nacl = require("tweetnacl");
+const tweetnacl_util_1 = require("tweetnacl-util");
+const keys_1 = require("../keys");
+/** Prefix for the persistent variable name that stores a package's signing secret key. */
+exports.PACKAGE_SIGNING_KEY_PREFIX = "packageSigningKey_";
+/**
+ * Extracts the signable payload from a PackageVersion record.
+ * Only includes optional hash fields when they have a value (undefined fields are omitted
+ * entirely so `stableStringify` produces a consistent output).
+ */
+function buildAuthorSignedPayload(pv, publicKey) {
+    const payload = {
+        packageId: pv.packageId,
+        packageVersionId: pv.packageVersionId,
+        version: pv.version,
+        versionTag: pv.versionTag ?? "",
+        packageBundleFileHash: pv.packageBundleFileHash,
+        publicKey,
+    };
+    if (pv.routesBundleFileHash) {
+        payload.routesBundleFileHash = pv.routesBundleFileHash;
+    }
+    if (pv.uiBundleFileHash) {
+        payload.uiBundleFileHash = pv.uiBundleFileHash;
+    }
+    return payload;
+}
+/**
+ * Signs a PackageVersion with the publisher's Ed25519 secret key.
+ * @returns A base64url-encoded detached Ed25519 signature over `stableStringify(payload)`.
+ */
+function signPackageAuthor(pv, secretKey) {
+    const keys = (0, keys_1.hydrateKeys)(secretKey);
+    const payload = buildAuthorSignedPayload(pv, keys.publicKey);
+    const message = (0, tweetnacl_util_1.decodeUTF8)((0, keys_1.stableStringify)(payload));
+    const sk = (0, keys_1.decodeBase64)(secretKey);
+    const signature = nacl.sign.detached(message, sk);
+    return (0, keys_1.encodeBase64)(signature);
+}
+/**
+ * Verifies the `packageAuthorSignature` on a PackageVersion record.
+ *
+ * The signature format is a raw base64url detached Ed25519 signature. The public key
+ * is NOT in the signature itself — it must be provided via `expectedPublicKey` (TOFU check)
+ * to reconstruct the payload and verify.
+ *
+ * @param pv - The PackageVersion record with `packageAuthorSignature` set
+ * @param expectedPublicKey - The public key to verify against (from Package.publishPublicKey)
+ * @returns `{ valid, publicKey }` — valid is true if signature verifies and key matches
+ */
+function verifyPackageAuthorSignature(pv, expectedPublicKey) {
+    const result = { valid: false, publicKey: expectedPublicKey };
+    if (!pv.packageAuthorSignature) {
+        return result;
+    }
+    try {
+        const payload = buildAuthorSignedPayload(pv, expectedPublicKey);
+        const message = (0, tweetnacl_util_1.decodeUTF8)((0, keys_1.stableStringify)(payload));
+        const signature = (0, keys_1.decodeBase64)(pv.packageAuthorSignature);
+        const pk = (0, keys_1.decodeBase64)(expectedPublicKey);
+        result.valid = nacl.sign.detached.verify(message, signature, pk);
+    }
+    catch {
+        result.valid = false;
+    }
+    return result;
+}

package/dist/package-installer/package-author-signing.test.d.ts

@@ -0,0 +1 @@
+export {};