@filefreak.io/sdk 0.0.0-stage → 0.2.0

package/dist/shards.js

@@ -0,0 +1,140 @@
+// 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.
+//
+// WebCrypto, so the same code runs in a page, in a worker and in Node.
+export const SHARD_VERSION = 1;
+/** What a stored fragment adds to the bytes of the file it holds: the version byte, the nonce and the tag. */
+export const SHARD_OVERHEAD = 29;
+const NONCE_BYTES = 12;
+const HEADER_BYTES = 1 + NONCE_BYTES;
+const LABEL = new TextEncoder().encode("filefreak-shard-v1");
+/** The associated data numbers places and the count in 32 bits. */
+const MOST_FRAGMENTS = 0xffff_ffff;
+export class ShardError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ShardError";
+    }
+}
+/** How a file of `size` bytes is cut into fragments of `fragmentSize`, which the API chooses. */
+export class ShardLayout {
+    size;
+    fragmentSize;
+    count;
+    constructor(size, fragmentSize) {
+        this.size = size;
+        this.fragmentSize = fragmentSize;
+        if (!Number.isSafeInteger(size) || size < 0)
+            throw new ShardError("layout", `A file's size is a whole number of bytes, not ${size}.`);
+        if (!Number.isSafeInteger(fragmentSize) || fragmentSize < 1) {
+            throw new ShardError("layout", `A fragment holds at least one byte of the file, not ${fragmentSize}.`);
+        }
+        // BigInt, so a size past 2^32 is divided exactly; an empty file is one
+        // empty fragment, so that even it has something to authenticate.
+        const count = size === 0 ? 1 : Number((BigInt(size) + BigInt(fragmentSize) - 1n) / BigInt(fragmentSize));
+        if (count > MOST_FRAGMENTS) {
+            throw new ShardError("layout", `A file of ${size} bytes in fragments of ${fragmentSize} is ${count} fragments, more than the format can number.`);
+        }
+        this.count = count;
+    }
+    /** Where in the file fragment `place` begins, and where it ends (exclusive). */
+    range(place) {
+        if (!Number.isInteger(place) || place < 0 || place >= this.count) {
+            throw new RangeError(`There is no fragment ${place}: this file has ${this.count}, numbered from 0.`);
+        }
+        const start = place * this.fragmentSize;
+        return { start, end: Math.min(start + this.fragmentSize, this.size) };
+    }
+    /** How many bytes of the file fragment `place` holds. */
+    length(place) {
+        const { start, end } = this.range(place);
+        return end - start;
+    }
+}
+/** A content's key, 32 bytes, made usable for its fragments and nothing else. */
+export function shardKey(raw) {
+    if (raw.length !== 32)
+        throw new RangeError(`A shard key is 32 bytes, not ${raw.length}.`);
+    return crypto.subtle.importKey("raw", new Uint8Array(raw), { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+/** The bytes a fragment's tag also covers: the label, the content id, the place and the count. */
+export function associatedData(at) {
+    const out = new Uint8Array(LABEL.length + 16 + 8);
+    out.set(LABEL, 0);
+    out.set(uuidBytes(at.contentId), LABEL.length);
+    const view = new DataView(out.buffer);
+    view.setUint32(LABEL.length + 16, at.place, false);
+    view.setUint32(LABEL.length + 20, at.layout.count, false);
+    return out;
+}
+/** One fragment of a file, encrypted and ready to store, under a nonce of its own. */
+export function sealFragment(key, at, plaintext) {
+    return sealWithNonce(key, at, plaintext, crypto.getRandomValues(new Uint8Array(NONCE_BYTES)));
+}
+/**
+ * sealFragment with the nonce chosen by the caller, which only the test
+ * files may do: two fragments sealed under one key with one nonce give away
+ * the difference between them, and the key's authentication with it. It is
+ * not exported from the package.
+ */
+export async function sealWithNonce(key, at, plaintext, nonce) {
+    const expected = at.layout.length(at.place);
+    if (plaintext.length !== expected) {
+        throw new ShardError("length", `Fragment ${at.place} holds ${expected} 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: associatedData(at), tagLength: 128 }, key, new Uint8Array(plaintext));
+    const out = new Uint8Array(HEADER_BYTES + sealed.byteLength);
+    out[0] = SHARD_VERSION;
+    out.set(iv, 1);
+    out.set(new Uint8Array(sealed), HEADER_BYTES);
+    return out;
+}
+/**
+ * A stored fragment's bytes of the file, once it is known to be this file's
+ * fragment at this place, unchanged. Nothing of a fragment that fails is
+ * returned: WebCrypto gives no plaintext until the tag has been checked.
+ */
+export async function openFragment(key, at, blob) {
+    const expected = at.layout.length(at.place);
+    if (blob.length < SHARD_OVERHEAD) {
+        throw new ShardError("short", `Fragment ${at.place} is ${blob.length} bytes, shorter than any fragment can be (${SHARD_OVERHEAD}).`);
+    }
+    if (blob[0] !== SHARD_VERSION) {
+        throw new ShardError("version", `Fragment ${at.place} is in version ${blob[0]} of the format, which this version of the SDK cannot read.`);
+    }
+    if (blob.length !== expected + SHARD_OVERHEAD) {
+        throw new ShardError("length", `Fragment ${at.place} is ${blob.length} bytes, and holding ${expected} bytes of the file it would be ${expected + SHARD_OVERHEAD}.`);
+    }
+    let plain;
+    try {
+        plain = await crypto.subtle.decrypt({ name: "AES-GCM", iv: new Uint8Array(blob.subarray(1, HEADER_BYTES)), additionalData: associatedData(at), tagLength: 128 }, key, new Uint8Array(blob.subarray(HEADER_BYTES)));
+    }
+    catch (e) {
+        // OperationError is WebCrypto's one answer to a tag that does not match.
+        // Anything else (a key made for something else) is not the fragment's fault.
+        if (e instanceof DOMException && e.name === "OperationError") {
+            throw new ShardError("authentication", `Fragment ${at.place} is not what was written as this file's fragment ${at.place}: it has been changed, or it belongs to another file or place.`);
+        }
+        throw e;
+    }
+    return new Uint8Array(plain);
+}
+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.`);
+    }
+    const hex = id.replaceAll("-", "");
+    const out = new Uint8Array(16);
+    for (let i = 0; i < 16; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}

package/dist/transport.d.ts

@@ -0,0 +1,61 @@
+/** A refusal from the API, or a request that could not be answered at all. Branch on `code`, which does not change; `message` is for a person. */
+export declare class FileFreakError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body: Record<string, unknown> | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(status: number, code: string, message: string, body?: Record<string, unknown> | null, retryAfterSeconds?: number | null);
+}
+/** A token as a string, or a function that fetches a fresh one from the developer's own server. */
+export type TokenSource = string | (() => Promise<string>);
+export interface ClientOptions {
+    /** An app's key, for a program on a server. Never put one in a web page: the API refuses a key sent from one. */
+    apiKey?: string;
+    /** For a web page: a token the developer's server made with POST /v1/tokens, or a function that asks the server for one. */
+    token?: TokenSource;
+    /** Where the API is. */
+    baseUrl?: string;
+    /** Another fetch, for a runtime without one or for tests. */
+    fetch?: typeof fetch;
+    /** How many times a request that failed for a passing reason is sent again. */
+    retries?: number;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+    /** For an endpoint that makes something: the caller's own key, so that the same request sent later, even from another process, makes nothing twice. */
+    idempotencyKey?: string;
+}
+export interface Request {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, unknown> | undefined;
+    body?: unknown;
+    /** The endpoint honours an Idempotency-Key. */
+    idempotent?: boolean;
+    /** The endpoint says it is safe to call again (finishing an upload). */
+    repeatable?: boolean;
+    options?: CallOptions;
+}
+export interface Response<T> {
+    status: number;
+    body: T;
+    headers: Headers;
+}
+export declare const DEFAULT_BASE_URL = "https://api.filefreak.io";
+/** Waits, or stops waiting when the signal is aborted. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** A wait that doubles with each try, with some spread so that many clients do not come back at once. */
+export declare function backoff(attempt: number): number;
+export declare class Transport {
+    readonly baseUrl: string;
+    private readonly fetcher;
+    private readonly retries;
+    private readonly apiKey;
+    private readonly tokenSource;
+    private token;
+    constructor(options: ClientOptions);
+    /** Another fetch, for reaching storage with the same retries and runtime. */
+    get fetch(): typeof fetch;
+    private credential;
+    send<T>(request: Request): Promise<Response<T>>;
+}

package/dist/transport.js

@@ -0,0 +1,173 @@
+// How every call reaches the API: the address, the key or token, and what is
+// done when an answer is not the one wanted.
+//
+// Sending a request again is where a client makes something twice, so the
+// rule is narrow. A request is sent again only when that cannot do anything
+// twice: a read; a request carrying an Idempotency-Key, which the API answers
+// once (every endpoint that makes something takes one, and one is made here
+// when the caller gave none); or an answer that says the API did nothing,
+// 429 (too many) and 503 waking_up (the database is starting). Retry-After is
+// honoured.
+/** A refusal from the API, or a request that could not be answered at all. Branch on `code`, which does not change; `message` is for a person. */
+export class FileFreakError extends Error {
+    status;
+    code;
+    body;
+    retryAfterSeconds;
+    constructor(status, code, message, body = null, retryAfterSeconds = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "FileFreakError";
+    }
+}
+export const DEFAULT_BASE_URL = "https://api.filefreak.io";
+const DEFAULT_RETRIES = 4;
+/** The longest wait between tries, whatever Retry-After says. */
+const MOST_WAIT_MS = 60_000;
+/** A sleeping database takes about a minute to start. Five minutes of asking is plenty. */
+const WAKING_TRIES = 60;
+/** Waits, or stops waiting when the signal is aborted. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(done, ms);
+        function done() {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }
+        function stop() {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+/** A wait that doubles with each try, with some spread so that many clients do not come back at once. */
+export function backoff(attempt) {
+    return Math.min(MOST_WAIT_MS, 500 * 2 ** attempt) * (0.5 + Math.random() / 2);
+}
+function randomKey() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function search(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        params.set(name, String(value));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : "";
+}
+export class Transport {
+    baseUrl;
+    fetcher;
+    retries;
+    apiKey;
+    tokenSource;
+    token = null;
+    constructor(options) {
+        if (!options.apiKey === !options.token)
+            throw new Error("Give the client an apiKey (on a server) or a token (in a web page), and not both.");
+        this.apiKey = options.apiKey ?? null;
+        this.tokenSource = options.token ?? null;
+        this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+        // Bound, because a fetch taken off globalThis and called on its own loses `this` in some browsers.
+        this.fetcher = options.fetch ?? fetch.bind(globalThis);
+        this.retries = options.retries ?? DEFAULT_RETRIES;
+    }
+    /** Another fetch, for reaching storage with the same retries and runtime. */
+    get fetch() {
+        return this.fetcher;
+    }
+    async credential(fresh) {
+        if (this.apiKey)
+            return this.apiKey;
+        const source = this.tokenSource;
+        if (typeof source === "string")
+            return source;
+        if (fresh || !this.token) {
+            this.token = source();
+            // A failed fetch of a token is not kept, so the next call asks again.
+            this.token.catch(() => (this.token = null));
+        }
+        return await this.token;
+    }
+    async send(request) {
+        const options = request.options ?? {};
+        const key = request.idempotent ? options.idempotencyKey || randomKey() : undefined;
+        const safe = request.method === "GET" || key !== undefined || request.repeatable === true;
+        const url = `${this.baseUrl}${request.path}${search(request.query)}`;
+        let refreshed = false;
+        let waking = 0;
+        for (let attempt = 0;; attempt++) {
+            const headers = { Authorization: `Bearer ${await this.credential(false)}`, Accept: "application/json" };
+            if (key)
+                headers["Idempotency-Key"] = key;
+            if (request.body !== undefined)
+                headers["Content-Type"] = "application/json";
+            let res;
+            try {
+                res = await this.fetcher(url, {
+                    method: request.method,
+                    headers,
+                    body: request.body === undefined ? undefined : JSON.stringify(request.body),
+                    signal: options.signal,
+                });
+            }
+            catch (e) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                // Nothing came back. Whether the API did anything is unknown, so only
+                // a request that cannot do anything twice is sent again.
+                if (!safe || attempt >= this.retries)
+                    throw new FileFreakError(0, "network_error", `The API could not be reached: ${e instanceof Error ? e.message : String(e)}`);
+                await sleep(backoff(attempt), options.signal);
+                continue;
+            }
+            const text = await res.text();
+            let body = null;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                body = text;
+            }
+            if (res.ok)
+                return { status: res.status, body: body, headers: res.headers };
+            const error = body && typeof body === "object" ? body : null;
+            const code = typeof error?.error === "string" ? error.error : `http_${res.status}`;
+            const message = typeof error?.message === "string" ? error.message : `The API answered ${res.status}.`;
+            // Not Number(header) alone: a missing header is null, and Number(null) is 0.
+            const header = res.headers.get("retry-after");
+            const after = header === null ? NaN : Number(header);
+            const retryAfter = Number.isFinite(after) && after >= 0 ? after : null;
+            const refusal = new FileFreakError(res.status, code, message, error, retryAfter);
+            if (res.status === 401 && code === "token_expired" && typeof this.tokenSource === "function" && !refreshed) {
+                refreshed = true;
+                await this.credential(true);
+                attempt--;
+                continue;
+            }
+            if (res.status === 503 && code === "waking_up" && waking < WAKING_TRIES) {
+                waking++;
+                attempt--;
+                await sleep(Math.min(MOST_WAIT_MS, (retryAfter ?? 5) * 1000), options.signal);
+                continue;
+            }
+            // Refused before anything was done, or a server between here and the API that failed.
+            const passing = res.status === 429 || (safe && (res.status === 502 || res.status === 503 || res.status === 504));
+            if (!passing || attempt >= this.retries)
+                throw refusal;
+            await sleep(retryAfter !== null ? Math.min(MOST_WAIT_MS, retryAfter * 1000) : backoff(attempt), options.signal);
+        }
+    }
+}

package/dist/uploads.d.ts

@@ -0,0 +1,53 @@
+import type { FilesGetAnswer, Item, Upload, UploadsBeginAnswer, UploadsBeginBody, UploadsCompleteAnswer, UploadsCompleteBody, UploadsGetAnswer, UploadsPartsAnswer, UploadsPartsQuery } from "./generated.js";
+import { type CallOptions } from "./transport.js";
+/** What can be uploaded. A File's name and type are used when none are given. */
+export type Source = Blob | ArrayBuffer | Uint8Array;
+export interface UploadOptions {
+    /** The name to store it under. Left out, a File's own name. */
+    name?: string;
+    /** The folder to put it in. Null, or left out, for the top. */
+    parentId?: string | null;
+    /** What to do if the folder already has a file of that name. */
+    onConflict?: "rename" | "replace" | "fail";
+    /** With onConflict "replace": the file as it was read. Anything else there, or this file at another revision, refuses the upload with 409 revision_changed, so a copy kept in step never writes over a change it has not seen. */
+    replacing?: {
+        id: string;
+        revision: number;
+    };
+    /** Left out, a Blob's own type, else worked out from the name. */
+    contentType?: string;
+    /** Smaller copies to make of an image as soon as it is stored. */
+    imageSizes?: number[];
+    /** Bytes in each part, from 8 MiB to 64 MiB. Left out, 32 MiB, or less for a small file. */
+    partBytes?: number;
+    /** Parts sent at once. */
+    concurrency?: number;
+    /** The file's SHA-256 in lower-case hex, if it is known. Kept with the file as clientSha256. */
+    sha256?: string;
+    /** The id of an upload that stopped part way: only what storage does not have is sent. */
+    resume?: string;
+    /** Called once the upload exists, before any part is sent. Keep its id to carry on after a crash. */
+    onBegun?: (upload: Upload) => void;
+    /** Called as parts arrive, with the bytes storage has. */
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /** Stops the upload. What reached storage is kept, to carry on with `resume`. */
+    signal?: AbortSignal;
+    /** For beginning: the caller's own key, so that a begin sent again makes one upload. */
+    idempotencyKey?: string;
+}
+/** An upload that stopped part way. What arrived stays in storage until the upload expires: carry on with `resume: uploadId`, or cancel it. */
+export declare class UploadStopped extends Error {
+    readonly uploadId: string;
+    constructor(uploadId: string, cause: unknown);
+}
+/** The calls an upload makes: the client's own, so that they are retried as any other call is. */
+export interface UploadCalls {
+    begin(body: UploadsBeginBody, options?: CallOptions): Promise<UploadsBeginAnswer>;
+    get(id: string, options?: CallOptions): Promise<UploadsGetAnswer>;
+    parts(id: string, query?: UploadsPartsQuery, options?: CallOptions): Promise<UploadsPartsAnswer>;
+    complete(id: string, body?: UploadsCompleteBody, options?: CallOptions): Promise<UploadsCompleteAnswer>;
+    file(id: string, options?: CallOptions): Promise<FilesGetAnswer>;
+}
+/** The part size to ask for: 32 MiB, halved while that would leave fewer parts than are sent at once. */
+export declare function partSizeFor(fileBytes: number, atOnce: number): number;
+export declare function upload(calls: UploadCalls, fetcher: typeof fetch, source: Source, options?: UploadOptions): Promise<Item>;