@mikeargento/bitgraph-player 0.5.1 → 0.6.0

package/src/pin.ts

@@ -0,0 +1,155 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * The pin store, and the fetch behind `bitgraph-play pin`: the ONLY code
+ * in this package that touches the network, and only when the reader
+ * invokes it. A pin is the reader's act and the reader's record: the
+ * domain's file is stored byte-verbatim on the reader's machine, and
+ * `check --from` reads the store and never fetches. A missing pin is an
+ * invocation error with the pin command as its remedy, never a verdict,
+ * and a stored pin outlives the file that provided it, deliberately.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { DomainFile } from "./domain.js";
+import { DOMAIN_FILE_MAX_BYTES, DOMAIN_WELL_KNOWN_PATH, isDomainName, parseDomainFile } from "./domain.js";
+
+/** ~/.bitgraph/pins, or BITGRAPH_PINS, or the --pins flag above this. */
+export function defaultPinsDir(): string {
+  const env = process.env["BITGRAPH_PINS"];
+  return env !== undefined && env.length > 0 ? env : join(homedir(), ".bitgraph", "pins");
+}
+
+function pinPath(pinsDir: string, domain: string): string {
+  if (!isDomainName(domain)) throw new Error(`not a domain name: ${domain}`);
+  // The domain grammar admits no path separators, so the name is the file.
+  return join(pinsDir, domain);
+}
+
+export interface StoredPin {
+  domain: string;
+  file: DomainFile;
+  bytes: Buffer;
+  pinnedAt: Date;
+}
+
+/**
+ * Read one stored pin. Undefined when no pin exists; throws
+ * DomainFileError when the stored bytes no longer parse (the remedy is to
+ * pin again, or --forget).
+ */
+export function readPin(domain: string, pinsDir: string = defaultPinsDir()): StoredPin | undefined {
+  const path = pinPath(pinsDir, domain);
+  let bytes: Buffer;
+  let pinnedAt: Date;
+  try {
+    bytes = readFileSync(path);
+    pinnedAt = statSync(path).mtime;
+  } catch {
+    return undefined;
+  }
+  const file = parseDomainFile(bytes, domain);
+  return { domain, file, bytes, pinnedAt };
+}
+
+/** Store the fetched bytes verbatim. Overwrites: a pin is current by choice. */
+export function writePin(domain: string, bytes: Uint8Array, pinsDir: string = defaultPinsDir()): string {
+  const path = pinPath(pinsDir, domain);
+  mkdirSync(pinsDir, { recursive: true });
+  writeFileSync(path, bytes);
+  return path;
+}
+
+/** Remove one pin. False when there was none. */
+export function forgetPin(domain: string, pinsDir: string = defaultPinsDir()): boolean {
+  try {
+    unlinkSync(pinPath(pinsDir, domain));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface PinListEntry {
+  domain: string;
+  /** Undefined when the stored bytes no longer parse. */
+  party?: string;
+  keyCount?: number;
+  pinnedAt: Date;
+  malformed: boolean;
+}
+
+/** Every stored pin, domain order. Malformed entries are listed, flagged. */
+export function listPins(pinsDir: string = defaultPinsDir()): PinListEntry[] {
+  let names: string[];
+  try {
+    names = readdirSync(pinsDir);
+  } catch {
+    return [];
+  }
+  const entries: PinListEntry[] = [];
+  for (const name of names.sort()) {
+    if (!isDomainName(name)) continue;
+    try {
+      const pin = readPin(name, pinsDir);
+      if (pin === undefined) continue;
+      entries.push({
+        domain: name,
+        party: pin.file.party,
+        keyCount: Object.keys(pin.file.keys).length,
+        pinnedAt: pin.pinnedAt,
+        malformed: false,
+      });
+    } catch {
+      entries.push({ domain: name, pinnedAt: statSync(join(pinsDir, name)).mtime, malformed: true });
+    }
+  }
+  return entries;
+}
+
+/** The slice of fetch() this module uses; injectable for tests. */
+export interface FetchLike {
+  (url: string, init?: { signal?: AbortSignal; redirect?: "follow" }): Promise<{
+    ok: boolean;
+    status: number;
+    headers: { get(name: string): string | null };
+    arrayBuffer(): Promise<ArrayBuffer>;
+  }>;
+}
+
+/**
+ * Fetch a domain's bitgraph-domain/1 file: one HTTPS GET of the fixed
+ * well-known path. Redirects are followed, but the file's own `domain`
+ * field must equal the requested domain (parseDomainFile enforces it), so
+ * a redirect cannot repoint the name. Throws on any failure; a malformed
+ * file is refused here and never stored.
+ */
+export async function fetchDomainFile(
+  domain: string,
+  fetchImpl: FetchLike = globalThis.fetch as unknown as FetchLike
+): Promise<{ bytes: Buffer; file: DomainFile }> {
+  if (!isDomainName(domain)) {
+    const hint = domain.includes("://") ? " (pass the bare hostname, without scheme or path)" : "";
+    throw new Error(`not a domain name: ${domain}${hint}`);
+  }
+  const url = `https://${domain}${DOMAIN_WELL_KNOWN_PATH}`;
+  let res: Awaited<ReturnType<FetchLike>>;
+  try {
+    res = await fetchImpl(url, { signal: AbortSignal.timeout(15_000), redirect: "follow" });
+  } catch (err) {
+    throw new Error(`cannot fetch ${url}: ${(err as Error).message}`);
+  }
+  if (!res.ok) throw new Error(`no domain file at ${url} (HTTP ${res.status})`);
+  const declared = res.headers.get("content-length");
+  if (declared !== null && Number(declared) > DOMAIN_FILE_MAX_BYTES) {
+    throw new Error(`the file at ${url} declares ${declared} bytes; the cap is ${DOMAIN_FILE_MAX_BYTES}`);
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.length > DOMAIN_FILE_MAX_BYTES) {
+    throw new Error(`the file at ${url} is ${bytes.length} bytes; the cap is ${DOMAIN_FILE_MAX_BYTES}`);
+  }
+  const file = parseDomainFile(bytes, domain);
+  return { bytes, file };
+}

package/src/play.ts

@@ -60,8 +60,13 @@ export function claimUsesSignatures(claim: Claim): boolean {
  * evaluation. Signature files are a few hundred bytes; the cap only
  * exists so a bundle full of large artifacts never inflates memory.
  * A file above the cap is simply not signature evidence.
+ *
+ * The constant lives in types.ts (dependency-free) so check.ts, which is
+ * also built into the browser verifier, can use it without pulling this
+ * module's node:fs import into that bundle. Re-exported here unchanged.
  */
-export const SIG_EVIDENCE_MAX_BYTES = 1_048_576;
+import { SIG_EVIDENCE_MAX_BYTES } from "./types.js";
+export { SIG_EVIDENCE_MAX_BYTES };
 
 /** The pure tail of the pipeline: no filesystem, no network. */
 export function playAudit(

package/src/sig.ts

@@ -93,7 +93,7 @@ export function parseSigFile(bytes: Uint8Array): SigFile | undefined {
 }
 
 /** Strict base64 decode: the spelling must round-trip byte-exactly. */
-function decodeB64Strict(s: string): Buffer | undefined {
+export function decodeB64Strict(s: string): Buffer | undefined {
   if (!/^[A-Za-z0-9+/]+=*$/.test(s)) return undefined;
   const bytes = Buffer.from(s, "base64");
   return bytes.toString("base64") === s ? bytes : undefined;

package/src/types.ts

@@ -239,3 +239,11 @@ export interface Verdict {
   evaluator: { name: string; version: string };
   network: "none";
 }
+
+/**
+ * Size cap on candidate signature-evidence files (SPEC §9.4): a bundle
+ * artifact larger than this is simply not signature evidence. Declared
+ * here, dependency-free, because both play.ts (which imports node:fs) and
+ * check.ts (which is also built into the browser verifier) need it.
+ */
+export const SIG_EVIDENCE_MAX_BYTES = 1_048_576;

package/src/verdict.ts

@@ -31,7 +31,7 @@ import type { DeclaredEntry, Resolution, Rule, Verdict } from "./types.js";
  * A unit test asserts this equals package.json's version, so the
  * constant cannot drift silently across releases.
  */
-export const PLAYER_VERSION = "0.5.1";
+export const PLAYER_VERSION = "0.6.0";
 
 /** The player package's own version. */
 export function playerVersion(): string {