@oatscenter/trellis 0.100.0-rc.1

package/transfer.d.ts

@@ -0,0 +1,112 @@
+import { AsyncResult, type Result as ResultType } from "@oatscenter/result";
+import { type MsgHdrs, type NatsConnection } from "@nats-io/nats-core";
+import Type, { type Static } from "typebox";
+import { TransferError } from "./errors/TransferError.ts";
+export declare const MAX_TRANSFER_CHUNK_BYTES: number;
+export declare const FileInfoSchema: Type.TObject<{
+    key: Type.TString;
+    size: Type.TInteger;
+    updatedAt: Type.TString;
+    digest: Type.TOptional<Type.TString>;
+    contentType: Type.TOptional<Type.TString>;
+    metadata: Type.TRecord<"^.*$", Type.TString>;
+}>;
+export type FileInfo = Static<typeof FileInfoSchema>;
+export declare const SendTransferGrantSchema: Type.TObject<{
+    direction: Type.TLiteral<"send">;
+    maxBytes: Type.TOptional<Type.TInteger>;
+    contentType: Type.TOptional<Type.TString>;
+    metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+    type: Type.TLiteral<"TransferGrant">;
+    service: Type.TString;
+    sessionKey: Type.TString;
+    transferId: Type.TString;
+    subject: Type.TString;
+    expiresAt: Type.TString;
+    chunkBytes: Type.TInteger;
+}>;
+export declare const ReceiveTransferGrantSchema: Type.TObject<{
+    direction: Type.TLiteral<"receive">;
+    info: Type.TObject<{
+        digest: Type.TString;
+        key: Type.TString;
+        size: Type.TInteger;
+        updatedAt: Type.TString;
+        contentType: Type.TOptional<Type.TString>;
+        metadata: Type.TRecord<"^.*$", Type.TString>;
+    }>;
+    type: Type.TLiteral<"TransferGrant">;
+    service: Type.TString;
+    sessionKey: Type.TString;
+    transferId: Type.TString;
+    subject: Type.TString;
+    expiresAt: Type.TString;
+    chunkBytes: Type.TInteger;
+}>;
+export declare const TransferGrantSchema: Type.TUnion<[Type.TObject<{
+    direction: Type.TLiteral<"send">;
+    maxBytes: Type.TOptional<Type.TInteger>;
+    contentType: Type.TOptional<Type.TString>;
+    metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+    type: Type.TLiteral<"TransferGrant">;
+    service: Type.TString;
+    sessionKey: Type.TString;
+    transferId: Type.TString;
+    subject: Type.TString;
+    expiresAt: Type.TString;
+    chunkBytes: Type.TInteger;
+}>, Type.TObject<{
+    direction: Type.TLiteral<"receive">;
+    info: Type.TObject<{
+        digest: Type.TString;
+        key: Type.TString;
+        size: Type.TInteger;
+        updatedAt: Type.TString;
+        contentType: Type.TOptional<Type.TString>;
+        metadata: Type.TRecord<"^.*$", Type.TString>;
+    }>;
+    type: Type.TLiteral<"TransferGrant">;
+    service: Type.TString;
+    sessionKey: Type.TString;
+    transferId: Type.TString;
+    subject: Type.TString;
+    expiresAt: Type.TString;
+    chunkBytes: Type.TInteger;
+}>]>;
+export type SendTransferGrant = Static<typeof SendTransferGrantSchema>;
+export type ReceiveTransferGrant = Static<typeof ReceiveTransferGrantSchema>;
+export type TransferGrant = Static<typeof TransferGrantSchema>;
+export type TransferBody = Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+type TrellisTransferAuth = {
+    sessionKey: string;
+    sign(data: Uint8Array): Promise<Uint8Array> | Uint8Array;
+    currentIat?: () => number;
+    contextDigest?: string | (() => string);
+};
+declare class BaseTransferHandle {
+    #private;
+    protected constructor(nc: NatsConnection, auth: TrellisTransferAuth, timeoutMs: number, inboxPrefix?: string);
+    protected get nc(): NatsConnection;
+    protected get inboxPrefix(): string;
+    protected get auth(): TrellisTransferAuth;
+    protected get timeoutMs(): number;
+    protected validateGrant(grant: TransferGrant, operation: string): ResultType<void, TransferError>;
+    protected buildHeaders(subject: string, reply: string, payload: Uint8Array, seq?: number, control?: "complete" | "cancel"): Promise<MsgHdrs>;
+    protected cancelTransfer(subject: string): Promise<void>;
+}
+export declare class SendTransferHandle extends BaseTransferHandle {
+    #private;
+    constructor(nc: NatsConnection, auth: TrellisTransferAuth, timeoutMs: number, grant: SendTransferGrant, inboxPrefix?: string);
+    send(body: TransferBody): AsyncResult<FileInfo, TransferError>;
+}
+export declare class ReceiveTransferHandle extends BaseTransferHandle {
+    #private;
+    constructor(nc: NatsConnection, auth: TrellisTransferAuth, timeoutMs: number, grant: ReceiveTransferGrant, inboxPrefix?: string);
+    stream(): AsyncResult<ReadableStream<Uint8Array>, TransferError>;
+    bytes(): AsyncResult<Uint8Array, TransferError>;
+}
+export type TransferHandle = SendTransferHandle | ReceiveTransferHandle;
+export declare function createTransferHandle(nc: NatsConnection, auth: TrellisTransferAuth, timeoutMs: number, grant: SendTransferGrant, inboxPrefix?: string): SendTransferHandle;
+export declare function createTransferHandle(nc: NatsConnection, auth: TrellisTransferAuth, timeoutMs: number, grant: ReceiveTransferGrant, inboxPrefix?: string): ReceiveTransferHandle;
+export declare function createTransferHandle(nc: NatsConnection, auth: TrellisTransferAuth, timeoutMs: number, grant: TransferGrant, inboxPrefix?: string): TransferHandle;
+export {};

package/transfer.js

@@ -0,0 +1,525 @@
+import { AsyncResult, isErr, Result, } from "@oatscenter/result";
+import { createInbox, headers as natsHeaders, } from "@nats-io/nats-core";
+import Type, {} from "typebox";
+import { ulid } from "ulid";
+import { sha256 as incrementalSha256 } from "@noble/hashes/sha256";
+import { buildProofInput } from "./auth/proof.js";
+import { base64urlEncode, sha256 } from "./auth/utils.js";
+import { TransferError } from "./errors/TransferError.js";
+import { createNatsHeaderCarrier, injectTraceContext, recordTrellisError, } from "./telemetry/mod.js";
+import { transferFrameProofPayload } from "./transfer_protocol.js";
+const TRANSFER_SEQUENCE_HEADER = "trellis-transfer-seq";
+const TRANSFER_EOF_HEADER = "trellis-transfer-eof";
+const TRANSFER_CONTROL_HEADER = "trellis-transfer-control";
+export const MAX_TRANSFER_CHUNK_BYTES = 1024 * 1024;
+export const FileInfoSchema = Type.Object({
+    key: Type.String({ minLength: 1 }),
+    size: Type.Integer({ minimum: 0 }),
+    updatedAt: Type.String({ minLength: 1 }),
+    digest: Type.Optional(Type.String({ minLength: 1 })),
+    contentType: Type.Optional(Type.String({ minLength: 1 })),
+    metadata: Type.Record(Type.String({ minLength: 1 }), Type.String()),
+});
+const TransferGrantBaseSchema = Type.Object({
+    type: Type.Literal("TransferGrant"),
+    service: Type.String({ minLength: 1 }),
+    sessionKey: Type.String({ minLength: 1 }),
+    transferId: Type.String({ minLength: 1 }),
+    subject: Type.String({ minLength: 1 }),
+    expiresAt: Type.String({ minLength: 1 }),
+    chunkBytes: Type.Integer({ minimum: 1, maximum: MAX_TRANSFER_CHUNK_BYTES }),
+});
+export const SendTransferGrantSchema = Type.Object({
+    ...TransferGrantBaseSchema.properties,
+    direction: Type.Literal("send"),
+    maxBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+    contentType: Type.Optional(Type.String({ minLength: 1 })),
+    metadata: Type.Optional(Type.Record(Type.String({ minLength: 1 }), Type.String())),
+});
+export const ReceiveTransferGrantSchema = Type.Object({
+    ...TransferGrantBaseSchema.properties,
+    direction: Type.Literal("receive"),
+    info: Type.Object({
+        ...FileInfoSchema.properties,
+        digest: Type.String({ minLength: 1 }),
+    }),
+});
+export const TransferGrantSchema = Type.Union([
+    SendTransferGrantSchema,
+    ReceiveTransferGrantSchema,
+]);
+async function createTransferProof(auth, subject, reply, payload) {
+    const contextDigest = typeof auth.contextDigest === "function"
+        ? auth.contextDigest()
+        : auth.contextDigest;
+    if (contextDigest === undefined) {
+        throw new Error("contextDigest is required to sign transfer proofs");
+    }
+    if (reply.length === 0) {
+        throw new Error("transfer reply subject must not be empty");
+    }
+    const payloadHash = await sha256(payload);
+    const iat = auth.currentIat?.() ?? Math.floor(Date.now() / 1000);
+    const requestId = ulid();
+    const proofOk = await auth.sign(await sha256(buildProofInput(contextDigest, subject, reply, payloadHash, iat, requestId)));
+    return {
+        proof: base64urlEncode(proofOk),
+        iat,
+        requestId,
+        contextDigest,
+    };
+}
+function expired(expiresAt) {
+    return Date.now() >= Date.parse(expiresAt);
+}
+function asUint8Array(body) {
+    return body instanceof Uint8Array ? body : new Uint8Array(body);
+}
+function streamFromAsyncIterable(iterable) {
+    const iterator = iterable[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            const next = await iterator.next();
+            if (next.done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue(next.value);
+        },
+        async cancel(reason) {
+            await iterator.return?.(reason);
+        },
+    });
+}
+function streamFromBody(body) {
+    if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
+        const bytes = asUint8Array(body);
+        return new ReadableStream({
+            start(controller) {
+                controller.enqueue(bytes);
+                controller.close();
+            },
+        });
+    }
+    return body instanceof ReadableStream ? body : streamFromAsyncIterable(body);
+}
+async function* chunkBody(body, chunkBytes) {
+    const reader = streamFromBody(body).getReader();
+    let completed = false;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                completed = true;
+                return;
+            }
+            let offset = 0;
+            while (offset < next.value.length) {
+                const end = Math.min(offset + chunkBytes, next.value.length);
+                yield next.value.slice(offset, end);
+                offset = end;
+            }
+        }
+    }
+    finally {
+        if (!completed)
+            void reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+function parseTransferAck(msg, operation) {
+    if (msg.headers?.get("status") === "error") {
+        return Result.err(deserializeTransferError(msg, operation));
+    }
+    try {
+        const value = JSON.parse(msg.string());
+        return Result.ok(value);
+    }
+    catch (cause) {
+        return Result.err(new TransferError({ operation, cause }));
+    }
+}
+function deserializeTransferError(msg, operation) {
+    try {
+        const value = JSON.parse(msg.string());
+        return new TransferError({
+            operation,
+            context: value.context,
+            cause: typeof value.context?.causeMessage === "string"
+                ? new Error(value.context.causeMessage)
+                : typeof value.context?.reason === "string"
+                    ? new Error(`${value.message ?? "Transfer failed"}: ${JSON.stringify(value.context)}`)
+                    : value.message
+                        ? new Error(value.message)
+                        : undefined,
+        });
+    }
+    catch (cause) {
+        return new TransferError({ operation, cause });
+    }
+}
+function recordTransferError(error, direction, phase) {
+    recordTrellisError(error, {
+        surface: "transfer",
+        direction,
+        operation: error.operation ?? direction,
+        phase,
+        messagingSystem: "nats",
+    });
+    return error;
+}
+async function requestTransfer(nc, subject, payload, headers, reply, timeoutMs) {
+    const subscription = nc.subscribe(reply, { max: 1 });
+    let timer;
+    try {
+        nc.publish(subject, payload, { headers, reply });
+        return await Promise.race([
+            subscription[Symbol.asyncIterator]().next().then((result) => {
+                if (result.done)
+                    throw new Error("Transfer reply subscription closed");
+                return result.value;
+            }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Transfer request timed out")), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        subscription.unsubscribe();
+    }
+}
+function receiveStream(grant, requestFrame, cancelTransfer) {
+    const hasher = incrementalSha256.create();
+    let expectedSeq = 0;
+    let receivedBytes = 0;
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const msg = await requestFrame(expectedSeq);
+                if (msg.headers?.get("status") === "error") {
+                    throw deserializeTransferError(msg, "stream");
+                }
+                const actualSeq = Number(msg.headers?.get(TRANSFER_SEQUENCE_HEADER));
+                if (!Number.isSafeInteger(actualSeq) || actualSeq !== expectedSeq) {
+                    throw new TransferError({
+                        operation: "stream",
+                        context: { reason: "sequence", expectedSeq, actualSeq },
+                    });
+                }
+                expectedSeq += 1;
+                if (msg.data.length > grant.chunkBytes) {
+                    throw new TransferError({
+                        operation: "stream",
+                        context: {
+                            reason: "chunk_too_large",
+                            maxChunkBytes: grant.chunkBytes,
+                            actualChunkBytes: msg.data.length,
+                        },
+                    });
+                }
+                const eof = msg.headers?.get(TRANSFER_EOF_HEADER) === "true";
+                if (eof && msg.data.length !== 0) {
+                    throw new TransferError({
+                        operation: "stream",
+                        context: {
+                            reason: "nonempty_eof",
+                            actualChunkBytes: msg.data.length,
+                        },
+                    });
+                }
+                if (!eof && msg.data.length > 0) {
+                    receivedBytes += msg.data.length;
+                    if (receivedBytes > grant.info.size) {
+                        throw new TransferError({
+                            operation: "stream",
+                            context: {
+                                reason: "size_mismatch",
+                                expectedBytes: grant.info.size,
+                                actualBytes: receivedBytes,
+                            },
+                        });
+                    }
+                    hasher.update(msg.data);
+                    controller.enqueue(msg.data);
+                }
+                if (eof) {
+                    if (receivedBytes !== grant.info.size) {
+                        throw new TransferError({
+                            operation: "stream",
+                            context: {
+                                reason: "size_mismatch",
+                                expectedBytes: grant.info.size,
+                                actualBytes: receivedBytes,
+                            },
+                        });
+                    }
+                    const digest = `SHA-256=${base64urlEncode(hasher.digest())}`;
+                    if (grant.info.digest.replace(/=+$/, "") !== digest.replace(/=+$/, "")) {
+                        throw new TransferError({
+                            operation: "stream",
+                            context: {
+                                reason: "digest_mismatch",
+                                expectedDigest: grant.info.digest,
+                                actualDigest: digest,
+                            },
+                        });
+                    }
+                    controller.close();
+                }
+            }
+            catch (cause) {
+                await cancelTransfer().catch(() => undefined);
+                const error = cause instanceof TransferError
+                    ? cause
+                    : new TransferError({ operation: "stream", cause });
+                controller.error(recordTransferError(error, "receive", "stream"));
+            }
+        },
+        async cancel() {
+            await cancelTransfer();
+        },
+    });
+}
+async function collectStream(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                const merged = new Uint8Array(total);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    merged.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                return Result.ok(merged);
+            }
+            chunks.push(next.value);
+            total += next.value.length;
+        }
+    }
+    catch (cause) {
+        return Result.err(cause instanceof TransferError
+            ? cause
+            : new TransferError({ operation: "bytes", cause }));
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+class BaseTransferHandle {
+    #nc;
+    #auth;
+    #timeoutMs;
+    #inboxPrefix;
+    constructor(nc, auth, timeoutMs, inboxPrefix = "_INBOX") {
+        this.#nc = nc;
+        this.#auth = auth;
+        this.#timeoutMs = timeoutMs;
+        this.#inboxPrefix = inboxPrefix;
+    }
+    get nc() {
+        return this.#nc;
+    }
+    get inboxPrefix() {
+        return this.#inboxPrefix;
+    }
+    get auth() {
+        return this.#auth;
+    }
+    get timeoutMs() {
+        return this.#timeoutMs;
+    }
+    validateGrant(grant, operation) {
+        if (expired(grant.expiresAt)) {
+            return Result.err(new TransferError({
+                operation,
+                context: { reason: "expired", transferId: grant.transferId },
+            }));
+        }
+        if (grant.sessionKey !== this.#auth.sessionKey) {
+            return Result.err(new TransferError({
+                operation,
+                context: {
+                    reason: "session_mismatch",
+                    expectedSessionKey: grant.sessionKey,
+                    actualSessionKey: this.#auth.sessionKey,
+                },
+            }));
+        }
+        return Result.ok(undefined);
+    }
+    async buildHeaders(subject, reply, payload, seq, control) {
+        const headers = natsHeaders();
+        const authHeaders = await createTransferProof(this.#auth, subject, reply, transferFrameProofPayload(seq ?? 0, control, payload));
+        headers.set("authorization-context", authHeaders.contextDigest);
+        headers.set("session-key", this.#auth.sessionKey);
+        headers.set("proof", authHeaders.proof);
+        headers.set("iat", String(authHeaders.iat));
+        headers.set("request-id", authHeaders.requestId);
+        if (seq !== undefined) {
+            headers.set(TRANSFER_SEQUENCE_HEADER, String(seq));
+        }
+        if (control !== undefined) {
+            headers.set(TRANSFER_CONTROL_HEADER, control);
+        }
+        injectTraceContext(createNatsHeaderCarrier(headers));
+        return headers;
+    }
+    async cancelTransfer(subject) {
+        const payload = new TextEncoder().encode(JSON.stringify({ action: "cancel" }));
+        const reply = createInbox(this.inboxPrefix);
+        const headers = await this.buildHeaders(subject, reply, payload, 0, "cancel");
+        const response = await requestTransfer(this.nc, subject, payload, headers, reply, this.timeoutMs);
+        const ack = parseTransferAck(response, "cancel").take();
+        if (isErr(ack) || ack.status !== "cancelled") {
+            throw isErr(ack) ? ack.error : new TransferError({
+                operation: "cancel",
+                context: { reason: "not_acknowledged" },
+            });
+        }
+    }
+}
+export class SendTransferHandle extends BaseTransferHandle {
+    #grant;
+    constructor(nc, auth, timeoutMs, grant, inboxPrefix = "_INBOX") {
+        super(nc, auth, timeoutMs, inboxPrefix);
+        this.#grant = grant;
+    }
+    send(body) {
+        return AsyncResult.from((async () => {
+            const valid = this.validateGrant(this.#grant, "send").take();
+            if (isErr(valid)) {
+                return Result.err(recordTransferError(valid.error, "send", "grant"));
+            }
+            let sentBytes = 0;
+            let seq = 0;
+            const hasher = incrementalSha256.create();
+            const abort = () => this.cancelTransfer(this.#grant.subject).catch(() => { });
+            try {
+                for await (const chunk of chunkBody(body, this.#grant.chunkBytes)) {
+                    sentBytes += chunk.length;
+                    if (this.#grant.maxBytes !== undefined &&
+                        sentBytes > this.#grant.maxBytes) {
+                        await abort();
+                        return Result.err(recordTransferError(new TransferError({
+                            operation: "send",
+                            context: {
+                                reason: "max_bytes_exceeded",
+                                maxBytes: this.#grant.maxBytes,
+                                attemptedBytes: sentBytes,
+                            },
+                        }), "send", "validation"));
+                    }
+                    const reply = createInbox(this.inboxPrefix);
+                    const headers = await this.buildHeaders(this.#grant.subject, reply, chunk, seq, undefined);
+                    const response = await AsyncResult.try(() => requestTransfer(this.nc, this.#grant.subject, chunk, headers, reply, this.timeoutMs)).take();
+                    if (isErr(response)) {
+                        await abort();
+                        return Result.err(recordTransferError(new TransferError({
+                            operation: "send",
+                            cause: response.error,
+                        }), "send", "send"));
+                    }
+                    const ack = parseTransferAck(response, "send").take();
+                    if (isErr(ack)) {
+                        await abort();
+                        return Result.err(recordTransferError(ack.error, "send", "ack"));
+                    }
+                    if (ack.status === "complete") {
+                        await abort();
+                        return Result.err(recordTransferError(new TransferError({
+                            operation: "send",
+                            context: { reason: "premature_completion" },
+                        }), "send", "ack"));
+                    }
+                    hasher.update(chunk);
+                    seq += 1;
+                }
+            }
+            catch (cause) {
+                await abort();
+                return Result.err(recordTransferError(new TransferError({ operation: "send", cause }), "send", "source"));
+            }
+            const sentDigest = `SHA-256=${base64urlEncode(hasher.digest())}`;
+            const completion = new TextEncoder().encode(JSON.stringify({
+                action: "complete",
+                size: sentBytes,
+                digest: sentDigest,
+            }));
+            const reply = createInbox(this.inboxPrefix);
+            const finalHeaders = await this.buildHeaders(this.#grant.subject, reply, completion, seq, "complete");
+            const finalResponse = await AsyncResult.try(() => requestTransfer(this.nc, this.#grant.subject, completion, finalHeaders, reply, this.timeoutMs)).take();
+            if (isErr(finalResponse)) {
+                return Result.err(recordTransferError(new TransferError({
+                    operation: "send",
+                    cause: finalResponse.error,
+                }), "send", "send"));
+            }
+            const finalAck = parseTransferAck(finalResponse, "send").take();
+            if (isErr(finalAck)) {
+                return Result.err(recordTransferError(finalAck.error, "send", "ack"));
+            }
+            if (finalAck.status !== "complete") {
+                return Result.err(recordTransferError(new TransferError({
+                    operation: "send",
+                    context: { reason: "missing_completion" },
+                }), "send", "ack"));
+            }
+            if (finalAck.info.size !== sentBytes ||
+                finalAck.info.digest?.replace(/=+$/, "") !==
+                    sentDigest.replace(/=+$/, "")) {
+                return Result.err(recordTransferError(new TransferError({
+                    operation: "send",
+                    context: {
+                        reason: "result_metadata_mismatch",
+                        expectedSize: sentBytes,
+                        actualSize: finalAck.info.size,
+                        expectedDigest: sentDigest,
+                        actualDigest: finalAck.info.digest,
+                    },
+                }), "send", "ack"));
+            }
+            return Result.ok(finalAck.info);
+        })());
+    }
+}
+export class ReceiveTransferHandle extends BaseTransferHandle {
+    #grant;
+    constructor(nc, auth, timeoutMs, grant, inboxPrefix = "_INBOX") {
+        super(nc, auth, timeoutMs, inboxPrefix);
+        this.#grant = grant;
+    }
+    stream() {
+        return AsyncResult.from((async () => {
+            const valid = this.validateGrant(this.#grant, "stream").take();
+            if (isErr(valid)) {
+                return Result.err(recordTransferError(valid.error, "receive", "grant"));
+            }
+            return Result.ok(receiveStream(this.#grant, async (seq) => {
+                const payload = new Uint8Array();
+                const reply = createInbox(this.inboxPrefix);
+                const headers = await this.buildHeaders(this.#grant.subject, reply, payload, seq, undefined);
+                return await requestTransfer(this.nc, this.#grant.subject, payload, headers, reply, this.timeoutMs);
+            }, () => this.cancelTransfer(this.#grant.subject)));
+        })());
+    }
+    bytes() {
+        return AsyncResult.from((async () => {
+            const streamResult = await this.stream().take();
+            if (isErr(streamResult)) {
+                return Result.err(streamResult.error);
+            }
+            return await collectStream(streamResult);
+        })());
+    }
+}
+export function createTransferHandle(nc, auth, timeoutMs, grant, inboxPrefix = "_INBOX") {
+    return grant.direction === "send"
+        ? new SendTransferHandle(nc, auth, timeoutMs, grant, inboxPrefix)
+        : new ReceiveTransferHandle(nc, auth, timeoutMs, grant, inboxPrefix);
+}

package/transfer_protocol.d.ts

@@ -0,0 +1 @@
+export declare function transferFrameProofPayload(seq: number, control: string | undefined, payload: Uint8Array): Uint8Array;

package/transfer_protocol.js

@@ -0,0 +1,13 @@
+const TRANSFER_FRAME_PROOF_DOMAIN = new TextEncoder().encode("trellis.transfer.v1.frame\0");
+export function transferFrameProofPayload(seq, control, payload) {
+    const controlBytes = new TextEncoder().encode(control ?? "");
+    const framed = new Uint8Array(TRANSFER_FRAME_PROOF_DOMAIN.length + 8 + 4 + controlBytes.length +
+        payload.length);
+    framed.set(TRANSFER_FRAME_PROOF_DOMAIN);
+    const view = new DataView(framed.buffer);
+    view.setBigUint64(TRANSFER_FRAME_PROOF_DOMAIN.length, BigInt(seq));
+    view.setUint32(TRANSFER_FRAME_PROOF_DOMAIN.length + 8, controlBytes.length);
+    framed.set(controlBytes, TRANSFER_FRAME_PROOF_DOMAIN.length + 12);
+    framed.set(payload, TRANSFER_FRAME_PROOF_DOMAIN.length + 12 + controlBytes.length);
+    return framed;
+}