@enbox/gitd 0.0.1

package/src/git-remote/parse-url.ts

@@ -0,0 +1,81 @@
+/**
+ * Parse DID URLs used with `git-remote-did`.
+ *
+ * Supported URL forms (all invoke `git-remote-did <remote> <url>`):
+ *
+ *   did::dht:abc123                → DID = did:dht:abc123, repo = undefined
+ *   did::dht:abc123/my-repo       → DID = did:dht:abc123, repo = my-repo
+ *   did://dht:abc123/my-repo      → DID = did:dht:abc123, repo = my-repo
+ *
+ * The double-colon form (`did::<address>`) is recommended because it avoids
+ * URL-parsing ambiguity.  Git strips the `did::` prefix and passes
+ * `<address>` as the URL argument.
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Parsed components of a DID remote URL. */
+export type ParsedDidUrl = {
+  /** Full DID URI, e.g. `did:dht:abc123xyz`. */
+  did: string;
+
+  /** Optional repository name from the path component. */
+  repo?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a DID remote URL into its components.
+ *
+ * @param url - The URL argument passed by Git to the remote helper.
+ *              After stripping the transport prefix:
+ *                `did::dht:abc123/repo` → Git passes `dht:abc123/repo`
+ *                `did://dht:abc123/repo` → Git passes `did://dht:abc123/repo`
+ */
+export function parseDidUrl(url: string): ParsedDidUrl {
+  let stripped = url;
+
+  // Strip did:// prefix if present (the `://` form).
+  if (stripped.startsWith('did://')) {
+    stripped = stripped.slice('did://'.length);
+  }
+
+  // At this point, `stripped` is either:
+  //   "dht:abc123"          (DID only)
+  //   "dht:abc123/my-repo"  (DID + repo path)
+  //   "web:example.com:path/my-repo"  (did:web)
+
+  // Split on the first `/` to separate DID from repo path.
+  const slashIdx = stripped.indexOf('/');
+
+  let didSuffix: string;
+  let repo: string | undefined;
+
+  if (slashIdx === -1) {
+    didSuffix = stripped;
+  } else {
+    didSuffix = stripped.slice(0, slashIdx);
+    const pathPart = stripped.slice(slashIdx + 1);
+    if (pathPart.length > 0) {
+      repo = pathPart;
+    }
+  }
+
+  // Reconstruct full DID URI.
+  const did = `did:${didSuffix}`;
+
+  // Basic validation.
+  const parts = did.split(':');
+  if (parts.length < 3 || parts[0] !== 'did' || parts[1].length === 0 || parts[2].length === 0) {
+    throw new Error(`Invalid DID URL: "${url}" (parsed DID: "${did}")`);
+  }
+
+  return { did, repo };
+}

package/src/git-remote/resolve.ts

@@ -0,0 +1,207 @@
+/**
+ * DID resolution and git transport endpoint discovery.
+ *
+ * Resolves a DID document and extracts the git transport endpoint URL.
+ * The resolution order is:
+ *   1. Service of type `GitTransport` (preferred)
+ *   2. Service of type `DecentralizedWebNode` with `/git` suffix appended
+ *   3. Failure — no git endpoint found
+ *
+ * @module
+ */
+
+import type { DidService } from '@enbox/dids';
+
+import { DidDht, DidJwk, DidKey, DidWeb, UniversalResolver } from '@enbox/dids';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result of resolving a DID to a git transport endpoint. */
+export type GitEndpoint = {
+  /** The resolved HTTPS URL for git smart HTTP transport. */
+  url: string;
+
+  /** The DID that was resolved. */
+  did: string;
+
+  /** How the endpoint was discovered. */
+  source: 'GitTransport' | 'DecentralizedWebNode';
+};
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+/** DID resolution timeout in milliseconds. */
+const DID_RESOLUTION_TIMEOUT_MS = 30_000;
+
+/**
+ * Resolve a DID to a git transport HTTPS endpoint.
+ *
+ * @param did - Full DID URI (e.g. `did:dht:abc123xyz`)
+ * @param repo - Optional repo name to append to the endpoint path
+ * @returns The resolved git transport endpoint
+ * @throws If resolution fails, times out, or no git-compatible service is found
+ */
+export async function resolveGitEndpoint(did: string, repo?: string): Promise<GitEndpoint> {
+  const { didDocument, didResolutionMetadata } = await Promise.race([
+    getResolver().resolve(did),
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`DID resolution timed out after ${DID_RESOLUTION_TIMEOUT_MS}ms for ${did}`)), DID_RESOLUTION_TIMEOUT_MS),
+    ),
+  ]);
+
+  if (didResolutionMetadata.error) {
+    throw new Error(`DID resolution failed for ${did}: ${didResolutionMetadata.error}`);
+  }
+
+  if (!didDocument) {
+    throw new Error(`DID resolution returned no document for ${did}`);
+  }
+
+  const services: DidService[] = didDocument.service ?? [];
+
+  // Priority 1: Look for a GitTransport service.
+  const gitService = services.find((s) => s.type === 'GitTransport');
+  if (gitService) {
+    const baseUrl = extractEndpointUrl(gitService);
+    return {
+      url    : buildUrl(baseUrl, did, repo),
+      did,
+      source : 'GitTransport',
+    };
+  }
+
+  // Priority 2: Fall back to DWN endpoint + /git suffix.
+  const dwnService = services.find((s) => s.type === 'DecentralizedWebNode');
+  if (dwnService) {
+    const baseUrl = extractEndpointUrl(dwnService);
+    const gitUrl = baseUrl.replace(/\/$/, '') + '/git';
+    return {
+      url    : buildUrl(gitUrl, did, repo),
+      did,
+      source : 'DecentralizedWebNode',
+    };
+  }
+
+  throw new Error(
+    `No GitTransport or DecentralizedWebNode service found in DID document for ${did}. ` +
+    `Services: ${services.map((s) => s.type).join(', ') || '(none)'}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Extract a URL string from a service endpoint (handles string and array forms). */
+function extractEndpointUrl(service: DidService): string {
+  const ep = service.serviceEndpoint;
+
+  let url: string | undefined;
+  if (typeof ep === 'string') {
+    url = ep;
+  } else if (Array.isArray(ep) && ep.length > 0) {
+    const first = ep[0];
+    if (typeof first === 'string') {
+      url = first;
+    }
+  }
+
+  if (!url) {
+    throw new Error(`Cannot extract URL from service endpoint: ${JSON.stringify(ep)}`);
+  }
+
+  assertNotPrivateUrl(url);
+  return url;
+}
+
+// ---------------------------------------------------------------------------
+// SSRF protection
+// ---------------------------------------------------------------------------
+
+/**
+ * Private / loopback IP ranges that must never be contacted via
+ * DID-resolved URLs (prevents SSRF attacks).
+ */
+const PRIVATE_IP_PATTERNS: RegExp[] = [
+  /^127\./, // 127.0.0.0/8 loopback
+  /^10\./, // 10.0.0.0/8 private
+  /^172\.(1[6-9]|2\d|3[01])\./, // 172.16.0.0/12 private
+  /^192\.168\./, // 192.168.0.0/16 private
+  /^169\.254\./, // 169.254.0.0/16 link-local
+  /^0\./, // 0.0.0.0/8
+];
+
+const PRIVATE_IPV6_PATTERNS: RegExp[] = [
+  /^::1$/, // IPv6 loopback
+  /^fc/i, // fc00::/7 unique local
+  /^fd/i, // fc00::/7 unique local
+  /^fe80:/i, // fe80::/10 link-local
+];
+
+/**
+ * Assert that a URL does not resolve to a private/loopback address.
+ * @throws If the URL hostname is a private or loopback IP
+ */
+function assertNotPrivateUrl(urlString: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(urlString);
+  } catch {
+    throw new Error(`Invalid URL from DID service endpoint: ${urlString}`);
+  }
+
+  const hostname = parsed.hostname;
+
+  // Strip IPv6 brackets if present.
+  const bare = hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+
+  // Reject localhost by name.
+  if (bare === 'localhost' || bare.endsWith('.localhost')) {
+    throw new Error(`SSRF blocked: resolved endpoint points to localhost: ${urlString}`);
+  }
+
+  // Check IPv4 private ranges.
+  for (const pattern of PRIVATE_IP_PATTERNS) {
+    if (pattern.test(bare)) {
+      throw new Error(`SSRF blocked: resolved endpoint points to private IP: ${urlString}`);
+    }
+  }
+
+  // Check IPv6 private ranges.
+  for (const pattern of PRIVATE_IPV6_PATTERNS) {
+    if (pattern.test(bare)) {
+      throw new Error(`SSRF blocked: resolved endpoint points to private IPv6: ${urlString}`);
+    }
+  }
+}
+
+/**
+ * Build the full git transport URL: `<base>/<did>[/<repo>]`.
+ *
+ * The DID is always included in the path since the git HTTP handler uses
+ * it for routing and authorization.
+ */
+function buildUrl(base: string, did: string, repo?: string): string {
+  const normalized = base.replace(/\/$/, '');
+  if (!repo) { return `${normalized}/${did}`; }
+  return `${normalized}/${did}/${repo}`;
+}

package/src/git-remote/service.ts

@@ -0,0 +1,126 @@
+/**
+ * GitTransport DID service type utilities.
+ *
+ * Provides helpers for creating and identifying `GitTransport` service entries
+ * in DID documents.  The `GitTransport` service type advertises a smart HTTP
+ * git endpoint that can be used by `git-remote-did` to locate repositories.
+ *
+ * When a DID document contains a GitTransport service, the git remote helper
+ * uses it directly (highest priority).  Otherwise it falls back to
+ * `DecentralizedWebNode` + `/git` suffix.
+ *
+ * @example
+ * ```ts
+ * import { createGitTransportService } from '@enbox/gitd/git-remote/service';
+ *
+ * const service = createGitTransportService({
+ *   id              : '#git',
+ *   serviceEndpoint : 'https://git.example.com',
+ * });
+ * // → { id: '#git', type: 'GitTransport', serviceEndpoint: 'https://git.example.com' }
+ * ```
+ *
+ * @module
+ */
+
+import type { DidDocument, DidService } from '@enbox/dids';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** The DID service type string for git smart HTTP transport endpoints. */
+export const GIT_TRANSPORT_SERVICE_TYPE = 'GitTransport' as const;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A DID service entry with `type` fixed to `GitTransport`.
+ *
+ * The `serviceEndpoint` should be an HTTPS URL (or array of URLs) pointing to
+ * a smart HTTP git server.  Repositories are addressed by appending the repo
+ * name as a path segment: `<serviceEndpoint>/<repo-name>`.
+ */
+export interface GitTransportService extends DidService {
+  type: typeof GIT_TRANSPORT_SERVICE_TYPE;
+}
+
+/** Options for creating a GitTransport service entry. */
+export type CreateGitTransportServiceOptions = {
+  /**
+   * The service entry `id`, typically a fragment like `#git`.
+   * If no `#` prefix is provided, it will be added automatically.
+   */
+  id: string;
+
+  /**
+   * The HTTPS URL (or URLs) of the git smart HTTP endpoint.
+   *
+   * @example 'https://git.example.com'
+   * @example ['https://git1.example.com', 'https://git2.example.com']
+   */
+  serviceEndpoint: string | string[];
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `GitTransport` DID service entry.
+ *
+ * @param options - Service configuration
+ * @returns A well-formed GitTransport service entry ready for inclusion in a
+ *          DID document's `service` array.
+ */
+export function createGitTransportService(
+  options: CreateGitTransportServiceOptions,
+): GitTransportService {
+  const { serviceEndpoint } = options;
+  let { id } = options;
+
+  // Normalize the id to include a # prefix if missing.
+  if (!id.startsWith('#')) {
+    id = `#${id}`;
+  }
+
+  // Validate endpoint(s).
+  const endpoints = Array.isArray(serviceEndpoint) ? serviceEndpoint : [serviceEndpoint];
+  for (const ep of endpoints) {
+    if (typeof ep !== 'string' || ep.length === 0) {
+      throw new Error(`GitTransport serviceEndpoint must be a non-empty string, got: ${JSON.stringify(ep)}`);
+    }
+  }
+
+  return {
+    id,
+    type            : GIT_TRANSPORT_SERVICE_TYPE,
+    serviceEndpoint : Array.isArray(serviceEndpoint) ? serviceEndpoint : serviceEndpoint,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a DID service entry is a GitTransport service.
+ *
+ * @param service - A service entry from a DID document
+ * @returns `true` if the service type is `GitTransport`
+ */
+export function isGitTransportService(service: DidService): service is GitTransportService {
+  return service.type === GIT_TRANSPORT_SERVICE_TYPE;
+}
+
+/**
+ * Extract all GitTransport service entries from a DID document.
+ *
+ * @param didDocument - A resolved DID document
+ * @returns An array of GitTransport services (may be empty)
+ */
+export function getGitTransportServices(didDocument: DidDocument): GitTransportService[] {
+  return (didDocument.service ?? []).filter(isGitTransportService);
+}