@graphty/graph-io 0.3.46 → 0.3.48

package/src/sources/sha256.ts

@@ -0,0 +1,99 @@
+/**
+ * SHA-256 in plain JavaScript (FIPS 180-4), for the one place Web Crypto is missing: a browser page
+ * that is not a secure context (plain http on a host other than localhost) has no
+ * `crypto.subtle`. Only the content hash uses it; signing still needs Web Crypto.
+ */
+
+const K = 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,
+]);
+
+/**
+ * Rotate a 32-bit word right.
+ * @param x - the word
+ * @param n - the bits
+ * @returns the rotated word
+ */
+function rotr(x: number, n: number): number {
+    return (x >>> n) | (x << (32 - n));
+}
+
+/**
+ * Pad a message to whole 64-byte blocks, with its bit length at the end.
+ * @param data - the message
+ * @returns the padded message
+ */
+function pad(data: Uint8Array): Uint8Array {
+    const blocks = Math.ceil((data.length + 9) / 64);
+    const out = new Uint8Array(blocks * 64);
+    out.set(data);
+    out[data.length] = 0x80;
+    const view = new DataView(out.buffer);
+    view.setUint32(out.length - 8, Math.floor(data.length / 0x20000000));
+    view.setUint32(out.length - 4, (data.length * 8) >>> 0);
+    return out;
+}
+
+/**
+ * Run one 64-byte block through the compression function.
+ * @param h - the running hash, updated in place
+ * @param w - the 64-word schedule, scratch
+ * @param view - the padded message
+ * @param offset - where the block starts
+ */
+function compress(h: Uint32Array, w: Uint32Array, view: DataView, offset: number): void {
+    for (let i = 0; i < 16; i++) {
+        w[i] = view.getUint32(offset + i * 4);
+    }
+    for (let i = 16; i < 64; i++) {
+        const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+        const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+        w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let i = 0; i < 64; i++) {
+        const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+        const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+        hh = g;
+        g = f;
+        f = e;
+        e = (d + t1) >>> 0;
+        d = c;
+        c = b;
+        b = a;
+        a = (t1 + t2) >>> 0;
+    }
+    const next = [a, b, c, d, e, f, g, hh];
+    for (let i = 0; i < 8; i++) {
+        h[i] = (h[i] + next[i]) >>> 0;
+    }
+}
+
+/**
+ * SHA-256 of bytes.
+ * @param data - the bytes
+ * @returns the 32-byte digest
+ */
+export function sha256Bytes(data: Uint8Array): ArrayBuffer {
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const padded = pad(data);
+    const view = new DataView(padded.buffer);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        compress(h, w, view, offset);
+    }
+    const out = new DataView(new ArrayBuffer(32));
+    h.forEach((word, i) => {
+        out.setUint32(i * 4, word);
+    });
+    return out.buffer;
+}

package/src/sources/sigv4.ts

@@ -0,0 +1,207 @@
+/**
+ * AWS Signature Version 4 over Web Crypto (design sections 6.3 and 12.4), loaded by
+ * `credentials.awsSigV4` on first use. No AWS SDK: it signs the request `ctx.fetch` is about to
+ * send, every header that request carries plus `host`, and is checked against AWS's published
+ * signature test suite. graph-io never reads `~/.aws` or the environment.
+ */
+
+import { detectRuntime } from "./context.js";
+import { type AwsSigV4Options } from "./credentials.js";
+import { failAlone } from "./fail.js";
+import { sha256Bytes } from "./sha256.js";
+
+/** Headers never signed: proxies and clients may change them in flight. */
+const UNSIGNED = new Set(["user-agent", "expect", "x-amzn-trace-id", "authorization", "content-length"]);
+
+/**
+ * The UTF-8 bytes of a string.
+ * @param text - the text
+ * @returns the bytes
+ */
+function utf8(text: string): Uint8Array {
+    return new TextEncoder().encode(text);
+}
+
+/**
+ * Code-unit order of two strings.
+ * @param a - one string
+ * @param b - another
+ * @returns negative, zero or positive
+ */
+function compareText(a: string, b: string): number {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+
+/**
+ * Web Crypto: the global one, or Node 18's, which is not global without a flag. A browser page that
+ * is not a secure context (plain http on a host other than localhost) has none.
+ * @returns the subtle crypto, or null where there is none
+ */
+async function subtle(): Promise<SubtleCrypto | null> {
+    const global = (globalThis as { crypto?: Crypto }).crypto;
+    if (global?.subtle !== undefined) {
+        return global.subtle;
+    }
+    if (detectRuntime() !== "node") {
+        return null;
+    }
+    const name = "node:crypto";
+    return ((await import(/* @vite-ignore */ name)) as { webcrypto: Crypto }).webcrypto.subtle;
+}
+
+/**
+ * Lowercase hex of bytes.
+ * @param bytes - the bytes
+ * @returns hex
+ */
+function hex(bytes: ArrayBuffer): string {
+    return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * SHA-256 of bytes, as hex.
+ * @param data - the bytes
+ * @returns the digest
+ */
+async function sha256(data: Uint8Array | ArrayBuffer): Promise<string> {
+    const s = await subtle();
+    if (s === null) {
+        return hex(sha256Bytes(data instanceof Uint8Array ? data : new Uint8Array(data)));
+    }
+    return hex(await s.digest("SHA-256", data as BufferSource));
+}
+
+/**
+ * SHA-256 of a text's UTF-8 bytes, as lowercase hex (the Cypher source's content hash).
+ * @param text - the text
+ * @returns the digest
+ */
+export function sha256Hex(text: string): Promise<string> {
+    return sha256(utf8(text));
+}
+
+/**
+ * HMAC-SHA-256.
+ * @param key - the key
+ * @param data - the message
+ * @returns the MAC
+ */
+async function hmac(key: Uint8Array | ArrayBuffer, data: string): Promise<ArrayBuffer> {
+    const s = await subtle();
+    if (s === null) {
+        failAlone("E_SOURCE_RUNTIME", "AWS signing needs Web Crypto, which a browser has only on a secure page", {
+            runtime: detectRuntime(),
+            reason: "needs-secure-context",
+        });
+    }
+    const k = await s.importKey("raw", key as BufferSource, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return s.sign("HMAC", k, utf8(data) as BufferSource);
+}
+
+/**
+ * RFC 3986 encoding, as SigV4 asks: every byte but letters, digits and `-_.~`.
+ * @param text - the text
+ * @returns the encoded text
+ */
+function encode(text: string): string {
+    return encodeURIComponent(text).replaceAll(
+        /[!'()*]/g,
+        (c) => `%${(c.codePointAt(0) ?? 0).toString(16).toUpperCase()}`,
+    );
+}
+
+/**
+ * The canonical query string: every pair encoded, sorted by key then value.
+ * @param url - the request URL
+ * @returns the canonical query
+ */
+function canonicalQuery(url: URL): string {
+    return [...url.searchParams]
+        .map(([k, v]) => [encode(k), encode(v)] as const)
+        .sort(([ak, av], [bk, bv]) => compareText(ak, bk) || compareText(av, bv))
+        .map(([k, v]) => `${k}=${v}`)
+        .join("&");
+}
+
+/**
+ * The `YYYYMMDDTHHMMSSZ` form of a time.
+ * @param date - the time
+ * @returns the AWS timestamp
+ */
+function amzDate(date: Date): string {
+    return date
+        .toISOString()
+        .replaceAll(/[-:]/g, "")
+        .replace(/\.\d{3}/, "");
+}
+
+/**
+ * Sign a request with AWS SigV4 (`Authorization`, `X-Amz-Date` and, for temporary credentials,
+ * `X-Amz-Security-Token`). In a browser, long-term keys (no session token) are refused, since every
+ * script on the page could read them: use temporary credentials from an identity pool.
+ * @param request - the request
+ * @param options - region, service (default "neptune-db") and the credentials or a provider
+ * @param now - the signing time; tests fix it. An `X-Amz-Date` already on the request wins.
+ * @returns the signed request
+ */
+export async function signRequest(
+    request: Request,
+    options: AwsSigV4Options,
+    now: Date = new Date(),
+): Promise<Request> {
+    const creds = typeof options.credentials === "function" ? await options.credentials() : options.credentials;
+    const runtime = detectRuntime();
+    if ((runtime === "browser" || runtime === "worker") && (creds.sessionToken ?? "") === "") {
+        failAlone("E_SOURCE_PARAM", "long-term AWS keys are never used in a browser", {
+            name: "credential",
+            reason: "long-term-key",
+        });
+    }
+    const service = options.service ?? "neptune-db";
+    const url = new URL(request.url);
+    const headers = new Headers(request.headers);
+    const stamp = headers.get("x-amz-date") ?? amzDate(now);
+    headers.set("x-amz-date", stamp);
+    if (creds.sessionToken !== undefined && creds.sessionToken !== "") {
+        headers.set("x-amz-security-token", creds.sessionToken);
+    }
+    const method = request.method.toUpperCase();
+    const body = method === "GET" || method === "HEAD" ? new Uint8Array(0) : await request.clone().arrayBuffer();
+
+    const signed = new Map<string, string>([["host", url.host]]);
+    headers.forEach((value, name) => {
+        if (!UNSIGNED.has(name)) {
+            signed.set(name, value.trim().replaceAll(/\s+/g, " "));
+        }
+    });
+    // SigV4 sorts header names by code unit, not by locale
+    const names = [...signed.keys()].sort((a, b) => Number(a > b) - Number(a < b));
+    const signedHeaders = names.join(";");
+    const canonical = [
+        method,
+        // non-S3 services encode the already-encoded path once more
+        url.pathname.split("/").map(encode).join("/"),
+        canonicalQuery(url),
+        ...names.map((n) => `${n}:${signed.get(n) ?? ""}`),
+        "",
+        signedHeaders,
+        await sha256(body),
+    ].join("\n");
+
+    const day = stamp.slice(0, 8);
+    const scope = `${day}/${options.region}/${service}/aws4_request`;
+    const toSign = ["AWS4-HMAC-SHA256", stamp, scope, await sha256(utf8(canonical))].join("\n");
+    let key: ArrayBuffer = await hmac(utf8(`AWS4${creds.secretAccessKey}`), day);
+    for (const part of [options.region, service, "aws4_request"]) {
+        key = await hmac(key, part);
+    }
+    const signature = hex(await hmac(key, toSign));
+    headers.set(
+        "Authorization",
+        `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    );
+    return new Request(request, { headers });
+}

package/src/sources/testing.ts

@@ -0,0 +1,210 @@
+/**
+ * Testing a source without a network: `replayFetch` answers requests from recorded responses and
+ * refuses any request it has no recording for. Browser-safe (no file system), so a graphty-element
+ * story and a third party's tests use it the same way.
+ */
+
+/**
+ * One recorded exchange. Experimental.
+ * @category Network sources
+ */
+export interface Recording {
+    /** The request method. @defaultValue "GET" */
+    readonly method?: string | undefined;
+    /** The request URL. Query parameters match in any order. */
+    readonly url: string;
+    /** The request body, when it must match (JSON bodies compare as JSON). */
+    readonly requestBody?: string | undefined;
+    /**
+     * true: the request must carry a credential; false: it must not. Absent: either. A credential
+     * is an Authorization header, or a header or query parameter named in `secretHeaders` /
+     * `secretQuery`; its value is never compared.
+     */
+    readonly credential?: boolean | undefined;
+    /** The response status. @defaultValue 200 */
+    readonly status?: number | undefined;
+    /** The response headers. */
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    /** The response body: text, or a value sent as JSON. */
+    readonly body?: unknown;
+}
+
+/**
+ * The options of `replayFetch`. Experimental.
+ * @category Network sources
+ */
+export interface ReplayOptions {
+    /** What an unrecorded request does: "throw" (the only choice; the test fails). @defaultValue "throw" */
+    readonly onUnrecorded?: "throw" | undefined;
+    /** Query parameters that hold a credential: ignored when matching, counted as a credential. */
+    readonly secretQuery?: readonly string[] | undefined;
+    /** Request headers that hold a credential, beside Authorization. */
+    readonly secretHeaders?: readonly string[] | undefined;
+}
+
+/**
+ * One request `replayFetch` answered. Experimental.
+ * @category Network sources
+ */
+export interface ReplayCall {
+    /** The method. */
+    readonly method: string;
+    /** The URL, origin and path only. */
+    readonly url: string;
+    /** Whether a credential was sent. */
+    readonly credential: boolean;
+}
+
+/**
+ * A fetch that answers from recordings, plus the requests it answered. Experimental.
+ * @category Network sources
+ */
+export type ReplayFetch = typeof fetch & {
+    /** The requests answered, in order. */
+    readonly calls: readonly ReplayCall[];
+};
+
+/**
+ * A fetch that answers every request from recordings: the first unused recording that matches
+ * (method, URL with its query in any order, body when recorded, and whether a credential was
+ * sent), else the last one that matched, so a recording answers every repeat. A request with no
+ * matching recording rejects with an Error naming its method and URL, which a source never
+ * retries. Like fetch, a request whose signal is already aborted rejects with the signal's
+ * reason. Pass it as the `fetch` option. Experimental.
+ * @param recordings - the recorded exchanges
+ * @param options - which headers and query parameters hold a credential
+ * @returns the fetch
+ * @example
+ * ```ts
+ * const fetch = replayFetch([{ url: "https://example.com/api/people.json?team=core", body: [{ id: "ana", knows: [] }] }]);
+ * await loadFromSource("people", { team: "core" }, { endpoint: "https://example.com", fetch });
+ * ```
+ * @category Network sources
+ */
+export function replayFetch(recordings: readonly Recording[], options: ReplayOptions = {}): ReplayFetch {
+    const secretQuery = new Set(options.secretQuery ?? []);
+    const secretHeaders = ["authorization", ...(options.secretHeaders ?? []).map((h) => h.toLowerCase())];
+    const used = new Set<number>();
+    const calls: ReplayCall[] = [];
+
+    const key = (url: URL): string => {
+        const params = [...url.searchParams].filter(([k]) => !secretQuery.has(k)).sort(compare);
+        return `${url.origin}${url.pathname}?${new URLSearchParams(params).toString()}`;
+    };
+
+    const replay = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+        const request = new Request(input, init);
+        // like fetch: an aborted signal rejects with its reason before anything is answered
+        request.signal.throwIfAborted();
+        const url = new URL(request.url);
+        const method = request.method.toUpperCase();
+        const body = method === "GET" || method === "HEAD" ? "" : await request.clone().text();
+        const credential =
+            secretHeaders.some((h) => request.headers.has(h)) ||
+            [...url.searchParams.keys()].some((k) => secretQuery.has(k));
+        const wanted = key(url);
+        const matches: number[] = [];
+        recordings.forEach((r, i) => {
+            if (
+                (r.method ?? "GET").toUpperCase() === method &&
+                key(new URL(r.url)) === wanted &&
+                (r.credential === undefined || r.credential === credential) &&
+                (r.requestBody === undefined || sameBody(r.requestBody, body))
+            ) {
+                matches.push(i);
+            }
+        });
+        const index = matches.find((i) => !used.has(i)) ?? matches.at(-1);
+        if (index === undefined) {
+            throw new Error(`replayFetch: no recording for ${method} ${url.origin}${url.pathname}`);
+        }
+        used.add(index);
+        calls.push({ method, url: `${url.origin}${url.pathname}`, credential });
+        const r = recordings[index];
+        const status = r.status ?? 200;
+        const text = bodyText(r.body);
+        const headers = new Headers(r.headers);
+        if (text !== null && typeof r.body !== "string" && !headers.has("content-type")) {
+            headers.set("content-type", "application/json");
+        }
+        const nullBody = status === 204 || status === 304 || (status >= 300 && status < 400 && text === null);
+        return new Response(nullBody ? null : text, { status, headers });
+    };
+    return Object.assign(replay, { calls });
+}
+
+/**
+ * A recorded body as response text.
+ * @param body - the recorded body
+ * @returns the text, or null for no body
+ */
+function bodyText(body: unknown): string | null {
+    if (body === undefined || body === null) {
+        return null;
+    }
+    return typeof body === "string" ? body : JSON.stringify(body);
+}
+
+/**
+ * Compare two query entries by key, then value.
+ * @param a - one entry
+ * @param b - another
+ * @returns the order
+ */
+function compare(a: [string, string], b: [string, string]): number {
+    return a[0] === b[0] ? a[1].localeCompare(b[1]) : a[0].localeCompare(b[0]);
+}
+
+/**
+ * Whether two bodies are the same, as JSON when both parse.
+ * @param recorded - the recorded body
+ * @param sent - the sent body
+ * @returns true when they match
+ */
+function sameBody(recorded: string, sent: string): boolean {
+    try {
+        return JSON.stringify(JSON.parse(recorded)) === JSON.stringify(JSON.parse(sent));
+    } catch {
+        return recorded === sent;
+    }
+}
+
+/**
+ * A recording made from a real exchange, without its credential: the request's headers are never
+ * kept, query parameters named in `secretQuery` are removed from the URL, and of the response only
+ * the status, the Content-Type and the headers named in `keepHeaders` are kept. Experimental.
+ * @param request - the request sent
+ * @param response - its response (read; pass a clone to keep using it)
+ * @param options - what to keep and drop
+ * @param options.keepHeaders - response headers to keep beside Content-Type
+ * @param options.secretQuery - query parameters removed from the URL
+ * @returns the recording
+ * @category Network sources
+ */
+export async function recordingFrom(
+    request: Request,
+    response: Response,
+    options: { readonly keepHeaders?: readonly string[]; readonly secretQuery?: readonly string[] } = {},
+): Promise<Recording> {
+    const headers: Record<string, string> = {};
+    for (const name of ["content-type", ...(options.keepHeaders ?? [])]) {
+        const value = response.headers.get(name);
+        if (value !== null) {
+            headers[name.toLowerCase()] = value;
+        }
+    }
+    const url = new URL(request.url);
+    for (const name of options.secretQuery ?? []) {
+        url.searchParams.delete(name);
+    }
+    const method = request.method.toUpperCase();
+    const requestBody = method === "GET" || method === "HEAD" ? undefined : await request.clone().text();
+    return {
+        method,
+        url: url.toString(),
+        ...(requestBody === undefined || requestBody === "" ? {} : { requestBody }),
+        status: response.status,
+        headers,
+        body: await response.text(),
+    };
+}