collabmd 0.1.20 → 0.1.23

package/README.md

@@ -17,6 +17,7 @@ Throughout this guide, **vault** simply means a regular folder on your computer
 - No migration: your files stay on disk
 - Your filesystem stays the source of truth: CollabMD does not move, rename, or delete files unless you explicitly do that in the app
 - Realtime editing with Yjs
+- External filesystem edits sync back into the app and connected browsers
 - Mermaid, PlantUML, and Excalidraw support
 - Source-anchored comments, chat, and presence
 - Works with plain folders, Obsidian-style vaults, and git-backed docs
@@ -60,6 +61,7 @@ Prefer video? [Open the WebM demo](https://raw.githubusercontent.com/andes90/col
 - **No migration** — point CollabMD at an existing markdown folder, diagram workspace, Obsidian-style vault, or git-backed docs repo
 - **Local-files-first** — your filesystem remains the source of truth
 - **Realtime collaboration** — multiple people can edit the same file at the same time via Yjs
+- **External edit sync** — changes made from tools like Obsidian or direct file writes are reflected back into open documents and the file explorer
 - **Markdown with context** — live preview, wiki-links, backlinks, outline, quick switcher, and scroll sync
 - **Source-anchored comments** — comment on lines or selected text with inline markers, preview bubbles, and thread cards
 - **Collaboration built in** — collaborator presence, follow mode, and team chat
@@ -150,13 +152,14 @@ Then share the printed URL and password with your collaborator. If `cloudflared`
 
 - Treat the URL as write access to the vault unless you enable auth
 - `--auth password` protects `/api/*` and `/ws/*` with a host password and signed session cookie
+- `--auth oidc` signs users in with Google and uses the verified Google name/email as the in-app identity and git commit author
 - If `cloudflared` is installed, CollabMD may expose the app through a Cloudflare Quick Tunnel unless you pass `--no-tunnel`
-- `oidc` is reserved for a future implementation and is not usable yet
+- `--auth oidc` requires a stable `PUBLIC_BASE_URL`; Quick Tunnel URLs are not supported for OIDC
 
 ## Current limitations
 
 - Single-instance deployment only: collaboration room state is kept in-process and is not shared across replicas
-- `oidc` auth is reserved for a future implementation and is not usable yet
+- `oidc` currently supports Google only
 - Source-anchored comments currently support markdown, Mermaid, and PlantUML text files, but not `.excalidraw`
 - Windows use is supported via WSL2 rather than native Windows execution
 
@@ -181,7 +184,7 @@ Comment threads are source-anchored and currently supported for markdown, Mermai
 
 Markdown video embeds are opt-in and use standard image syntax such as `![Video](https://www.youtube.com/watch?v=...)` or `![Video](https://cdn.example.com/demo.webm)`. The preview currently supports public YouTube URLs plus direct public `https` video files ending in `.mp4`, `.webm`, or `.ogg`. The editor toolbar also includes a `Video` action that inserts the same Markdown syntax for you.
 
-Your filesystem is the source of truth. CollabMD reads files from disk, uses Yjs for realtime collaboration, and continuously writes plain text back to disk as you type.
+Your filesystem is the source of truth. CollabMD reads files from disk, uses Yjs for realtime collaboration, and continuously writes plain text back to disk as you type. External changes from tools like Obsidian, direct file writes, or git-driven file updates are watched and reconciled back into live rooms and the explorer.
 
 ## Usage
 
@@ -201,7 +204,7 @@ collabmd [directory] [options]
 |--------|-------------|---------|
 | `-p, --port` | Port to listen on | `1234` |
 | `--host` | Host to bind to | `127.0.0.1` |
-| `--auth` | Auth strategy: `none`, `password`, `oidc` (`oidc` is reserved and not yet available) | `none` |
+| `--auth` | Auth strategy: `none`, `password`, `oidc` | `none` |
 | `--auth-password` | Password for `--auth password` | generated per run |
 | `--local-plantuml` | Start the bundled local docker-compose PlantUML service | off |
 | `--no-tunnel` | Don't start Cloudflare Tunnel | tunnel on |
@@ -226,6 +229,12 @@ collabmd --auth password
 # Require an explicit password
 collabmd --auth password --auth-password "shared-secret"
 
+# Use Google OIDC on a stable public domain
+PUBLIC_BASE_URL=https://notes.example.com \
+AUTH_OIDC_CLIENT_ID=your-google-client-id \
+AUTH_OIDC_CLIENT_SECRET=your-google-client-secret \
+collabmd --auth oidc --no-tunnel
+
 # Use the local docker-compose PlantUML service
 collabmd --local-plantuml
 
@@ -256,6 +265,39 @@ To disable the tunnel:
 collabmd --no-tunnel
 ```
 
+### Google OIDC setup
+
+`--auth oidc` uses Google OpenID Connect with the authorization code + PKCE flow.
+
+For the full Google Cloud Console walkthrough, including where to create the OAuth client and copy the client ID/client secret, see [docs/google-oidc-setup.md](https://github.com/andes90/collabmd/blob/master/docs/google-oidc-setup.md).
+
+Required environment variables:
+
+```bash
+PUBLIC_BASE_URL=https://notes.example.com
+AUTH_OIDC_CLIENT_ID=your-google-client-id
+AUTH_OIDC_CLIENT_SECRET=your-google-client-secret
+```
+
+In Google Cloud Console, create a Web application OAuth client and register this redirect URI:
+
+```text
+https://notes.example.com/api/auth/oidc/callback
+```
+
+If you mount the app under a subpath with `BASE_PATH=/collabmd`, the redirect URI becomes:
+
+```text
+https://notes.example.com/collabmd/api/auth/oidc/callback
+```
+
+Notes:
+
+- OIDC requires a stable public URL and is not compatible with ephemeral Cloudflare Quick Tunnel URLs
+- After sign-in, the verified Google name/email become the displayed app identity and the default in-app git commit author
+- You can restrict sign-in to exact users with `AUTH_OIDC_ALLOWED_EMAILS` or entire domains with `AUTH_OIDC_ALLOWED_DOMAINS`
+- The CLI disables the tunnel automatically when `--auth oidc` is active
+
 You can also configure the tunnel via environment variables:
 
 ```bash
@@ -276,6 +318,26 @@ docker run -p 1234:1234 -v /path/to/vault:/data ghcr.io/andes90/collabmd:latest
 
 The container listens on `0.0.0.0:1234` and stores vault files at `/data`.
 
+### Kubernetes / Helm
+
+CollabMD now includes a Helm chart at [`packaging/helm/collabmd`](./packaging/helm/collabmd).
+
+Use it when you want a Kubernetes-native deployment with:
+
+- one supported application replica
+- a persistent volume mounted at `/data`
+- optional ingress
+- optional bundled PlantUML
+- secret-backed auth and private git bootstrap settings
+
+Quick start:
+
+```bash
+helm install collabmd ./packaging/helm/collabmd
+```
+
+For examples covering ingress, OIDC, PlantUML, and private git bootstrap, see [packaging/helm/collabmd/README.md](./packaging/helm/collabmd/README.md).
+
 To bootstrap `/data` from a private git repository instead, pass the repo URL plus SSH credentials:
 
 ```bash
@@ -322,6 +384,24 @@ docker compose up
 
 Open `http://localhost:1234`.
 
+To test Google OIDC locally with the included compose setup, register this redirect URI in Google Cloud Console:
+
+```text
+http://localhost:1234/api/auth/oidc/callback
+```
+
+Then start compose with the OIDC env vars:
+
+```bash
+AUTH_STRATEGY=oidc \
+PUBLIC_BASE_URL=http://localhost:1234 \
+AUTH_OIDC_CLIENT_ID=your-google-client-id \
+AUTH_OIDC_CLIENT_SECRET=your-google-client-secret \
+docker compose up
+```
+
+If you change `COLLABMD_HOST_PORT`, update `PUBLIC_BASE_URL` and the Google redirect URI to match that host port.
+
 By default, compose uses `COLLABMD_IMAGE=ghcr.io/andes90/collabmd:latest`. If you want to test a local image while developing instead:
 
 ```bash
@@ -341,9 +421,11 @@ To use an existing vault on your machine instead of `./data/vault`:
 HOST_VAULT_DIR=/absolute/path/to/vault docker compose up
 ```
 
+`HOST_VAULT_DIR` controls the host-side bind mount source. The app uses `COLLABMD_VAULT_DIR` for the in-container vault path and defaults that to `/data` in Docker.
+
 To bootstrap the compose-managed vault from a private repo, set the git env vars in `.env` and keep `HOST_VAULT_DIR` on a persistent host path. For file-based SSH auth, point `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` and `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` at mounted secret paths; for simpler setups, set `COLLABMD_GIT_SSH_PRIVATE_KEY_B64` instead.
 
-If you want the in-app Git commit action to work inside the container, also set `COLLABMD_GIT_USER_NAME` and `COLLABMD_GIT_USER_EMAIL` so CollabMD can configure the checkout identity automatically.
+If you want the in-app Git commit action to work inside the container without OIDC, also set `COLLABMD_GIT_USER_NAME` and `COLLABMD_GIT_USER_EMAIL` so CollabMD can configure the checkout identity automatically. With `AUTH_STRATEGY=oidc`, CollabMD uses the signed-in Google identity for each commit instead.
 
 To change the host port:
 
@@ -379,6 +461,8 @@ Health check: `GET /health`
 - The app is reachable only from localhost: pass `--host 0.0.0.0` or set `HOST=0.0.0.0` when you intend to expose it on your network
 - Port `1234` is already in use: pass `--port 3000` or set `PORT` to another free port
 - Tunnel did not start: install `cloudflared`, or pass `--no-tunnel` to stay local-only
+- `--auth oidc` fails on startup: set `PUBLIC_BASE_URL`, `AUTH_OIDC_CLIENT_ID`, and `AUTH_OIDC_CLIENT_SECRET`, and make sure the Google redirect URI matches `/api/auth/oidc/callback`
+- Google login loops back to the auth screen: verify the configured `PUBLIC_BASE_URL` matches the browser URL and that your reverse proxy forwards HTTPS correctly
 - `--local-plantuml` fails: make sure Docker is installed and running, or point `PLANTUML_SERVER_URL` at another PlantUML server
 - Private git bootstrap fails on startup: verify `COLLABMD_GIT_REPO_URL` plus either `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` or `COLLABMD_GIT_SSH_PRIVATE_KEY_B64`
 - WSL2 path issues: run CollabMD against a directory inside your Linux filesystem when possible rather than a mounted Windows path
@@ -485,16 +569,21 @@ scripts/
 | `AUTH_PASSWORD` | Shared password for `AUTH_STRATEGY=password` | generated per run |
 | `AUTH_SESSION_COOKIE_NAME` | Session cookie name | `collabmd_auth` |
 | `AUTH_SESSION_SECRET` | Cookie signing secret | generated per run |
+| `PUBLIC_BASE_URL` | Stable public app origin required for `AUTH_STRATEGY=oidc` | |
+| `AUTH_OIDC_CLIENT_ID` | Google OAuth client ID used for `AUTH_STRATEGY=oidc` | |
+| `AUTH_OIDC_CLIENT_SECRET` | Google OAuth client secret used for `AUTH_STRATEGY=oidc` | |
+| `AUTH_OIDC_ALLOWED_EMAILS` | Comma-separated exact email allowlist for `AUTH_STRATEGY=oidc` | |
+| `AUTH_OIDC_ALLOWED_DOMAINS` | Comma-separated email domain allowlist for `AUTH_STRATEGY=oidc` | |
 | `BASE_PATH` | URL path prefix for subpath deployments | |
 | `PLANTUML_SERVER_URL` | Upstream PlantUML server base URL used for server-side SVG rendering | `https://www.plantuml.com/plantuml` |
-| `COLLABMD_VAULT_DIR` | Vault directory path | current directory |
+| `COLLABMD_VAULT_DIR` | Vault directory path | CLI: current directory, server entrypoint: `data/vault`, Docker: `/data` |
 | `COLLABMD_GIT_ENABLED` | Enable or disable git integration in the UI and API | `true` |
 | `COLLABMD_GIT_REPO_URL` | Remote git repository used to bootstrap the vault checkout | |
 | `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` | SSH private key file path for remote git auth; preferred over base64 input | |
 | `COLLABMD_GIT_SSH_PRIVATE_KEY_B64` | Base64-encoded SSH private key used when no key file path is provided | |
 | `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` | Optional `known_hosts` file path for strict SSH host verification | |
-| `COLLABMD_GIT_USER_NAME` | Git author/committer name configured for in-app commits in git-backed deployments | |
-| `COLLABMD_GIT_USER_EMAIL` | Git author/committer email configured for in-app commits in git-backed deployments | |
+| `COLLABMD_GIT_USER_NAME` | Fallback git author/committer name for in-app commits when OIDC is not active | |
+| `COLLABMD_GIT_USER_EMAIL` | Fallback git author/committer email for in-app commits when OIDC is not active | |
 | `WS_BASE_PATH` | WebSocket base path | `/ws` |
 | `PUBLIC_WS_BASE_URL` | Public WebSocket URL override for reverse proxies | |
 | `HTTP_KEEP_ALIVE_TIMEOUT_MS` | Keep-alive timeout | `5000` |
@@ -523,7 +612,7 @@ cp .env.example .env
 - The filesystem is the source of truth; Yjs provides the collaboration layer.
 - When `COLLABMD_GIT_REPO_URL` is set, startup clones the configured repo into `COLLABMD_VAULT_DIR` on first boot and reuses an existing same-origin checkout on later starts.
 - If `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` is not set, SSH falls back to `StrictHostKeyChecking=accept-new`.
-- CollabMD assumes it is the only writer while a file is open; there is no live `fs.watch` reconciliation.
+- External filesystem edits are reconciled back into active rooms and the explorer. Ambiguous watcher bursts still fall back to batched workspace reconciliation.
 - `.obsidian`, `.git`, `.trash`, and `node_modules` directories are ignored.
 - Only `.md`, `.markdown`, and `.mdx` files are indexed.
 - PlantUML preview rendering is server-side and uses `PLANTUML_SERVER_URL`; point it at a self-hosted renderer if you do not want to use the public PlantUML service.

package/bin/collabmd.js

@@ -61,12 +61,14 @@ if (values.help) {
   process.exit(0);
 }
 
-const vaultPath = resolve(positionals[0] || '.');
 const port = parseInt(values.port ?? process.env.PORT ?? '1234', 10) || 1234;
 const host = values.host || process.env.HOST || '127.0.0.1';
 const enableTunnel = !values['no-tunnel'];
 const useLocalPlantUml = values['local-plantuml'];
 
+const { resolveCliVaultDir, loadConfig } = await import('../src/server/config/env.js');
+const vaultPath = resolveCliVaultDir(positionals);
+
 process.env.COLLABMD_VAULT_DIR = vaultPath;
 process.env.PORT = String(port);
 process.env.HOST = host;
@@ -101,7 +103,6 @@ if (useLocalPlantUml) {
 }
 
 const { createAppServer } = await import('../src/server/create-app-server.js');
-const { loadConfig } = await import('../src/server/config/env.js');
 const { prepareConfigForStartup } = await import('../src/server/startup/git-remote-bootstrap.js');
 
 const config = loadConfig({ vaultDir: vaultPath });

package/docker-compose.yml

@@ -6,7 +6,19 @@ services:
     environment:
       HOST: 0.0.0.0
       PORT: 1234
+      AUTH_STRATEGY: ${AUTH_STRATEGY:-none}
+      AUTH_PASSWORD: ${AUTH_PASSWORD:-}
+      AUTH_SESSION_COOKIE_NAME: ${AUTH_SESSION_COOKIE_NAME:-collabmd_auth}
+      AUTH_SESSION_SECRET: ${AUTH_SESSION_SECRET:-}
+      PUBLIC_BASE_URL: ${PUBLIC_BASE_URL:-http://localhost:1234}
+      AUTH_OIDC_CLIENT_ID: ${AUTH_OIDC_CLIENT_ID:-}
+      AUTH_OIDC_CLIENT_SECRET: ${AUTH_OIDC_CLIENT_SECRET:-}
+      AUTH_OIDC_ALLOWED_EMAILS: ${AUTH_OIDC_ALLOWED_EMAILS:-}
+      AUTH_OIDC_ALLOWED_DOMAINS: ${AUTH_OIDC_ALLOWED_DOMAINS:-}
+      BASE_PATH: ${BASE_PATH:-}
+      PUBLIC_WS_BASE_URL: ${PUBLIC_WS_BASE_URL:-}
       PLANTUML_SERVER_URL: http://plantuml:8080
+      COLLABMD_VAULT_DIR: ${COLLABMD_VAULT_DIR:-/data}
       COLLABMD_GIT_REPO_URL: ${COLLABMD_GIT_REPO_URL:-}
       COLLABMD_GIT_SSH_PRIVATE_KEY_FILE: ${COLLABMD_GIT_SSH_PRIVATE_KEY_FILE:-}
       COLLABMD_GIT_SSH_PRIVATE_KEY_B64: ${COLLABMD_GIT_SSH_PRIVATE_KEY_B64:-}
@@ -25,7 +37,7 @@ services:
     volumes:
       - type: bind
         source: ${HOST_VAULT_DIR:-./data/vault}
-        target: /data
+        target: ${COLLABMD_VAULT_DIR:-/data}
       # Optional: mount secret files when using file-based SSH auth.
       # - type: bind
       #   source: ${HOST_SSH_KEY_FILE}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "collabmd",
-  "version": "0.1.20",
+  "version": "0.1.23",
   "type": "module",
   "description": "Collaborative markdown vault — like Obsidian, but online. Serve any directory of markdown files for realtime collaborative editing.",
   "repository": {
@@ -71,6 +71,7 @@
     "lib0": "^0.2.0",
     "markdown-it": "^14.1.0",
     "mermaid": "^11.13.0",
+    "openid-client": "^6.8.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "ws": "^8.0.0",