@filefreak.io/sdk 0.3.0 → 0.3.1

package/dist/generated.d.ts

@@ -436,8 +436,8 @@ export type UsageGetAnswer = {
         plan: string;
         storageUsedBytes: number;
         storageIncludedBytes: number;
-        /** Where uploads are refused: what the plan includes, plus what the account's spending limit allows beyond it. */
-        storageLimitBytes: number;
+        /** Where uploads are refused: what the plan includes, plus what the account's spending limit allows beyond it. Null when nothing is: Pro that FileFreak has given the account has no storage limit. */
+        storageLimitBytes: number | null;
         downloadedBytesThisMonth: number;
         downloadsIncludedBytes: number;
         apiCallsThisMonth: number;

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { FileFreak, Walk, type DownloadOptions, type FollowOptions } from "./cli
 export * from "./generated.js";
 export { get, type GetOptions, type Got, type Into, type LinkedFile } from "./links.js";
 export { type Sink } from "./ranges.js";
-export { openFragment, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, ShardError, shardKey, ShardLayout, type FragmentAt, type ShardErrorCode, type ShardKey, } from "./shards.js";
+export { checkOutline, fileKeys, MOST_BLOCK_BYTES, openBlock, openFragment, outlineMac, sealBlock, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, ShardError, shardKey, ShardLayout, type FileKeys, type FragmentAt, type Outline, type OutlineBlock, type ShardErrorCode, type ShardKey, } from "./shards.js";
 export { FileFreakError, type CallOptions, type ClientOptions, type TokenSource } from "./transport.js";
 export { UploadStopped, type Source, type UploadOptions } from "./uploads.js";

package/dist/index.js

@@ -12,6 +12,6 @@
 export { FileFreak, Walk } from "./client.js";
 export * from "./generated.js";
 export { get } from "./links.js";
-export { openFragment, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, ShardError, shardKey, ShardLayout, } from "./shards.js";
+export { checkOutline, fileKeys, MOST_BLOCK_BYTES, openBlock, openFragment, outlineMac, sealBlock, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, ShardError, shardKey, ShardLayout, } from "./shards.js";
 export { FileFreakError } from "./transport.js";
 export { UploadStopped } from "./uploads.js";

package/dist/shards.d.ts

@@ -4,9 +4,10 @@ export declare const SHARD_OVERHEAD = 29;
 /**
  * Why a fragment or a description was refused. A reader checks in this
  * order, and says the first that fails: short, version, length,
- * authentication. layout is a description of a file no fragment can match.
+ * authentication, and in version 2 id. layout is a description of a file no
+ * fragment can match; outline is a version-2 outline whose MAC does not hold.
  */
-export type ShardErrorCode = "short" | "version" | "length" | "authentication" | "layout";
+export type ShardErrorCode = "short" | "version" | "length" | "authentication" | "id" | "layout" | "outline";
 export declare class ShardError extends Error {
     readonly code: ShardErrorCode;
     constructor(code: ShardErrorCode, message: string);
@@ -57,3 +58,61 @@ export declare function sealWithNonce(key: ShardKey, at: FragmentAt, plaintext:
  * returned: WebCrypto gives no plaintext until the tag has been checked.
  */
 export declare function openFragment(key: ShardKey, at: FragmentAt, blob: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+export declare const SHARD_VERSION_2 = 2;
+/** The most bytes of a file one block holds, as the API takes blocks. */
+export declare const MOST_BLOCK_BYTES: number;
+/** A block id: the HMAC-SHA256 of its bytes under the file's block key. */
+export declare const BLOCK_ID_BYTES = 32;
+/**
+ * A file's key in version 2, as the three keys derived from it: never the
+ * key itself, so that sealing, naming blocks and vouching for the outline
+ * cannot be played against each other.
+ */
+export interface FileKeys {
+    seal: ShardKey;
+    block: ShardKey;
+    outline: ShardKey;
+}
+/** One block as an outline gives it: its id and how many bytes of the file it holds. */
+export interface OutlineBlock {
+    id: Uint8Array;
+    length: number;
+}
+/** What a content in version 2 is, as its outline gives it, before any block is fetched. */
+export interface Outline {
+    contentId: string;
+    size: number;
+    blocks: OutlineBlock[];
+}
+/** The three keys of a file's key: HKDF-SHA256 with no salt, each named by its use. */
+export declare function fileKeys(raw: Uint8Array): Promise<FileKeys>;
+/** A block's id: what the map holds in place of a hash anybody could make of the same bytes. */
+export declare function blockId(keys: FileKeys, plaintext: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+/** The bytes a block's tag also covers: the label and its id, and nothing about where it is, so that a later version can keep it as it is. */
+export declare function blockAssociatedData(id: Uint8Array): Uint8Array<ArrayBuffer>;
+/** One block, encrypted and ready to store under a nonce of its own, with its id. */
+export declare function sealBlock(keys: FileKeys, plaintext: Uint8Array): Promise<{
+    id: Uint8Array<ArrayBuffer>;
+    blob: Uint8Array<ArrayBuffer>;
+}>;
+/**
+ * sealBlock with the id and the nonce chosen by the caller, which only the
+ * test files may do, as with sealWithNonce. Not exported from the package.
+ */
+export declare function sealBlockWithNonce(keys: FileKeys, id: Uint8Array, plaintext: Uint8Array, nonce: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * A stored block's bytes of the file, once it is known to be the block the
+ * outline names, unchanged: in this order, short, version, length,
+ * authentication (the tag, which binds it to its id), and id (that its
+ * bytes are the ones the id was made of). Nothing of a block that fails is
+ * returned.
+ */
+export declare function openBlock(keys: FileKeys, block: OutlineBlock, blob: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+/** The outline's MAC, which the writer sends with the upload's completion and every reader checks before it releases a byte. */
+export declare function outlineMac(keys: FileKeys, outline: Outline): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Refuse an outline unless its MAC holds under the file's key: whoever has
+ * the map and not the key cannot reorder, drop, repeat or swap a content's
+ * blocks, or give one content's blocks as another's.
+ */
+export declare function checkOutline(keys: FileKeys, outline: Outline, mac: Uint8Array): Promise<void>;

package/dist/shards.js

@@ -1,9 +1,13 @@
-// The shard format, version 1: how a file under Shard Protection is kept, as
-// fragments each encrypted on its own. docs/reference/shard-format.md is the
-// definition, and docs/reference/shard-format-v1.json holds the test files
-// this is checked against (test/shards.test.ts), as the CLI's copy is: a
-// writer here whose bytes differ by one from the CLI's makes files the CLI
-// cannot read, and the reverse.
+// The shard format: how a file under Shard Protection is kept, as fragments
+// each encrypted on its own. Version 1 cuts a content into fragments of one
+// size, each sealed to its content's own key, id, place and count. Version 2
+// cuts it into blocks by content, sealed under a key the file's versions
+// share, so that a block a new version still has can be kept as it is.
+// docs/reference/shard-format.md is the definition, and
+// docs/reference/shard-format-v1.json and -v2.json hold the test files this
+// is checked against (test/shards.test.ts), as the CLI's copy is: a writer
+// here whose bytes differ by one from the CLI's makes files the CLI cannot
+// read, and the reverse.
 //
 // WebCrypto, so the same code runs in a page, in a worker and in Node.
 export const SHARD_VERSION = 1;
@@ -128,6 +132,158 @@ export async function openFragment(key, at, blob) {
     }
     return new Uint8Array(plain);
 }
+// ---------------------------------------------------------------------------
+// Version 2: blocks cut by content, under a file's key that versions share
+// ---------------------------------------------------------------------------
+export const SHARD_VERSION_2 = 2;
+/** The most bytes of a file one block holds, as the API takes blocks. */
+export const MOST_BLOCK_BYTES = 64 * 1024 * 1024;
+/** A block id: the HMAC-SHA256 of its bytes under the file's block key. */
+export const BLOCK_ID_BYTES = 32;
+const LABEL_2 = new TextEncoder().encode("filefreak-shard-v2");
+const OUTLINE_LABEL = new TextEncoder().encode("filefreak-outline-v2");
+/** The three keys of a file's key: HKDF-SHA256 with no salt, each named by its use. */
+export async function fileKeys(raw) {
+    if (raw.length !== 32)
+        throw new RangeError(`A shard key is 32 bytes, not ${raw.length}.`);
+    const base = await crypto.subtle.importKey("raw", new Uint8Array(raw), "HKDF", false, ["deriveBits"]);
+    const derive = (use) => crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: new TextEncoder().encode(`filefreak-shard-v2 ${use}`) }, base, 256);
+    const [seal, block, outline] = await Promise.all([derive("seal"), derive("block"), derive("outline")]);
+    const hmac = (raw) => crypto.subtle.importKey("raw", raw, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+    return {
+        seal: await crypto.subtle.importKey("raw", seal, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]),
+        block: await hmac(block),
+        outline: await hmac(outline),
+    };
+}
+/** A block's id: what the map holds in place of a hash anybody could make of the same bytes. */
+export async function blockId(keys, plaintext) {
+    return new Uint8Array(await crypto.subtle.sign("HMAC", keys.block, new Uint8Array(plaintext)));
+}
+/** The bytes a block's tag also covers: the label and its id, and nothing about where it is, so that a later version can keep it as it is. */
+export function blockAssociatedData(id) {
+    if (id.length !== BLOCK_ID_BYTES)
+        throw new RangeError(`A block id is ${BLOCK_ID_BYTES} bytes, not ${id.length}.`);
+    const out = new Uint8Array(LABEL_2.length + BLOCK_ID_BYTES);
+    out.set(LABEL_2, 0);
+    out.set(id, LABEL_2.length);
+    return out;
+}
+/** One block, encrypted and ready to store under a nonce of its own, with its id. */
+export async function sealBlock(keys, plaintext) {
+    const id = await blockId(keys, plaintext);
+    return { id, blob: await sealBlockWithNonce(keys, id, plaintext, crypto.getRandomValues(new Uint8Array(NONCE_BYTES))) };
+}
+/**
+ * sealBlock with the id and the nonce chosen by the caller, which only the
+ * test files may do, as with sealWithNonce. Not exported from the package.
+ */
+export async function sealBlockWithNonce(keys, id, plaintext, nonce) {
+    if (plaintext.length > MOST_BLOCK_BYTES)
+        throw new ShardError("length", `A block holds at most ${MOST_BLOCK_BYTES} bytes of the file, not ${plaintext.length}.`);
+    if (nonce.length !== NONCE_BYTES)
+        throw new RangeError(`A nonce is ${NONCE_BYTES} bytes, not ${nonce.length}.`);
+    const iv = new Uint8Array(nonce);
+    const sealed = await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: blockAssociatedData(id), tagLength: 128 }, keys.seal, new Uint8Array(plaintext));
+    const out = new Uint8Array(HEADER_BYTES + sealed.byteLength);
+    out[0] = SHARD_VERSION_2;
+    out.set(iv, 1);
+    out.set(new Uint8Array(sealed), HEADER_BYTES);
+    return out;
+}
+/**
+ * A stored block's bytes of the file, once it is known to be the block the
+ * outline names, unchanged: in this order, short, version, length,
+ * authentication (the tag, which binds it to its id), and id (that its
+ * bytes are the ones the id was made of). Nothing of a block that fails is
+ * returned.
+ */
+export async function openBlock(keys, block, blob) {
+    const named = hexOf(block.id).slice(0, 12);
+    if (blob.length < SHARD_OVERHEAD) {
+        throw new ShardError("short", `Block ${named} is ${blob.length} bytes, shorter than any block can be (${SHARD_OVERHEAD}).`);
+    }
+    if (blob[0] !== SHARD_VERSION_2) {
+        throw new ShardError("version", `Block ${named} is in version ${blob[0]} of the format, where version ${SHARD_VERSION_2} was expected.`);
+    }
+    if (blob.length !== block.length + SHARD_OVERHEAD) {
+        throw new ShardError("length", `Block ${named} is ${blob.length} bytes, and holding ${block.length} bytes of the file it would be ${block.length + SHARD_OVERHEAD}.`);
+    }
+    let plain;
+    try {
+        plain = await crypto.subtle.decrypt({ name: "AES-GCM", iv: new Uint8Array(blob.subarray(1, HEADER_BYTES)), additionalData: blockAssociatedData(block.id), tagLength: 128 }, keys.seal, new Uint8Array(blob.subarray(HEADER_BYTES)));
+    }
+    catch (e) {
+        if (e instanceof DOMException && e.name === "OperationError") {
+            throw new ShardError("authentication", `Block ${named} is not what was written as this file's block ${named}: it has been changed, or it belongs to another file or block.`);
+        }
+        throw e;
+    }
+    const bytes = new Uint8Array(plain);
+    // The tag says somebody with the key sealed these bytes under this id; this says the id is theirs.
+    if (!(await crypto.subtle.verify("HMAC", keys.block, new Uint8Array(block.id), bytes))) {
+        throw new ShardError("id", `Block ${named} opens, but its bytes are not the ones its id was made of.`);
+    }
+    return bytes;
+}
+/** Refuse an outline that describes no file: no blocks, a block too long, an empty block in a file that is not empty, or lengths that do not add up. */
+function checkShape(outline) {
+    const { size, blocks } = outline;
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new ShardError("layout", `A file's size is a whole number of bytes, not ${size}.`);
+    if (blocks.length === 0)
+        throw new ShardError("layout", "An outline names at least one block: an empty file is one empty block.");
+    if (blocks.length > MOST_FRAGMENTS)
+        throw new ShardError("layout", `An outline of ${blocks.length} blocks is more than the format can number.`);
+    let total = 0;
+    for (const [place, b] of blocks.entries()) {
+        if (b.id.length !== BLOCK_ID_BYTES)
+            throw new ShardError("layout", `Block ${place}'s id is ${b.id.length} bytes, not ${BLOCK_ID_BYTES}.`);
+        if (!Number.isSafeInteger(b.length) || b.length < 0 || b.length > MOST_BLOCK_BYTES) {
+            throw new ShardError("layout", `Block ${place} holds ${b.length} bytes, outside 0 to ${MOST_BLOCK_BYTES}.`);
+        }
+        if (b.length === 0 && size > 0)
+            throw new ShardError("layout", `Block ${place} is empty, and only an empty file has an empty block.`);
+        total += b.length;
+    }
+    if (total !== size)
+        throw new ShardError("layout", `The blocks hold ${total} bytes, and the file is ${size}.`);
+}
+/** The bytes the outline's MAC is over: the label, the content id, the size, the count, and each block's id and length in order. */
+function outlineBytes(outline) {
+    const head = OUTLINE_LABEL.length + 16 + 8 + 4;
+    const out = new Uint8Array(head + outline.blocks.length * (BLOCK_ID_BYTES + 4));
+    const view = new DataView(out.buffer);
+    out.set(OUTLINE_LABEL, 0);
+    out.set(uuidBytes(outline.contentId), OUTLINE_LABEL.length);
+    view.setBigUint64(OUTLINE_LABEL.length + 16, BigInt(outline.size), false);
+    view.setUint32(OUTLINE_LABEL.length + 24, outline.blocks.length, false);
+    for (const [i, b] of outline.blocks.entries()) {
+        const at = head + i * (BLOCK_ID_BYTES + 4);
+        out.set(b.id, at);
+        view.setUint32(at + BLOCK_ID_BYTES, b.length, false);
+    }
+    return out;
+}
+/** The outline's MAC, which the writer sends with the upload's completion and every reader checks before it releases a byte. */
+export async function outlineMac(keys, outline) {
+    checkShape(outline);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", keys.outline, outlineBytes(outline)));
+}
+/**
+ * Refuse an outline unless its MAC holds under the file's key: whoever has
+ * the map and not the key cannot reorder, drop, repeat or swap a content's
+ * blocks, or give one content's blocks as another's.
+ */
+export async function checkOutline(keys, outline, mac) {
+    checkShape(outline);
+    if (!(await crypto.subtle.verify("HMAC", keys.outline, new Uint8Array(mac), outlineBytes(outline)))) {
+        throw new ShardError("outline", "The file's outline is not what was written for it: its blocks have been reordered, dropped or swapped, or it is another file's.");
+    }
+}
+function hexOf(b) {
+    return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}
 function uuidBytes(id) {
     if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
         throw new RangeError(`A content id is a UUID, and ${JSON.stringify(id)} is not one.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@filefreak.io/sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "FileFreak's developer API for Node and the browser: every endpoint, uploads straight to storage in parts, downloads in ranges, and the changes to follow.",
   "license": "Apache-2.0",
   "homepage": "https://filefreak.io/developers/reference",