@enbox/gitd 0.0.1

package/src/git-server/server.ts

@@ -0,0 +1,236 @@
+/**
+ * Git transport sidecar server.
+ *
+ * A standalone HTTP server that serves Git smart HTTP transport alongside
+ * a DWN.  Uses Node.js `http` module for maximum compatibility.
+ *
+ * Usage:
+ * ```ts
+ * import { createGitServer } from '@enbox/gitd/git-server/server';
+ *
+ * const server = createGitServer({
+ *   basePath : '/var/lib/gitd/repos',
+ *   port     : 9418,
+ * });
+ *
+ * console.log(`Git server listening on port ${server.port}`);
+ * ```
+ *
+ * @module
+ */
+
+import type { IncomingMessage } from 'node:http';
+
+import { createServer } from 'node:http';
+
+import { createGitHttpHandler } from './http-handler.js';
+import { GitBackend } from './git-backend.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Default maximum request body size for git pack data (50 MB). */
+const DEFAULT_MAX_BODY_GIT = 50 * 1024 * 1024;
+
+/** Configuration for the git transport sidecar server. */
+export type GitServerOptions = {
+  /** Base directory for storing bare repositories. */
+  basePath: string;
+
+  /** TCP port to listen on. Use 0 for a random available port. @default 9418 */
+  port?: number;
+
+  /** Hostname to bind to. @default '0.0.0.0' */
+  hostname?: string;
+
+  /** Optional path prefix for the HTTP handler (e.g. `/git`). */
+  pathPrefix?: string;
+
+  /**
+   * Optional authentication callback for push operations.
+   * @see GitHttpHandlerOptions.authenticatePush
+   */
+  authenticatePush?: (request: Request, did: string, repo: string) => Promise<boolean>;
+
+  /**
+   * Optional callback invoked after a successful push.
+   * @see GitHttpHandlerOptions.onPushComplete
+   */
+  onPushComplete?: (did: string, repo: string, repoPath: string) => Promise<void>;
+
+  /**
+   * Optional callback invoked when a repo is not found on disk.
+   * Implementations can restore the repo from DWN bundle records.
+   * @see GitHttpHandlerOptions.onRepoNotFound
+   */
+  onRepoNotFound?: (did: string, repo: string, repoPath: string) => Promise<boolean>;
+
+  /**
+   * Maximum request body size in bytes for POST requests (git pack data).
+   * @default 50 * 1024 * 1024 (50 MB)
+   */
+  maxBodySize?: number;
+};
+
+/** A running git server instance. */
+export type GitServer = {
+  /** The TCP port the server is listening on. */
+  port: number;
+
+  /** The git backend managing repositories. */
+  backend: GitBackend;
+
+  /** Stop the server. Returns a promise that resolves when fully closed. */
+  stop(): Promise<void>;
+};
+
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create and start a git transport sidecar server.
+ *
+ * @param options - Server configuration
+ * @returns A promise resolving to a running GitServer instance
+ */
+export async function createGitServer(options: GitServerOptions): Promise<GitServer> {
+  const {
+    basePath,
+    port = 9418,
+    hostname = '0.0.0.0',
+    pathPrefix,
+    authenticatePush,
+    onPushComplete,
+    onRepoNotFound,
+    maxBodySize = DEFAULT_MAX_BODY_GIT,
+  } = options;
+
+  const backend = new GitBackend({ basePath });
+
+  const fetchHandler = createGitHttpHandler({
+    backend,
+    pathPrefix,
+    authenticatePush,
+    onPushComplete,
+    onRepoNotFound,
+  });
+
+  const server = createServer(async (req, res) => {
+    // Health check endpoint.
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', service: 'git-server' }));
+      return;
+    }
+
+    try {
+      // Build a Request object from the Node.js IncomingMessage.
+      const url = `http://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`;
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value) {
+          headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+        }
+      }
+
+      // Collect request body for POST with size limit.
+      let body: Uint8Array | undefined;
+      if (req.method === 'POST') {
+        const collected = await collectRequestBody(req, maxBodySize);
+        if (collected === null) {
+          res.writeHead(413, { 'Content-Type': 'text/plain' });
+          res.end('Payload Too Large');
+          return;
+        }
+        body = collected;
+      }
+
+      const request = new Request(url, {
+        method  : req.method ?? 'GET',
+        headers : headers,
+        body    : body ?? null,
+      });
+
+      const response = await fetchHandler(request);
+
+      // Write response back to Node.js ServerResponse.
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => { responseHeaders[key] = value; });
+      res.writeHead(response.status, responseHeaders);
+      if (response.body) {
+        const reader = response.body.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) { break; }
+            res.write(value);
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      }
+      res.end();
+    } catch (err) {
+      console.error(`Git HTTP handler error: ${(err as Error).message}`);
+      res.writeHead(500);
+      res.end('Internal Server Error');
+    }
+  });
+
+  // Start listening.
+  const actualPort = await new Promise<number>((resolve) => {
+    server.listen(port, hostname, () => {
+      const addr = server.address();
+      const boundPort = typeof addr === 'object' && addr !== null ? addr.port : port;
+      resolve(boundPort);
+    });
+  });
+
+  return {
+    port    : actualPort,
+    backend : backend,
+    async stop(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) { reject(err); } else { resolve(); }
+        });
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect the full request body from a Node.js IncomingMessage.
+ * Returns `null` if the body exceeds `maxBytes`.
+ */
+function collectRequestBody(req: IncomingMessage, maxBytes: number = DEFAULT_MAX_BODY_GIT): Promise<Uint8Array | null> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let totalSize = 0;
+    let exceeded = false;
+    req.on('data', (chunk: Buffer) => {
+      if (exceeded) { return; }
+      totalSize += chunk.length;
+      if (totalSize > maxBytes) {
+        exceeded = true;
+        // Stop reading but don't destroy — let the response be sent.
+        req.resume();
+        resolve(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!exceeded) { resolve(new Uint8Array(Buffer.concat(chunks))); }
+    });
+    req.on('error', () => {
+      if (!exceeded) { resolve(null); }
+    });
+  });
+}

package/src/git-server/verify.ts

@@ -0,0 +1,116 @@
+/**
+ * DID-based signature verification for push authentication.
+ *
+ * Resolves a DID document, extracts the Ed25519 authentication key,
+ * and verifies the signature. This is the production implementation
+ * of the `SignatureVerifier` callback used by `createPushAuthenticator`.
+ *
+ * @module
+ */
+
+import type { SignatureVerifier } from './auth.js';
+
+import { Ed25519 } from '@enbox/crypto';
+import { DidDht, DidJwk, DidKey, DidWeb, UniversalResolver } from '@enbox/dids';
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+/** Shared resolver instance (lazy-initialized). */
+let resolver: UniversalResolver | undefined;
+
+/** Get or create the DID resolver. */
+function getResolver(): UniversalResolver {
+  if (!resolver) {
+    resolver = new UniversalResolver({
+      didResolvers: [DidDht, DidJwk, DidWeb, DidKey],
+    });
+  }
+  return resolver;
+}
+
+// ---------------------------------------------------------------------------
+// Signature verifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `SignatureVerifier` that resolves a DID and verifies an Ed25519
+ * signature against the DID document's authentication verification method.
+ *
+ * The verifier looks for the first Ed25519 verification method in the DID
+ * document's `authentication` purpose (or falls back to `verificationMethod`
+ * if no authentication methods are defined).
+ *
+ * @returns A `SignatureVerifier` callback
+ */
+/** DID resolution timeout in milliseconds. */
+const DID_RESOLUTION_TIMEOUT_MS = 30_000;
+
+export function createDidSignatureVerifier(): SignatureVerifier {
+  return async (did: string, payload: Uint8Array, signature: Uint8Array): Promise<boolean> => {
+    try {
+      const { didDocument, didResolutionMetadata } = await Promise.race([
+        getResolver().resolve(did),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error(`DID resolution timed out for ${did}`)), DID_RESOLUTION_TIMEOUT_MS),
+        ),
+      ]);
+
+      if (didResolutionMetadata.error || !didDocument) {
+        return false;
+      }
+
+      // Find an Ed25519 public key from the authentication verification methods.
+      const publicKeyJwk = findEd25519AuthKey(didDocument);
+      if (!publicKeyJwk) {
+        return false;
+      }
+
+      return await Ed25519.verify({
+        key       : publicKeyJwk,
+        data      : payload,
+        signature : signature,
+      });
+    } catch {
+      return false;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the first Ed25519 public key JWK from a DID document's authentication
+ * verification methods.
+ */
+function findEd25519AuthKey(didDocument: { verificationMethod?: any[]; authentication?: any[] }): any | undefined {
+  const methods = didDocument.verificationMethod ?? [];
+
+  // If authentication references exist, filter to those methods.
+  const authRefs = didDocument.authentication ?? [];
+  const authMethodIds = new Set<string>();
+  for (const ref of authRefs) {
+    if (typeof ref === 'string') {
+      authMethodIds.add(ref);
+    } else if (ref?.id) {
+      authMethodIds.add(ref.id);
+    }
+  }
+
+  // Prefer authentication methods; fall back to all verification methods.
+  const candidates = authMethodIds.size > 0
+    ? methods.filter((m) => authMethodIds.has(m.id))
+    : methods;
+
+  for (const method of candidates) {
+    const jwk = method.publicKeyJwk;
+    if (jwk && jwk.kty === 'OKP' && jwk.crv === 'Ed25519' && jwk.x) {
+      return jwk;
+    }
+  }
+
+  return undefined;
+}

package/src/github-shim/helpers.ts

@@ -0,0 +1,311 @@
+/**
+ * Shared helpers for the GitHub API compatibility shim.
+ *
+ * Provides DID-to-numeric-ID hashing, `from` option building, repo
+ * record lookup, GitHub-style owner objects, pagination, and standard
+ * response headers.
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../cli/agent.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** GitHub-style owner sub-object synthesized from a DID. */
+export type GitHubOwner = {
+  login : string;
+  id : number;
+  type : string;
+  avatar_url : string;
+  html_url : string;
+  url : string;
+};
+
+/** Repo metadata extracted from a DWN repo record. */
+export type RepoInfo = {
+  name : string;
+  description : string;
+  defaultBranch : string;
+  contextId : string;
+  visibility : string;
+  dateCreated : string;
+  timestamp : string;
+};
+
+/** Pagination parameters parsed from query string. */
+export type PaginationParams = {
+  page : number;
+  perPage : number;
+};
+
+/** Standard JSON API response shape. */
+export type JsonResponse = {
+  status : number;
+  headers : Record<string, string>;
+  body : string;
+};
+
+// ---------------------------------------------------------------------------
+// Numeric ID from DWN identifiers
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic numeric ID from a DWN string identifier.
+ *
+ * Uses a simple FNV-1a-inspired hash to produce a positive 32-bit
+ * integer — sufficient for GitHub API compatibility where consumers
+ * expect numeric IDs.
+ */
+export function numericId(id: string): number {
+  let hash = 2166136261;
+  for (let i = 0; i < id.length; i++) {
+    hash ^= id.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0); // ensure unsigned 32-bit
+}
+
+// ---------------------------------------------------------------------------
+// DWN query helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `from` option for a DWN query.  When the target is the
+ * local agent's own DID we omit `from`; otherwise set it so the SDK
+ * routes the message to the remote DWN.
+ */
+export function fromOpt(ctx: AgentContext, targetDid: string): string | undefined {
+  return targetDid === ctx.did ? undefined : targetDid;
+}
+
+/**
+ * Look up the singleton repo record for a target DID.  Returns `null`
+ * if no repo record exists.
+ */
+export async function getRepoRecord(ctx: AgentContext, targetDid: string): Promise<RepoInfo | null> {
+  const from = fromOpt(ctx, targetDid);
+  const { records } = await ctx.repo.records.query('repo', { from });
+  if (records.length === 0) { return null; }
+
+  const rec = records[0];
+  const data = await rec.data.json();
+  const tags = rec.tags as Record<string, string> | undefined;
+
+  return {
+    name          : data.name ?? 'unnamed',
+    description   : data.description ?? '',
+    defaultBranch : data.defaultBranch ?? 'main',
+    contextId     : rec.contextId ?? '',
+    visibility    : tags?.visibility ?? 'public',
+    dateCreated   : rec.dateCreated,
+    timestamp     : rec.timestamp,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GitHub-style owner object
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a GitHub-style owner sub-object from a DID.  The DID itself is
+ * used as the `login` field since DIDs are globally unique identifiers
+ * (just like GitHub usernames).
+ */
+export function buildOwner(did: string, baseUrl: string): GitHubOwner {
+  return {
+    login      : did,
+    id         : numericId(did),
+    type       : 'User',
+    avatar_url : '',
+    html_url   : `${baseUrl}/users/${did}`,
+    url        : `${baseUrl}/users/${did}`,
+  };
+}
+
+/**
+ * Build the base API URL from request context.  Defaults to
+ * `http://localhost:<port>` for local development.
+ */
+export function buildApiUrl(url: URL): string {
+  return `${url.protocol}//${url.host}`;
+}
+
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+
+/** Parse `page` and `per_page` from the URL query string. */
+export function parsePagination(url: URL): PaginationParams {
+  const page = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10));
+  const perPage = Math.min(100, Math.max(1, parseInt(url.searchParams.get('per_page') ?? '30', 10)));
+  return { page, perPage };
+}
+
+/** Apply pagination to an array and return the slice. */
+export function paginate<T>(items: T[], params: PaginationParams): T[] {
+  const start = (params.page - 1) * params.perPage;
+  return items.slice(start, start + params.perPage);
+}
+
+/** Build Link header value for pagination. */
+export function buildLinkHeader(baseUrl: string, path: string, page: number, perPage: number, totalItems: number): string | null {
+  const lastPage = Math.max(1, Math.ceil(totalItems / perPage));
+  if (lastPage <= 1) { return null; }
+
+  const links: string[] = [];
+  if (page < lastPage) {
+    links.push(`<${baseUrl}${path}?page=${page + 1}&per_page=${perPage}>; rel="next"`);
+    links.push(`<${baseUrl}${path}?page=${lastPage}&per_page=${perPage}>; rel="last"`);
+  }
+  if (page > 1) {
+    links.push(`<${baseUrl}${path}?page=1&per_page=${perPage}>; rel="first"`);
+    links.push(`<${baseUrl}${path}?page=${page - 1}&per_page=${perPage}>; rel="prev"`);
+  }
+
+  return links.length > 0 ? links.join(', ') : null;
+}
+
+// ---------------------------------------------------------------------------
+// Response builders
+// ---------------------------------------------------------------------------
+
+/** Standard headers for all GitHub API shim responses. */
+export function baseHeaders(): Record<string, string> {
+  return {
+    'Content-Type'                 : 'application/json; charset=utf-8',
+    'X-GitHub-Media-Type'          : 'github.v3',
+    'Access-Control-Allow-Origin'  : '*',
+    'Access-Control-Allow-Headers' : 'Authorization, Accept, Content-Type',
+    'X-RateLimit-Limit'            : '5000',
+    'X-RateLimit-Remaining'        : '4999',
+    'X-RateLimit-Reset'            : String(Math.floor(Date.now() / 1000) + 3600),
+  };
+}
+
+/** Build a successful JSON response. */
+export function jsonOk(data: unknown, extraHeaders?: Record<string, string>): JsonResponse {
+  return {
+    status  : 200,
+    headers : { ...baseHeaders(), ...extraHeaders },
+    body    : JSON.stringify(data),
+  };
+}
+
+/** Build a 404 JSON response. */
+export function jsonNotFound(message: string): JsonResponse {
+  return {
+    status  : 404,
+    headers : baseHeaders(),
+    body    : JSON.stringify({ message, documentation_url: 'https://docs.github.com/rest' }),
+  };
+}
+
+/** Build a 201 Created JSON response. */
+export function jsonCreated(data: unknown, extraHeaders?: Record<string, string>): JsonResponse {
+  return {
+    status  : 201,
+    headers : { ...baseHeaders(), ...extraHeaders },
+    body    : JSON.stringify(data),
+  };
+}
+
+/** Build a 422 JSON response (validation error). */
+export function jsonValidationError(message: string): JsonResponse {
+  return {
+    status  : 422,
+    headers : baseHeaders(),
+    body    : JSON.stringify({ message, documentation_url: 'https://docs.github.com/rest' }),
+  };
+}
+
+/** Build a 405 Method Not Allowed JSON response. */
+export function jsonMethodNotAllowed(message: string): JsonResponse {
+  return {
+    status  : 405,
+    headers : baseHeaders(),
+    body    : JSON.stringify({ message }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Sequential numbering
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the next sequential issue number.
+ * Returns `max(existing numbers) + 1`, or 1 if no issues exist.
+ */
+export async function getNextIssueNumber(ctx: AgentContext, repoContextId: string): Promise<number> {
+  const { records } = await ctx.issues.records.query('repo/issue', {
+    filter: { contextId: repoContextId },
+  });
+
+  let maxNumber = 0;
+  for (const rec of records) {
+    const recTags = rec.tags as Record<string, string> | undefined;
+    const num = parseInt(recTags?.number ?? '0', 10);
+    if (num > maxNumber) { maxNumber = num; }
+  }
+
+  return maxNumber + 1;
+}
+
+/**
+ * Get the next sequential patch number.
+ */
+export async function getNextPatchNumber(ctx: AgentContext, repoContextId: string): Promise<number> {
+  const { records } = await ctx.patches.records.query('repo/patch', {
+    filter: { contextId: repoContextId },
+  });
+
+  let maxNumber = 0;
+  for (const rec of records) {
+    const recTags = rec.tags as Record<string, string> | undefined;
+    const num = parseInt(recTags?.number ?? '0', 10);
+    if (num > maxNumber) { maxNumber = num; }
+  }
+
+  return maxNumber + 1;
+}
+
+/** Convert an ISO date string to GitHub's ISO 8601 format. */
+export function toISODate(dateStr: string | undefined): string {
+  if (!dateStr) { return new Date(0).toISOString(); }
+  // DWN dates may already be ISO 8601; normalize to ensure consistency.
+  return new Date(dateStr).toISOString();
+}
+
+// ---------------------------------------------------------------------------
+// Authentication
+// ---------------------------------------------------------------------------
+
+/** Build a 401 Unauthorized JSON response. */
+export function jsonUnauthorized(message: string): JsonResponse {
+  return {
+    status  : 401,
+    headers : baseHeaders(),
+    body    : JSON.stringify({ message }),
+  };
+}
+
+/**
+ * Validate a Bearer token from the Authorization header.
+ * Returns `true` if the token matches `GITD_API_TOKEN`, or if
+ * no token is configured (open access).
+ */
+export function validateBearerToken(authHeader: string | null): boolean {
+  const expected = process.env.GITD_API_TOKEN;
+  if (!expected) { return true; } // No token configured — open access.
+  if (!authHeader?.startsWith('Bearer ')) { return false; }
+  const token = authHeader.slice(7);
+  // Constant-time comparison to prevent timing attacks.
+  if (token.length !== expected.length) { return false; }
+  let mismatch = 0;
+  for (let i = 0; i < token.length; i++) {
+    mismatch |= token.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return mismatch === 0;
+}

package/src/github-shim/index.ts

@@ -0,0 +1,35 @@
+/**
+ * GitHub API compatibility shim — barrel exports.
+ *
+ * @module
+ */
+
+export { handleShimRequest, startShimServer } from './server.js';
+export type { ShimServerOptions } from './server.js';
+
+export { handleGetRepo, buildRepoResponse } from './repos.js';
+export { handleCreateIssue, handleCreateIssueComment, handleGetIssue, handleListIssueComments, handleListIssues, handleUpdateIssue } from './issues.js';
+export { handleCreatePull, handleCreatePullReview, handleGetPull, handleListPullReviews, handleListPulls, handleMergePull, handleUpdatePull } from './pulls.js';
+export { handleCreateRelease, handleGetReleaseByTag, handleListReleases } from './releases.js';
+export { handleGetUser } from './users.js';
+
+export {
+  buildApiUrl,
+  buildLinkHeader,
+  buildOwner,
+  fromOpt,
+  getNextIssueNumber,
+  getNextPatchNumber,
+  getRepoRecord,
+  numericId,
+  paginate,
+  parsePagination,
+  toISODate,
+} from './helpers.js';
+
+export type {
+  GitHubOwner,
+  JsonResponse,
+  PaginationParams,
+  RepoInfo,
+} from './helpers.js';