@xtr-dev/rondevu-client 0.21.5 → 0.21.8

package/dist/meta.d.ts

@@ -0,0 +1,221 @@
+/**
+ * meta.json format for authenticated torrent metadata
+ *
+ * Provides cryptographic proof of authorship using Ed25519 signatures.
+ * Supports extensible metadata for audio, video, image, and document files.
+ */
+import { CryptoAdapter, KeyPair } from './crypto/adapter.js';
+/**
+ * Root meta.json structure
+ */
+export interface TorrentMeta {
+    version: string;
+    infohash?: string;
+    created: number;
+    title: string;
+    description?: string;
+    files: MetaFile[];
+    authors: MetaAuthor[];
+    extensions?: MetaExtensions;
+}
+/**
+ * File entry with optional per-file metadata
+ */
+export interface MetaFile {
+    path: string;
+    size: number;
+    type?: string;
+    sha256?: string;
+    role?: FileRole;
+    meta?: FileMetaExtensions;
+}
+/**
+ * Special file roles for cover art, thumbnails, etc.
+ */
+export type FileRole = 'cover' | 'thumbnail' | 'preview' | 'lyrics' | 'subtitles';
+/**
+ * Author entry with signature
+ */
+export interface MetaAuthor {
+    publicKey: string;
+    role?: AuthorRole;
+    signedAt: number;
+    signature: string;
+}
+/**
+ * Author roles
+ */
+export type AuthorRole = 'creator' | 'co-author' | 'endorser';
+/**
+ * Torrent-level metadata extensions
+ */
+export interface MetaExtensions {
+    audio?: AudioMeta;
+    video?: VideoMeta;
+    image?: ImageMeta;
+    document?: DocumentMeta;
+}
+/**
+ * Per-file metadata extensions
+ */
+export interface FileMetaExtensions {
+    audio?: AudioFileMeta;
+    video?: VideoMeta;
+    image?: ImageMeta;
+    document?: DocumentMeta;
+}
+/**
+ * Audio metadata (torrent-level, e.g., album info)
+ */
+export interface AudioMeta {
+    artist?: string;
+    album?: string;
+    genre?: string;
+    year?: number;
+    totalTracks?: number;
+}
+/**
+ * Audio metadata (file-level, e.g., track info)
+ */
+export interface AudioFileMeta {
+    title?: string;
+    track?: number;
+    duration?: number;
+    artist?: string;
+    bpm?: number;
+}
+/**
+ * Video metadata
+ */
+export interface VideoMeta {
+    duration?: number;
+    width?: number;
+    height?: number;
+    codec?: string;
+    framerate?: number;
+    bitrate?: number;
+}
+/**
+ * Image metadata
+ */
+export interface ImageMeta {
+    width?: number;
+    height?: number;
+    format?: string;
+    camera?: string;
+    takenAt?: number;
+    gps?: {
+        lat: number;
+        lon: number;
+    };
+}
+/**
+ * Document metadata
+ */
+export interface DocumentMeta {
+    pages?: number;
+    author?: string;
+    language?: string;
+    format?: string;
+}
+/**
+ * The canonical payload that gets signed
+ * Includes author public keys to prevent fake co-author additions
+ * Note: infohash is optional because we may not know it before signing
+ * (torrent infohash includes meta.json, creating a chicken-egg problem)
+ * Content authenticity is ensured by sha256 hashes in the files array
+ */
+export interface SigningPayload {
+    created: number;
+    title: string;
+    files: MetaFile[];
+    authors: string[];
+    signedAt: number;
+}
+/**
+ * Canonicalize an object to JSON with sorted keys (deterministic)
+ * This ensures the same object always produces the same string for signing
+ */
+export declare function canonicalize(obj: unknown): string;
+/**
+ * Build the signing payload from meta.json data
+ */
+export declare function buildSigningPayload(meta: Pick<TorrentMeta, 'created' | 'title' | 'files'>, authorPublicKeys: string[], signedAt: number): SigningPayload;
+/**
+ * Sign a torrent meta.json
+ *
+ * @param crypto - Crypto adapter for signing
+ * @param keyPair - The signer's key pair
+ * @param meta - The meta.json data (without this author's signature)
+ * @param authorPublicKeys - All author public keys (including this signer)
+ * @param role - This author's role
+ * @returns MetaAuthor entry with signature
+ */
+export declare function signMeta(crypto: CryptoAdapter, keyPair: KeyPair, meta: Pick<TorrentMeta, 'created' | 'title' | 'files'>, authorPublicKeys: string[], role?: AuthorRole): Promise<MetaAuthor>;
+/**
+ * Verify a single author's signature
+ *
+ * @param crypto - Crypto adapter for verification
+ * @param meta - The meta.json data
+ * @param author - The author entry to verify
+ * @returns True if signature is valid
+ */
+export declare function verifyAuthorSignature(crypto: CryptoAdapter, meta: Pick<TorrentMeta, 'created' | 'title' | 'files' | 'authors'>, author: MetaAuthor): Promise<boolean>;
+/**
+ * Verify all author signatures in a meta.json
+ *
+ * @param crypto - Crypto adapter for verification
+ * @param meta - The complete meta.json
+ * @returns Object with verification results per author
+ */
+export declare function verifyMeta(crypto: CryptoAdapter, meta: TorrentMeta): Promise<{
+    valid: boolean;
+    results: Map<string, boolean>;
+}>;
+/**
+ * Create a complete meta.json with signatures from all authors
+ *
+ * @param crypto - Crypto adapter for signing
+ * @param options - Meta creation options
+ * @returns Complete TorrentMeta with all signatures
+ */
+export declare function createMeta(crypto: CryptoAdapter, options: {
+    title: string;
+    description?: string;
+    files: MetaFile[];
+    authors: Array<{
+        keyPair: KeyPair;
+        role?: AuthorRole;
+    }>;
+    extensions?: MetaExtensions;
+    infohash?: string;
+}): Promise<TorrentMeta>;
+/**
+ * Parse and validate a meta.json string
+ * Does NOT verify signatures - use verifyMeta for that
+ *
+ * @param json - JSON string to parse
+ * @returns Parsed TorrentMeta or null if invalid
+ */
+export declare function parseMeta(json: string): TorrentMeta | null;
+/**
+ * Find a file with a specific role (e.g., cover art)
+ */
+export declare function findFileByRole(meta: TorrentMeta, role: FileRole): MetaFile | undefined;
+/**
+ * Get the cover art file if present
+ */
+export declare function getCoverFile(meta: TorrentMeta): MetaFile | undefined;
+/**
+ * Compute SHA256 hash of a file (browser-compatible)
+ */
+export declare function computeFileSha256(file: File | Blob | ArrayBuffer): Promise<string>;
+/**
+ * Build MetaFile entries from File objects with SHA256 hashes
+ */
+export declare function buildMetaFiles(files: File[]): Promise<MetaFile[]>;
+/**
+ * Set the infohash on a TorrentMeta after torrent creation
+ * Note: This does NOT re-sign - infohash is informational only
+ */
+export declare function setInfohash(meta: TorrentMeta, infohash: string): TorrentMeta;

package/dist/meta.js

@@ -0,0 +1,213 @@
+/**
+ * meta.json format for authenticated torrent metadata
+ *
+ * Provides cryptographic proof of authorship using Ed25519 signatures.
+ * Supports extensible metadata for audio, video, image, and document files.
+ */
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Canonicalize an object to JSON with sorted keys (deterministic)
+ * This ensures the same object always produces the same string for signing
+ */
+export function canonicalize(obj) {
+    return JSON.stringify(obj, (_, value) => {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return Object.keys(value)
+                .sort()
+                .reduce((sorted, key) => {
+                sorted[key] = value[key];
+                return sorted;
+            }, {});
+        }
+        return value;
+    });
+}
+/**
+ * Build the signing payload from meta.json data
+ */
+export function buildSigningPayload(meta, authorPublicKeys, signedAt) {
+    return {
+        created: meta.created,
+        title: meta.title,
+        files: meta.files,
+        authors: authorPublicKeys,
+        signedAt
+    };
+}
+/**
+ * Sign a torrent meta.json
+ *
+ * @param crypto - Crypto adapter for signing
+ * @param keyPair - The signer's key pair
+ * @param meta - The meta.json data (without this author's signature)
+ * @param authorPublicKeys - All author public keys (including this signer)
+ * @param role - This author's role
+ * @returns MetaAuthor entry with signature
+ */
+export async function signMeta(crypto, keyPair, meta, authorPublicKeys, role) {
+    const signedAt = Date.now();
+    const payload = buildSigningPayload(meta, authorPublicKeys, signedAt);
+    const message = canonicalize(payload);
+    const signature = await crypto.signMessage(keyPair.privateKey, message);
+    return {
+        publicKey: keyPair.publicKey,
+        role,
+        signedAt,
+        signature
+    };
+}
+/**
+ * Verify a single author's signature
+ *
+ * @param crypto - Crypto adapter for verification
+ * @param meta - The meta.json data
+ * @param author - The author entry to verify
+ * @returns True if signature is valid
+ */
+export async function verifyAuthorSignature(crypto, meta, author) {
+    const authorPublicKeys = meta.authors.map(a => a.publicKey);
+    const payload = buildSigningPayload(meta, authorPublicKeys, author.signedAt);
+    const message = canonicalize(payload);
+    return crypto.verifySignature(author.publicKey, message, author.signature);
+}
+/**
+ * Verify all author signatures in a meta.json
+ *
+ * @param crypto - Crypto adapter for verification
+ * @param meta - The complete meta.json
+ * @returns Object with verification results per author
+ */
+export async function verifyMeta(crypto, meta) {
+    const results = new Map();
+    let allValid = true;
+    for (const author of meta.authors) {
+        const isValid = await verifyAuthorSignature(crypto, meta, author);
+        results.set(author.publicKey, isValid);
+        if (!isValid) {
+            allValid = false;
+        }
+    }
+    return { valid: allValid, results };
+}
+/**
+ * Create a complete meta.json with signatures from all authors
+ *
+ * @param crypto - Crypto adapter for signing
+ * @param options - Meta creation options
+ * @returns Complete TorrentMeta with all signatures
+ */
+export async function createMeta(crypto, options) {
+    const created = Date.now();
+    const authorPublicKeys = options.authors.map(a => a.keyPair.publicKey);
+    const baseMeta = {
+        created,
+        title: options.title,
+        files: options.files
+    };
+    // Sign with each author
+    const signedAuthors = [];
+    for (const { keyPair, role } of options.authors) {
+        const author = await signMeta(crypto, keyPair, baseMeta, authorPublicKeys, role);
+        signedAuthors.push(author);
+    }
+    const meta = {
+        version: '1',
+        created,
+        title: options.title,
+        files: options.files,
+        authors: signedAuthors,
+    };
+    if (options.infohash) {
+        meta.infohash = options.infohash;
+    }
+    if (options.description) {
+        meta.description = options.description;
+    }
+    if (options.extensions) {
+        meta.extensions = options.extensions;
+    }
+    return meta;
+}
+/**
+ * Parse and validate a meta.json string
+ * Does NOT verify signatures - use verifyMeta for that
+ *
+ * @param json - JSON string to parse
+ * @returns Parsed TorrentMeta or null if invalid
+ */
+export function parseMeta(json) {
+    try {
+        const data = JSON.parse(json);
+        // Basic validation
+        if (typeof data.version !== 'string')
+            return null;
+        // infohash is optional
+        if (data.infohash !== undefined && typeof data.infohash !== 'string')
+            return null;
+        if (typeof data.created !== 'number')
+            return null;
+        if (typeof data.title !== 'string')
+            return null;
+        if (!Array.isArray(data.files))
+            return null;
+        if (!Array.isArray(data.authors))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a file with a specific role (e.g., cover art)
+ */
+export function findFileByRole(meta, role) {
+    return meta.files.find(f => f.role === role);
+}
+/**
+ * Get the cover art file if present
+ */
+export function getCoverFile(meta) {
+    return findFileByRole(meta, 'cover');
+}
+/**
+ * Compute SHA256 hash of a file (browser-compatible)
+ */
+export async function computeFileSha256(file) {
+    let buffer;
+    if (file instanceof ArrayBuffer) {
+        buffer = file;
+    }
+    else {
+        buffer = await file.arrayBuffer();
+    }
+    const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Build MetaFile entries from File objects with SHA256 hashes
+ */
+export async function buildMetaFiles(files) {
+    const metaFiles = [];
+    for (const file of files) {
+        const sha256 = await computeFileSha256(file);
+        const metaFile = {
+            path: file.name,
+            size: file.size,
+            type: file.type || undefined,
+            sha256
+        };
+        metaFiles.push(metaFile);
+    }
+    return metaFiles;
+}
+/**
+ * Set the infohash on a TorrentMeta after torrent creation
+ * Note: This does NOT re-sign - infohash is informational only
+ */
+export function setInfohash(meta, infohash) {
+    return { ...meta, infohash };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/rondevu-client",
-  "version": "0.21.5",
+  "version": "0.21.8",
   "description": "TypeScript client for Rondevu with durable WebRTC connections, automatic reconnection, and message queuing",
   "type": "module",
   "main": "dist/core/index.js",
@@ -47,6 +47,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@noble/ed25519": "^3.0.0",
     "eventemitter3": "^5.0.1"
   },
   "lint-staged": {