@graphty/graph-io 0.3.47 → 0.3.49

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,209 @@
+/**
+ * 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 as 64 lowercase hexadecimal digits: of bytes exactly as given, or of a text's UTF-8 bytes
+ * (the Cypher source's content hash, a project file's record of a file it loaded). Web Crypto where
+ * there is one, else plain JavaScript (a page that is not a secure context). Experimental.
+ * @param data - the bytes or the text
+ * @returns the digest
+ */
+export function sha256Hex(data: string | Uint8Array): Promise<string> {
+    return sha256(typeof data === "string" ? utf8(data) : data);
+}
+
+/**
+ * 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/sparql/descriptor.ts

@@ -0,0 +1,67 @@
+/**
+ * The SPARQL source's descriptor: catalog data, available without loading the source's code.
+ */
+
+import { type SourceDescriptor } from "../types.js";
+
+/** A small Wikidata query: physics Nobel laureates and their doctoral advisors. */
+const WIKIDATA_ADVISORS = `PREFIX wd: <http://www.wikidata.org/entity/>
+PREFIX wdt: <http://www.wikidata.org/prop/direct/>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+CONSTRUCT { ?person wdt:P184 ?advisor . ?person rdfs:label ?name . ?advisor rdfs:label ?advisorName . }
+WHERE {
+  ?person wdt:P166 wd:Q38104 ; wdt:P184 ?advisor ; rdfs:label ?name .
+  ?advisor rdfs:label ?advisorName .
+  FILTER(lang(?name) = "en" && lang(?advisorName) = "en")
+}`;
+
+/**
+ * The descriptor of the `sparql` source. Experimental.
+ * @category Network sources
+ */
+export const SPARQL_DESCRIPTOR: SourceDescriptor = Object.freeze({
+    plainName: "SPARQL endpoint",
+    kind: "sparql",
+    version: 1,
+    auth: ["basic", "bearer"],
+    authRequired: "optional",
+    features: ["expand", "probe", "validate", "page"],
+    params: [
+        { name: "query", plainName: "Query", type: "query", language: "sparql" },
+        {
+            name: "mode",
+            plainName: "Mode",
+            type: "enum",
+            values: [
+                { value: "query", label: "Query" },
+                { value: "all", label: "Everything" },
+                { value: "neighborhood", label: "Seed nodes" },
+            ],
+        },
+        { name: "ids", plainName: "Seed IRIs", type: "node-id" },
+        { name: "language", plainName: "Language", type: "string", advanced: true },
+        { name: "predicates", plainName: "Follow predicates", type: "string", advanced: true },
+        {
+            name: "pageSize",
+            plainName: "Page size",
+            type: "integer",
+            default: 1000,
+            min: 1,
+            max: 10000,
+            advanced: true,
+        },
+    ],
+    samples: [
+        {
+            id: "wikidata-physics-advisors",
+            plainName: "Wikidata: physics Nobel laureates and their advisors",
+            endpoint: "https://query.wikidata.org/sparql",
+            params: {
+                query: WIKIDATA_ADVISORS,
+                pageSize: 100,
+                language: "en",
+                predicates: ["http://www.wikidata.org/prop/direct/"], // NOSONAR(S5332): an RDF namespace IRI, never fetched; Wikidata's IRIs are http
+            },
+        },
+    ],
+});