fix(git-sync): address PR #119 review — close 403/404 space-existence leak + warnings/tests/arch

Security (must-fix):
- /git smart-HTTP gate: an authenticated NON-member of a git-sync space now gets
  404 (not 403), so the 403<->404 difference can no longer be used to brute-force
  which spaces exist / have git-sync enabled. 403 is reserved for a MEMBER who
  lacks the required role (existence already known). New gate input
  userIsSpaceMember; decision-table + service specs extended.

Config (must-fix):
- Remove the dead GIT_SYNC_SSH_KEY_PATH knob (getter + validation field + two
  .env.example lines) — it had zero consumers and advertised a nonexistent push
  capability.

Stability/docs (warnings):
- Wire the lost-lock AbortSignal into runReceivePack -> git http-backend so the
  receive-pack child is killed if the per-space lock lapses mid-write.
- Raise the divergent-`docmost` (invariant §5) push refusal from info -> warn and
  surface divergentDocmost in the run status (/status).
- Comment the stale read-after-debounced-collab-write updatedAt in
  importPageMarkdown (deferred §10 loop-guard must not trust it).
- Fix the Dockerfile comment: the loader uses require.resolve + dynamic import(),
  it deliberately does NOT require('@docmost/git-sync').
- Merge the two near-identical space toggle handlers into one parameterized
  handler; add the 2 missing en-US i18n keys for the auto-merge switch (ru-RU not
  maintained for these git-sync strings, mirrored).

Tests:
- isGitSyncHttpEnabled() default-branch (unset -> isGitSyncEnabled fallback).
- agentSourceFields 'git-sync' case (source stamped, chat key omitted).
- editor-ext name-level schema contract (vendored mirror superset of editor-ext
  node/mark types) + the new shared resolver + non-member 404 gate cases.

Architecture:
- Extract resolveRequestWorkspace shared by DomainMiddleware + GitHttpService
  (the two real self-hosted/cloud copies; McpService has no cloud branch).
- Document the in-process setInterval multi-replica limitation + BullMQ/fencing
  future direction (deferred, not implemented).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/server/src/integrations/git-sync/http/git-http-backend.service.ts

@@ -146,11 +146,18 @@ export class GitHttpBackendService {
    * child exited and its output was flushed), or after a 500 was sent on an
    * early failure. Never rejects — push ingestion relies on this resolving so
    * the lock-held cycle body can run afterwards.
+   *
+   * `signal` (optional) is the git-sync per-space lock's lost-lock abort signal.
+   * A receive-pack writes `main`'s working tree, so if the lock lapses mid-push
+   * (heartbeat CAS miss / Redis outage) the signal fires and we kill the child —
+   * preventing it from continuing to write the working tree while another replica
+   * may have taken over the lock and started a cycle (warning #3).
    */
   async run(
     parsed: GitHttpBackendRequest,
     rawReq: IncomingMessage,
     rawRes: ServerResponse,
+    signal?: AbortSignal,
   ): Promise<void> {
     const { vaultGitEnv } = await loadGitSync();
     const projectRoot = this.environmentService.getGitSyncDataDir();
@@ -162,12 +169,33 @@ export class GitHttpBackendService {
 
     return new Promise<void>((resolve) => {
       let settled = false;
+      // Set once the child exists so the abort handler can target it.
+      let onAbort: (() => void) | null = null;
       const done = () => {
         if (settled) return;
         settled = true;
+        // Detach the abort listener so a later lock loss does not fire into a
+        // request that already finished.
+        if (onAbort) {
+          signal?.removeEventListener('abort', onAbort);
+          onAbort = null;
+        }
         resolve();
       };
 
+      // Reject early if the lock was already lost before we even spawned: do not
+      // start writing the working tree after a possible lock takeover.
+      if (signal?.aborted) {
+        if (!rawRes.headersSent) this.send500(rawRes, 'lock-lost');
+        else
+          try {
+            rawRes.end();
+          } catch {
+            /* ignore */
+          }
+        return done();
+      }
+
       let child: ReturnType<typeof spawn>;
       try {
         child = spawn('git', ['http-backend'], { env });
@@ -176,6 +204,39 @@ export class GitHttpBackendService {
         return done();
       }
 
+      // Lost-lock abort: the per-space lock lapsed mid-request. Kill the child so
+      // a receive-pack stops writing `main`'s working tree before another replica
+      // (which may now hold the lock) starts a cycle. Mirrors the watchdog kill.
+      onAbort = () => {
+        this.logger.warn(
+          'git http-backend aborted (git-sync lock lost mid-request); killing child',
+        );
+        try {
+          child.kill('SIGTERM');
+          const sigkill = setTimeout(() => {
+            try {
+              child.kill('SIGKILL');
+            } catch {
+              /* ignore */
+            }
+          }, 2000);
+          sigkill.unref?.();
+        } catch {
+          /* ignore */
+        }
+        if (!headerParsed && !rawRes.headersSent) {
+          this.send500(rawRes, 'lock-lost');
+        } else {
+          try {
+            rawRes.end();
+          } catch {
+            /* ignore */
+          }
+        }
+        done();
+      };
+      signal?.addEventListener('abort', onAbort);
+
       // Watchdog: a client that opens git-receive-pack and stalls keeps the
       // child alive forever, so run() never resolves and (because this runs
       // inside withSpaceLock) the per-space lock is held + heartbeat-refreshed

apps/server/src/integrations/git-sync/http/git-http.helpers.spec.ts

@@ -111,6 +111,7 @@ describe('decideGitHttpGate', () => {
     gitHttpEnabled: true,
     spaceExists: true,
     spaceGitSyncEnabled: true,
+    userIsSpaceMember: true,
     permissionGranted: true,
   };
 
@@ -160,16 +161,43 @@ describe('decideGitHttpGate', () => {
     });
   });
 
-  it('403 when authenticated but lacking the required permission (reader on write)', () => {
+  it('403 when a MEMBER lacks the required permission (reader on write)', () => {
+    // A member of the space (existence already known to them) who lacks the role:
+    // 403 leaks nothing new.
     expect(
       decideGitHttpGate({
         ...base,
         serviceKind: 'write',
+        userIsSpaceMember: true,
         permissionGranted: false,
       }),
     ).toEqual({ kind: 'forbidden' });
   });
 
+  it('404 (NOT 403) when an authenticated NON-member hits a git-sync space', () => {
+    // SECURITY: a non-member must be indistinguishable from a missing/disabled
+    // space. If this returned 403, the 403↔404 difference would let any
+    // authenticated workspace user brute-force slugs to discover which spaces
+    // exist and which have git-sync enabled.
+    expect(
+      decideGitHttpGate({
+        ...base,
+        serviceKind: 'write',
+        userIsSpaceMember: false,
+        permissionGranted: false,
+      }),
+    ).toEqual({ kind: 'not-found' });
+    // Same for a read by a non-member.
+    expect(
+      decideGitHttpGate({
+        ...base,
+        serviceKind: 'read',
+        userIsSpaceMember: false,
+        permissionGranted: false,
+      }),
+    ).toEqual({ kind: 'not-found' });
+  });
+
   it('still 401 (not 404) for missing creds against a disabled space', () => {
     // Anonymous probe must always get 401 first, regardless of space state.
     expect(

apps/server/src/integrations/git-sync/http/git-http.helpers.ts

@@ -111,12 +111,24 @@ export type GitHttpGateDecision =
  *   2. credentials present but invalid             -> 401.
  *   3. unparseable git request shape               -> 400.
  *   4. git-sync globally disabled, or git-http disabled, or the space is missing
- *      / not git-sync-enabled                       -> 404 (never reveal existence).
- *   5. authenticated but lacking the required perm -> 403.
+ *      / not git-sync-enabled, OR the authenticated user is NOT a member of the
+ *      space (has no role at all)                   -> 404 (never reveal existence).
+ *   5. a MEMBER of the space who lacks the required perm (e.g. a reader trying to
+ *      push)                                        -> 403.
  *   6. otherwise                                    -> proceed.
  *
  * Note (4) is checked AFTER (1)/(2): an anonymous probe always gets 401 first;
- * an authenticated user hitting a hidden/disabled space gets 404 (not 403).
+ * an authenticated user hitting a hidden/disabled space — OR a space they are not
+ * a member of — gets 404 (not 403). Folding non-membership into the 404 branch is
+ * a SECURITY requirement: if a non-member got 403 here (as a "permission denied")
+ * while a non-existent / sync-disabled space got 404, the 403↔404 difference would
+ * let any authenticated workspace user brute-force slugs to discover which spaces
+ * exist and which have git-sync enabled — including spaces they cannot see. 403 is
+ * therefore reserved for the one case where existence is ALREADY known to the
+ * caller because they ARE a member (so it leaks nothing new): a member without the
+ * required role. `userIsSpaceMember` is the resolved "the user has SOME role in
+ * this space" boolean (false when SpaceAbilityFactory.createForUser throws
+ * NotFound / the user has no role).
  */
 export function decideGitHttpGate(input: {
   hasCredentials: boolean;
@@ -126,6 +138,8 @@ export function decideGitHttpGate(input: {
   gitHttpEnabled: boolean;
   spaceExists: boolean;
   spaceGitSyncEnabled: boolean;
+  /** The user has SOME role in the space (false = non-member -> 404, not 403). */
+  userIsSpaceMember: boolean;
   permissionGranted: boolean;
 }): GitHttpGateDecision {
   if (!input.hasCredentials) return { kind: 'unauthorized' };
@@ -136,7 +150,10 @@ export function decideGitHttpGate(input: {
     !input.gitSyncEnabled ||
     !input.gitHttpEnabled ||
     !input.spaceExists ||
-    !input.spaceGitSyncEnabled
+    !input.spaceGitSyncEnabled ||
+    // A non-member must be indistinguishable from a missing/disabled space: 404,
+    // never 403 (otherwise the 403↔404 split leaks space existence — see above).
+    !input.userIsSpaceMember
   ) {
     return { kind: 'not-found' };
   }

apps/server/src/integrations/git-sync/http/git-http.service.spec.ts

@@ -8,7 +8,11 @@
 // come from WorkspaceRepo. If the handler regressed to reading
 // `req.raw.workspaceId`, the happy-path fetch test below would fail (the repo
 // would not be consulted and the request would 401).
-import { Logger, UnauthorizedException } from '@nestjs/common';
+import {
+  Logger,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
 import {
   SpaceCaslAction,
   SpaceCaslSubject,
@@ -297,6 +301,30 @@ describe('GitHttpService.handle', () => {
     expect(built.backend.run).not.toHaveBeenCalled();
   });
 
+  it('an authenticated NON-member of a git-sync space -> 404, NOT 403 (no existence leak)', async () => {
+    // createForUser throws NotFound when the user holds no role in the space (a
+    // non-member). The gate must return 404 — the SAME response a missing /
+    // sync-disabled space gives — so a 403↔404 difference cannot be used to
+    // brute-force which spaces exist / have git-sync enabled (the security fix).
+    const built = build({ abilityCan: false });
+    built.abilityFactory.createForUser.mockRejectedValue(
+      new NotFoundException('Space permissions not found'),
+    );
+    const { reply, state } = fakeReply();
+    const req = fakeRequest({
+      url: '/git/secret-space.git/info/refs?service=git-upload-pack',
+      method: 'GET',
+      authorization: basic('dev@example.com', 'pw'),
+    });
+
+    await built.service.handle(req, reply);
+
+    expect(built.abilityFactory.createForUser).toHaveBeenCalledTimes(1);
+    expect(state.statusCode).toBe(404);
+    expect(built.backend.run).not.toHaveBeenCalled();
+    expect(built.orchestrator.ingestExternalPush).not.toHaveBeenCalled();
+  });
+
   it('a space that is not git-sync-enabled -> 404 (existence never revealed)', async () => {
     const built = build({
       space: { id: 'space-1', settings: { gitSync: { enabled: false } } },

apps/server/src/integrations/git-sync/http/git-http.service.ts

@@ -10,6 +10,7 @@ import { SpaceRepo } from '@docmost/db/repos/space/space.repo';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 import { User } from '@docmost/db/types/entity.types';
 import { parseBasicAuth } from '../../mcp/mcp-auth.helpers';
+import { resolveRequestWorkspace } from '../../../common/helpers/resolve-request-workspace';
 import { EnvironmentService } from '../../environment/environment.service';
 import { VaultRegistryService } from '../services/vault-registry.service';
 import {
@@ -57,7 +58,8 @@ export class GitHttpService {
    * Resolve the workspace for a /git request the SAME way DomainMiddleware does,
    * because Nest middleware does NOT run for this raw root-mounted route (it is
    * registered under the global '/api' router), so `req.raw.workspaceId` is never
-   * populated here. We replicate DomainMiddleware / McpService:
+   * populated here. Delegates to the shared `resolveRequestWorkspace` helper (the
+   * SAME self-hosted/cloud branch DomainMiddleware uses) and returns just the id:
    *   - self-hosted (single workspace) -> workspaceRepo.findFirst();
    *   - cloud (multi-tenant)           -> resolve by the host-header subdomain.
    * Returns null when no workspace resolves; the gate then 404s (after the
@@ -65,17 +67,14 @@ export class GitHttpService {
    */
   private async resolveWorkspaceId(req: FastifyRequest): Promise<string | null> {
     try {
-      if (this.environmentService.isSelfHosted()) {
-        const workspace = await this.workspaceRepo.findFirst();
-        return workspace?.id ?? null;
-      }
-      if (this.environmentService.isCloud()) {
-        const host = this.headerValue(req.headers['host']);
-        const subdomain = host ? host.split('.')[0] : '';
-        if (!subdomain) return null;
-        const workspace = await this.workspaceRepo.findByHostname(subdomain);
-        return workspace?.id ?? null;
-      }
+      // Same self-hosted/cloud resolution DomainMiddleware uses — shared so the
+      // branch cannot drift between the two call sites.
+      const workspace = await resolveRequestWorkspace(
+        this.environmentService,
+        this.workspaceRepo,
+        this.headerValue(req.headers['host']),
+      );
+      return workspace?.id ?? null;
     } catch (err) {
       // A DB error resolving the workspace must not leak details; treat as
       // unresolvable (the gate will 404, unless creds are missing -> 401 first).
@@ -150,6 +149,12 @@ export class GitHttpService {
     let spaceExists = false;
     let spaceGitSyncEnabled = false;
     let spaceId: string | undefined;
+    // The user has SOME role in the space. SECURITY: a non-member must get the
+    // SAME 404 a missing/disabled space gets — never a 403 — or the 403↔404 split
+    // would let any authenticated user brute-force slugs to learn which spaces
+    // exist / have sync enabled (the leak this gate's contract forbids). 403 is
+    // reserved for a MEMBER who lacks the required role (existence already known).
+    let userIsSpaceMember = false;
     let permissionGranted = false;
     if (credentialsValid && user && workspaceId && parsedPath && serviceKind) {
       const space = await this.spaceRepo.findById(
@@ -170,6 +175,11 @@ export class GitHttpService {
               user,
               space.id,
             );
+            // createForUser RESOLVED -> the user holds a role in this space (it
+            // throws NotFound for a non-member). Record membership BEFORE the
+            // permission check: a member lacking the role -> 403; a non-member ->
+            // 404 (handled by the gate via userIsSpaceMember=false below).
+            userIsSpaceMember = true;
             const action =
               serviceKind === 'write'
                 ? SpaceCaslAction.Manage
@@ -177,7 +187,12 @@ export class GitHttpService {
             permissionGranted = ability.can(action, SpaceCaslSubject.Page);
           } catch {
             // createForUser throws NotFoundException when the user has no role in
-            // the space — that is simply "no permission" here.
+            // the space (a non-member). Leave userIsSpaceMember=false so the gate
+            // returns 404, NOT 403 — a non-member must not be able to tell this
+            // space apart from a non-existent one. (Any other error also falls
+            // here and is treated as non-member -> 404, the safe default that
+            // never reveals existence.)
+            userIsSpaceMember = false;
             permissionGranted = false;
           }
         }
@@ -193,6 +208,7 @@ export class GitHttpService {
       gitHttpEnabled: this.environmentService.isGitSyncHttpEnabled(),
       spaceExists,
       spaceGitSyncEnabled,
+      userIsSpaceMember,
       permissionGranted,
     });
 
@@ -268,8 +284,12 @@ export class GitHttpService {
 
     // Push: run the receive-pack under the space lock, then a Docmost cycle.
     try {
-      await this.orchestrator.ingestExternalPush(spaceId, workspaceId, () =>
-        this.backend.run(backendRequest, rawReq, rawRes),
+      await this.orchestrator.ingestExternalPush(
+        spaceId,
+        workspaceId,
+        // The lock's lost-lock signal is threaded into the backend so the
+        // receive-pack child is killed if the lock lapses mid-write (warning #3).
+        (signal) => this.backend.run(backendRequest, rawReq, rawRes, signal),
       );
     } catch (err) {
       if (err instanceof GitSyncLockHeldError) {

apps/server/src/integrations/git-sync/services/git-sync.orchestrator.ts

@@ -48,6 +48,13 @@ export interface GitSyncRunStatus {
     | 'merge-in-progress';
   pull?: { written: number; deleted: number; conflict: boolean };
   push?: { mode: string; failures: number };
+  /**
+   * True when the push REFUSED to fast-forward a divergent `docmost` mirror
+   * (invariant §5 broken — `docmost` no longer mirrors what Docmost contains).
+   * Surfaced here (not just logged) so /status can report it. No data is lost,
+   * but it signals an operator-visible drift that needs attention.
+   */
+  divergentDocmost?: boolean;
   error?: string;
 }
 
@@ -200,11 +207,18 @@ export class GitSyncOrchestrator implements OnModuleInit, OnModuleDestroy {
    * request behind a potentially long cycle). The receive-pack is NOT run when
    * the lock is held — we never write to the working tree concurrently with a
    * cycle.
+   *
+   * `runReceivePack` receives the per-space lock's lost-lock `AbortSignal`: a
+   * receive-pack writes `main`'s working tree (receive.denyCurrentBranch=
+   * updateInstead), so if the lock is lost mid-push (a long Redis outage drops the
+   * heartbeat CAS) the signal fires and the receive-pack's `git http-backend`
+   * child is killed — closing the window where another replica could grab the lock
+   * and start a cycle while this child is still writing the working tree.
    */
   async ingestExternalPush(
     spaceId: string,
     workspaceId: string,
-    runReceivePack: () => Promise<void>,
+    runReceivePack: (signal: AbortSignal) => Promise<void>,
   ): Promise<void> {
     if (!this.environmentService.isGitSyncEnabled()) {
       // The HTTP gate already checks this, but be defensive: never run a cycle
@@ -215,7 +229,9 @@ export class GitSyncOrchestrator implements OnModuleInit, OnModuleDestroy {
 
     const result = await this.spaceLock.withSpaceLock(spaceId, async (signal) => {
       // 1) Stream the receive-pack to the client (durable commits land on main).
-      await runReceivePack();
+      // Pass the lost-lock signal so the receive-pack child is killed if the lock
+      // lapses mid-write (no concurrent working-tree writer across replicas).
+      await runReceivePack(signal);
 
       // 2) Reconcile the new commits into Docmost. A service user is required to
       // attribute the writes; without one we cannot run the cycle — the commits
@@ -292,6 +308,18 @@ export class GitSyncOrchestrator implements OnModuleInit, OnModuleDestroy {
       log: (line: string) => this.logger.log(`git-sync[${spaceId}] ${line}`),
     });
 
+    // §5 invariant breach: the push refused to fast-forward a divergent `docmost`
+    // mirror. No data is lost (the refusal is the safety), but the mirror no
+    // longer reflects Docmost and the next push will keep refusing until an
+    // operator reconciles it — so escalate from the engine's info `log` to a
+    // WARN with the spaceId, and surface the flag in the returned status (/status).
+    if (result.divergentDocmost) {
+      this.logger.warn(
+        `git-sync[${spaceId}] push refused to fast-forward a DIVERGENT 'docmost' ` +
+          `mirror (invariant §5 broken); manual reconciliation required`,
+      );
+    }
+
     return { spaceId, ...result };
   }
 
@@ -309,6 +337,18 @@ export class GitSyncOrchestrator implements OnModuleInit, OnModuleDestroy {
    * ScheduleModule: forRoot() is registered ONCE globally by TelemetryModule;
    * GitSyncModule imports the plain ScheduleModule so SchedulerRegistry is
    * injectable without a duplicate forRoot.
+   *
+   * KNOWN MULTI-REPLICA LIMITATION (deferred — do not silently lose this):
+   * This is an IN-PROCESS `setInterval` running on EVERY replica. Cross-replica
+   * single-writer safety currently rests on the per-space Redis lock
+   * (SpaceLockService) plus best-effort abort-on-failed-heartbeat — NOT on true
+   * fencing. Under an adversarial schedule (lock TTL lapse during a GC/IO pause)
+   * two replicas could still briefly believe they hold a space's lock. The
+   * intended future direction is to move this orchestration to a BullMQ queue
+   * (one durable, deduplicated job per space instead of N independent interval
+   * timers) and add FENCING TOKENS so a stale writer's writes are rejected by the
+   * store. The author deferred fencing tokens; this comment is the breadcrumb so
+   * the gap is tracked rather than forgotten. See SpaceLockService.liveLocks.
    */
   onModuleInit(): void {
     if (!this.environmentService.isGitSyncEnabled()) return;

apps/server/src/integrations/git-sync/services/gitmost-datasource.service.ts

@@ -185,6 +185,13 @@ export class GitmostDataSourceService {
 
     await this.writeBody(pageId, doc, ctx.userId, baseDoc);
 
+    // CAVEAT: writeBody merges through collab, whose persistence is DEBOUNCED, so
+    // this `updatedAt` read can be STALE — it may reflect the row BEFORE the
+    // debounced flush lands. Currently harmless: the only consumer is the deferred
+    // §10 loop-guard, which is not yet wired. When that loop-guard is implemented
+    // it MUST NOT trust this timestamp as a read-after-write of the body change
+    // (it would misfire on the pre-flush value); it needs a post-flush read (or to
+    // key off the collab flush completion) instead.
     const page = await this.pageRepo.findById(pageId);
     return {
       updatedAt: page ? new Date(page.updatedAt).toISOString() : undefined,