@enbox/gitd 0.0.1

package/src/git-server/http-handler.ts

@@ -0,0 +1,386 @@
+/**
+ * Git smart HTTP transport handler.
+ *
+ * Implements the server side of Git's smart HTTP protocol (v1):
+ *   - `GET /<did>/<repo>/info/refs?service=git-upload-pack`  — ref discovery (clone/fetch)
+ *   - `POST /<did>/<repo>/git-upload-pack`                   — pack negotiation (clone/fetch)
+ *   - `GET /<did>/<repo>/info/refs?service=git-receive-pack` — ref discovery (push)
+ *   - `POST /<did>/<repo>/git-receive-pack`                  — receive pack (push)
+ *
+ * When `onRepoNotFound` is provided, the handler auto-restores repos from
+ * DWN bundle records on first access (cold-start). This enables commodity
+ * git hosts to serve repos they've never seen before.
+ *
+ * The handler is a pure function `(Request) => Response | Promise<Response>`
+ * suitable for use with `Bun.serve()`, `Deno.serve()`, or any fetch-compatible
+ * HTTP runtime.
+ *
+ * URL format: `/<did>/<repo>/...`
+ *   The DID is URL-encoded in the path (colons are preserved since they're
+ *   valid in path segments).
+ *
+ * @module
+ */
+
+import { spawn } from 'node:child_process';
+
+import type { GitBackend } from './git-backend.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for creating the git HTTP handler. */
+export type GitHttpHandlerOptions = {
+  /** The git backend for repository operations. */
+  backend: GitBackend;
+
+  /**
+   * Optional authentication callback for push operations.
+   * Called before `git-receive-pack` is allowed to proceed.
+   * Should return `true` if the request is authorized.
+   *
+   * @param request - The incoming HTTP request
+   * @param did - The repository owner's DID
+   * @param repo - The repository name
+   */
+  authenticatePush?: (request: Request, did: string, repo: string) => Promise<boolean>;
+
+  /**
+   * Optional callback invoked after a successful `git receive-pack` (push).
+   * Use this for post-push operations like syncing refs to DWN records.
+   *
+   * @param did - The repository owner's DID
+   * @param repo - The repository name
+   * @param repoPath - Filesystem path to the bare repository
+   */
+  onPushComplete?: (did: string, repo: string, repoPath: string) => Promise<void>;
+
+  /**
+   * Optional callback invoked when a clone/fetch request arrives for a
+   * repository that doesn't exist on disk. Implementations can restore
+   * the repo from DWN bundle records.
+   *
+   * @param did - The repository owner's DID
+   * @param repo - The repository name
+   * @param repoPath - The filesystem path where the repo should be created
+   * @returns `true` if the repo was restored successfully
+   */
+  onRepoNotFound?: (did: string, repo: string, repoPath: string) => Promise<boolean>;
+
+  /**
+   * Optional path prefix to strip from incoming URLs.
+   * For example, if the sidecar is mounted at `/git`, set this to `/git`.
+   * @default ''
+   */
+  pathPrefix?: string;
+};
+
+/** Parsed route from a git smart HTTP URL. */
+type GitRoute = {
+  did: string;
+  repo: string;
+  /** The path suffix after `/<did>/<repo>/`, e.g. `info/refs` or `git-upload-pack`. */
+  action: string;
+};
+
+// ---------------------------------------------------------------------------
+// Handler factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a fetch-compatible HTTP handler for Git smart HTTP transport.
+ *
+ * @param options - Handler configuration
+ * @returns A function that handles incoming HTTP requests
+ */
+export function createGitHttpHandler(
+  options: GitHttpHandlerOptions,
+): (request: Request) => Response | Promise<Response> {
+  const { backend, authenticatePush, onPushComplete, onRepoNotFound, pathPrefix = '' } = options;
+
+  /**
+   * Ensure a repo exists on disk, attempting DWN bundle restore if absent.
+   * Returns `true` when the repo is available (or was restored).
+   */
+  async function ensureRepo(did: string, repo: string): Promise<boolean> {
+    if (backend.exists(did, repo)) { return true; }
+
+    if (onRepoNotFound) {
+      const repoPath = backend.repoPath(did, repo);
+      try {
+        return await onRepoNotFound(did, repo, repoPath);
+      } catch (err) {
+        console.error(`onRepoNotFound error for ${did}/${repo}: ${(err as Error).message}`);
+        return false;
+      }
+    }
+
+    return false;
+  }
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    let pathname = url.pathname;
+
+    // Strip path prefix.
+    if (pathPrefix && pathname.startsWith(pathPrefix)) {
+      pathname = pathname.slice(pathPrefix.length);
+    }
+
+    // Parse the route.
+    const route = parseRoute(pathname);
+    if (!route) {
+      return new Response('Not Found', { status: 404 });
+    }
+
+    const { did, repo, action } = route;
+
+    // -----------------------------------------------------------------------
+    // GET /<did>/<repo>/info/refs?service=<service>
+    // -----------------------------------------------------------------------
+    if (request.method === 'GET' && action === 'info/refs') {
+      const service = url.searchParams.get('service');
+      if (service !== 'git-upload-pack' && service !== 'git-receive-pack') {
+        return new Response('Dumb HTTP transport is not supported. Use git smart HTTP.', { status: 403 });
+      }
+
+      // Auth check for push ref discovery.
+      if (service === 'git-receive-pack' && authenticatePush) {
+        const authorized = await authenticatePush(request, did, repo);
+        if (!authorized) {
+          return new Response('Unauthorized', {
+            status  : 401,
+            headers : { 'WWW-Authenticate': 'Basic realm="gitd"' },
+          });
+        }
+      }
+
+      // Ensure repo exists (auto-restore from DWN if possible).
+      if (!(await ensureRepo(did, repo))) {
+        return new Response('Repository not found', { status: 404 });
+      }
+
+      return handleInfoRefs(backend, did, repo, service);
+    }
+
+    // -----------------------------------------------------------------------
+    // POST /<did>/<repo>/git-upload-pack
+    // -----------------------------------------------------------------------
+    if (request.method === 'POST' && action === 'git-upload-pack') {
+      if (!(await ensureRepo(did, repo))) {
+        return new Response('Repository not found', { status: 404 });
+      }
+      return handleServiceRpc(backend, did, repo, 'upload-pack', request);
+    }
+
+    // -----------------------------------------------------------------------
+    // POST /<did>/<repo>/git-receive-pack
+    // -----------------------------------------------------------------------
+    if (request.method === 'POST' && action === 'git-receive-pack') {
+      // Auth check for push.
+      if (authenticatePush) {
+        const authorized = await authenticatePush(request, did, repo);
+        if (!authorized) {
+          return new Response('Unauthorized', {
+            status  : 401,
+            headers : { 'WWW-Authenticate': 'Basic realm="gitd"' },
+          });
+        }
+      }
+
+      if (!(await ensureRepo(did, repo))) {
+        return new Response('Repository not found', { status: 404 });
+      }
+
+      const response = await handleServiceRpc(backend, did, repo, 'receive-pack', request);
+
+      // Fire the post-push callback asynchronously (don't block the response).
+      if (onPushComplete && response.status === 200) {
+        const repoPath = backend.repoPath(did, repo);
+        onPushComplete(did, repo, repoPath).catch((err) => {
+          console.error(`onPushComplete error for ${did}/${repo}: ${(err as Error).message}`);
+        });
+      }
+
+      return response;
+    }
+
+    return new Response('Not Found', { status: 404 });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a URL path into DID, repo, and action components.
+ *
+ * Expected format: `/<did>/<repo>/<action>`
+ * The DID occupies exactly 3 colon-separated segments: `did:<method>:<id>`.
+ * However, since the DID is in the URL path, we split by `/` and reconstruct.
+ *
+ * URL form: `/<did-scheme>:<did-method>:<did-id>/<repo>/<action...>`
+ * Example:  `/did:dht:abc123/my-repo/info/refs`
+ */
+function parseRoute(pathname: string): GitRoute | undefined {
+  // Remove leading slash.
+  const path = pathname.startsWith('/') ? pathname.slice(1) : pathname;
+
+  // The DID is the first path segment (contains colons, not slashes).
+  const firstSlash = path.indexOf('/');
+  if (firstSlash === -1) { return undefined; }
+
+  const did = decodeURIComponent(path.slice(0, firstSlash));
+
+  // Validate it looks like a DID.
+  if (!did.startsWith('did:') || did.split(':').length < 3) {
+    return undefined;
+  }
+
+  // Remaining path: <repo>/<action...>
+  const rest = path.slice(firstSlash + 1);
+  const secondSlash = rest.indexOf('/');
+  if (secondSlash === -1) { return undefined; }
+
+  const repo = rest.slice(0, secondSlash);
+  const action = rest.slice(secondSlash + 1);
+
+  if (!repo || !action) { return undefined; }
+
+  // Reject path-traversal and unsafe repo names.
+  if (!/^[a-zA-Z0-9._-]+$/.test(repo) || repo === '.' || repo === '..') {
+    return undefined;
+  }
+
+  return { did, repo, action };
+}
+
+// ---------------------------------------------------------------------------
+// Git smart HTTP protocol handlers
+// ---------------------------------------------------------------------------
+
+/** Git pkt-line helper: encode a single line. */
+function pktLine(line: string): string {
+  const len = line.length + 4;
+  return len.toString(16).padStart(4, '0') + line;
+}
+
+/** Git pkt-line flush: `0000`. */
+const PKT_FLUSH = '0000';
+
+/**
+ * Handle `GET /info/refs?service=<service>`.
+ *
+ * Runs `git <service> --stateless-rpc --advertise-refs` and wraps the output
+ * in the smart HTTP ref advertisement format.
+ */
+async function handleInfoRefs(
+  backend: GitBackend,
+  did: string,
+  repo: string,
+  service: 'git-upload-pack' | 'git-receive-pack',
+): Promise<Response> {
+  const gitService = service === 'git-upload-pack' ? 'upload-pack' : 'receive-pack';
+  const repoPath = backend.repoPath(did, repo);
+
+  // Run git with --advertise-refs to get the ref listing.
+  const refData = await spawnAndCollect(gitService, repoPath);
+
+  if (refData === null) {
+    return new Response('Git service error', { status: 500 });
+  }
+
+  // Build the smart HTTP response: service announcement + ref data.
+  const encoder = new TextEncoder();
+  const announcement = pktLine(`# service=${service}\n`) + PKT_FLUSH;
+  const announcementBytes = encoder.encode(announcement);
+
+  const body = new Uint8Array(announcementBytes.length + refData.length);
+  body.set(announcementBytes, 0);
+  body.set(refData, announcementBytes.length);
+
+  return new Response(body, {
+    status  : 200,
+    headers : {
+      'Content-Type'  : `application/x-${service}-advertisement`,
+      'Cache-Control' : 'no-cache',
+    },
+  });
+}
+
+/**
+ * Handle `POST /git-upload-pack` or `POST /git-receive-pack`.
+ *
+ * Pipes the request body to `git <service> --stateless-rpc` stdin and
+ * streams stdout back as the response.
+ */
+async function handleServiceRpc(
+  backend: GitBackend,
+  did: string,
+  repo: string,
+  service: 'upload-pack' | 'receive-pack',
+  request: Request,
+): Promise<Response> {
+  const gitProcess = service === 'upload-pack'
+    ? backend.uploadPack(did, repo)
+    : backend.receivePack(did, repo);
+
+  // Pipe request body into git subprocess stdin.
+  if (request.body) {
+    const writer = gitProcess.stdin.getWriter();
+    const reader = request.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) { break; }
+        await writer.write(value);
+      }
+    } finally {
+      await writer.close();
+      reader.releaseLock();
+    }
+  } else {
+    const writer = gitProcess.stdin.getWriter();
+    await writer.close();
+  }
+
+  return new Response(gitProcess.stdout, {
+    status  : 200,
+    headers : {
+      'Content-Type'  : `application/x-git-${service}-result`,
+      'Cache-Control' : 'no-cache',
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn `git <service> --stateless-rpc --advertise-refs` and collect stdout.
+ * Returns `null` if the process exits with a non-zero code.
+ */
+function spawnAndCollect(service: string, repoPath: string): Promise<Uint8Array | null> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', [service, '--stateless-rpc', '--advertise-refs', repoPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const chunks: Buffer[] = [];
+
+    child.stdout!.on('data', (chunk: Buffer) => chunks.push(chunk));
+    child.stdout!.on('error', reject);
+
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        resolve(null);
+      } else {
+        resolve(new Uint8Array(Buffer.concat(chunks)));
+      }
+    });
+  });
+}

package/src/git-server/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Git transport server — smart HTTP git backend with DID-based push auth.
+ *
+ * @module git-server
+ */
+
+export * from './auth.js';
+export * from './bundle-restore.js';
+export * from './bundle-sync.js';
+export * from './did-service.js';
+export * from './git-backend.js';
+export * from './http-handler.js';
+export * from './push-authorizer.js';
+export * from './ref-sync.js';
+export * from './server.js';
+export * from './verify.js';

package/src/git-server/push-authorizer.ts

@@ -0,0 +1,77 @@
+/**
+ * DWN-based push authorization — checks collaborator roles in the DWN.
+ *
+ * When a DID attempts to push to a repository, this module queries the
+ * DWN for `repo/maintainer` and `repo/contributor` role records to
+ * determine if the pusher is authorized.
+ *
+ * Authorization rules:
+ * - The repo owner (DID that owns the DWN) can always push
+ * - DIDs with a `maintainer` role record can push
+ * - DIDs with a `contributor` role record can push
+ * - All other DIDs are rejected
+ *
+ * @module
+ */
+
+import type { TypedWeb5 } from '@enbox/api';
+
+import type { ForgeRepoProtocol } from '../repo.js';
+import type { ForgeRepoSchemaMap } from '../repo.js';
+
+import type { PushAuthorizer } from './auth.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for creating a DWN-based push authorizer. */
+export type DwnPushAuthorizerOptions = {
+  /** The typed ForgeRepoProtocol Web5 handle. */
+  repo: TypedWeb5<typeof ForgeRepoProtocol.definition, ForgeRepoSchemaMap>;
+  /** The DID of the DWN owner (server operator). */
+  ownerDid: string;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `PushAuthorizer` that checks DWN collaborator role records.
+ *
+ * The authorizer queries the ForgeRepoProtocol for `maintainer` and
+ * `contributor` role records matching the pusher's DID. The repo owner
+ * is always authorized.
+ *
+ * @param options - Authorizer configuration
+ * @returns A PushAuthorizer callback
+ */
+export function createDwnPushAuthorizer(options: DwnPushAuthorizerOptions): PushAuthorizer {
+  const { repo, ownerDid } = options;
+
+  return async (did: string, owner: string, _repoName: string): Promise<boolean> => {
+    // The owner can always push to their own repos.
+    if (did === owner || did === ownerDid) {
+      return true;
+    }
+
+    // Query for maintainer role records for this DID.
+    const { records: maintainers } = await repo.records.query('repo/maintainer' as any, {
+      filter: { tags: { did } },
+    });
+    if (maintainers.length > 0) {
+      return true;
+    }
+
+    // Query for contributor role records for this DID.
+    const { records: contributors } = await repo.records.query('repo/contributor' as any, {
+      filter: { tags: { did } },
+    });
+    if (contributors.length > 0) {
+      return true;
+    }
+
+    return false;
+  };
+}

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

@@ -0,0 +1,166 @@
+/**
+ * Git ref → DWN sync — mirrors git branch/tag refs as ForgeRefs records.
+ *
+ * After a successful `git push`, this module reads the current refs from
+ * the bare repository and creates or updates corresponding DWN records
+ * using the ForgeRefsProtocol.
+ *
+ * Ref sync flow:
+ * 1. Run `git for-each-ref` on the bare repo to enumerate current refs
+ * 2. Query existing DWN ref records for the repo
+ * 3. Create new records for refs that don't exist in DWN
+ * 4. Update existing records whose target (SHA) has changed
+ * 5. Delete DWN records for refs that no longer exist in git
+ *
+ * @module
+ */
+
+import type { TypedWeb5 } from '@enbox/api';
+
+import { spawn } from 'node:child_process';
+
+import type { ForgeRefsProtocol } from '../refs.js';
+import type { ForgeRefsSchemaMap } from '../refs.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A git ref as read from `git for-each-ref`. */
+export type GitRef = {
+  /** Full ref name, e.g. `refs/heads/main` or `refs/tags/v1.0.0`. */
+  name: string;
+  /** The commit SHA this ref points to. */
+  target: string;
+  /** Ref type discriminator. */
+  type: 'branch' | 'tag';
+};
+
+/** Options for syncing refs. */
+export type RefSyncOptions = {
+  /** The typed ForgeRefsProtocol Web5 handle. */
+  refs: TypedWeb5<typeof ForgeRefsProtocol.definition, ForgeRefsSchemaMap>;
+  /** The repo's contextId (from the ForgeRepoProtocol repo record). */
+  repoContextId: string;
+};
+
+/** Callback for post-push ref synchronization. */
+export type OnPushComplete = (
+  did: string,
+  repo: string,
+  repoPath: string,
+) => Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an `onPushComplete` callback that syncs git refs to DWN records.
+ *
+ * @param options - Ref sync configuration
+ * @returns An async callback to invoke after a successful push
+ */
+export function createRefSyncer(options: RefSyncOptions): OnPushComplete {
+  const { refs, repoContextId } = options;
+
+  return async (_did: string, _repo: string, repoPath: string): Promise<void> => {
+    // Read current git refs from the bare repository.
+    const gitRefs = await readGitRefs(repoPath);
+
+    // Query existing DWN ref records for this repo.
+    // The parentContextId links ref records to the repo context via $ref.
+    const { records: existingRecords } = await refs.records.query('repo/ref' as any);
+
+    // Build a map of existing DWN refs: name → { record, target }.
+    const existingMap = new Map<string, { record: any; target: string }>();
+    for (const record of existingRecords) {
+      const data = await record.data.json();
+      existingMap.set(data.name, { record, target: data.target });
+    }
+
+    // Build a set of current git ref names.
+    const gitRefNames = new Set(gitRefs.map((r) => r.name));
+
+    // Create or update refs.
+    for (const ref of gitRefs) {
+      const existing = existingMap.get(ref.name);
+
+      if (!existing) {
+        // Create a new DWN ref record.
+        await refs.records.create('repo/ref', {
+          data            : { name: ref.name, target: ref.target, type: ref.type },
+          tags            : { name: ref.name, type: ref.type, target: ref.target },
+          parentContextId : repoContextId,
+        });
+      } else if (existing.target !== ref.target) {
+        // Update existing record with new target.
+        await existing.record.update({
+          data : { name: ref.name, target: ref.target, type: ref.type },
+          tags : { name: ref.name, type: ref.type, target: ref.target },
+        });
+      }
+      // If target matches, no action needed.
+    }
+
+    // Delete DWN records for refs that no longer exist in git.
+    for (const [name, { record }] of existingMap) {
+      if (!gitRefNames.has(name)) {
+        await record.delete();
+      }
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Git ref reader
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all refs from a bare git repository using `git for-each-ref`.
+ *
+ * @param repoPath - Path to the bare git repository
+ * @returns Array of GitRef objects
+ */
+export async function readGitRefs(repoPath: string): Promise<GitRef[]> {
+  const output = await spawnCollectStdout('git', [
+    'for-each-ref',
+    '--format=%(refname)\t%(objectname)',
+    'refs/heads/',
+    'refs/tags/',
+  ], repoPath);
+
+  const refs: GitRef[] = [];
+  for (const line of output.split('\n')) {
+    if (!line.trim()) { continue; }
+    const [name, target] = line.split('\t');
+    if (!name || !target) { continue; }
+
+    const type: 'branch' | 'tag' = name.startsWith('refs/tags/') ? 'tag' : 'branch';
+    refs.push({ name, target, type });
+  }
+
+  return refs;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** 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) {
+        resolve(''); // Empty refs for non-zero exit (e.g., empty repo).
+      } else {
+        resolve(Buffer.concat(chunks).toString('utf-8'));
+      }
+    });
+  });
+}