javascript-solid-server 0.0.36 → 0.0.37

package/.claude/settings.local.json

@@ -114,7 +114,9 @@
       "Bash(if [ ! -d \"jose\" ])",
       "Bash(then git clone --depth 1 --branch v0.7.0 https://github.com/solid/jose.git)",
       "Bash(fi)",
-      "Bash(timeout 45 node:*)"
+      "Bash(timeout 45 node:*)",
+      "Bash(gh issue list:*)",
+      "Bash(DATA_ROOT=/tmp/jss-git-test JSS_PORT=4444 timeout 3 node:*)"
     ]
   }
 }

package/bin/jss.js

@@ -54,6 +54,8 @@ program
   .option('--mashlib-cdn', 'Enable Mashlib data browser (CDN mode, no local files needed)')
   .option('--no-mashlib', 'Disable Mashlib data browser')
   .option('--mashlib-version <version>', 'Mashlib version for CDN mode (default: 2.0.0)')
+  .option('--git', 'Enable Git HTTP backend (clone/push support)')
+  .option('--no-git', 'Disable Git HTTP backend')
   .option('-q, --quiet', 'Suppress log output')
   .option('--print-config', 'Print configuration and exit')
   .action(async (options) => {
@@ -95,6 +97,7 @@ program
         mashlib: config.mashlib || config.mashlibCdn,
         mashlibCdn: config.mashlibCdn,
         mashlibVersion: config.mashlibVersion,
+        git: config.git,
       });
 
       await server.listen({ port: config.port, host: config.host });
@@ -113,6 +116,7 @@ program
         } else if (config.mashlib) {
           console.log(`  Mashlib: local (data browser enabled)`);
         }
+        if (config.git) console.log('  Git: enabled (clone/push support)');
         console.log('\n  Press Ctrl+C to stop\n');
       }
 

package/docs/git-support.md

@@ -0,0 +1,283 @@
+# Adding Git Support to a Solid Server
+
+This guide explains how to add Git HTTP backend support to a Solid server, enabling `git clone` and `git push` operations on pod containers.
+
+## Overview
+
+The Git HTTP protocol allows clients to clone and push to repositories over HTTP. This is implemented using Git's built-in `git http-backend` CGI program - the same one used by Apache and Nginx.
+
+### How It Works
+
+```
+┌─────────────┐     HTTP      ┌──────────────┐     CGI      ┌─────────────────┐
+│  Git Client │ ─────────────▶│ Solid Server │ ────────────▶│ git http-backend│
+│             │◀───────────── │              │◀──────────── │                 │
+└─────────────┘               └──────────────┘              └─────────────────┘
+```
+
+**Clone flow:**
+1. `GET /repo/info/refs?service=git-upload-pack` - Discovery
+2. `POST /repo/git-upload-pack` - Fetch objects
+
+**Push flow:**
+1. `GET /repo/info/refs?service=git-receive-pack` - Discovery
+2. `POST /repo/git-receive-pack` - Send objects
+
+## Implementation
+
+### 1. Detect Git Requests
+
+Git protocol requests are identified by URL patterns:
+
+```javascript
+function isGitRequest(urlPath) {
+  return urlPath.includes('/info/refs') ||
+    urlPath.includes('/git-upload-pack') ||
+    urlPath.includes('/git-receive-pack');
+}
+
+function isGitWriteOperation(urlPath) {
+  return urlPath.includes('/git-receive-pack');
+}
+```
+
+### 2. Security: Block Direct .git Access
+
+**Important:** Git protocol requests should be allowed, but direct file access to `.git/` contents must be blocked:
+
+```javascript
+// BLOCK: Direct access to .git contents (security risk)
+GET /.git/config         → 403 Forbidden
+GET /.git/objects/abc123 → 403 Forbidden
+
+// ALLOW: Git protocol (handled by git http-backend)
+GET /repo/info/refs?service=git-upload-pack → 200 OK
+POST /repo/git-upload-pack                   → 200 OK
+```
+
+### 3. Authorization with WAC
+
+Check permissions before allowing git operations:
+
+```javascript
+// Clone/fetch requires Read access
+// Push requires Write access
+
+const needsWrite = isGitWriteOperation(request.url);
+const requiredMode = needsWrite ? 'write' : 'read';
+
+const { allowed } = await checkAccess({
+  resourceUrl,
+  resourcePath,
+  agentWebId: request.webId,
+  requiredMode
+});
+
+if (!allowed) {
+  return reply.code(needsWrite ? 403 : 401).send({
+    error: needsWrite ? 'Write access required' : 'Read access required'
+  });
+}
+```
+
+### 4. Git HTTP Backend Handler
+
+The core handler spawns `git http-backend` with CGI environment variables:
+
+```javascript
+import { spawn } from 'child_process';
+
+async function handleGit(request, reply) {
+  const urlPath = decodeURIComponent(request.url.split('?')[0]);
+  const queryString = request.url.split('?')[1] || '';
+
+  // Build CGI environment
+  const env = {
+    ...process.env,
+    GIT_PROJECT_ROOT: dataRoot,           // Where repos are stored
+    GIT_HTTP_EXPORT_ALL: '',              // Allow read access
+    GIT_HTTP_RECEIVE_PACK: 'true',        // Enable push
+    PATH_INFO: urlPath,
+    REQUEST_METHOD: request.method,
+    CONTENT_TYPE: request.headers['content-type'] || '',
+    QUERY_STRING: queryString,
+    CONTENT_LENGTH: request.headers['content-length'] || '0',
+  };
+
+  // For non-bare repos, set GIT_DIR to .git subdirectory
+  if (isRegularRepo) {
+    env.GIT_DIR = path.join(repoPath, '.git');
+  }
+
+  // Spawn git http-backend
+  const child = spawn('git', ['http-backend'], { env });
+
+  // Send request body (for POST requests)
+  if (request.body && request.body.length > 0) {
+    child.stdin.write(request.body);
+  }
+  child.stdin.end();
+
+  // Parse CGI response and send to client
+  // ... (see full implementation below)
+}
+```
+
+### 5. CGI Response Parsing
+
+Git http-backend outputs CGI format (headers + body). Parse and forward:
+
+```javascript
+let buffer = Buffer.alloc(0);
+let headersSent = false;
+
+child.stdout.on('data', (data) => {
+  buffer = Buffer.concat([buffer, data]);
+
+  if (!headersSent) {
+    // Find header/body separator (try both \r\n\r\n and \n\n)
+    let headerEnd = buffer.indexOf('\r\n\r\n');
+    let sep = '\r\n';
+    let sepLen = 4;
+
+    if (headerEnd === -1) {
+      headerEnd = buffer.indexOf('\n\n');
+      sep = '\n';
+      sepLen = 2;
+    }
+
+    if (headerEnd !== -1) {
+      const headerSection = buffer.subarray(0, headerEnd).toString();
+      const bodySection = buffer.subarray(headerEnd + sepLen);
+
+      // Parse CGI headers
+      for (const line of headerSection.split(sep)) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx > 0) {
+          const key = line.substring(0, colonIdx).trim();
+          const value = line.substring(colonIdx + 1).trim();
+
+          if (key.toLowerCase() === 'status') {
+            statusCode = parseInt(value.split(' ')[0], 10);
+          } else {
+            reply.raw.setHeader(key, value);
+          }
+        }
+      }
+
+      reply.raw.writeHead(statusCode);
+      reply.raw.write(bodySection);
+      headersSent = true;
+    }
+  } else {
+    reply.raw.write(buffer);
+  }
+  buffer = Buffer.alloc(0);
+});
+
+child.stdout.on('end', () => {
+  reply.raw.end();
+});
+```
+
+## Repository Setup
+
+### Regular Repository (with working directory)
+
+```bash
+cd /path/to/pod/myrepo
+git init
+echo "# My Project" > README.md
+git add .
+git commit -m "Initial commit"
+```
+
+### Bare Repository (server-only, more efficient)
+
+```bash
+cd /path/to/pod
+git init --bare myrepo.git
+```
+
+### ACL for Public Clone
+
+Create `/path/to/pod/myrepo/.acl`:
+
+```turtle
+@prefix acl: <http://www.w3.org/ns/auth/acl#>.
+@prefix foaf: <http://xmlns.com/foaf/0.1/>.
+
+<#public>
+    a acl:Authorization;
+    acl:agentClass foaf:Agent;
+    acl:accessTo <./>;
+    acl:default <./>;
+    acl:mode acl:Read.
+```
+
+### ACL for Authenticated Push
+
+```turtle
+@prefix acl: <http://www.w3.org/ns/auth/acl#>.
+@prefix foaf: <http://xmlns.com/foaf/0.1/>.
+
+<#owner>
+    a acl:Authorization;
+    acl:agent <https://alice.example.com/#me>;
+    acl:accessTo <./>;
+    acl:default <./>;
+    acl:mode acl:Read, acl:Write, acl:Control.
+
+<#public>
+    a acl:Authorization;
+    acl:agentClass foaf:Agent;
+    acl:accessTo <./>;
+    acl:default <./>;
+    acl:mode acl:Read.
+```
+
+## Usage
+
+### Server
+
+```bash
+# Start server with git support enabled
+jss start --git
+
+# Or via environment variable
+JSS_GIT=true jss start
+```
+
+### Client
+
+```bash
+# Clone
+git clone http://localhost:3000/myrepo
+
+# Clone with authentication (if required)
+git clone http://localhost:3000/myrepo
+# Git will prompt for credentials
+
+# Push (requires write access)
+cd myrepo
+echo "New content" >> README.md
+git add .
+git commit -m "Update readme"
+git push
+```
+
+## Complete Handler Code
+
+See `src/handlers/git.js` in the JSS repository for the full implementation.
+
+## References
+
+- [Git HTTP Protocol](https://git-scm.com/book/en/v2/Git-on-the-Server-Smart-HTTP)
+- [git-http-backend documentation](https://git-scm.com/docs/git-http-backend)
+- [CGI Specification](https://www.rfc-editor.org/rfc/rfc3875)
+- [Web Access Control (WAC)](https://solidproject.org/TR/wac)
+
+## Prior Art
+
+- [nosdav/server](https://github.com/nosdav/server) - Git support implementation
+- [QuitStore](https://github.com/AKSW/QuitStore) - Git + RDF versioning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/handlers/git.js

@@ -0,0 +1,207 @@
+import { spawn } from 'child_process';
+import { existsSync, statSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Check if a URL path is a Git protocol request
+ * @param {string} urlPath - The URL path
+ * @returns {boolean}
+ */
+export function isGitRequest(urlPath) {
+  return urlPath.includes('/info/refs') ||
+    urlPath.includes('/git-upload-pack') ||
+    urlPath.includes('/git-receive-pack');
+}
+
+/**
+ * Determine if this is a write operation (push)
+ * @param {string} urlPath - The URL path
+ * @returns {boolean}
+ */
+export function isGitWriteOperation(urlPath) {
+  return urlPath.includes('/git-receive-pack');
+}
+
+/**
+ * Extract the repository path from the URL
+ * @param {string} urlPath - The URL path
+ * @returns {string|null} The repository relative path or null
+ */
+function extractRepoPath(urlPath) {
+  // Remove git service suffixes to get the repo path
+  const cleanPath = urlPath
+    .replace(/\/info\/refs.*$/, '')
+    .replace(/\/git-upload-pack$/, '')
+    .replace(/\/git-receive-pack$/, '');
+
+  // Remove leading slash
+  return cleanPath.replace(/^\//, '') || null;
+}
+
+/**
+ * Find the git directory for a path
+ * @param {string} repoPath - Absolute path to check
+ * @returns {{gitDir: string, isRegular: boolean}|null}
+ */
+function findGitDir(repoPath) {
+  if (!existsSync(repoPath) || !statSync(repoPath).isDirectory()) {
+    return null;
+  }
+
+  // Check for regular repo with .git subdirectory
+  const dotGitPath = join(repoPath, '.git');
+  if (existsSync(dotGitPath) && statSync(dotGitPath).isDirectory()) {
+    return { gitDir: dotGitPath, isRegular: true };
+  }
+
+  // Check for bare repository
+  const objectsPath = join(repoPath, 'objects');
+  const refsPath = join(repoPath, 'refs');
+  if (existsSync(objectsPath) && existsSync(refsPath)) {
+    return { gitDir: repoPath, isRegular: false };
+  }
+
+  return null;
+}
+
+/**
+ * Handle Git HTTP requests using git http-backend
+ * @param {FastifyRequest} request
+ * @param {FastifyReply} reply
+ */
+export async function handleGit(request, reply) {
+  const urlPath = decodeURIComponent(request.url.split('?')[0]);
+  const queryString = request.url.split('?')[1] || '';
+
+  // Extract repository path
+  const repoRelative = extractRepoPath(urlPath);
+  if (!repoRelative) {
+    return reply.code(400).send({ error: 'Invalid git request' });
+  }
+
+  // Handle subdomain mode
+  let dataRoot = process.env.DATA_ROOT || './data';
+  if (request.podName) {
+    dataRoot = join(dataRoot, request.podName);
+  }
+
+  const repoAbs = join(dataRoot, repoRelative);
+
+  // Find git directory
+  const gitInfo = findGitDir(repoAbs);
+  if (!gitInfo) {
+    return reply.code(404).send({ error: 'Not a git repository' });
+  }
+
+  // Build CGI environment
+  const env = {
+    ...process.env,
+    GIT_PROJECT_ROOT: dataRoot,
+    GIT_HTTP_EXPORT_ALL: '',                    // Allow read access
+    GIT_HTTP_RECEIVE_PACK: 'true',              // Enable push
+    GIT_CONFIG_PARAMETERS: "'uploadpack.allowTipSHA1InWant=true'",
+    PATH_INFO: urlPath,
+    REQUEST_METHOD: request.method,
+    CONTENT_TYPE: request.headers['content-type'] || '',
+    QUERY_STRING: queryString,
+    REMOTE_USER: request.webId || '',           // Pass authenticated user
+    CONTENT_LENGTH: request.headers['content-length'] || '0',
+  };
+
+  // For regular repositories, set GIT_DIR
+  if (gitInfo.isRegular) {
+    env.GIT_DIR = gitInfo.gitDir;
+  }
+
+  // Spawn git http-backend
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', ['http-backend'], { env });
+
+    let buffer = Buffer.alloc(0);
+    let headersSent = false;
+
+    child.stdout.on('data', (data) => {
+      buffer = Buffer.concat([buffer, data]);
+
+      if (!headersSent) {
+        // Look for end of CGI headers (try both \r\n\r\n and \n\n)
+        let headerEnd = buffer.indexOf('\r\n\r\n');
+        let headerSep = '\r\n';
+        let headerEndLen = 4;
+
+        if (headerEnd === -1) {
+          headerEnd = buffer.indexOf('\n\n');
+          headerSep = '\n';
+          headerEndLen = 2;
+        }
+
+        if (headerEnd !== -1) {
+          const headerSection = buffer.subarray(0, headerEnd).toString();
+          const bodySection = buffer.subarray(headerEnd + headerEndLen);
+
+          // Parse CGI headers and set on raw response
+          const lines = headerSection.split(headerSep);
+          let statusCode = 200;
+
+          for (const line of lines) {
+            const colonIndex = line.indexOf(':');
+            if (colonIndex > 0) {
+              const key = line.substring(0, colonIndex).trim();
+              const value = line.substring(colonIndex + 1).trim();
+
+              // Handle Status header specially
+              if (key.toLowerCase() === 'status') {
+                statusCode = parseInt(value.split(' ')[0], 10);
+              } else {
+                reply.raw.setHeader(key, value);
+              }
+            }
+          }
+
+          reply.raw.writeHead(statusCode);
+          headersSent = true;
+          reply.raw.write(bodySection);
+          buffer = Buffer.alloc(0);
+        }
+      } else {
+        reply.raw.write(buffer);
+        buffer = Buffer.alloc(0);
+      }
+    });
+
+    child.stdout.on('end', () => {
+      reply.raw.end();
+      resolve();
+    });
+
+    // Send request body to git
+    // For POST requests, Fastify has already parsed the body into request.body
+    if (request.body && request.body.length > 0) {
+      child.stdin.write(request.body);
+      child.stdin.end();
+    } else {
+      // For GET requests or empty bodies, just close stdin
+      child.stdin.end();
+    }
+
+    // Log errors
+    child.stderr.on('data', (data) => {
+      console.error('git http-backend stderr:', data.toString());
+    });
+
+    child.on('error', (err) => {
+      console.error('Failed to spawn git http-backend:', err);
+      if (!headersSent) {
+        reply.code(500).send({ error: 'Git backend error' });
+      }
+      resolve();
+    });
+
+    child.on('close', (code) => {
+      if (code !== 0 && !headersSent) {
+        reply.code(500).send({ error: 'Git operation failed' });
+      }
+      resolve();
+    });
+  });
+}

package/src/server.js

@@ -8,6 +8,7 @@ import { getCorsHeaders } from './ldp/headers.js';
 import { authorize, handleUnauthorized } from './auth/middleware.js';
 import { notificationsPlugin } from './notifications/index.js';
 import { idpPlugin } from './idp/index.js';
+import { isGitRequest, isGitWriteOperation, handleGit } from './handlers/git.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -23,6 +24,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * @param {string} options.root - Data directory path (default from env or ./data)
  * @param {boolean} options.subdomains - Enable subdomain-based pods for XSS protection (default false)
  * @param {string} options.baseDomain - Base domain for subdomain pods (e.g., "example.com")
+ * @param {boolean} options.git - Enable Git HTTP backend for clone/push (default false)
  */
 export function createServer(options = {}) {
   // Content negotiation is OFF by default - we're a JSON-LD native server
@@ -40,6 +42,8 @@ export function createServer(options = {}) {
   const mashlibEnabled = options.mashlib ?? false;
   const mashlibCdn = options.mashlibCdn ?? false;
   const mashlibVersion = options.mashlibVersion ?? '2.0.0';
+  // Git HTTP backend is OFF by default - enables clone/push via git protocol
+  const gitEnabled = options.git ?? false;
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -128,16 +132,64 @@ export function createServer(options = {}) {
     // Note: OPTIONS requests are handled by handleOptions to include Accept-* headers
   });
 
+  // Security: Block access to dotfiles except allowed Solid-specific ones
+  // This prevents exposure of .git/, .env, .htpasswd, etc.
+  // Git protocol requests bypass this check when git is enabled
+  const ALLOWED_DOTFILES = ['.well-known', '.acl', '.meta'];
+  fastify.addHook('onRequest', async (request, reply) => {
+    // Allow git protocol requests through when git is enabled
+    if (gitEnabled && isGitRequest(request.url)) {
+      return;
+    }
+
+    const segments = request.url.split('/').map(s => s.split('?')[0]); // Remove query strings
+    const hasForbiddenDotfile = segments.some(seg =>
+      seg.startsWith('.') &&
+      seg.length > 1 &&
+      !ALLOWED_DOTFILES.includes(seg)
+    );
+
+    if (hasForbiddenDotfile) {
+      return reply.code(403).send({ error: 'Forbidden', message: 'Dotfile access is not allowed' });
+    }
+  });
+
+  // Git HTTP backend handler - uses git http-backend CGI
+  // Authorization: Read for clone/fetch, Write for push
+  if (gitEnabled) {
+    fastify.addHook('preHandler', async (request, reply) => {
+      if (!isGitRequest(request.url)) {
+        return;
+      }
+
+      // Run WAC authorization - checkAccess already verifies the required mode
+      const { authorized, webId, wacAllow, authError } = await authorize(request, reply);
+      request.webId = webId;
+      request.wacAllow = wacAllow;
+
+      if (!authorized) {
+        const needsWrite = isGitWriteOperation(request.url);
+        const message = needsWrite ? 'Write access required for push' : 'Read access required for clone';
+        reply.header('WAC-Allow', wacAllow);
+        return reply.code(webId ? 403 : 401).send({ error: message });
+      }
+
+      // Handle the git request directly
+      return handleGit(request, reply);
+    });
+  }
+
   // Authorization hook - check WAC permissions
   // Skip for pod creation endpoint (needs special handling)
   fastify.addHook('preHandler', async (request, reply) => {
-    // Skip auth for pod creation, OPTIONS, IdP routes, mashlib, well-known, and notifications
+    // Skip auth for pod creation, OPTIONS, IdP routes, mashlib, well-known, notifications, and git
     const mashlibPaths = ['/mashlib.min.js', '/mash.css', '/841.mashlib.min.js'];
     if (request.url === '/.pods' ||
         request.url === '/.notifications' ||
         request.method === 'OPTIONS' ||
         request.url.startsWith('/idp/') ||
         request.url.startsWith('/.well-known/') ||
+        (gitEnabled && isGitRequest(request.url)) ||
         mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
       return;
     }