javascript-solid-server 0.0.35 → 0.0.37

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.35",
+  "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/handlers/resource.js

@@ -75,36 +75,57 @@ export async function handleGet(request, reply) {
         acceptHeader.includes('text/n3') ||
         acceptHeader.includes('application/n-triples')
       );
+      const wantsJsonLd = connegEnabled && (
+        acceptHeader.includes('application/ld+json') ||
+        acceptHeader.includes('application/json')
+      );
 
-      if (wantsTurtle) {
-        // Extract JSON-LD from HTML and convert to Turtle
+      if (wantsTurtle || wantsJsonLd) {
+        // Extract JSON-LD from HTML data island
         try {
           const htmlStr = content.toString();
-          const jsonLdMatch = htmlStr.match(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/);
+          const jsonLdMatch = htmlStr.match(/<script type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/);
           if (jsonLdMatch) {
             const jsonLd = JSON.parse(jsonLdMatch[1]);
-            const { content: turtleContent } = await fromJsonLd(
-              jsonLd,
-              'text/turtle',
-              resourceUrl,
-              true
-            );
-
-            const headers = getAllHeaders({
-              isContainer: true,
-              etag: indexStats?.etag || stats.etag,
-              contentType: 'text/turtle',
-              origin,
-              resourceUrl,
-              connegEnabled
-            });
 
-            Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
-            return reply.send(turtleContent);
+            if (wantsTurtle) {
+              // Convert to Turtle
+              const { content: turtleContent } = await fromJsonLd(
+                jsonLd,
+                'text/turtle',
+                resourceUrl,
+                true
+              );
+
+              const headers = getAllHeaders({
+                isContainer: true,
+                etag: indexStats?.etag || stats.etag,
+                contentType: 'text/turtle',
+                origin,
+                resourceUrl,
+                connegEnabled
+              });
+
+              Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+              return reply.send(turtleContent);
+            } else {
+              // Return JSON-LD directly
+              const headers = getAllHeaders({
+                isContainer: true,
+                etag: indexStats?.etag || stats.etag,
+                contentType: 'application/ld+json',
+                origin,
+                resourceUrl,
+                connegEnabled
+              });
+
+              Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+              return reply.send(JSON.stringify(jsonLd, null, 2));
+            }
           }
         } catch (err) {
           // Fall through to serve HTML if conversion fails
-          console.error('Failed to convert profile to Turtle:', err.message);
+          console.error('Failed to convert profile to RDF:', err.message);
         }
       }
 
@@ -329,14 +350,45 @@ export async function handleHead(request, reply) {
   }
 
   const origin = request.headers.origin;
-  const contentType = stats.isDirectory ? 'application/ld+json' : getContentType(storagePath);
+  const connegEnabled = request.connegEnabled || false;
+  let contentType;
+
+  if (stats.isDirectory) {
+    // For directories with index.html, determine content type based on Accept header
+    const indexPath = storagePath.endsWith('/') ? `${storagePath}index.html` : `${storagePath}/index.html`;
+    const indexExists = await storage.exists(indexPath);
+
+    if (indexExists && connegEnabled) {
+      const acceptHeader = request.headers.accept || '';
+      const wantsTurtle = acceptHeader.includes('text/turtle') ||
+                          acceptHeader.includes('text/n3') ||
+                          acceptHeader.includes('application/n-triples');
+      const wantsJsonLd = acceptHeader.includes('application/ld+json') ||
+                          acceptHeader.includes('application/json');
+
+      if (wantsTurtle) {
+        contentType = 'text/turtle';
+      } else if (wantsJsonLd) {
+        contentType = 'application/ld+json';
+      } else {
+        contentType = 'text/html';
+      }
+    } else if (indexExists) {
+      contentType = 'text/html';
+    } else {
+      contentType = 'application/ld+json';
+    }
+  } else {
+    contentType = getContentType(storagePath);
+  }
 
   const headers = getAllHeaders({
     isContainer: stats.isDirectory,
     etag: stats.etag,
     contentType,
     origin,
-    resourceUrl
+    resourceUrl,
+    connegEnabled
   });
 
   if (!stats.isDirectory) {

package/src/idp/credentials.js

@@ -106,7 +106,8 @@ export async function handleCredentials(request, reply, issuer) {
   // Always generate a proper JWT - CTH requires JWT format
   const jwks = await getJwks();
   const signingKey = jwks.keys[0];
-  const privateKey = await jose.importJWK(signingKey, 'ES256');
+  const signingAlg = signingKey.alg || 'ES256'; // Use key's algorithm
+  const privateKey = await jose.importJWK(signingKey, signingAlg);
 
   const now = Math.floor(Date.now() / 1000);
   const tokenPayload = {
@@ -131,7 +132,7 @@ export async function handleCredentials(request, reply, issuer) {
   }
 
   const accessToken = await new jose.SignJWT(tokenPayload)
-    .setProtectedHeader({ alg: 'ES256', kid: signingKey.kid })
+    .setProtectedHeader({ alg: signingAlg, kid: signingKey.kid })
     .sign(privateKey);
 
   // Response

package/src/idp/index.js

@@ -179,7 +179,7 @@ export async function idpPlugin(fastify, options) {
       response_modes_supported: ['query', 'fragment', 'form_post'],
       grant_types_supported: ['authorization_code', 'refresh_token', 'client_credentials'],
       subject_types_supported: ['public'],
-      id_token_signing_alg_values_supported: ['ES256'],
+      id_token_signing_alg_values_supported: ['RS256', 'ES256'],
       token_endpoint_auth_methods_supported: ['none', 'client_secret_basic', 'client_secret_post'],
       claims_supported: ['sub', 'webid', 'name', 'email', 'email_verified'],
       code_challenge_methods_supported: ['S256'],