@enbox/gitd 0.0.1

package/src/resolver/trust-chain.ts

@@ -0,0 +1,217 @@
+/**
+ * Dependency trust chain — recursive verification of a package's
+ * dependency tree.
+ *
+ * Given a root package specifier like `did:dht:abc/utils@1.0.0`, the
+ * trust chain validator:
+ *
+ *   1. Resolves the package from the publisher's DWN
+ *   2. Verifies the package version (author, tarball, attestations)
+ *   3. Reads the version's `dependencies` field
+ *   4. Recursively resolves and verifies each dependency
+ *   5. Returns a tree of verification results
+ *
+ * The entire chain is verifiable without any central authority — each
+ * DID resolution, signature verification, and attestation check uses
+ * decentralized infrastructure.
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../cli/agent.js';
+import type { VerificationResult } from './verify.js';
+
+import { verifyPackageVersion } from './verify.js';
+
+import { parseSpecifier, resolvePackage, resolveVersion } from './resolve.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single node in the dependency trust chain tree. */
+export type TrustChainNode = {
+  specifier : string;
+  did : string;
+  name : string;
+  version : string;
+  verification : VerificationResult;
+  dependencies : TrustChainNode[];
+};
+
+/** Summary of the trust chain validation. */
+export type TrustChainResult = {
+  root : TrustChainNode;
+  totalChecked : number;
+  allPassed : boolean;
+  failures : string[];
+};
+
+// ---------------------------------------------------------------------------
+// Trust chain builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build and verify a full dependency trust chain.
+ *
+ * @param ctx - Agent context
+ * @param targetDid - Root package publisher DID
+ * @param name - Root package name
+ * @param semver - Root package version
+ * @param ecosystem - Package ecosystem (default: 'npm')
+ * @param trustedAttestors - DIDs of trusted build services
+ * @param maxDepth - Maximum recursion depth (default: 10)
+ */
+export async function buildTrustChain(
+  ctx: AgentContext,
+  targetDid: string,
+  name: string,
+  semver: string,
+  ecosystem: string = 'npm',
+  trustedAttestors: string[] = [],
+  maxDepth: number = 10,
+): Promise<TrustChainResult> {
+  const visited = new Set<string>();
+  const failures: string[] = [];
+  let totalChecked = 0;
+
+  const root = await buildNode(
+    ctx, targetDid, name, semver, ecosystem, trustedAttestors,
+    maxDepth, 0, visited, failures,
+  );
+
+  totalChecked = visited.size;
+  const allPassed = failures.length === 0;
+
+  return { root, totalChecked, allPassed, failures };
+}
+
+/**
+ * Recursively build a trust chain node.
+ */
+async function buildNode(
+  ctx: AgentContext,
+  targetDid: string,
+  name: string,
+  semver: string,
+  ecosystem: string,
+  trustedAttestors: string[],
+  maxDepth: number,
+  depth: number,
+  visited: Set<string>,
+  failures: string[],
+): Promise<TrustChainNode> {
+  const specifier = `${targetDid}/${name}@${semver}`;
+  const node: TrustChainNode = {
+    specifier,
+    did          : targetDid,
+    name,
+    version      : semver,
+    verification : {
+      passed       : false,
+      publisherDid : targetDid,
+      packageName  : name,
+      version      : semver,
+      checks       : [],
+      attestations : [],
+    },
+    dependencies: [],
+  };
+
+  // Cycle detection.
+  if (visited.has(specifier)) {
+    node.verification.passed = true;
+    node.verification.checks = [{ check: 'cycle-skip', passed: true, detail: 'Already verified (cycle)' }];
+    return node;
+  }
+  visited.add(specifier);
+
+  // Depth guard.
+  if (depth > maxDepth) {
+    node.verification.checks = [{ check: 'max-depth', passed: true, detail: `Max depth ${maxDepth} reached` }];
+    node.verification.passed = true;
+    return node;
+  }
+
+  // Verify this package version.
+  node.verification = await verifyPackageVersion(
+    ctx, targetDid, name, semver, ecosystem, trustedAttestors,
+  );
+
+  if (!node.verification.passed) {
+    failures.push(`${specifier}: ${node.verification.checks.filter((c) => !c.passed).map((c) => c.detail).join('; ')}`);
+  }
+
+  // Resolve dependencies.
+  const pkg = await resolvePackage(ctx, targetDid, name, ecosystem);
+  if (!pkg) { return node; }
+
+  const version = await resolveVersion(ctx, targetDid, pkg.contextId, semver);
+  if (!version || !version.dependencies) { return node; }
+
+  const deps = version.dependencies;
+  for (const [depSpec, depVersion] of Object.entries(deps)) {
+    const parsed = parseSpecifier(`${depSpec}@${depVersion}`);
+    if (!parsed) {
+      // Dependency specifier is not a DID-scoped package — skip.
+      continue;
+    }
+
+    const childNode = await buildNode(
+      ctx, parsed.did, parsed.name, parsed.version, ecosystem,
+      trustedAttestors, maxDepth, depth + 1, visited, failures,
+    );
+
+    node.dependencies.push(childNode);
+  }
+
+  return node;
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a trust chain tree as an indented string for CLI output.
+ */
+export function formatTrustChain(result: TrustChainResult): string {
+  const lines: string[] = [];
+
+  lines.push(`Trust chain for ${result.root.specifier}`);
+  lines.push(`  Total packages checked: ${result.totalChecked}`);
+  lines.push(`  All passed: ${result.allPassed ? 'yes' : 'NO'}`);
+
+  if (result.failures.length > 0) {
+    lines.push('  Failures:');
+    for (const f of result.failures) {
+      lines.push(`    - ${f}`);
+    }
+  }
+
+  lines.push('');
+  formatNode(result.root, lines, 0);
+
+  return lines.join('\n');
+}
+
+function formatNode(node: TrustChainNode, lines: string[], depth: number): void {
+  const indent = '  '.repeat(depth);
+  const status = node.verification.passed ? 'PASS' : 'FAIL';
+  lines.push(`${indent}${status} ${node.specifier}`);
+
+  for (const check of node.verification.checks) {
+    const mark = check.passed ? '+' : 'x';
+    lines.push(`${indent}  [${mark}] ${check.check}: ${check.detail}`);
+  }
+
+  if (node.verification.attestations.length > 0) {
+    for (const att of node.verification.attestations) {
+      lines.push(`${indent}  [a] ${att.claim} by ${att.attestorDid}`);
+    }
+  }
+
+  for (const child of node.dependencies) {
+    formatNode(child, lines, depth + 1);
+  }
+}

package/src/resolver/verify.ts

@@ -0,0 +1,237 @@
+/**
+ * Package verification — cryptographic verification of DWN package records.
+ *
+ * Verification checks:
+ *   1. **Author verification**: the record's `author` DID matches the publisher
+ *   2. **Attestation verification**: third-party attestation records are present
+ *      and signed by trusted attestors
+ *   3. **Integrity check**: tarball exists and is non-empty
+ *
+ * Since every DWN record is cryptographically signed via JWS in the
+ * `authorization` field, verification relies on the DWN SDK having
+ * already validated signatures during record ingestion.  Our verification
+ * layer adds semantic checks on top of that foundation.
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../cli/agent.js';
+
+import { DateSort } from '@enbox/dwn-sdk-js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Individual verification check result. */
+export type VerificationCheck = {
+  check : string;
+  passed : boolean;
+  detail : string;
+};
+
+/** Attestation record as returned by the DWN. */
+export type AttestationRecord = {
+  attestorDid : string;
+  claim : string;
+  sourceCommit : string | undefined;
+  sourceRepo : string | undefined;
+  dateCreated : string;
+};
+
+/** Full verification result for a package version. */
+export type VerificationResult = {
+  passed : boolean;
+  publisherDid : string;
+  packageName : string;
+  version : string;
+  checks : VerificationCheck[];
+  attestations : AttestationRecord[];
+};
+
+// ---------------------------------------------------------------------------
+// Attestation queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch attestation records for a specific package version.
+ */
+export async function fetchAttestations(
+  ctx: AgentContext,
+  targetDid: string,
+  versionContextId: string,
+): Promise<AttestationRecord[]> {
+  const from = targetDid === ctx.did ? undefined : targetDid;
+
+  const { records } = await ctx.registry.records.query('package/version/attestation' as any, {
+    from,
+    filter   : { contextId: versionContextId },
+    dateSort : DateSort.CreatedAscending,
+  });
+
+  const attestations: AttestationRecord[] = [];
+  for (const rec of records) {
+    const data = await rec.data.json() as Record<string, unknown>;
+    attestations.push({
+      attestorDid  : String(data.attestorDid ?? ''),
+      claim        : String(data.claim ?? ''),
+      sourceCommit : data.sourceCommit as string | undefined,
+      sourceRepo   : data.sourceRepo as string | undefined,
+      dateCreated  : rec.dateCreated,
+    });
+  }
+
+  return attestations;
+}
+
+// ---------------------------------------------------------------------------
+// Verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a package version's integrity and provenance.
+ *
+ * Performs the following checks:
+ *   1. Package record exists and is owned by the expected DID
+ *   2. Version record exists and is authored by the publisher
+ *   3. Tarball exists and is non-empty
+ *   4. Attestations are present (informational — not required to pass)
+ *
+ * @param ctx - Agent context
+ * @param targetDid - Expected publisher DID
+ * @param name - Package name
+ * @param semver - Version string
+ * @param ecosystem - Ecosystem (default: 'npm')
+ * @param trustedAttestors - DIDs of trusted attestors (optional)
+ */
+export async function verifyPackageVersion(
+  ctx: AgentContext,
+  targetDid: string,
+  name: string,
+  semver: string,
+  ecosystem: string = 'npm',
+  trustedAttestors: string[] = [],
+): Promise<VerificationResult> {
+  const checks: VerificationCheck[] = [];
+  const from = targetDid === ctx.did ? undefined : targetDid;
+
+  // -------------------------------------------------------------------------
+  // 1. Package record exists
+  // -------------------------------------------------------------------------
+  const { records: pkgRecords } = await ctx.registry.records.query('package', {
+    from,
+    filter: { tags: { name, ecosystem } },
+  });
+
+  if (pkgRecords.length === 0) {
+    checks.push({ check: 'package-exists', passed: false, detail: `Package '${name}' not found on ${targetDid}` });
+    return { passed: false, publisherDid: targetDid, packageName: name, version: semver, checks, attestations: [] };
+  }
+
+  const pkgRec = pkgRecords[0];
+  checks.push({ check: 'package-exists', passed: true, detail: `Package '${name}' found` });
+
+  // -------------------------------------------------------------------------
+  // 2. Publisher matches — the record author is the expected DID
+  // -------------------------------------------------------------------------
+  const authorMatchesPkg = pkgRec.author === targetDid || pkgRec.creator === targetDid;
+  checks.push({
+    check  : 'publisher-match',
+    passed : authorMatchesPkg,
+    detail : authorMatchesPkg
+      ? `Package authored by ${targetDid}`
+      : `Package author ${pkgRec.author} does not match expected ${targetDid}`,
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. Version record exists and is authored by the publisher
+  // -------------------------------------------------------------------------
+  const { records: verRecords } = await ctx.registry.records.query('package/version' as any, {
+    from,
+    filter: {
+      contextId : pkgRec.contextId,
+      tags      : { semver },
+    },
+  });
+
+  if (verRecords.length === 0) {
+    checks.push({ check: 'version-exists', passed: false, detail: `Version ${semver} not found` });
+    return { passed: false, publisherDid: targetDid, packageName: name, version: semver, checks, attestations: [] };
+  }
+
+  const verRec = verRecords[0];
+  checks.push({ check: 'version-exists', passed: true, detail: `Version ${semver} found` });
+
+  const authorMatchesVer = verRec.author === targetDid || verRec.creator === targetDid;
+  checks.push({
+    check  : 'version-author',
+    passed : authorMatchesVer,
+    detail : authorMatchesVer
+      ? `Version authored by ${targetDid}`
+      : `Version author ${verRec.author} does not match expected ${targetDid}`,
+  });
+
+  // -------------------------------------------------------------------------
+  // 4. Tarball exists and is non-empty
+  // -------------------------------------------------------------------------
+  const { records: tarRecords } = await ctx.registry.records.query('package/version/tarball' as any, {
+    from,
+    filter: { contextId: verRec.contextId },
+  });
+
+  if (tarRecords.length === 0) {
+    checks.push({ check: 'tarball-exists', passed: false, detail: 'No tarball found' });
+  } else {
+    const tarRec = tarRecords[0];
+    const size = tarRec.dataSize ?? 0;
+    const hasData = size > 0;
+    checks.push({
+      check  : 'tarball-exists',
+      passed : hasData,
+      detail : hasData ? `Tarball present (${size} bytes)` : 'Tarball is empty',
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // 5. Attestations
+  // -------------------------------------------------------------------------
+  const attestations = await fetchAttestations(ctx, targetDid, verRec.contextId ?? '');
+
+  if (attestations.length > 0) {
+    checks.push({
+      check  : 'has-attestations',
+      passed : true,
+      detail : `${attestations.length} attestation(s) found`,
+    });
+  } else {
+    checks.push({
+      check  : 'has-attestations',
+      passed : true, // Informational — not required
+      detail : 'No attestations (none required)',
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // 6. Trusted attestor check (only if trustedAttestors provided)
+  // -------------------------------------------------------------------------
+  if (trustedAttestors.length > 0) {
+    const trustedFound = attestations.filter(
+      (a) => trustedAttestors.includes(a.attestorDid),
+    );
+
+    checks.push({
+      check  : 'trusted-attestor',
+      passed : trustedFound.length > 0,
+      detail : trustedFound.length > 0
+        ? `${trustedFound.length} trusted attestation(s): ${trustedFound.map((a) => a.claim).join(', ')}`
+        : `No attestations from trusted attestors: ${trustedAttestors.join(', ')}`,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Overall result
+  // -------------------------------------------------------------------------
+  const passed = checks.every((c) => c.passed);
+
+  return { passed, publisherDid: targetDid, packageName: name, version: semver, checks, attestations };
+}

package/src/shims/go/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Go module proxy shim module — DID-scoped module resolution via the
+ * GOPROXY HTTP protocol.
+ *
+ * @module
+ */
+
+export { handleGoProxyRequest, parseGoModulePath } from './proxy.js';
+
+export type { GoProxyResponse } from './proxy.js';
+
+export { startGoShim } from './server.js';
+
+export type { GoShimOptions } from './server.js';