@karmaniverous/jeeves-server 3.0.0-0

package/guides/sharing.md

@@ -0,0 +1,204 @@
+# Insiders, Outsiders & Sharing
+
+Jeeves Server has a clear access model built around two roles: **insiders** and **outsiders**. Understanding the difference is key to using sharing effectively.
+
+## Insiders
+
+An insider is an **authenticated user** on the server. Depending on their configuration, they may have full access or be scoped to specific paths. Within their scope, they can navigate directories, view files, and generate share links for others.
+
+### Who is an insider?
+
+Anyone listed in the `insiders` map in your config:
+
+```typescript
+insiders: {
+  'alice@example.com': {},
+  'bob@example.com': { scopes: ['/d/projects/*'] },
+},
+```
+
+### How insiders authenticate
+
+Depends on which auth modes are active:
+
+- **Google OAuth** (`'google'` mode) — Insider logs in with Google. The server checks their email against the `insiders` map. On first login, a key seed is auto-generated and stored in `state.json`.
+- **Key auth** (`'keys'` mode) — Insider uses a derived URL key (`?key=<insider-key>`). The key is derived from a configured seed via HMAC-SHA256.
+
+### What insiders can do
+
+- Browse all drives and directories (within their scopes)
+- View rendered Markdown, code, SVG, Mermaid diagrams, and images
+- Switch between Rendered and Raw views
+- Export files as PDF, DOCX, or ZIP
+- Copy insider links (for other insiders)
+- Generate outsider links (for external sharing)
+- Rotate their key (invalidating all their outsider links)
+
+### Scoped insiders
+
+Scopes restrict which paths an insider can access. Three formats are supported:
+
+**Allow-only** (string array — backward compatible):
+```typescript
+'contractor@example.com': {
+  scopes: ['/d/projects/client-x/*'],
+},
+```
+
+**Allow with deny** (broad access with cutouts):
+```typescript
+'team-member@example.com': {
+  scopes: {
+    allow: ['/d/*'],
+    deny: ['/d/secrets/*', '/d/.private/*'],
+  },
+},
+```
+
+**Deny-only** (everything except exclusions):
+```typescript
+'almost-full@example.com': {
+  scopes: {
+    deny: ['/d/hr/*', '/d/finance/*'],
+  },
+},
+```
+
+**Semantics:**
+- A path must match at least one allow rule **and** not match any deny rule
+- Omitting `allow` = implicit `['/**']` (allow everything)
+- Omitting `deny` = no exclusions
+- Omitting scopes entirely = **full access** (unchanged)
+
+---
+
+## Outsiders
+
+An outsider is someone viewing a **specific file or directory** via a share link. They can see exactly what was shared — nothing more.
+
+### What outsiders can do
+
+- View the shared file (rendered Markdown, code, images, etc.)
+- Download the file (raw, PDF, or DOCX)
+- Navigate within a shared directory (if a directory link was shared)
+
+### What outsiders cannot do
+
+- Browse to other files or directories
+- See the drive listing or parent directories
+- Generate their own share links
+- Rotate keys
+
+---
+
+## How Sharing Works
+
+### The key model
+
+Every insider has a **seed** — a secret string (either configured manually or auto-generated on Google login). From this seed, the server derives two types of keys:
+
+| Key type | Derivation | Grants |
+|----------|-----------|--------|
+| **Insider key** | `HMAC-SHA256(seed, "insider")` | Full browsing access (within scopes) |
+| **Outsider key** | `HMAC-SHA256(seed, normalized_path)` | Access to one specific path |
+| **Expiring outsider key** | `HMAC-SHA256(seed, path + "\|" + expiry)` | Access to one path, until expiry |
+
+All keys are truncated to 32 hex characters. Verification uses timing-safe comparison.
+
+### Generating a share link
+
+In the header of any file or directory view, insiders see sharing controls:
+
+1. **Link dropdown** (🔗) — Copy a share link
+2. **Expiry selector** — Choose how long the link is valid: never, 1 hour, 1 day, 1 week, 1 month, or 1 year
+
+The generated URL includes the outsider key as a `?key=` parameter and (if expiring) an `&exp=` parameter with the expiration timestamp.
+
+**Example insider link:**
+```
+https://jeeves.example.com/browse/d/docs/design.md?key=a1b2c3d4...
+```
+
+**Example outsider link (expiring):**
+```
+https://jeeves.example.com/browse/d/docs/design.md?key=e5f6a7b8...&exp=1771340000000
+```
+
+### Directory sharing
+
+When you share a directory link, the outsider can:
+- See the directory listing
+- Navigate into subdirectories
+- View any file within that directory tree
+
+The server checks the outsider key against the requested path **and all ancestor paths**, so a key generated for `/d/docs/` also grants access to `/d/docs/report.md` and `/d/docs/specs/api.md`.
+
+### Link expiration
+
+- **"Never"** links work until the insider rotates their key
+- **Timed** links expire at the specified time — after that, the key is cryptographically invalid
+- Expiry is embedded in the key derivation itself, not stored server-side — there's nothing to clean up
+
+### Key rotation
+
+The 🔑 button in the header rotates the insider's key seed. This:
+
+- **Invalidates all outsider links** that insider has ever generated
+- **Generates a new insider key** for the insider
+- Is **irreversible** — old links cannot be restored
+
+Use rotation when you need to revoke all shared links at once (e.g., a contractor's access ended, a link was shared too broadly).
+
+---
+
+## Machine Keys
+
+In addition to insider-generated keys, the server supports **named machine keys** for programmatic access:
+
+```typescript
+keys: {
+  primary: 'random-seed-string',
+  'webhook-notion': { key: 'another-seed', scopes: ['/event'] },
+  _internal: 'internal-seed',
+},
+```
+
+Machine keys follow the same derivation model:
+- The **insider key** derived from an unscoped machine seed grants full access
+- Machine seeds can also generate **outsider keys** for specific paths
+- **Scoped** machine keys (like `webhook-notion` above) can only access matching paths
+
+### The `_internal` key
+
+Reserved for server-side operations. Puppeteer uses this key when rendering PDFs and DOCX files (it loads the page in headless Chrome and needs to authenticate). It must be unscoped — the schema enforces this.
+
+---
+
+## Access Decision Flow
+
+When a request arrives, the server determines access as follows:
+
+![Access Decision Flow](access-decision-flow.svg)
+
+### Insider vs outsider UI
+
+The server renders different UI based on access mode:
+
+| Feature | Insider | Outsider |
+|---------|---------|----------|
+| Drive/directory browsing | ✅ | Only shared path |
+| File viewing | ✅ | ✅ |
+| PDF/DOCX export | ✅ | ✅ |
+| Share link generation | ✅ | ❌ |
+| Key rotation | ✅ | ❌ |
+| Download dropdown | Full options | File download only |
+
+---
+
+## Security Notes
+
+- **All keys are derived** — seeds are never exposed in URLs. Even if someone captures an outsider key, they can't derive the insider key or access other paths.
+- **Timing-safe comparison** — key verification uses constant-time comparison to prevent timing attacks.
+- **No server-side link storage** — outsider keys are computed on-the-fly from the seed + path (+ optional expiry). There's no database of active links to breach.
+- **Scopes are enforced at verification time** — even if a valid key is presented, it's rejected if the path doesn't match the key's scopes.
+- **HTTPS recommended** — keys are in URL parameters. Use HTTPS in production to prevent interception.

package/jeeves-server.config.template.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "./jeeves-server.schema.json",
+  "port": 1934,
+  "chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+  "auth": {
+    "modes": ["google", "keys"],
+    "google": {
+      "clientId": "your-google-client-id.apps.googleusercontent.com",
+      "clientSecret": "${GOOGLE_CLIENT_SECRET}"
+    },
+    "sessionSecret": "${SESSION_SECRET}"
+  },
+  "insiders": {
+    "user@example.com": {
+      "scopes": ["/**"]
+    }
+  },
+  "keys": {
+    "primary": "${KEY_PRIMARY}",
+    "_internal": "${KEY_INTERNAL}"
+  },
+  "events": {},
+  "eventTimeoutMs": 30000,
+  "eventLogPurgeMs": 2592000000
+}

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@karmaniverous/jeeves-server",
+  "version": "3.0.0-0",
+  "description": "Secure file browser, markdown viewer, and webhook gateway with PDF/DOCX export and expiring share links",
+  "keywords": [
+    "fastify",
+    "react",
+    "markdown",
+    "file-server",
+    "file-browser",
+    "pdf-export",
+    "docx-export",
+    "mermaid",
+    "typescript",
+    "webhook",
+    "document-viewer",
+    "self-hosted",
+    "share-links",
+    "hmac",
+    "google-oauth"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node dist/src/server.js",
+    "dev": "tsx watch src/server.ts",
+    "prebuild": "npx rimraf dist .tsbuildinfo",
+    "build": "tsc",
+    "postbuild": "cd client && npm run build",
+    "typecheck": "cross-env NODE_OPTIONS=--max-old-space-size=4096 tsc --noEmit",
+    "test": "vitest run",
+    "changelog": "auto-changelog",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "postinstall": "node scripts/download-plantuml.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "knip": "knip",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/jeeves-server.git"
+  },
+  "author": "Jeeves",
+  "license": "MIT",
+  "dependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/static": "^8.3.0",
+    "@karmaniverous/jsonmap": "^0.3.1",
+    "@mermaid-js/mermaid-cli": "^11.12.0",
+    "@turbodocx/html-to-docx": "^1.1.0",
+    "ajv": "^8.17.1",
+    "archiver": "^7.0.1",
+    "cheerio": "^1.2.0",
+    "cosmiconfig": "^9.0.1",
+    "fastify": "^5.2.3",
+    "lz-string": "^1.5.0",
+    "marked": "^17.0.1",
+    "mime-types": "^3.0.2",
+    "picomatch": "^4.0.3",
+    "plantuml-encoder": "^1.4.0",
+    "puppeteer": "^23.11.1",
+    "puppeteer-core": "^23.11.1",
+    "radash": "^12.1.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.54.1",
+    "@types/archiver": "^7.0.0",
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^22.0.0",
+    "@types/picomatch": "^4.0.2",
+    "@vitest/coverage-v8": "^4.0.16",
+    "auto-changelog": "^2.5.0",
+    "cross-env": "^10.1.0",
+    "happy-dom": "^20.0.11",
+    "release-it": "^19.2.4",
+    "rimraf": "^6.0.1",
+    "vitest": "^4.0.16"
+  },
+  "auto-changelog": {
+    "output": "CHANGELOG.md",
+    "unreleased": true,
+    "commitLimit": false,
+    "hideCredit": true
+  },
+  "release-it": {
+    "git": {
+      "changelog": "npx auto-changelog --unreleased-only --stdout --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "commitMessage": "chore: release @karmaniverous/jeeves-server v${version}",
+      "tagName": "service/${version}",
+      "requireBranch": "main"
+    },
+    "github": {
+      "release": true
+    },
+    "hooks": {
+      "after:init": [
+        "npm run lint",
+        "npm run typecheck",
+        "npm run test",
+        "npm run build"
+      ],
+      "before:npm:release": [
+        "npx auto-changelog -p",
+        "git add -A"
+      ],
+      "after:release": [
+        "git switch -c release/service/${version}",
+        "git push -u origin release/service/${version}",
+        "git switch ${branchName}"
+      ]
+    },
+    "npm": {
+      "publish": true
+    }
+  },
+  "bin": {
+    "jeeves-server": "./dist/src/cli/index.js"
+  }
+}

package/scripts/download-plantuml.js

@@ -0,0 +1,70 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+
+/**
+ * Downloads a pinned PlantUML jar to vendor/plantuml.jar.
+ * Run automatically via postinstall, or manually: node scripts/download-plantuml.js
+ *
+ * The jar is gitignored and server-side only (never touches the client build).
+ * To upgrade PlantUML: bump PLANTUML_VERSION below and run npm install.
+ */
+
+import fs from 'node:fs';
+import https from 'node:https';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PLANTUML_VERSION = 'v1.2026.2';
+const PLANTUML_URL = `https://github.com/plantuml/plantuml/releases/download/${PLANTUML_VERSION}/plantuml-${PLANTUML_VERSION.slice(1)}.jar`;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const vendorDir = path.resolve(__dirname, '..', 'vendor');
+const jarPath = path.join(vendorDir, 'plantuml.jar');
+const versionFile = path.join(vendorDir, '.plantuml-version');
+
+// Skip if already downloaded at this version
+if (fs.existsSync(jarPath) && fs.existsSync(versionFile)) {
+  const currentVersion = fs.readFileSync(versionFile, 'utf8').trim();
+  if (currentVersion === PLANTUML_VERSION) {
+    console.log(`PlantUML ${PLANTUML_VERSION} already present, skipping download.`);
+    process.exit(0);
+  }
+}
+
+fs.mkdirSync(vendorDir, { recursive: true });
+
+console.log(`Downloading PlantUML ${PLANTUML_VERSION}...`);
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const follow = (url) => {
+      https.get(url, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          follow(res.headers.location);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${String(res.statusCode)} downloading PlantUML`));
+          return;
+        }
+        const file = fs.createWriteStream(dest);
+        res.pipe(file);
+        file.on('finish', () => { file.close(); resolve(); });
+        file.on('error', reject);
+      }).on('error', reject);
+    };
+    follow(url);
+  });
+}
+
+try {
+  await download(PLANTUML_URL, jarPath);
+  fs.writeFileSync(versionFile, PLANTUML_VERSION);
+  const stats = fs.statSync(jarPath);
+  console.log(`PlantUML ${PLANTUML_VERSION} downloaded (${(stats.size / 1024 / 1024).toFixed(1)} MB)`);
+} catch (err) {
+  console.warn(`Warning: Failed to download PlantUML: ${err.message}`);
+  console.warn('PlantUML local rendering will fall back to server-based rendering.');
+  // Don't fail the install — PlantUML is optional
+  process.exit(0);
+}

package/src/auth/google.ts

@@ -0,0 +1,93 @@
+/**
+ * Google OAuth 2.0 helpers.
+ * Uses native fetch — no googleapis SDK needed.
+ */
+
+const GOOGLE_AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const GOOGLE_USERINFO_URL = 'https://openidconnect.googleapis.com/v1/userinfo';
+
+export interface GoogleTokens {
+  access_token: string;
+  id_token?: string;
+  refresh_token?: string;
+  expires_in: number;
+  token_type: string;
+}
+
+export interface GoogleUserInfo {
+  sub: string;
+  email: string;
+  email_verified: boolean;
+  name?: string;
+  picture?: string;
+}
+
+/**
+ * Build the Google OAuth consent URL.
+ */
+export function buildAuthUrl(
+  clientId: string,
+  redirectUri: string,
+  state?: string,
+): string {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    scope: 'openid email profile',
+    access_type: 'offline',
+    prompt: 'consent',
+  });
+  if (state) params.set('state', state);
+  return `${GOOGLE_AUTH_URL}?${params.toString()}`;
+}
+
+/**
+ * Exchange authorization code for tokens.
+ */
+export async function exchangeCode(
+  clientId: string,
+  clientSecret: string,
+  redirectUri: string,
+  code: string,
+): Promise<GoogleTokens> {
+  const resp = await fetch(GOOGLE_TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: clientId,
+      client_secret: clientSecret,
+      redirect_uri: redirectUri,
+      code,
+      grant_type: 'authorization_code',
+    }),
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(
+      `Google token exchange failed: ${String(resp.status)} ${text}`,
+    );
+  }
+
+  return (await resp.json()) as GoogleTokens;
+}
+
+/**
+ * Fetch user info using an access token.
+ */
+export async function getUserInfo(
+  accessToken: string,
+): Promise<GoogleUserInfo> {
+  const resp = await fetch(GOOGLE_USERINFO_URL, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`Google userinfo failed: ${String(resp.status)} ${text}`);
+  }
+
+  return (await resp.json()) as GoogleUserInfo;
+}