@mdbase-dev/connect 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/file-crypto.js

@@ -0,0 +1,132 @@
+import { FILE_TRANSFER_PROTOCOL_VERSION, decodeFileFrame, encodeFileFrame, fileFrameAuthenticatedData } from "@mdbase-dev/connect-protocol";
+import { RelayCryptoError, deriveP256SharedSecret, validateGrantEncryption } from "./crypto.js";
+const FILE_KEY_INFO = "mdbase-connect file chunk key v1";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export class FileTransferCryptoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "FileTransferCryptoError";
+    }
+}
+/** Grant-bound, direction-separated cipher for one resumable file transfer. */
+export class GrantFileTransferCipher {
+    binding;
+    key;
+    constructor(binding, key) {
+        this.binding = binding;
+        this.key = key;
+    }
+    static async open(store, handle, binding) {
+        validateFileTransferBinding(binding);
+        const record = await store.get(handle);
+        if (!record || record.agreementPublicKey !== binding.encryption.application_agreement_public_key) {
+            throw new RelayCryptoError("missing_grant_key", "The encrypted grant key is unavailable or does not match the file transfer grant.");
+        }
+        const sharedSecret = await deriveP256SharedSecret(record.agreementPrivateKey, binding.encryption.connector_agreement_public_key);
+        return GrantFileTransferCipher.fromSharedSecret(sharedSecret, binding);
+    }
+    /** @internal Enables non-browser key-agreement adapters and compatibility tests. */
+    static async fromSharedSecret(sharedSecret, binding) {
+        validateFileTransferBinding(binding);
+        const key = await deriveFileTransferKey(sharedSecret, binding);
+        return new GrantFileTransferCipher(binding, key);
+    }
+    async encryptChunk(kind, header, plaintext) {
+        this.validateHeader(header);
+        if (plaintext.byteLength !== header.plaintext_length) {
+            throw new FileTransferCryptoError("plaintext_length_mismatch", "File chunk plaintext length does not match its authenticated header.");
+        }
+        const authenticatedData = fileFrameAuthenticatedData(kind, header);
+        const payload = await crypto.subtle.encrypt({
+            name: "AES-GCM",
+            iv: chunkNonce(header.chunk_index),
+            additionalData: arrayBuffer(authenticatedData),
+            tagLength: 128
+        }, this.key, arrayBuffer(plaintext));
+        return encodeFileFrame({ kind, header, payload: new Uint8Array(payload) });
+    }
+    async decryptChunk(encoded) {
+        const frame = decodeFileFrame(encoded);
+        this.validateHeader(frame.header);
+        const authenticatedData = fileFrameAuthenticatedData(frame.kind, frame.header);
+        try {
+            const plaintext = await crypto.subtle.decrypt({
+                name: "AES-GCM",
+                iv: chunkNonce(frame.header.chunk_index),
+                additionalData: arrayBuffer(authenticatedData),
+                tagLength: 128
+            }, this.key, arrayBuffer(frame.payload));
+            return new Uint8Array(plaintext);
+        }
+        catch {
+            throw new FileTransferCryptoError("authentication_failed", "The encrypted file chunk could not be authenticated.");
+        }
+    }
+    validateHeader(header) {
+        const encryption = this.binding.encryption;
+        if (header.protocol_version !== FILE_TRANSFER_PROTOCOL_VERSION
+            || header.protection !== "grant_aead_v1"
+            || header.grant_id !== this.binding.grantId
+            || header.authority_id !== this.binding.authorityId
+            || header.collection_id !== encryption.collection_id
+            || header.transfer_id !== this.binding.transferId
+            || header.direction !== this.binding.direction
+            || header.scope_epoch !== encryption.scope_epoch
+            || header.key_id !== encryption.key_id) {
+            throw new FileTransferCryptoError("header_binding_mismatch", "The file frame does not match its transfer encryption binding.");
+        }
+    }
+}
+/** @internal Deterministic HKDF profile shared with connector authorities. */
+export async function deriveFileTransferKey(sharedSecret, binding) {
+    const contextBytes = new TextEncoder().encode(fileTransferContext(binding));
+    const salt = await crypto.subtle.digest("SHA-256", contextBytes);
+    const material = await crypto.subtle.importKey("raw", sharedSecret, "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt,
+        info: new TextEncoder().encode(FILE_KEY_INFO)
+    }, material, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+function validateFileTransferBinding(binding) {
+    validateGrantEncryption(binding.encryption);
+    if (!UUID_PATTERN.test(binding.grantId)
+        || !UUID_PATTERN.test(binding.applicationId)
+        || !UUID_PATTERN.test(binding.authorityId)
+        || !UUID_PATTERN.test(binding.transferId)
+        || (binding.direction !== "upload" && binding.direction !== "download")) {
+        throw new FileTransferCryptoError("invalid_binding", "The file transfer encryption binding is invalid.");
+    }
+}
+function fileTransferContext(binding) {
+    const encryption = binding.encryption;
+    return [
+        "mdbase-connect",
+        "file-transfer",
+        FILE_TRANSFER_PROTOCOL_VERSION,
+        encryption.suite,
+        binding.grantId,
+        binding.applicationId,
+        encryption.connector_id,
+        binding.authorityId,
+        encryption.collection_id,
+        encryption.scope_epoch,
+        encryption.key_id,
+        binding.transferId,
+        binding.direction
+    ].join("|");
+}
+function chunkNonce(index) {
+    if (!Number.isSafeInteger(index) || index < 0) {
+        throw new FileTransferCryptoError("invalid_chunk_index", "The file chunk index is invalid.");
+    }
+    const nonce = new Uint8Array(new ArrayBuffer(12));
+    new DataView(nonce.buffer).setBigUint64(4, BigInt(index), false);
+    return nonce;
+}
+function arrayBuffer(bytes) {
+    return Uint8Array.from(bytes).buffer;
+}

package/dist/file-sha256.d.ts

@@ -0,0 +1,12 @@
+/** Small dependency-free incremental SHA-256 for Blob and stream hashing. */
+export declare class IncrementalSha256 {
+    private readonly state;
+    private readonly block;
+    private readonly words;
+    private blockLength;
+    private byteLength;
+    private finished;
+    update(input: Uint8Array): this;
+    digestHex(): string;
+    private compress;
+}

package/dist/file-sha256.js

@@ -0,0 +1,143 @@
+const ROUND_CONSTANTS = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+    0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+    0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+    0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+    0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+    0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+const INITIAL_STATE = new Uint32Array([
+    0x6a09e667,
+    0xbb67ae85,
+    0x3c6ef372,
+    0xa54ff53a,
+    0x510e527f,
+    0x9b05688c,
+    0x1f83d9ab,
+    0x5be0cd19
+]);
+/** Small dependency-free incremental SHA-256 for Blob and stream hashing. */
+export class IncrementalSha256 {
+    state = INITIAL_STATE.slice();
+    block = new Uint8Array(64);
+    words = new Uint32Array(64);
+    blockLength = 0;
+    byteLength = 0;
+    finished = false;
+    update(input) {
+        if (this.finished)
+            throw new Error("SHA-256 digest is already finalized.");
+        this.byteLength += input.byteLength;
+        if (!Number.isSafeInteger(this.byteLength)) {
+            throw new Error("SHA-256 input exceeds the safe browser byte range.");
+        }
+        let offset = 0;
+        if (this.blockLength > 0) {
+            const length = Math.min(64 - this.blockLength, input.byteLength);
+            this.block.set(input.subarray(0, length), this.blockLength);
+            this.blockLength += length;
+            offset += length;
+            if (this.blockLength === 64) {
+                this.compress(this.block);
+                this.blockLength = 0;
+            }
+        }
+        while (offset + 64 <= input.byteLength) {
+            this.compress(input.subarray(offset, offset + 64));
+            offset += 64;
+        }
+        if (offset < input.byteLength) {
+            this.block.set(input.subarray(offset), 0);
+            this.blockLength = input.byteLength - offset;
+        }
+        return this;
+    }
+    digestHex() {
+        if (this.finished)
+            throw new Error("SHA-256 digest is already finalized.");
+        this.finished = true;
+        this.block[this.blockLength] = 0x80;
+        this.block.fill(0, this.blockLength + 1);
+        if (this.blockLength >= 56) {
+            this.compress(this.block);
+            this.block.fill(0);
+        }
+        const bitLength = this.byteLength * 8;
+        const high = Math.floor(bitLength / 0x1_0000_0000);
+        const low = bitLength >>> 0;
+        writeU32(this.block, 56, high);
+        writeU32(this.block, 60, low);
+        this.compress(this.block);
+        return [...this.state]
+            .map((word) => word.toString(16).padStart(8, "0"))
+            .join("");
+    }
+    compress(block) {
+        const words = this.words;
+        for (let index = 0; index < 16; index += 1) {
+            const offset = index * 4;
+            words[index] = ((block[offset] << 24)
+                | (block[offset + 1] << 16)
+                | (block[offset + 2] << 8)
+                | block[offset + 3]) >>> 0;
+        }
+        for (let index = 16; index < 64; index += 1) {
+            const left = words[index - 15];
+            const right = words[index - 2];
+            const sigma0 = rotateRight(left, 7) ^ rotateRight(left, 18) ^ (left >>> 3);
+            const sigma1 = rotateRight(right, 17) ^ rotateRight(right, 19) ^ (right >>> 10);
+            words[index] = (words[index - 16] + sigma0 + words[index - 7] + sigma1) >>> 0;
+        }
+        let a = this.state[0];
+        let b = this.state[1];
+        let c = this.state[2];
+        let d = this.state[3];
+        let e = this.state[4];
+        let f = this.state[5];
+        let g = this.state[6];
+        let h = this.state[7];
+        for (let index = 0; index < 64; index += 1) {
+            const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choice = (e & f) ^ (~e & g);
+            const temp1 = (h + sum1 + choice + ROUND_CONSTANTS[index] + words[index]) >>> 0;
+            const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (sum0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temp1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) >>> 0;
+        }
+        this.state[0] = (this.state[0] + a) >>> 0;
+        this.state[1] = (this.state[1] + b) >>> 0;
+        this.state[2] = (this.state[2] + c) >>> 0;
+        this.state[3] = (this.state[3] + d) >>> 0;
+        this.state[4] = (this.state[4] + e) >>> 0;
+        this.state[5] = (this.state[5] + f) >>> 0;
+        this.state[6] = (this.state[6] + g) >>> 0;
+        this.state[7] = (this.state[7] + h) >>> 0;
+    }
+}
+function rotateRight(value, amount) {
+    return (value >>> amount) | (value << (32 - amount));
+}
+function writeU32(target, offset, value) {
+    target[offset] = value >>> 24;
+    target[offset + 1] = value >>> 16;
+    target[offset + 2] = value >>> 8;
+    target[offset + 3] = value;
+}

package/dist/file-stream-source.d.ts

@@ -0,0 +1,17 @@
+/** Converts a one-shot byte source into exact upload parts without read-ahead. */
+export declare class BinaryPartReader {
+    private readonly signal?;
+    private readonly iterator;
+    private remainder;
+    private remainderOffset;
+    private maxSourceChunkBytes;
+    private iteratorClosing;
+    private ended;
+    constructor(source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, signal?: AbortSignal | undefined);
+    setMaxSourceChunkBytes(value: number): void;
+    read(length: number): Promise<Uint8Array<ArrayBuffer>>;
+    expectEnd(): Promise<void>;
+    close(): Promise<void>;
+    private nextSourceChunk;
+    private closeIterator;
+}

package/dist/file-stream-source.js

@@ -0,0 +1,157 @@
+import { connectError } from "./errors.js";
+/** Converts a one-shot byte source into exact upload parts without read-ahead. */
+export class BinaryPartReader {
+    signal;
+    iterator;
+    remainder = new Uint8Array();
+    remainderOffset = 0;
+    maxSourceChunkBytes = null;
+    iteratorClosing = false;
+    ended = false;
+    constructor(source, signal) {
+        this.signal = signal;
+        this.iterator = sourceIterator(source);
+    }
+    setMaxSourceChunkBytes(value) {
+        this.maxSourceChunkBytes = value;
+    }
+    async read(length) {
+        const output = new Uint8Array(length);
+        let offset = 0;
+        while (offset < length) {
+            if (this.remainderOffset === this.remainder.byteLength) {
+                const next = await this.nextSourceChunk();
+                if (next.done) {
+                    this.ended = true;
+                    throw connectError("invalid_request", "Streamed file bytes ended before the declared size.");
+                }
+                if (!(next.value instanceof Uint8Array)) {
+                    throw connectError("invalid_request", "A streamed file chunk was not a Uint8Array.");
+                }
+                if (this.maxSourceChunkBytes === null) {
+                    throw new Error("Stream source was read before upload negotiation completed.");
+                }
+                if (next.value.byteLength > this.maxSourceChunkBytes) {
+                    throw connectError("invalid_request", `A streamed file chunk exceeded the negotiated ${this.maxSourceChunkBytes}-byte upload part size.`);
+                }
+                this.remainder = next.value;
+                this.remainderOffset = 0;
+                if (this.remainder.byteLength === 0)
+                    continue;
+            }
+            const count = Math.min(length - offset, this.remainder.byteLength - this.remainderOffset);
+            output.set(this.remainder.subarray(this.remainderOffset, this.remainderOffset + count), offset);
+            offset += count;
+            this.remainderOffset += count;
+        }
+        return output;
+    }
+    async expectEnd() {
+        if (this.remainderOffset < this.remainder.byteLength) {
+            throw connectError("invalid_request", "Streamed file bytes exceed the declared size.");
+        }
+        while (!this.ended) {
+            const next = await this.nextSourceChunk();
+            if (next.done) {
+                this.ended = true;
+                return;
+            }
+            if (!(next.value instanceof Uint8Array)) {
+                throw connectError("invalid_request", "A streamed file chunk was not a Uint8Array.");
+            }
+            if (next.value.byteLength > 0) {
+                throw connectError("invalid_request", "Streamed file bytes exceed the declared size.");
+            }
+        }
+    }
+    async close() {
+        this.ended = true;
+        this.closeIterator();
+    }
+    async nextSourceChunk() {
+        throwIfAborted(this.signal);
+        const pending = this.iterator.next();
+        const signal = this.signal;
+        if (!signal)
+            return pending;
+        let removeAbortListener = () => { };
+        const cancelled = new Promise((_resolve, reject) => {
+            const abort = () => {
+                this.closeIterator();
+                reject(cancelledError(signal));
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            removeAbortListener = () => signal.removeEventListener("abort", abort);
+            if (signal.aborted)
+                abort();
+        });
+        try {
+            const next = await Promise.race([pending, cancelled]);
+            throwIfAborted(signal);
+            return next;
+        }
+        finally {
+            removeAbortListener();
+        }
+    }
+    closeIterator() {
+        if (this.iteratorClosing)
+            return;
+        this.iteratorClosing = true;
+        try {
+            const closing = this.iterator.return?.();
+            void closing?.catch(() => undefined);
+        }
+        catch {
+            // Cancellation and transfer cleanup must not wait for a broken source.
+        }
+    }
+}
+function sourceIterator(source) {
+    if (typeof source.getReader === "function") {
+        const reader = source.getReader();
+        let released = false;
+        const release = () => {
+            if (!released) {
+                released = true;
+                reader.releaseLock();
+            }
+        };
+        return {
+            async next() {
+                if (released)
+                    return { done: true, value: undefined };
+                const next = await reader.read();
+                if (next.done)
+                    release();
+                return next;
+            },
+            async return() {
+                if (!released) {
+                    try {
+                        await reader.cancel();
+                    }
+                    finally {
+                        release();
+                    }
+                }
+                return { done: true, value: undefined };
+            }
+        };
+    }
+    const iterable = source;
+    if (typeof iterable[Symbol.asyncIterator] !== "function") {
+        throw connectError("invalid_request", "Streamed files require a readable byte stream.");
+    }
+    return iterable[Symbol.asyncIterator]();
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw cancelledError(signal);
+}
+function cancelledError(signal) {
+    return connectError("operation_cancelled", "The file transfer was cancelled.", {
+        operationOutcome: "not_sent",
+        cause: signal?.reason
+    });
+}

package/dist/files.d.ts

@@ -0,0 +1,91 @@
+import type { CollectionFileDescriptor, DeleteFileReceipt, FileCapability, FileTransferSession } from "@mdbase-dev/connect-protocol";
+export type MdbaseFileSource = Blob | ArrayBuffer | ArrayBufferView;
+export interface MdbaseFileStreamSource {
+    /** Exact plaintext byte length. */
+    size: number;
+    /** SHA-256 commitment verified by both this client and the authority. */
+    contentDigest: `sha256:${string}`;
+    /**
+     * A one-shot byte source. Each yielded chunk must fit within the upload part
+     * size negotiated by the authority; ordinary browser and Node streams do.
+     */
+    stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+    mediaType?: string;
+}
+export interface MdbaseFileProgress {
+    phase: "hashing" | "uploading" | "downloading";
+    transferredBytes: number;
+    totalBytes: number;
+}
+export interface MdbaseFileListOptions {
+    folder?: string;
+    pageSize?: number;
+    signal?: AbortSignal;
+}
+export interface MdbaseFileUploadOptions {
+    mediaType?: string;
+    ifRevision?: string;
+    concurrency?: number;
+    /** Stable retry key. Reuse it after an ambiguous failure to resume or replay commit. */
+    transferId?: string;
+    signal?: AbortSignal;
+    onProgress?: (progress: MdbaseFileProgress) => void;
+}
+export type MdbaseFileStreamUploadOptions = Omit<MdbaseFileUploadOptions, "concurrency">;
+export interface MdbaseFileDownloadOptions {
+    concurrency?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: MdbaseFileProgress) => void;
+}
+export interface MdbaseFileMoveOptions {
+    ifRevision?: string;
+    /** Reuse after an ambiguous network failure to receive the original receipt. */
+    mutationId?: string;
+    signal?: AbortSignal;
+}
+export interface MdbaseFileDeleteOptions {
+    ifRevision?: string;
+    /** Reuse after an ambiguous network failure to receive the original receipt. */
+    mutationId?: string;
+    signal?: AbortSignal;
+}
+/** Internal transport seam used by direct and relayed encrypted chunk delivery. */
+export interface MdbaseFramedFileTransport {
+    uploadChunk(session: FileTransferSession, chunkIndex: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>;
+    downloadChunk(session: FileTransferSession, chunkIndex: number, signal?: AbortSignal): Promise<Uint8Array>;
+}
+/** Internal authenticated hosted-object delivery seam. */
+export interface MdbaseHostedFileTransport {
+    downloadPart(session: FileTransferSession, partIndex: number, expectedLength: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+}
+type ControlRequest = <Result>(method: "GET" | "POST" | "DELETE", path?: string, input?: unknown, signal?: AbortSignal) => Promise<Result>;
+/** Ergonomic facade over resumable, authority-specific file delivery. */
+export declare class MdbaseFileClient {
+    private readonly capability;
+    private readonly request;
+    private readonly framed?;
+    private readonly hosted?;
+    constructor(capability: () => FileCapability | null, request: ControlRequest, framed?: MdbaseFramedFileTransport | undefined, hosted?: MdbaseHostedFileTransport | undefined);
+    list(options?: MdbaseFileListOptions): AsyncGenerator<CollectionFileDescriptor>;
+    upload(path: string, source: MdbaseFileSource, options?: MdbaseFileUploadOptions): Promise<CollectionFileDescriptor>;
+    /**
+     * Upload a one-shot byte stream without accumulating multiple file parts.
+     * SDK memory is bounded by one assembled negotiated part plus at most one
+     * source chunk; a single-part upload may therefore hold the complete file.
+     * Reuse `transferId` with a newly opened source after an ambiguous failure.
+     */
+    uploadStream(path: string, source: MdbaseFileStreamSource, options?: MdbaseFileStreamUploadOptions): Promise<CollectionFileDescriptor>;
+    private uploadKnownSource;
+    download(file: CollectionFileDescriptor, options?: MdbaseFileDownloadOptions): Promise<Blob>;
+    /** Download and verify a file with network backpressure and bounded buffering. */
+    downloadStream(file: CollectionFileDescriptor, options?: MdbaseFileDownloadOptions): Promise<ReadableStream<Uint8Array>>;
+    downloadBytes(file: CollectionFileDescriptor, options?: MdbaseFileDownloadOptions): Promise<Uint8Array>;
+    move(file: CollectionFileDescriptor, path: string, options?: MdbaseFileMoveOptions): Promise<CollectionFileDescriptor>;
+    delete(file: CollectionFileDescriptor, options?: MdbaseFileDeleteOptions): Promise<DeleteFileReceipt>;
+    private uploadPart;
+    private tryReplayUploadCommit;
+    private commitUpload;
+    private requireAction;
+    private abort;
+}
+export {};