trellis 1.0.8 → 2.0.6

package/src/git/git-reader.ts

@@ -0,0 +1,189 @@
+/**
+ * Git Reader
+ *
+ * Reads a Git repository's commit graph and file-level diffs
+ * by shelling out to `git`. No libgit2 dependency.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GitCommit {
+  hash: string;
+  authorName: string;
+  authorEmail: string;
+  timestamp: string; // ISO 8601
+  message: string;
+  parentHashes: string[];
+}
+
+export interface GitFileChange {
+  status: 'A' | 'M' | 'D' | 'R'; // Added, Modified, Deleted, Renamed
+  path: string;
+  oldPath?: string; // only for renames
+}
+
+export interface GitCommitWithChanges extends GitCommit {
+  changes: GitFileChange[];
+}
+
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+
+export class GitReader {
+  private repoPath: string;
+
+  constructor(repoPath: string) {
+    this.repoPath = repoPath;
+  }
+
+  /**
+   * Verifies this is a valid Git repository.
+   */
+  isGitRepo(): boolean {
+    return existsSync(join(this.repoPath, '.git'));
+  }
+
+  /**
+   * Returns all commits in topological order (oldest first).
+   */
+  readCommits(): GitCommit[] {
+    // Format: hash|authorName|authorEmail|isoTimestamp|parentHashes|subject
+    const SEP = '‖'; // unlikely to appear in commit messages
+    const format = `%H${SEP}%an${SEP}%ae${SEP}%aI${SEP}%P${SEP}%s`;
+
+    const raw = this.git(`log --all --reverse --format="${format}"`);
+    if (!raw.trim()) {
+      return [];
+    }
+
+    return raw
+      .trim()
+      .split('\n')
+      .map((line) => {
+        const parts = line.split(SEP);
+        return {
+          hash: parts[0],
+          authorName: parts[1],
+          authorEmail: parts[2],
+          timestamp: parts[3],
+          parentHashes: parts[4] ? parts[4].split(' ').filter(Boolean) : [],
+          message: parts[5] ?? '',
+        };
+      });
+  }
+
+  /**
+   * Returns file changes for a specific commit.
+   * For the root commit (no parents), diffs against empty tree.
+   */
+  readChanges(commitHash: string, parentHash?: string): GitFileChange[] {
+    let raw: string;
+
+    if (parentHash) {
+      // Diff between parent and this commit
+      raw = this.git(
+        `diff-tree -r --name-status --no-commit-id -M ${parentHash} ${commitHash}`,
+      );
+    } else {
+      // Root commit: use --root flag to diff against empty tree
+      raw = this.git(
+        `diff-tree -r --root --name-status --no-commit-id -M ${commitHash}`,
+      );
+    }
+
+    if (!raw.trim()) {
+      return [];
+    }
+
+    return raw
+      .trim()
+      .split('\n')
+      .map((line) => {
+        const parts = line.split('\t');
+        const statusCode = parts[0].charAt(0) as 'A' | 'M' | 'D' | 'R';
+
+        if (statusCode === 'R') {
+          // Rename: R100\toldPath\tnewPath
+          return { status: 'R', oldPath: parts[1], path: parts[2] };
+        }
+
+        return { status: statusCode, path: parts[1] };
+      });
+  }
+
+  /**
+   * Returns the full content of a file at a specific commit.
+   */
+  readFileContent(commitHash: string, filePath: string): Buffer | null {
+    try {
+      return Buffer.from(this.gitBuffer(`show ${commitHash}:${filePath}`));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Reads all commits with their file changes in topological order.
+   * This is the main entry point for the import pipeline.
+   */
+  readFullHistory(): GitCommitWithChanges[] {
+    const commits = this.readCommits();
+
+    return commits.map((commit) => {
+      const parentHash = commit.parentHashes[0]; // first parent for changes
+      const changes = this.readChanges(commit.hash, parentHash);
+      return { ...commit, changes };
+    });
+  }
+
+  /**
+   * Returns the total number of commits.
+   */
+  commitCount(): number {
+    const raw = this.git('rev-list --all --count');
+    return parseInt(raw.trim(), 10) || 0;
+  }
+
+  /**
+   * Returns the current branch name.
+   */
+  currentBranch(): string {
+    try {
+      return this.git('rev-parse --abbrev-ref HEAD').trim();
+    } catch {
+      return 'main';
+    }
+  }
+
+  /**
+   * Returns all branch names.
+   */
+  branches(): string[] {
+    const raw = this.git('branch --format="%(refname:short)"');
+    return raw.trim().split('\n').filter(Boolean);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------------------
+
+  private git(args: string): string {
+    return execSync(`git -C "${this.repoPath}" ${args}`, {
+      encoding: 'utf-8',
+      maxBuffer: 100 * 1024 * 1024, // 100MB for large repos
+    });
+  }
+
+  private gitBuffer(args: string): Buffer {
+    return execSync(`git -C "${this.repoPath}" ${args}`, {
+      maxBuffer: 100 * 1024 * 1024,
+    });
+  }
+}

package/src/git/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Git Bridge — Public Surface
+ */
+
+export { GitReader } from './git-reader.js';
+export { importFromGit } from './git-importer.js';
+export { exportToGit } from './git-exporter.js';
+export type {
+  ImportOptions,
+  ImportResult,
+  ImportProgress,
+} from './git-importer.js';
+export type {
+  ExportOptions,
+  ExportResult,
+  ExportProgress,
+} from './git-exporter.js';
+export type {
+  GitCommit,
+  GitFileChange,
+  GitCommitWithChanges,
+} from './git-reader.js';

package/src/identity/governance.ts

@@ -0,0 +1,211 @@
+/**
+ * Governance Module
+ *
+ * DESIGN.md §6.3–6.4 — Policy nodes and governance enforcement.
+ *
+ * Policy rules are expressed as EAV entities. The governance engine evaluates
+ * ops against applicable policies before allowing them through.
+ */
+
+import type { VcsOp } from '../vcs/types.js';
+import type { IdentityResolver } from './signing-middleware.js';
+import { verifySignature } from './identity.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PolicyRule {
+  id: string;
+  /** What this policy protects. */
+  target: 'branch' | 'path' | 'entityType';
+  targetPattern: string;
+  /** What action requires authorization. */
+  action: 'push' | 'merge' | 'createMilestone' | 'deleteBranch';
+  /** Who is authorized (identity entity IDs). */
+  requiredSigners: string[];
+  /** Minimum number of valid signatures required. */
+  minSignatures: number;
+  /** Optional: require CI attestation. */
+  requireAttestation?: {
+    type: 'test-pass' | 'build-pass' | 'review-approved';
+    from: string;
+  };
+  /** Whether this policy is active. */
+  enabled: boolean;
+}
+
+export interface PolicyViolation {
+  policyId: string;
+  op: VcsOp;
+  reason: string;
+}
+
+export interface GovernanceResult {
+  allowed: boolean;
+  violations: PolicyViolation[];
+}
+
+// ---------------------------------------------------------------------------
+// Op → action mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine which governance action an op corresponds to.
+ */
+function opToAction(op: VcsOp): string | null {
+  switch (op.kind) {
+    case 'vcs:branchDelete':
+      return 'deleteBranch';
+    case 'vcs:milestoneCreate':
+      return 'createMilestone';
+    case 'vcs:merge':
+      return 'merge';
+    case 'vcs:fileAdd':
+    case 'vcs:fileModify':
+    case 'vcs:fileDelete':
+    case 'vcs:fileRename':
+    case 'vcs:branchAdvance':
+      return 'push';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Check if an op's target matches a policy's target pattern.
+ */
+function matchesTarget(op: VcsOp, policy: PolicyRule): boolean {
+  switch (policy.target) {
+    case 'branch': {
+      const branchName = op.vcs?.branchName ?? op.vcs?.sourceBranch;
+      if (!branchName) return false;
+      return matchGlob(branchName, policy.targetPattern);
+    }
+    case 'path': {
+      const filePath = op.vcs?.filePath;
+      if (!filePath) return false;
+      return matchGlob(filePath, policy.targetPattern);
+    }
+    case 'entityType': {
+      return op.kind.includes(policy.targetPattern.toLowerCase());
+    }
+    default:
+      return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Policy evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate an op against a set of policies.
+ */
+export function evaluatePolicy(
+  op: VcsOp,
+  policies: PolicyRule[],
+  resolver: IdentityResolver,
+): GovernanceResult {
+  const violations: PolicyViolation[] = [];
+  const action = opToAction(op);
+
+  if (!action) {
+    return { allowed: true, violations: [] };
+  }
+
+  const applicable = policies.filter(
+    (p) => p.enabled && p.action === action && matchesTarget(op, p),
+  );
+
+  for (const policy of applicable) {
+    // Check signature requirements
+    if (policy.minSignatures > 0) {
+      const validSigners = countValidSigners(op, policy, resolver);
+
+      if (validSigners < policy.minSignatures) {
+        violations.push({
+          policyId: policy.id,
+          op,
+          reason:
+            `Policy '${policy.id}' requires ${policy.minSignatures} signature(s) ` +
+            `from [${policy.requiredSigners.join(', ')}], got ${validSigners}.`,
+        });
+      }
+    }
+  }
+
+  return {
+    allowed: violations.length === 0,
+    violations,
+  };
+}
+
+/**
+ * Count how many valid required signers signed the op.
+ */
+function countValidSigners(
+  op: VcsOp,
+  policy: PolicyRule,
+  resolver: IdentityResolver,
+): number {
+  if (!op.vcs?.signature || !op.vcs?.signedBy) return 0;
+
+  // Check if the signer is in the required signers list
+  if (!policy.requiredSigners.includes(op.vcs.signedBy)) return 0;
+
+  // Verify signature
+  const publicKey = resolver.resolvePublicKey(op.vcs.signedBy);
+  if (!publicKey) return 0;
+
+  const valid = verifySignature(op.hash, op.vcs.signature, publicKey);
+  return valid ? 1 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Policy CRUD helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new policy rule.
+ */
+export function createPolicy(opts: {
+  id: string;
+  target: PolicyRule['target'];
+  targetPattern: string;
+  action: PolicyRule['action'];
+  requiredSigners: string[];
+  minSignatures?: number;
+}): PolicyRule {
+  return {
+    id: opts.id,
+    target: opts.target,
+    targetPattern: opts.targetPattern,
+    action: opts.action,
+    requiredSigners: opts.requiredSigners,
+    minSignatures: opts.minSignatures ?? 1,
+    enabled: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple glob matcher supporting * and ** patterns.
+ */
+function matchGlob(value: string, pattern: string): boolean {
+  if (pattern === '*' || pattern === '**') return true;
+  if (pattern === value) return true;
+
+  // Convert glob to regex
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '{{DOUBLESTAR}}')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\{\{DOUBLESTAR\}\}/g, '.*');
+
+  const regex = new RegExp(`^${escaped}$`);
+  return regex.test(value);
+}

package/src/identity/identity.ts

@@ -0,0 +1,224 @@
+/**
+ * Identity Module
+ *
+ * Ed25519 key pair generation, DID derivation, and local identity storage.
+ * DESIGN.md §6.1 — Every actor is an Identity entity with a cryptographic key pair.
+ *
+ * Private keys are stored locally in `.trellis/identity.json` (never synced).
+ * Public keys and DIDs are graph entities that get replicated to peers.
+ */
+
+import {
+  generateKeyPairSync,
+  sign,
+  verify,
+  createPublicKey,
+  type KeyObject,
+} from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface IdentityConfig {
+  displayName: string;
+  email?: string;
+  /** Ed25519 public key, base64-encoded. */
+  publicKey: string;
+  /** Ed25519 private key, base64-encoded (local only, never synced). */
+  privateKey: string;
+  /** did:key identifier derived from public key. */
+  did: string;
+  /** Entity ID for use in the EAV store. */
+  entityId: string;
+  /** ISO timestamp of creation. */
+  createdAt: string;
+}
+
+export interface PublicIdentity {
+  displayName: string;
+  email?: string;
+  publicKey: string;
+  did: string;
+  entityId: string;
+  createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Key generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a new Ed25519 identity.
+ */
+export function createIdentity(opts: {
+  displayName: string;
+  email?: string;
+}): IdentityConfig {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+
+  const pubDer = publicKey.export({ type: 'spki', format: 'der' });
+  const privDer = privateKey.export({ type: 'pkcs8', format: 'der' });
+
+  // Extract raw 32-byte public key from SPKI DER (last 32 bytes)
+  const rawPub = pubDer.subarray(pubDer.length - 32);
+
+  const did = deriveDid(rawPub);
+  const entityId = `identity:${did}`;
+
+  return {
+    displayName: opts.displayName,
+    email: opts.email,
+    publicKey: pubDer.toString('base64'),
+    privateKey: privDer.toString('base64'),
+    did,
+    entityId,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Derive a did:key identifier from a raw Ed25519 public key.
+ * Format: did:key:z6Mk... (multicodec 0xed01 prefix + base58btc)
+ */
+function deriveDid(rawPublicKey: Buffer | Uint8Array): string {
+  // Multicodec prefix for Ed25519 public key: 0xed 0x01
+  const multicodec = Buffer.concat([
+    Buffer.from([0xed, 0x01]),
+    Buffer.from(rawPublicKey),
+  ]);
+  // Base58btc encoding
+  const encoded = base58btcEncode(multicodec);
+  return `did:key:z${encoded}`;
+}
+
+// ---------------------------------------------------------------------------
+// Op signing / verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign a message (typically an op hash) with a private key.
+ */
+export function signMessage(
+  message: string,
+  privateKeyBase64: string,
+): string {
+  const privDer = Buffer.from(privateKeyBase64, 'base64');
+  const privateKey = createPrivateKeyFromDer(privDer);
+  const sig = sign(null, Buffer.from(message, 'utf-8'), privateKey);
+  return sig.toString('base64');
+}
+
+/**
+ * Verify a signature against a message and public key.
+ */
+export function verifySignature(
+  message: string,
+  signatureBase64: string,
+  publicKeyBase64: string,
+): boolean {
+  const pubDer = Buffer.from(publicKeyBase64, 'base64');
+  const publicKey = createPublicKey({
+    key: pubDer,
+    format: 'der',
+    type: 'spki',
+  });
+  const sig = Buffer.from(signatureBase64, 'base64');
+  return verify(null, Buffer.from(message, 'utf-8'), publicKey, sig);
+}
+
+// ---------------------------------------------------------------------------
+// Local identity storage
+// ---------------------------------------------------------------------------
+
+const IDENTITY_FILE = 'identity.json';
+
+/**
+ * Save an identity to the local .trellis directory.
+ */
+export function saveIdentity(trellisDir: string, identity: IdentityConfig): void {
+  const filePath = join(trellisDir, IDENTITY_FILE);
+  if (!existsSync(dirname(filePath))) {
+    mkdirSync(dirname(filePath), { recursive: true });
+  }
+  writeFileSync(filePath, JSON.stringify(identity, null, 2), 'utf-8');
+}
+
+/**
+ * Load the local identity from .trellis/identity.json.
+ */
+export function loadIdentity(trellisDir: string): IdentityConfig | null {
+  const filePath = join(trellisDir, IDENTITY_FILE);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8')) as IdentityConfig;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a local identity exists.
+ */
+export function hasIdentity(trellisDir: string): boolean {
+  return existsSync(join(trellisDir, IDENTITY_FILE));
+}
+
+/**
+ * Extract the public (safe-to-share) portion of an identity.
+ */
+export function toPublicIdentity(identity: IdentityConfig): PublicIdentity {
+  return {
+    displayName: identity.displayName,
+    email: identity.email,
+    publicKey: identity.publicKey,
+    did: identity.did,
+    entityId: identity.entityId,
+    createdAt: identity.createdAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createPrivateKeyFromDer(der: Buffer): KeyObject {
+  const { createPrivateKey } = require('crypto');
+  return createPrivateKey({
+    key: der,
+    format: 'der',
+    type: 'pkcs8',
+  });
+}
+
+/**
+ * Base58btc encoding (Bitcoin alphabet).
+ */
+function base58btcEncode(buf: Buffer | Uint8Array): string {
+  const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+  let num = BigInt(0);
+  for (const byte of buf) {
+    num = num * 256n + BigInt(byte);
+  }
+
+  let encoded = '';
+  while (num > 0n) {
+    const rem = Number(num % 58n);
+    num = num / 58n;
+    encoded = ALPHABET[rem] + encoded;
+  }
+
+  // Preserve leading zeros
+  for (const byte of buf) {
+    if (byte === 0) {
+      encoded = '1' + encoded;
+    } else {
+      break;
+    }
+  }
+
+  return encoded || '1';
+}

package/src/identity/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Identity Module — Public Surface
+ */
+
+export {
+  createIdentity,
+  signMessage,
+  verifySignature,
+  saveIdentity,
+  loadIdentity,
+  hasIdentity,
+  toPublicIdentity,
+} from './identity.js';
+
+export type { IdentityConfig, PublicIdentity } from './identity.js';
+
+export { signOp, verifyOp, verifyOpBatch } from './signing-middleware.js';
+
+export type {
+  IdentityResolver,
+  SignatureVerificationResult,
+} from './signing-middleware.js';
+
+export { evaluatePolicy, createPolicy } from './governance.js';
+
+export type {
+  PolicyRule,
+  PolicyViolation,
+  GovernanceResult,
+} from './governance.js';