@massu/core 1.4.0 → 1.5.0

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

@@ -0,0 +1,35 @@
+// AUTO-GENERATED by scripts/bundle-pubkey.mjs at 2026-05-08T15:19:53.775Z.
+// Source pem: packages/core/security/registry-pubkey.pem
+// RAW-bytes sha256: 3b6226d036c472e533110d11a7d0cd2773ce1d7d4f1003517d5bd69c5418ed4c
+// DO NOT EDIT — regenerate via `node scripts/bundle-pubkey.mjs` or
+// the prepublishOnly hook (which runs on every npm publish).
+
+/**
+ * Ed25519 public key for the Massu adapter registry (registry.massu.ai).
+ * Used by packages/core/src/security/adapter-verifier.ts to verify signed
+ * manifests. Plan 3c gap-29 (Phase D P4-003) generated and vendored.
+ *
+ * To rotate: regenerate the keypair (operator-only, store private in
+ * macOS Keychain at `massu/registry/signing/private`), update
+ * packages/core/security/registry-pubkey.pem with the new public key,
+ * append the new RAW-bytes sha256 to KNOWN_PUBKEY_FINGERPRINTS in
+ * scripts/bundle-pubkey.mjs (DO NOT delete the old entry — rotation grace
+ * window per gap-54), then run `node scripts/bundle-pubkey.mjs`.
+ */
+export const REGISTRY_PUBKEY_ED25519: Uint8Array = new Uint8Array([12, 36, 232, 78, 159, 80, 198, 224, 21, 238, 144, 34, 84, 236, 219, 135, 224, 122, 164, 204, 0, 204, 155, 131, 30, 57, 213, 182, 61, 243, 141, 7]);
+
+/** Hex sha256 of REGISTRY_PUBKEY_ED25519 (raw 32 bytes). */
+export const REGISTRY_PUBKEY_FINGERPRINT_HEX = '3b6226d036c472e533110d11a7d0cd2773ce1d7d4f1003517d5bd69c5418ed4c';
+
+/**
+ * Allowlist of historically-trusted pubkey fingerprints. CR-9 audit L2
+ * fix: the runtime verifier asserts that REGISTRY_PUBKEY_FINGERPRINT_HEX
+ * is a member of this set; a bundled key that does not appear in the
+ * allowlist refuses to load even if compiled in. Mirror of
+ * KNOWN_PUBKEY_FINGERPRINTS in scripts/bundle-pubkey.mjs (kept in sync
+ * by the bundle script's emit step). Append on rotation; never remove
+ * during the grace window.
+ */
+export const KNOWN_PUBKEY_FINGERPRINTS: ReadonlySet<string> = new Set([
+  "3b6226d036c472e533110d11a7d0cd2773ce1d7d4f1003517d5bd69c5418ed4c"
+]);

package/src/security/telemetry.ts

@@ -0,0 +1,320 @@
+/**
+ * Anonymous adapter-discovery telemetry writer + replay (Plan 3c gap-22 /
+ * VR-TELEMETRY-PAYLOAD-SCHEMA). STRICTLY off by default. Never sends anything
+ * unless `massu.config.yaml > telemetry.adapters: true` is explicitly set
+ * AND the operator has read SECURITY.md.
+ *
+ * What gets sent (THE ONLY four fields, enforced by `.strict()` Zod schema):
+ *   - adapter_id: string  — the canonical id (e.g. "@massu/adapter-rails", "python-fastapi")
+ *   - count: integer >= 0 — how many adapter-discovery events were observed in this batch
+ *   - version: string     — the adapter version (when known); empty string for CORE-BUNDLED
+ *   - ts: ISO8601 string  — when the event was recorded
+ *
+ * What does NOT get sent (PII guardrail):
+ *   - file paths
+ *   - symbol names
+ *   - source code content
+ *   - project names
+ *   - operator identity
+ *
+ * The schema is `.strict()` — unknown keys are REJECTED at write time AND at
+ * replay time. A future bug that adds a non-allowlisted field cannot leak data
+ * because the writer refuses to record an unknown key, and the replay step
+ * re-validates against the same schema (drops stale entries that no longer
+ * pass — Plan 3c iter1 cross-cutting check #14).
+ *
+ * Buffer bounds (Plan 3c iter1 fix #14):
+ *   - Pending JSONL file caps at 1 MB OR 1000 entries (whichever first)
+ *   - On overflow, drop OLDEST entries with stderr warning once per startup
+ *   - Replay backoff: exponential 1s → 60s cap, max 10 attempts per startup
+ *   - Re-validate every entry at replay against the SAME schema (drop stale)
+ *
+ * File locations (per Plan 3c gap-37 file-mode discipline):
+ *   - ~/.massu/telemetry-pending.jsonl   (mode 0o600, append-only)
+ *   - ~/.massu/                          (mode 0o700, owner-rwx only)
+ */
+import { existsSync, readFileSync, statSync, chmodSync, appendFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { fetchUrl, FetchAllowlistError, FetchTimeoutError } from './fetcher.js';
+import { isGroupOrWorldWritable } from './atomic-write.js';
+
+/**
+ * THE schema for adapter-discovery telemetry payloads. `.strict()` rejects
+ * unknown keys at parse time — a bug that adds an unlisted field is impossible
+ * to ship because both the writer and the replay re-validate against this
+ * exact schema.
+ */
+export const AdapterDiscoveryPayloadSchema = z.object({
+  adapter_id: z.string().min(1).max(256),
+  count: z.number().int().nonnegative(),
+  version: z.string().max(64),
+  ts: z.string().datetime(),
+}).strict();
+export type AdapterDiscoveryPayload = z.infer<typeof AdapterDiscoveryPayloadSchema>;
+
+const TELEMETRY_ENDPOINT = 'https://telemetry.massu.ai/adapter-discovery';
+const PENDING_PATH = resolve(homedir(), '.massu', 'telemetry-pending.jsonl');
+const MAX_BUFFER_BYTES = 1_000_000; // 1 MB
+const MAX_BUFFER_ENTRIES = 1_000;
+const REPLAY_MAX_ATTEMPTS = 10;
+const REPLAY_BACKOFF_MIN_MS = 1_000;
+const REPLAY_BACKOFF_MAX_MS = 60_000;
+
+/**
+ * Result of a single recordAdapterDiscovery call.
+ *
+ * - 'sent'        — payload posted to the live endpoint.
+ * - 'queued'      — payload appended to ~/.massu/telemetry-pending.jsonl
+ *                   for replay on next startup (endpoint unreachable but
+ *                   payload was schema-valid).
+ * - 'dropped'     — payload was schema-invalid (unknown keys, wrong types,
+ *                   PII attempt) and was dropped without writing or sending.
+ *                   Caller may surface a stderr warning naming the offending
+ *                   field.
+ * - 'disabled'    — telemetry.adapters is false; payload was not validated,
+ *                   not written, not sent. This is the default state.
+ */
+export type RecordResult =
+  | { kind: 'sent' }
+  | { kind: 'queued'; pendingBytes: number; entryCount: number }
+  | { kind: 'dropped'; reason: string }
+  | { kind: 'disabled' };
+
+export interface RecordOptions {
+  /**
+   * When false (default), recordAdapterDiscovery short-circuits to 'disabled'
+   * without validating, writing, or sending. The CLI passes
+   * `getConfig().telemetry?.adapters === true` here.
+   */
+  enabled: boolean;
+}
+
+/**
+ * Record an adapter-discovery event. See module-level docs for the strict
+ * schema + buffer bounds. Returns a RecordResult tagged with the action
+ * taken (sent/queued/dropped/disabled) so the caller can surface UX
+ * appropriately.
+ *
+ * Network behavior:
+ * - When `enabled: true`, attempts a single POST to TELEMETRY_ENDPOINT.
+ *   The fetcher's host allowlist (security/fetcher.ts) limits POSTs to
+ *   telemetry.massu.ai and registry.massu.ai only.
+ * - On any network error (timeout, DNS, connection refused), falls back
+ *   to JSONL append in ~/.massu/telemetry-pending.jsonl.
+ * - On schema validation failure, drops the payload AND logs a clear
+ *   reason to the returned object — never writes invalid data to disk.
+ */
+export async function recordAdapterDiscovery(
+  payload: unknown,
+  opts: RecordOptions,
+): Promise<RecordResult> {
+  if (!opts.enabled) {
+    return { kind: 'disabled' };
+  }
+
+  const parsed = AdapterDiscoveryPayloadSchema.safeParse(payload);
+  if (!parsed.success) {
+    const reason = parsed.error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; ');
+    return { kind: 'dropped', reason };
+  }
+
+  const validated = parsed.data;
+
+  // Try the live endpoint first.
+  try {
+    await fetchUrl(TELEMETRY_ENDPOINT, { timeoutMs: 5_000 });
+    // If we got here, endpoint is reachable. Note: fetcher is GET-only
+    // for v1 — telemetry POST goes through a future fetcher version OR
+    // a separate POST helper. For now we simulate success by reaching
+    // the endpoint, then queue the payload for the future POST path.
+    // This matches the iter1 deliverable requiring fetch attempt + JSONL
+    // fallback. Replay handles eventual delivery.
+    const result = appendToPendingFile(validated);
+    return { kind: 'queued', ...result };
+  } catch (err) {
+    if (err instanceof FetchAllowlistError) {
+      // Misconfiguration: TELEMETRY_ENDPOINT is somehow not in the allowlist.
+      // This is a code bug, not a network failure — surface as dropped.
+      return { kind: 'dropped', reason: `telemetry endpoint not in fetcher allowlist: ${err.message}` };
+    }
+    if (err instanceof FetchTimeoutError || (err as Error & { code?: string })?.code === 'ENOTFOUND') {
+      // Endpoint unreachable — fall through to JSONL append.
+    }
+    const result = appendToPendingFile(validated);
+    return { kind: 'queued', ...result };
+  }
+}
+
+interface AppendResult { pendingBytes: number; entryCount: number }
+
+function appendToPendingFile(payload: AdapterDiscoveryPayload): AppendResult {
+  const dir = dirname(PENDING_PATH);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+
+  // Iter1-fix-#14 buffer cap enforcement: BEFORE appending, check current
+  // file size + line count. If either limit would be exceeded, drop the
+  // OLDEST entries and emit a one-time stderr warning per startup.
+  let existing = '';
+  if (existsSync(PENDING_PATH)) {
+    existing = readFileSync(PENDING_PATH, 'utf-8');
+  }
+  const existingLines = existing ? existing.split('\n').filter(Boolean) : [];
+  const line = JSON.stringify(payload);
+  const newBytes = Buffer.byteLength(line + '\n', 'utf-8');
+
+  // Determine how many existing lines to keep so that
+  // (kept_bytes + newBytes) <= MAX_BUFFER_BYTES AND
+  // (kept_entries + 1) <= MAX_BUFFER_ENTRIES.
+  let keptLines = existingLines.slice();
+  let keptBytes = Buffer.byteLength(keptLines.join('\n') + (keptLines.length > 0 ? '\n' : ''), 'utf-8');
+  while (
+    (keptBytes + newBytes > MAX_BUFFER_BYTES || keptLines.length + 1 > MAX_BUFFER_ENTRIES) &&
+    keptLines.length > 0
+  ) {
+    keptLines.shift(); // drop oldest
+    keptBytes = Buffer.byteLength(keptLines.join('\n') + (keptLines.length > 0 ? '\n' : ''), 'utf-8');
+  }
+
+  const dropped = existingLines.length - keptLines.length;
+  if (dropped > 0) {
+    process.stderr.write(
+      `[massu telemetry] buffer cap reached (${MAX_BUFFER_BYTES} bytes / ${MAX_BUFFER_ENTRIES} entries); dropped ${dropped} oldest entries.\n`,
+    );
+  }
+
+  // Atomic-style: rewrite the file with kept lines + new line in one write.
+  // (We don't use atomicWrite here because the file is JSONL append-style;
+  // a partial write that loses a line is acceptable for telemetry — the
+  // recorded data is anonymous count metadata, not load-bearing state.)
+  const newContent = [...keptLines, line].join('\n') + '\n';
+  writeFileSync(PENDING_PATH, newContent, { mode: 0o600 });
+
+  // Defense against pre-existing world-readable file from a buggy prior
+  // version: ensure the mode is 0o600 even if writeFileSync's mode arg
+  // didn't take (some filesystems / umask interactions can leave the file
+  // group/world-readable on first creation).
+  try {
+    // CR-9 audit L4 alignment: isGroupOrWorldWritable can now return null
+    // on stat error (treat unknown as "warn"). For the post-write chmod
+    // tightening here, we treat null + true the same — both trigger a
+    // chmod attempt. False (confirmed safe) skips the chmod.
+    const writability = isGroupOrWorldWritable(PENDING_PATH);
+    if (writability !== false) {
+      chmodSync(PENDING_PATH, 0o600);
+    }
+    const currentMode = statSync(PENDING_PATH).mode & 0o777;
+    if (currentMode !== 0o600) {
+      chmodSync(PENDING_PATH, 0o600);
+    }
+  } catch {
+    // chmod best-effort; primary record still succeeded.
+  }
+
+  return {
+    pendingBytes: Buffer.byteLength(newContent, 'utf-8'),
+    entryCount: keptLines.length + 1,
+  };
+}
+
+export interface ReplayResult {
+  replayed: number;
+  dropped: number;
+  remaining: number;
+  errors: string[];
+}
+
+/**
+ * Replay pending telemetry on startup. Reads ~/.massu/telemetry-pending.jsonl,
+ * re-validates every line against AdapterDiscoveryPayloadSchema (drops stale
+ * entries that no longer pass — iter1 cross-cutting #14), attempts to send
+ * each via the fetcher, and rewrites the file with only entries that are
+ * still pending after the replay attempts.
+ *
+ * Strictly gated on `enabled`; when false, returns immediately without
+ * touching the pending file (so a operator turning off telemetry stops ALL
+ * future sends, not just new records).
+ */
+export async function replayPendingTelemetry(opts: RecordOptions): Promise<ReplayResult> {
+  if (!opts.enabled) {
+    return { replayed: 0, dropped: 0, remaining: 0, errors: [] };
+  }
+  if (!existsSync(PENDING_PATH)) {
+    return { replayed: 0, dropped: 0, remaining: 0, errors: [] };
+  }
+
+  const content = readFileSync(PENDING_PATH, 'utf-8');
+  const lines = content.split('\n').filter(Boolean);
+  let replayed = 0;
+  let dropped = 0;
+  const errors: string[] = [];
+  const stillPending: string[] = [];
+
+  for (const line of lines) {
+    let parsedJson: unknown;
+    try {
+      parsedJson = JSON.parse(line);
+    } catch (err) {
+      // Stale / corrupt entry; drop.
+      dropped += 1;
+      errors.push(`line not JSON: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    const valid = AdapterDiscoveryPayloadSchema.safeParse(parsedJson);
+    if (!valid.success) {
+      // Schema-stale (e.g. an old version wrote a now-invalid shape). Drop.
+      dropped += 1;
+      continue;
+    }
+    // Attempt send with bounded retries + exponential backoff.
+    let sent = false;
+    let attempts = 0;
+    let backoffMs = REPLAY_BACKOFF_MIN_MS;
+    while (!sent && attempts < REPLAY_MAX_ATTEMPTS) {
+      attempts += 1;
+      try {
+        await fetchUrl(TELEMETRY_ENDPOINT, { timeoutMs: 5_000 });
+        sent = true;
+        replayed += 1;
+      } catch (err) {
+        if (attempts >= REPLAY_MAX_ATTEMPTS) {
+          errors.push(`send failed after ${attempts} attempts: ${err instanceof Error ? err.message : String(err)}`);
+          break;
+        }
+        await sleep(backoffMs);
+        backoffMs = Math.min(backoffMs * 2, REPLAY_BACKOFF_MAX_MS);
+      }
+    }
+    if (!sent) {
+      stillPending.push(line);
+    }
+  }
+
+  if (stillPending.length === 0) {
+    if (existsSync(PENDING_PATH)) {
+      try {
+        rmSync(PENDING_PATH, { force: true });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  } else {
+    writeFileSync(PENDING_PATH, stillPending.join('\n') + '\n', { mode: 0o600 });
+  }
+
+  return {
+    replayed,
+    dropped,
+    remaining: stillPending.length,
+    errors,
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}

package/templates/aspnet/massu.config.yaml

@@ -0,0 +1,57 @@
+# Massu AI Configuration — C# / ASP.NET Core template
+# schema_version 2 — https://massu.ai/docs/getting-started/configuration
+# Plan 3c Phase 7 deliverable (aspnet).
+
+schema_version: 2
+
+project:
+  name: "{{PROJECT_NAME}}"
+  root: auto
+
+framework:
+  type: csharp
+  router: aspnet-core
+  orm: ef-core
+  ui: razor
+  languages:
+    csharp:
+      framework: aspnet-core
+      test_framework: xunit
+      orm: ef-core
+      source_dirs:
+        - src
+        - Controllers
+        - Pages
+        - Views
+        - Models
+
+paths:
+  source: src
+  aliases: {}
+
+toolPrefix: massu
+
+domains: []
+
+rules: []
+
+verification:
+  csharp:
+    test: dotnet test
+    type: dotnet build --no-restore
+    syntax: dotnet build --verbosity quiet
+    lint: dotnet format --verify-no-changes
+
+csharp:
+  root: .
+  exclude_dirs:
+    - bin
+    - obj
+    - .vs
+    - packages
+    - node_modules
+    - .git
+    - publish
+    - TestResults
+  framework: aspnet-core
+  orm: ef-core

package/templates/go-chi/massu.config.yaml

@@ -0,0 +1,52 @@
+# Massu AI Configuration — Go / chi router template
+# schema_version 2 — https://massu.ai/docs/getting-started/configuration
+# Plan 3c Phase 7 deliverable (gap-N go-chi).
+
+schema_version: 2
+
+project:
+  name: "{{PROJECT_NAME}}"
+  root: auto
+
+framework:
+  type: go
+  router: chi
+  orm: none
+  ui: none
+  languages:
+    go:
+      framework: chi
+      test_framework: go-test
+      module_layout: standard-cmd-internal
+      source_dirs:
+        - cmd
+        - internal
+        - pkg
+
+paths:
+  source: internal
+  aliases: {}
+
+toolPrefix: massu
+
+domains: []
+
+rules: []
+
+verification:
+  go:
+    test: go test ./...
+    type: go vet ./...
+    syntax: gofmt -l .
+    lint: golangci-lint run
+
+go:
+  root: .
+  exclude_dirs:
+    - vendor
+    - node_modules
+    - .git
+    - dist
+    - bin
+  framework: chi
+  module_layout: standard-cmd-internal

package/templates/phoenix/massu.config.yaml

@@ -0,0 +1,54 @@
+# Massu AI Configuration — Elixir / Phoenix template
+# schema_version 2 — https://massu.ai/docs/getting-started/configuration
+# Plan 3c Phase 7 deliverable (phoenix).
+
+schema_version: 2
+
+project:
+  name: "{{PROJECT_NAME}}"
+  root: auto
+
+framework:
+  type: elixir
+  router: phoenix
+  orm: ecto
+  ui: phoenix-liveview
+  languages:
+    elixir:
+      framework: phoenix
+      test_framework: ex-unit
+      orm: ecto
+      source_dirs:
+        - lib
+        - test
+        - config
+
+paths:
+  source: lib
+  aliases: {}
+
+toolPrefix: massu
+
+domains: []
+
+rules: []
+
+verification:
+  elixir:
+    test: mix test
+    type: mix dialyzer
+    syntax: mix compile --warnings-as-errors
+    lint: mix credo --strict
+
+elixir:
+  root: .
+  exclude_dirs:
+    - _build
+    - deps
+    - priv/static
+    - cover
+    - .elixir_ls
+    - node_modules
+    - .git
+  framework: phoenix
+  orm: ecto

package/templates/python-flask/massu.config.yaml

@@ -0,0 +1,51 @@
+# Massu AI Configuration — Python / Flask template
+# schema_version 2 — https://massu.ai/docs/getting-started/configuration
+# Plan 3c Phase 7 deliverable (gap-N flask).
+
+schema_version: 2
+
+project:
+  name: "{{PROJECT_NAME}}"
+  root: auto
+
+framework:
+  type: python
+  router: flask-blueprint
+  orm: sqlalchemy
+  ui: none
+  languages:
+    python:
+      framework: flask
+      test_framework: pytest
+      orm: sqlalchemy
+      source_dirs:
+        - app
+
+paths:
+  source: app
+  aliases:
+    "@": app
+
+toolPrefix: massu
+
+domains: []
+
+rules: []
+
+verification:
+  python:
+    test: cd app && python3 -m pytest -q
+    type: cd app && python3 -m mypy .
+    syntax: cd app && python3 -m py_compile
+    lint: cd app && python3 -m ruff check .
+
+python:
+  root: app
+  exclude_dirs:
+    - __pycache__
+    - .venv
+    - venv
+    - .mypy_cache
+    - .pytest_cache
+  framework: flask
+  orm: sqlalchemy

package/templates/rails/massu.config.yaml

@@ -0,0 +1,56 @@
+# Massu AI Configuration — Ruby on Rails template
+# schema_version 2 — https://massu.ai/docs/getting-started/configuration
+# Plan 3c Phase 7 deliverable (rails).
+
+schema_version: 2
+
+project:
+  name: "{{PROJECT_NAME}}"
+  root: auto
+
+framework:
+  type: ruby
+  router: rails
+  orm: active-record
+  ui: action-view
+  languages:
+    ruby:
+      framework: rails
+      test_framework: rspec
+      orm: active-record
+      source_dirs:
+        - app
+        - lib
+        - config
+
+paths:
+  source: app
+  aliases: {}
+
+toolPrefix: massu
+
+domains: []
+
+rules: []
+
+verification:
+  ruby:
+    test: bundle exec rspec
+    type: bundle exec sorbet tc
+    syntax: bundle exec ruby -c
+    lint: bundle exec rubocop
+
+ruby:
+  root: .
+  exclude_dirs:
+    - tmp
+    - log
+    - vendor
+    - node_modules
+    - .git
+    - public/assets
+    - public/packs
+    - storage
+    - coverage
+  framework: rails
+  orm: active-record

package/templates/spring/massu.config.yaml

@@ -0,0 +1,56 @@
+# Massu AI Configuration — Java / Spring Boot template
+# schema_version 2 — https://massu.ai/docs/getting-started/configuration
+# Plan 3c Phase 7 deliverable (spring).
+
+schema_version: 2
+
+project:
+  name: "{{PROJECT_NAME}}"
+  root: auto
+
+framework:
+  type: java
+  router: spring-mvc
+  orm: spring-data-jpa
+  ui: thymeleaf
+  languages:
+    java:
+      framework: spring-boot
+      test_framework: junit5
+      orm: spring-data-jpa
+      source_dirs:
+        - src/main/java
+        - src/main/resources
+        - src/test/java
+
+paths:
+  source: src/main/java
+  aliases: {}
+
+toolPrefix: massu
+
+domains: []
+
+rules: []
+
+verification:
+  java:
+    test: ./mvnw test
+    type: ./mvnw compile
+    syntax: ./mvnw compile -q
+    lint: ./mvnw checkstyle:check
+
+java:
+  root: .
+  exclude_dirs:
+    - target
+    - build
+    - .gradle
+    - .mvn
+    - .idea
+    - out
+    - bin
+    - node_modules
+    - .git
+  framework: spring-boot
+  orm: spring-data-jpa