@massu/core 1.10.7 → 1.12.0

package/src/security/fetcher.ts

@@ -1,200 +0,0 @@
-/**
- * HTTPS fetch helper with strict host allowlist + bounded timeout.
- *
- * Plan 3c Phase 5 deliverable (gap-3 / Phase 5 deps line 114). The Phase 5
- * adapter-verifier is the only consumer; fetching from arbitrary URLs is
- * forbidden. Allowlist:
- *   - registry.massu.ai (manifest fetch)
- *   - telemetry.massu.ai (adapter-discovery telemetry)
- *
- * Why an allowlist: an unrestricted fetch primitive in @massu/core would
- * be a supply-chain liability — a future bug or compromised adapter could
- * exfiltrate data to attacker-controlled hosts. The allowlist lives in
- * THIS module's source code (single source of truth), not in
- * massu.config.yaml — operators cannot widen it without auditing this
- * file.
- *
- * Why this module instead of a third-party http lib: Node 18+ has a built-in
- * fetch (per Plan 3c gap-3 audit-fact line 46 — "no deps for `node-fetch`").
- * This module wraps it with the allowlist + timeout + JSON parsing in a
- * single typed surface. The verifier doesn't need redirects, retry, or
- * streaming — those features are attack surface we don't want.
- */
-
-const DEFAULT_TIMEOUT_MS = 10_000;
-/**
- * CR-9 audit H3 fix: hard cap on response body size. Without this, a
- * compromised CDN (or TLS-MITM) could serve a multi-GB body that exceeds
- * available heap before the timeout fires. The manifest is on the order
- * of KB; even with 1000 adapter entries it should fit comfortably under
- * 1 MB. The 10 MB ceiling here is generous enough to never affect
- * legitimate manifests AND tight enough to bound damage from a malicious
- * upstream.
- */
-const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
-
-/**
- * Allowlist of hosts the fetcher will GET from. Exported for unit testing
- * but intentionally read-only (`as const`) — runtime mutation is impossible.
- * To widen the allowlist for a new use case, edit this constant in source
- * and ship a `@massu/core` minor release.
- */
-export const ALLOWED_HOSTS = [
-  'registry.massu.ai',
-  'telemetry.massu.ai',
-] as const;
-
-export interface FetchUrlOptions {
-  /** Maximum time the request may take, in milliseconds. Defaults to 10s. */
-  timeoutMs?: number;
-  /**
-   * Override the allowlist for tests. Production code MUST NOT pass this —
-   * the default ALLOWED_HOSTS is the production contract. Test-only.
-   */
-  allowedHosts?: readonly string[];
-  /**
-   * Override the response body size cap (test-only). Defaults to 10 MB.
-   * CR-9 audit H3 fix: bounds OOM exposure from a malicious upstream.
-   */
-  maxBodyBytes?: number;
-}
-
-export interface FetchUrlResult {
-  status: number;
-  /** Response body as UTF-8 string. */
-  body: string;
-}
-
-export class FetchAllowlistError extends Error {
-  constructor(public readonly url: string, public readonly host: string) {
-    super(
-      `Refusing to fetch ${url}: host '${host}' is not in the @massu/core ` +
-      `fetcher allowlist. Allowed hosts: ${ALLOWED_HOSTS.join(', ')}. ` +
-      `Widening the allowlist requires editing packages/core/src/security/fetcher.ts ` +
-      `at the source level.`,
-    );
-    this.name = 'FetchAllowlistError';
-  }
-}
-
-export class FetchTimeoutError extends Error {
-  constructor(public readonly url: string, public readonly timeoutMs: number) {
-    super(`Fetch of ${url} timed out after ${timeoutMs}ms`);
-    this.name = 'FetchTimeoutError';
-  }
-}
-
-export class FetchBodySizeError extends Error {
-  constructor(public readonly url: string, public readonly maxBodyBytes: number) {
-    super(
-      `Fetch of ${url} exceeded body size cap of ${maxBodyBytes} bytes. ` +
-      `This indicates either a malicious upstream OR an unexpectedly large ` +
-      `legitimate response. Refusing to load.`,
-    );
-    this.name = 'FetchBodySizeError';
-  }
-}
-
-/**
- * GET an HTTPS URL with allowlist enforcement + timeout. Returns the response
- * body as a string (caller is responsible for JSON.parse + schema validation).
- *
- * Throws:
- * - FetchAllowlistError if the URL's host is not in ALLOWED_HOSTS (or the
- *   test override). Includes the host name in the error so operators can
- *   debug misconfigurations.
- * - FetchTimeoutError if the request exceeds the timeout.
- * - TypeError if the URL does not parse as a valid URL.
- * - Error (with .cause set to the underlying network error) for other failures.
- */
-export async function fetchUrl(url: string, opts: FetchUrlOptions = {}): Promise<FetchUrlResult> {
-  const allowedHosts = opts.allowedHosts ?? ALLOWED_HOSTS;
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
-
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch (err) {
-    throw new TypeError(`fetchUrl: invalid URL: ${url}`);
-  }
-
-  if (parsed.protocol !== 'https:') {
-    throw new FetchAllowlistError(url, parsed.host);
-  }
-
-  if (!allowedHosts.includes(parsed.host as (typeof ALLOWED_HOSTS)[number])) {
-    throw new FetchAllowlistError(url, parsed.host);
-  }
-
-  const controller = new AbortController();
-  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
-
-  try {
-    const response = await fetch(url, {
-      method: 'GET',
-      signal: controller.signal,
-      redirect: 'error', // refuse redirects — would defeat the allowlist
-    });
-
-    // CR-9 audit H3 fix: stream the body with a hard byte cap. Without this,
-    // a malicious upstream could OOM the host with a multi-GB response
-    // before the wall-clock timeout fires. content-length header check is
-    // a fast pre-filter; the streaming reader is the actual enforcement.
-    // Headers can be absent in test mocks; treat missing as "no pre-filter".
-    if (response.headers && typeof response.headers.get === 'function') {
-      const contentLengthHeader = response.headers.get('content-length');
-      if (contentLengthHeader !== null && contentLengthHeader !== undefined) {
-        const declared = Number.parseInt(contentLengthHeader, 10);
-        if (Number.isFinite(declared) && declared > maxBodyBytes) {
-          throw new FetchBodySizeError(url, maxBodyBytes);
-        }
-      }
-    }
-
-    const body = response.body;
-    if (body && typeof body.getReader === 'function') {
-      // Streaming path: bound the read by maxBodyBytes. Used in production
-      // (Node 18+ fetch returns a ReadableStream).
-      const reader = body.getReader();
-      const chunks: Uint8Array[] = [];
-      let received = 0;
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        if (value) {
-          received += value.byteLength;
-          if (received > maxBodyBytes) {
-            try { await reader.cancel(); } catch { /* best effort */ }
-            throw new FetchBodySizeError(url, maxBodyBytes);
-          }
-          chunks.push(value);
-        }
-      }
-      const merged = new Uint8Array(received);
-      let offset = 0;
-      for (const chunk of chunks) {
-        merged.set(chunk, offset);
-        offset += chunk.byteLength;
-      }
-      return { status: response.status, body: new TextDecoder().decode(merged) };
-    }
-
-    // Fallback when response.body is not a ReadableStream (e.g. test
-    // mocks that only stub `text()`). The size cap is still enforced
-    // post-read because the text length is the byte length for ASCII +
-    // a strict upper bound for UTF-8 content.
-    const text = await response.text();
-    if (text.length > maxBodyBytes) {
-      throw new FetchBodySizeError(url, maxBodyBytes);
-    }
-    return { status: response.status, body: text };
-  } catch (err) {
-    if (err instanceof Error && err.name === 'AbortError') {
-      throw new FetchTimeoutError(url, timeoutMs);
-    }
-    throw err;
-  } finally {
-    clearTimeout(timeoutHandle);
-  }
-}

package/src/security/install-tracking.ts

@@ -1,319 +0,0 @@
-/**
- * Install-time + load-time sha256 verification of REGISTRY-VERIFIED adapter
- * package contents (Plan 3c gap-37).
- *
- * Two checks defend against post-install tampering:
- *
- * 1. INSTALL-time: when the operator runs `npx massu adapters install <pkg>`,
- *    this module walks the installed package's directory, computes a content-
- *    addressed sha256, AND verifies it equals the sha256 the signed registry
- *    manifest entry pinned. On match → record in
- *    ~/.massu/adapter-manifest-installed.json with the version + timestamp.
- *    Mismatch → refuse to register; the operator should `npm uninstall` the
- *    suspicious package.
- *
- * 2. LOAD-time: discovery (detect/adapters/discover.ts) re-computes the
- *    package's sha256 on every startup, compares to the install-time recorded
- *    hash from the sidecar file. Mismatch → REFUSE to load (post-install
- *    tampering of unpacked files in node_modules). The load-time check
- *    compares to the LOCAL sidecar, NOT the live registry — re-fetching
- *    from the registry every startup would be a network dependency on the
- *    boot path (per Plan 3c gap-3 deliverable: NO network on boot).
- *
- * Why content-addressed (not tarball sha256):
- * The published tarball's sha256 is a moving target — npm tarballs include
- * timestamps + permission bits that vary across operating systems. The
- * SAME tarball extracted to two different machines produces different
- * tarball hashes but identical FILE CONTENT hashes. Content-addressed
- * hashing (sha256 of canonical-stringified path:fileSha pairs, sorted by
- * path) is stable across machines + filesystems.
- *
- * Per CR-46 / Rule 0 single-source-of-truth: this is the ONLY recursive
- * directory hashing in @massu/core. Future modules that need to hash
- * directories MUST consume sha256OfDir from here, not re-implement.
- */
-import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-import { createHash } from 'node:crypto';
-import { z } from 'zod';
-import { atomicWrite } from './atomic-write.js';
-
-export const INSTALLED_MANIFEST_PATH = resolve(homedir(), '.massu', 'adapter-manifest-installed.json');
-
-/**
- * Compute a content-addressed sha256 of a directory recursively. Stable
- * across machines + filesystems: sorts files by relative POSIX path,
- * hashes each file's bytes, concatenates `<path>\0<sha256-hex>\n` per
- * file, then sha256s the whole concatenation.
- *
- * Symlinks are NOT followed (they're hashed as their target path content).
- * Directory entries (themselves) are NOT hashed (their content is implied
- * by the files inside). Files exceeding `maxFileBytes` (default 64 MB)
- * abort with an error — adapter packages should not ship huge binary
- * blobs; the cap is a sanity ceiling against accidental misuse.
- *
- * Excluded patterns (NEVER hashed; they are install-time artifacts that
- * vary across machines):
- *   - .git/
- *   - node_modules/  (transitive deps; their integrity is npm's concern)
- *   - any path containing /.cache/ or /.tmp/
- */
-const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
-/**
- * Directory names that sha256OfDir EXCLUDES from hashing — these are
- * install-time artifacts that vary across machines (.git history,
- * transitive deps, build caches, scratch dirs). Their CONTENT is not
- * part of the adapter package's content-addressable hash.
- *
- * CR-9 audit M5 + iter-2 audit MED-NEW-1/-2 enforcement: a published
- * npm tarball MUST NOT ship these directories. Any package that does
- * is refused at install + resign + load-time discovery via
- * `containsHiddenDirs()` below. Without these refusals, a malicious
- * tarball could smuggle payload files under `.git/payload.js` (excluded
- * from the hash) and have them require()'d by the legitimate adapter
- * at runtime — hash matches, payload runs.
- */
-export const EXCLUDED_DIR_NAMES: ReadonlySet<string> = new Set(['.git', 'node_modules', '.cache', '.tmp']);
-
-/**
- * Returns the first hidden-dir name found in `packageDir`, or null if
- * none are present. Caller (install / resign / discovery) refuses the
- * package on non-null return.
- */
-export function containsHiddenDirs(packageDir: string): string | null {
-  for (const hidden of EXCLUDED_DIR_NAMES) {
-    if (existsSync(`${packageDir}/${hidden}`)) {
-      return hidden;
-    }
-  }
-  return null;
-}
-
-export interface Sha256OfDirOpts {
-  /** Override the file-size cap (test-only). */
-  maxFileBytes?: number;
-}
-
-export function sha256OfDir(dir: string, opts: Sha256OfDirOpts = {}): string {
-  const maxFileBytes = opts.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
-  const files: Array<{ relativePath: string; absPath: string }> = [];
-
-  function walk(currentDir: string): void {
-    let entries: string[];
-    try {
-      entries = readdirSync(currentDir);
-    } catch {
-      return;
-    }
-    for (const entry of entries.sort()) {
-      const absPath = join(currentDir, entry);
-      let lst;
-      try {
-        // CR-9 audit H1 fix: lstatSync (not statSync) so symlinks are
-        // detected + skipped without following. Following symlinks would
-        // expose a read-anywhere primitive (a malicious dist/x.js -> /etc/shadow
-        // would have the target's content captured into the hash) AND would
-        // cause readFileSync to block on named-pipe targets.
-        lst = lstatSync(absPath);
-      } catch {
-        continue;
-      }
-      if (lst.isSymbolicLink()) {
-        // Skip symlinks entirely — they're not part of the package's
-        // content-addressable hash. A package author who legitimately wants
-        // to ship a symlink (rare) must replace it with a real file at
-        // publish time.
-        continue;
-      }
-      if (lst.isDirectory()) {
-        if (EXCLUDED_DIR_NAMES.has(entry)) continue;
-        walk(absPath);
-        continue;
-      }
-      if (!lst.isFile()) continue;
-      if (lst.size > maxFileBytes) {
-        throw new Error(
-          `sha256OfDir: file ${absPath} exceeds maxFileBytes (${lst.size} > ${maxFileBytes}); ` +
-          `adapter packages should not ship files this large.`,
-        );
-      }
-      const rel = relative(dir, absPath).split(sep).join('/');
-      files.push({ relativePath: rel, absPath });
-    }
-  }
-  walk(dir);
-
-  // Sort by relative POSIX path so the hash is stable regardless of
-  // readdir order (some filesystems return entries in inode order).
-  files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0));
-
-  const top = createHash('sha256');
-  for (const f of files) {
-    const fileHash = createHash('sha256').update(readFileSync(f.absPath)).digest('hex');
-    top.update(f.relativePath, 'utf-8');
-    top.update('\0', 'utf-8');
-    top.update(fileHash, 'utf-8');
-    top.update('\n', 'utf-8');
-  }
-  return top.digest('hex');
-}
-
-/**
- * Per-package install record. Keyed by package name in the sidecar's
- * top-level object.
- */
-const InstallEntrySchema = z.object({
-  // CR-9 iter-3 audit LOW-NEW3-1 fix: reject control characters in version.
-  // Without this, a same-user attacker writing the install-tracking
-  // sidecar could embed ANSI escapes (or other control chars) in version,
-  // log-injecting via runAdaptersResign's `${name}@${entry.version}`
-  // stderr emits. The regex permits printable ASCII (0x20-0x7e) plus
-  // common semver characters; control chars (0x00-0x1f, 0x7f) are
-  // rejected at parse time. Schema-level validation closes the vector
-  // at every callsite that reads the sidecar — no per-callsite escaping
-  // gymnastics needed.
-  version: z.string().min(1).regex(/^[\x20-\x7e]+$/, 'version must be printable ASCII (no control characters)'),
-  installed_sha256: z.string().regex(/^[0-9a-f]{64}$/),
-  manifest_sha256: z.string().regex(/^[0-9a-f]{64}$/),
-  ts: z.string().min(1).regex(/^[\x20-\x7e]+$/, 'ts must be printable ASCII (no control characters)'),
-}).strict();
-export type InstallEntry = z.infer<typeof InstallEntrySchema>;
-
-const InstalledManifestSchema = z.record(z.string(), InstallEntrySchema);
-export type InstalledManifest = z.infer<typeof InstalledManifestSchema>;
-
-/**
- * Read the install-tracking sidecar at ~/.massu/adapter-manifest-installed.json.
- * Returns an empty object when the file is absent OR fails parse / schema —
- * caller should treat absent + corrupt the same way (no install records, so
- * REGISTRY-VERIFIED adapters cannot satisfy the load-time check + are refused
- * until reinstalled via `npx massu adapters install`).
- */
-export function readInstalledManifest(path: string = INSTALLED_MANIFEST_PATH): InstalledManifest {
-  if (!existsSync(path)) return {};
-  let raw: unknown;
-  try {
-    raw = JSON.parse(readFileSync(path, 'utf-8'));
-  } catch {
-    return {};
-  }
-  const parsed = InstalledManifestSchema.safeParse(raw);
-  return parsed.success ? parsed.data : {};
-}
-
-export type InstallTrackingWriteResult = { written: true } | { written: false; error: string };
-
-/**
- * Write a single package's install entry to the sidecar (additive). Reads
- * the current sidecar, updates the named key, writes back atomically with
- * mode 0o600. Concurrent calls to this function for DIFFERENT package
- * names are NOT serialized — the manifest cache lock at
- * ~/.massu/.adapter-manifest.lock applies only to the cache, not this
- * sidecar. Since the install flow runs interactively (one CLI invocation
- * at a time per shell), racing writes are not a practical concern.
- */
-export function writeInstalledManifestEntry(
-  packageName: string,
-  entry: InstallEntry,
-  path: string = INSTALLED_MANIFEST_PATH,
-): InstallTrackingWriteResult {
-  // CR-9 iter-4 audit LOW-NEW4-1 fix: validate entry against the schema
-  // BEFORE writing. TypeScript types do NOT enforce Zod regex constraints
-  // at runtime; without this .parse(), a caller passing a control-char-
-  // contaminated entry (e.g. version from an attacker-controlled
-  // node_modules package.json) would write the malformed entry to disk,
-  // and the corresponding stderr emit at the install/resign callsite
-  // would log-inject before the next read-time validation could catch it.
-  const validated = InstallEntrySchema.safeParse(entry);
-  if (!validated.success) {
-    const issues = validated.error.issues
-      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
-      .join('; ');
-    return { written: false, error: `install-tracking entry shape invalid: ${issues}` };
-  }
-  const current = readInstalledManifest(path);
-  current[packageName] = validated.data;
-  const result = atomicWrite(path, JSON.stringify(current, null, 2), {
-    mode: 0o600,
-    ensureParentDirMode: 0o700,
-  });
-  if (!result.written) {
-    return { written: false, error: result.error ?? 'unknown atomicWrite error' };
-  }
-  return { written: true };
-}
-
-/**
- * Remove a single package's install entry from the sidecar. Used by
- * `npx massu adapters resign --uninstall` (or by future cleanup tooling).
- * No-op if the entry is absent; sidecar file persists.
- */
-export function removeInstalledManifestEntry(
-  packageName: string,
-  path: string = INSTALLED_MANIFEST_PATH,
-): InstallTrackingWriteResult {
-  const current = readInstalledManifest(path);
-  if (!(packageName in current)) {
-    return { written: true };
-  }
-  delete current[packageName];
-  const result = atomicWrite(path, JSON.stringify(current, null, 2), {
-    mode: 0o600,
-    ensureParentDirMode: 0o700,
-  });
-  if (!result.written) {
-    return { written: false, error: result.error ?? 'unknown atomicWrite error' };
-  }
-  return { written: true };
-}
-
-export type IntegrityCheckResult =
-  | { kind: 'ok'; entry: InstallEntry }
-  | { kind: 'no-entry'; reason: string }
-  | { kind: 'drift'; entry: InstallEntry; computedSha: string; reason: string };
-
-/**
- * Load-time integrity check for an installed REGISTRY-VERIFIED adapter
- * package. Compares the package directory's CURRENT sha256OfDir output
- * to the install-time hash recorded in the sidecar. Mismatch → drift,
- * caller refuses to load.
- *
- * Caller (typically discoverAdapters) interprets:
- *   - 'ok'        → load is safe
- *   - 'no-entry'  → package is in node_modules but never registered via
- *                    `massu adapters install`; refuse + tell operator to run install
- *   - 'drift'     → contents tampered after install; REFUSE; tell operator
- *                    to `npm uninstall` + `npm install` + `massu adapters install`
- */
-export function verifyInstalledIntegrity(
-  packageName: string,
-  packageDir: string,
-  sidecarPath: string = INSTALLED_MANIFEST_PATH,
-): IntegrityCheckResult {
-  const installed = readInstalledManifest(sidecarPath);
-  const entry = installed[packageName];
-  if (!entry) {
-    return {
-      kind: 'no-entry',
-      reason:
-        `${packageName} is in node_modules but has no install-tracking entry in ~/.massu/adapter-manifest-installed.json. ` +
-        `Run \`npx massu adapters install ${packageName}\` to register it.`,
-    };
-  }
-  const computedSha = sha256OfDir(packageDir);
-  if (computedSha !== entry.installed_sha256) {
-    return {
-      kind: 'drift',
-      entry,
-      computedSha,
-      reason:
-        `${packageName}@${entry.version} contents changed after install: ` +
-        `expected sha256 ${entry.installed_sha256.slice(0, 16)}..., got ${computedSha.slice(0, 16)}.... ` +
-        `This indicates post-install tampering of the package files. Recover by running ` +
-        `\`npm uninstall ${packageName} && npm install ${packageName} && npx massu adapters install ${packageName}\`.`,
-    };
-  }
-  return { kind: 'ok', entry };
-}

package/src/security/license-pubkey.generated.ts

@@ -1,30 +0,0 @@
-// AUTO-GENERATED by scripts/bundle-license-pubkey.mjs at 2026-05-17T15:51:32.373Z.
-// Source pem: packages/core/security/license-pubkey.pem
-// RAW-bytes sha256: 18a63d64fdec9e5a368fc45feaa49bed6ced815967e582bc7b8af534f22a9475
-// DO NOT EDIT — regenerate via `node scripts/bundle-license-pubkey.mjs` or
-// the prepublishOnly hook (which runs on every npm publish).
-
-/**
- * Ed25519 public key for verifying signed /validate-key responses from
- * massu.ai. Used by packages/core/src/security/license-response-verifier.ts
- * to reject MITM / malicious-cloud-endpoint responses.
- *
- * P-H019 (plan-stage-c-high-batch / 1.10.5).
- *
- * To rotate: regenerate the keypair via Node crypto.generateKeyPairSync,
- * update packages/core/security/license-pubkey.pem with the new public key,
- * append the new RAW-bytes sha256 to KNOWN_PUBKEY_FINGERPRINTS in
- * scripts/bundle-license-pubkey.mjs (DO NOT delete the old entry during
- * the rotation grace window), then run `node scripts/bundle-license-pubkey.mjs`.
- * Operator then updates the Supabase Edge Function env var
- * `LICENSE_RESPONSE_SIGNING_PRIVATE_KEY_B64` with the new private key.
- */
-export const LICENSE_PUBKEY_ED25519: Uint8Array = new Uint8Array([39, 136, 108, 146, 85, 233, 119, 252, 223, 226, 123, 155, 234, 168, 200, 150, 36, 249, 174, 6, 130, 146, 125, 196, 136, 224, 202, 150, 53, 228, 114, 15]);
-
-/** Hex sha256 of LICENSE_PUBKEY_ED25519 (raw 32 bytes). */
-export const LICENSE_PUBKEY_FINGERPRINT_HEX = '18a63d64fdec9e5a368fc45feaa49bed6ced815967e582bc7b8af534f22a9475';
-
-/** Allowlist of historically-trusted license pubkey fingerprints. */
-export const KNOWN_LICENSE_PUBKEY_FINGERPRINTS: ReadonlySet<string> = new Set([
-  "18a63d64fdec9e5a368fc45feaa49bed6ced815967e582bc7b8af534f22a9475"
-]);