@enbox/gitd 0.0.1

package/src/git-server/bundle-sync.ts

@@ -0,0 +1,300 @@
+/**
+ * Git bundle → DWN sync — creates/updates a git bundle as a DWN record.
+ *
+ * After a successful `git push`, this module generates a `git bundle` from
+ * the bare repository and writes it as a ForgeRepo `bundle` record.
+ * Incremental bundles are created when a previous bundle exists; periodic
+ * squash writes compact all incrementals into a single full bundle.
+ *
+ * Bundle sync flow:
+ * 1. Query existing bundle records for the repo (sorted by timestamp desc)
+ * 2. If no bundles exist → create full bundle (`git bundle create --all`)
+ * 3. If bundles exist → create incremental bundle since last tip commit
+ * 4. Every N pushes (configurable), create a squash bundle (full bundle
+ *    with `squash: true`) which purges all older bundle records
+ *
+ * The bundle data (binary `application/x-git-bundle`) is stored as the
+ * record payload. Queryable metadata is stored in tags.
+ *
+ * @module
+ */
+
+import type { ForgeRepoProtocol } from '../repo.js';
+import type { ForgeRepoSchemaMap } from '../repo.js';
+import type { OnPushComplete } from './ref-sync.js';
+import type { TypedWeb5 } from '@enbox/api';
+
+import { DateSort } from '@enbox/dwn-sdk-js';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { readFile, stat, unlink } from 'node:fs/promises';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for creating a bundle syncer. */
+export type BundleSyncOptions = {
+  /** The typed ForgeRepoProtocol Web5 handle. */
+  repo: TypedWeb5<typeof ForgeRepoProtocol.definition, ForgeRepoSchemaMap>;
+
+  /** The repo's contextId (from the ForgeRepoProtocol repo record). */
+  repoContextId: string;
+
+  /**
+   * Repo visibility — controls whether bundle records are encrypted.
+   *
+   * - `'private'` → bundles are JWE-encrypted (only key-holders can read)
+   * - `'public'`  → bundles are plaintext (IPFS-friendly, globally readable)
+   *
+   * The protocol must be installed with `encryption: true` for private repos
+   * to work (this injects `$encryption` keys on all protocol paths).
+   *
+   * @default 'public'
+   */
+  visibility?: 'public' | 'private';
+
+  /**
+   * Number of incremental bundles to accumulate before squashing.
+   * When this threshold is reached, the next bundle write is a squash
+   * that replaces all older bundles with a single full bundle.
+   *
+   * @default 5
+   */
+  squashThreshold?: number;
+};
+
+/** Metadata about a generated git bundle. */
+export type BundleInfo = {
+  /** Path to the bundle file on disk. */
+  path: string;
+  /** SHA of the tip commit (HEAD of default branch). */
+  tipCommit: string;
+  /** Whether this is a full bundle (all refs) or incremental. */
+  isFull: boolean;
+  /** Number of refs included in the bundle. */
+  refCount: number;
+  /** File size in bytes. */
+  size: number;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an `onPushComplete` callback that syncs a git bundle to a DWN record.
+ *
+ * @param options - Bundle sync configuration
+ * @returns An async callback to invoke after a successful push
+ */
+export function createBundleSyncer(options: BundleSyncOptions): OnPushComplete {
+  const { repo, repoContextId, visibility = 'public', squashThreshold = 5 } = options;
+  const encrypt = visibility === 'private';
+
+  return async (_did: string, _repoName: string, repoPath: string): Promise<void> => {
+    // Query existing bundle records, newest first.
+    const { records: existingBundles } = await repo.records.query('repo/bundle', {
+      filter   : { tags: { isFull: true } },
+      dateSort : DateSort.CreatedDescending,
+    });
+
+    // Also query incremental bundles.
+    const { records: incrementalBundles } = await repo.records.query('repo/bundle', {
+      filter   : { tags: { isFull: false } },
+      dateSort : DateSort.CreatedDescending,
+    });
+
+    const totalBundles = existingBundles.length + incrementalBundles.length;
+
+    // Determine the last tip commit from the most recent bundle (full or incremental).
+    let lastTipCommit: string | undefined;
+    if (incrementalBundles.length > 0 && incrementalBundles[0].tags) {
+      lastTipCommit = incrementalBundles[0].tags.tipCommit as string;
+    } else if (existingBundles.length > 0 && existingBundles[0].tags) {
+      lastTipCommit = existingBundles[0].tags.tipCommit as string;
+    }
+
+    // Decide whether to create a full or incremental bundle.
+    const shouldSquash = totalBundles > 0 && totalBundles >= squashThreshold;
+    const isIncremental = !shouldSquash && lastTipCommit !== undefined;
+
+    let bundleInfo: BundleInfo;
+    try {
+      if (isIncremental) {
+        // Create incremental bundle: only objects reachable from --all but not from lastTipCommit.
+        bundleInfo = await createIncrementalBundle(repoPath, lastTipCommit!);
+      } else {
+        // Create full bundle: all refs, all objects.
+        bundleInfo = await createFullBundle(repoPath);
+      }
+    } catch (err) {
+      console.error(`bundle-sync: failed to create bundle: ${(err as Error).message}`);
+      return;
+    }
+
+    try {
+      // Read the bundle data from disk.
+      const bundleData = new Uint8Array(await readFile(bundleInfo.path));
+
+      const tags = {
+        tipCommit : bundleInfo.tipCommit,
+        isFull    : bundleInfo.isFull,
+        refCount  : bundleInfo.refCount,
+        size      : bundleInfo.size,
+      };
+
+      const createOptions: any = {
+        data            : bundleData,
+        dataFormat      : 'application/x-git-bundle',
+        tags,
+        parentContextId : repoContextId,
+        encryption      : encrypt,
+      };
+
+      if (shouldSquash) {
+        // Squash write: creates a new bundle record and purges all older ones.
+        createOptions.squash = true;
+      }
+
+      await repo.records.create('repo/bundle', createOptions);
+    } finally {
+      // Clean up the temp bundle file.
+      await unlink(bundleInfo.path).catch(() => {});
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Bundle creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a full git bundle containing all refs and all reachable objects.
+ *
+ * @param repoPath - Path to the bare git repository
+ * @returns Bundle metadata and file path
+ */
+export async function createFullBundle(repoPath: string): Promise<BundleInfo> {
+  const bundlePath = join(tmpdir(), `gitd-bundle-${Date.now()}-${Math.random().toString(36).slice(2)}.bundle`);
+
+  await spawnChecked('git', ['bundle', 'create', bundlePath, '--all'], repoPath);
+
+  const tipCommit = await getTipCommit(repoPath);
+  const refCount = await getRefCount(repoPath);
+  const fileInfo = await stat(bundlePath);
+
+  return {
+    path   : bundlePath,
+    tipCommit,
+    isFull : true,
+    refCount,
+    size   : fileInfo.size,
+  };
+}
+
+/**
+ * Create an incremental git bundle containing only objects since a base commit.
+ *
+ * The bundle uses the base commit as a prerequisite, meaning the consumer
+ * must already have it to apply the incremental bundle.
+ *
+ * @param repoPath - Path to the bare git repository
+ * @param baseCommit - The commit SHA to use as the prerequisite (exclude point)
+ * @returns Bundle metadata and file path
+ */
+export async function createIncrementalBundle(
+  repoPath: string,
+  baseCommit: string,
+): Promise<BundleInfo> {
+  const bundlePath = join(tmpdir(), `gitd-bundle-${Date.now()}-${Math.random().toString(36).slice(2)}.bundle`);
+
+  // `--all ^<base>` means: include all refs, exclude objects reachable from base.
+  await spawnChecked('git', ['bundle', 'create', bundlePath, '--all', `^${baseCommit}`], repoPath);
+
+  const tipCommit = await getTipCommit(repoPath);
+  const refCount = await getRefCount(repoPath);
+  const fileInfo = await stat(bundlePath);
+
+  return {
+    path   : bundlePath,
+    tipCommit,
+    isFull : false,
+    refCount,
+    size   : fileInfo.size,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the tip commit SHA (HEAD of the default branch).
+ * Falls back to the first ref if HEAD is unset.
+ */
+async function getTipCommit(repoPath: string): Promise<string> {
+  try {
+    const sha = (await spawnCollectStdout('git', ['rev-parse', 'HEAD'], repoPath)).trim();
+    // In bare repos, HEAD may be a dangling symbolic ref (e.g. refs/heads/master
+    // doesn't exist). `git rev-parse HEAD` outputs the literal string "HEAD" in
+    // that case instead of a 40-hex SHA.
+    if (/^[0-9a-f]{40}$/.test(sha)) {
+      return sha;
+    }
+  } catch {
+    // rev-parse failed entirely — fall through to for-each-ref.
+  }
+
+  // HEAD didn't resolve; get the first ref.
+  const output = await spawnCollectStdout(
+    'git', ['for-each-ref', '--format=%(objectname)', '--count=1', 'refs/'], repoPath,
+  );
+  return output.trim();
+}
+
+/** Count the number of refs (branches + tags) in the repo. */
+async function getRefCount(repoPath: string): Promise<number> {
+  const output = await spawnCollectStdout(
+    'git', ['for-each-ref', '--format=x', 'refs/heads/', 'refs/tags/'], repoPath,
+  );
+  return output.split('\n').filter((l) => l.trim()).length;
+}
+
+/** Spawn a process and reject if it exits with non-zero code. */
+function spawnChecked(cmd: string, args: string[], cwd: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    const stderrChunks: Buffer[] = [];
+
+    child.stderr!.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+        reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}: ${stderr}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+/** Spawn a process, collect stdout, and return it as a string. */
+function spawnCollectStdout(cmd: string, args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    const chunks: Buffer[] = [];
+
+    child.stdout!.on('data', (chunk: Buffer) => chunks.push(chunk));
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+      } else {
+        resolve(Buffer.concat(chunks).toString('utf-8'));
+      }
+    });
+  });
+}

package/src/git-server/did-service.ts

@@ -0,0 +1,77 @@
+/**
+ * DID document service management for git transport.
+ *
+ * Adds or updates a `GitTransport` service entry in a DID document,
+ * advertising the git smart HTTP endpoint for the `git-remote-did` helper.
+ *
+ * This module works with the agent's DID API to persist and publish
+ * service updates. For `did:dht`, the updated document is republished
+ * to the DHT network.
+ *
+ * @module
+ */
+
+import type { Web5 } from '@enbox/api';
+
+import { GIT_TRANSPORT_SERVICE_TYPE } from '../git-remote/service.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default service entry ID for the git transport endpoint. */
+const GIT_SERVICE_ID = '#git';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a GitTransport service endpoint in the agent's DID document.
+ *
+ * If a GitTransport service already exists, its endpoint is updated.
+ * Otherwise, a new service entry is created. The updated DID document
+ * is persisted in the agent store and (for did:dht) republished.
+ *
+ * @param web5 - The Web5 instance (provides agent DID and did API)
+ * @param endpoint - The git transport HTTPS URL (e.g. `https://git.example.com`)
+ * @throws If the agent does not support DID updates
+ */
+export async function registerGitService(web5: Web5, endpoint: string): Promise<void> {
+  const agent = web5.agent as any;
+
+  // Verify the agent supports DID updates.
+  if (!agent.did?.update) {
+    console.warn(
+      'Agent does not support DID document updates. ' +
+      'GitTransport service not registered. ' +
+      'The git-remote-did helper will need a DWN endpoint fallback.',
+    );
+    return;
+  }
+
+  const bearerDid = agent.agentDid;
+  const portableDid = await bearerDid.export();
+
+  // Look for an existing GitTransport service.
+  const services = portableDid.document.service ?? [];
+  const existingIdx = services.findIndex(
+    (s: any) => s.type === GIT_TRANSPORT_SERVICE_TYPE || s.id?.endsWith('git'),
+  );
+
+  const newService = {
+    id              : GIT_SERVICE_ID,
+    type            : GIT_TRANSPORT_SERVICE_TYPE,
+    serviceEndpoint : endpoint,
+  };
+
+  if (existingIdx >= 0) {
+    services[existingIdx] = newService;
+  } else {
+    services.push(newService);
+  }
+
+  portableDid.document.service = services;
+
+  await agent.did.update({ portableDid });
+}

package/src/git-server/git-backend.ts

@@ -0,0 +1,222 @@
+/**
+ * Git backend — wraps Git CLI commands for bare repository management.
+ *
+ * Provides a thin abstraction over `git init --bare`, `git upload-pack`, and
+ * `git receive-pack` for use by the smart HTTP transport handler.
+ *
+ * All repositories are stored as bare repos under a configurable base
+ * directory, organized by DID:  `<basePath>/<did-hash>/<repo-name>.git`
+ *
+ * @module
+ */
+
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+
+import { existsSync, mkdirSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for creating a GitBackend instance. */
+export type GitBackendOptions = {
+  /**
+   * Base directory for storing bare repositories.
+   * Repos are stored as `<basePath>/<did-hash>/<repo>.git`
+   */
+  basePath: string;
+};
+
+/** Readable stream from a git subprocess. */
+export type GitProcess = {
+  /** The subprocess stdout (pack data). */
+  stdout: ReadableStream<Uint8Array>;
+
+  /** The subprocess stdin for writing request data. */
+  stdin: WritableStream<Uint8Array>;
+
+  /** Promise that resolves with the exit code when the process completes. */
+  exitCode: Promise<number>;
+};
+
+// ---------------------------------------------------------------------------
+// GitBackend
+// ---------------------------------------------------------------------------
+
+/**
+ * Manages bare git repositories on the filesystem and spawns git subprocess
+ * for smart HTTP transport.
+ */
+export class GitBackend {
+  private readonly _basePath: string;
+
+  public constructor(options: GitBackendOptions) {
+    this._basePath = options.basePath;
+  }
+
+  /** Get the base path for all repositories. */
+  public get basePath(): string {
+    return this._basePath;
+  }
+
+  /**
+   * Compute the filesystem path for a repository.
+   *
+   * @param did - The DID of the repository owner
+   * @param repo - The repository name
+   * @returns Absolute path to the bare repo directory
+   * @throws If the repo name contains path traversal characters
+   */
+  public repoPath(did: string, repo: string): string {
+    validateRepoName(repo);
+    const didHash = hashDid(did);
+    const repoDir = join(this._basePath, didHash, `${repo}.git`);
+    const resolved = resolve(repoDir);
+    const base = resolve(this._basePath);
+    if (!resolved.startsWith(base + '/') && resolved !== base) {
+      throw new Error(`Path traversal detected: repo name '${repo}' escapes base directory`);
+    }
+    return resolved;
+  }
+
+  /**
+   * Check whether a repository exists on disk.
+   *
+   * @param did - The DID of the repository owner
+   * @param repo - The repository name
+   */
+  public exists(did: string, repo: string): boolean {
+    const path = this.repoPath(did, repo);
+    return existsSync(join(path, 'HEAD'));
+  }
+
+  /**
+   * Initialize a new bare repository.
+   *
+   * @param did - The DID of the repository owner
+   * @param repo - The repository name
+   * @returns The path to the new bare repository
+   * @throws If `git init --bare` fails
+   */
+  public async initRepo(did: string, repo: string): Promise<string> {
+    const path = this.repoPath(did, repo);
+    mkdirSync(path, { recursive: true });
+
+    const exitCode = await runGit(['init', '--bare', path]);
+    if (exitCode !== 0) {
+      throw new Error(`git init --bare failed with exit code ${exitCode} for ${path}`);
+    }
+
+    return path;
+  }
+
+  /**
+   * Spawn `git upload-pack` for fetch/clone operations.
+   *
+   * @param did - The DID of the repository owner
+   * @param repo - The repository name
+   * @returns A GitProcess with stdin/stdout streams for the subprocess
+   * @throws If the repository does not exist
+   */
+  public uploadPack(did: string, repo: string): GitProcess {
+    this._assertRepoExists(did, repo);
+    const path = this.repoPath(did, repo);
+    return spawnGitService('upload-pack', path);
+  }
+
+  /**
+   * Spawn `git receive-pack` for push operations.
+   *
+   * @param did - The DID of the repository owner
+   * @param repo - The repository name
+   * @returns A GitProcess with stdin/stdout streams for the subprocess
+   * @throws If the repository does not exist
+   */
+  public receivePack(did: string, repo: string): GitProcess {
+    this._assertRepoExists(did, repo);
+    const path = this.repoPath(did, repo);
+    return spawnGitService('receive-pack', path);
+  }
+
+  /** Throw if the repo doesn't exist on disk. */
+  private _assertRepoExists(did: string, repo: string): void {
+    if (!this.exists(did, repo)) {
+      throw new Error(`Repository not found: ${did}/${repo}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Allowed characters in a repository name: alphanumeric, dots, hyphens, underscores. */
+const SAFE_REPO_NAME_RE = /^[a-zA-Z0-9._-]+$/;
+
+/**
+ * Validate that a repository name is safe for filesystem use.
+ * Rejects path traversal components and unsafe characters.
+ *
+ * @throws If the repo name is invalid
+ */
+function validateRepoName(name: string): void {
+  if (!name || !SAFE_REPO_NAME_RE.test(name)) {
+    throw new Error(`Invalid repository name: '${name}'. Names must match ${SAFE_REPO_NAME_RE}`);
+  }
+  if (name === '.' || name === '..' || name.startsWith('.git')) {
+    throw new Error(`Invalid repository name: '${name}'`);
+  }
+}
+
+/** Hash a DID to a short filesystem-safe directory name. */
+function hashDid(did: string): string {
+  return createHash('sha256').update(did).digest('hex').slice(0, 16);
+}
+
+/** Run a git command and return the exit code. */
+async function runGit(args: string[]): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { stdio: 'pipe' });
+    child.on('error', reject);
+    child.on('exit', (code) => resolve(code ?? 128));
+  });
+}
+
+/**
+ * Spawn a git service subprocess (upload-pack or receive-pack) and return
+ * web-standard ReadableStream/WritableStream wrappers around its stdio.
+ */
+function spawnGitService(service: 'upload-pack' | 'receive-pack', repoPath: string): GitProcess {
+  const child = spawn('git', [service, '--stateless-rpc', repoPath], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  const stdout = new ReadableStream<Uint8Array>({
+    start(controller): void {
+      child.stdout!.on('data', (chunk: Buffer) => controller.enqueue(new Uint8Array(chunk)));
+      child.stdout!.on('end', () => controller.close());
+      child.stdout!.on('error', (err) => controller.error(err));
+    },
+  });
+
+  const stdin = new WritableStream<Uint8Array>({
+    write(chunk): void {
+      child.stdin!.write(chunk);
+    },
+    close(): void {
+      child.stdin!.end();
+    },
+    abort(): void {
+      child.stdin!.destroy();
+    },
+  });
+
+  const exitCode = new Promise<number>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('exit', (code) => resolve(code ?? 128));
+  });
+
+  return { stdout, stdin, exitCode };
+}