@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/mirror-routes.ts

@@ -24,29 +24,42 @@
  * hand + restarting the vault.
  */
 
+import { existsSync } from "node:fs";
+
 import {
   defaultMirrorConfig,
+  mirrorConfigPath,
+  readMirrorConfigForVault,
   validateExternalPath,
   validateMirrorConfigShape,
   type MirrorConfig,
 } from "./mirror-config.ts";
 import type { MirrorManager } from "./mirror-manager.ts";
+import { getMirrorManager } from "./mirror-registry.ts";
 import {
   applyToGitRemote,
   deleteCredentials,
   emptyCredentials,
+  githubAuthedRemoteUrl,
   readCredentials,
+  redactRemoteUrl,
   sanitizeCredentials,
   unsetGitRemote,
   writeCredentials,
   type MirrorCredentials,
 } from "./mirror-credentials.ts";
 import {
+  GITHUB_APP_SLUG_DEFAULT,
+  GITHUB_CLIENT_ID_DEFAULT,
+  GitHubApiError,
   createRepo,
   fetchUser,
+  getGithubAppSlug,
   getGithubClientId,
+  installUrlForSlug,
   isPlaceholderClientId,
-  listRepos,
+  listInstallationRepos,
+  listInstallations,
   pollForToken,
   requestDeviceCode,
   type FetchLike,
@@ -62,6 +75,7 @@ import {
   type ImportResult,
 } from "./mirror-import.ts";
 import { redactToken } from "./export-watch.ts";
+import { GitNotInstalledError, ensureGitAvailable } from "./git-preflight.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { assetsDir } from "./routes.ts";
 
@@ -120,6 +134,10 @@ export function handleMirrorGet(manager: MirrorManager): Response {
 export async function handleMirrorPut(
   req: Request,
   manager: MirrorManager,
+  // Test seam for the external-path git-presence preflight (default
+  // `Bun.which` inside `validateExternalPath`). Inject a fn returning `null`
+  // to exercise the git_not_installed 503 path without uninstalling git.
+  whichOverride?: (cmd: string) => string | null,
 ): Promise<Response> {
   let body: unknown;
   try {
@@ -154,7 +172,25 @@ export async function handleMirrorPut(
   // to *do* something with an external path. Disabling the mirror by-
   // flipping enabled to false shouldn't fail because the path went away.
   if (config.enabled && config.location === "external" && config.external_path) {
-    const pathCheck = await validateExternalPath(config.external_path);
+    let pathCheck;
+    try {
+      pathCheck = await validateExternalPath(config.external_path, whichOverride);
+    } catch (err) {
+      if (err instanceof GitNotInstalledError) {
+        // 503 git_not_installed — consistent with the import route. The
+        // server can't validate (or later sync) an external git mirror
+        // without git installed; the message tells the operator how to fix.
+        return Response.json(
+          {
+            error: "git not installed",
+            error_type: "git_not_installed",
+            message: err.message,
+          },
+          { status: 503 },
+        );
+      }
+      throw err;
+    }
     if (!pathCheck.ok) {
       return Response.json(
         {
@@ -271,9 +307,10 @@ export function buildMirrorGetResponse(
 }
 
 // ---------------------------------------------------------------------------
-// Credential routes — Cut 3 of the UI-configurable push credentials work.
+// Credential routes — Cut 3 of the UI-configurable push credentials work,
+// reshaped by the GitHub-App installation semantics (vault#480).
 //
-// Six surfaces, all `vault:<name>:admin`-gated upstream:
+// Surfaces, all `vault:<name>:admin`-gated upstream:
 //
 //   POST   /.parachute/mirror/auth/github/device-code  — start GitHub Device
 //          Flow; returns { polling_id, user_code, verification_uri, expires_in,
@@ -281,19 +318,29 @@ export function buildMirrorGetResponse(
 //          by polling_id (a short opaque token) so the device_code doesn't
 //          land on the wire twice.
 //   POST   /.parachute/mirror/auth/github/poll         — poll for token, body
-//          { polling_id }. On `granted`: fetch user, save credentials, set
-//          remote URL, return { state: "granted", user }. Other states
-//          surface verbatim.
+//          { polling_id }. On `granted`: fetch user, save credentials, enable
+//          history for a never-configured vault (vault#483), return
+//          { state: "granted", user, history_enabled }. Other states surface
+//          verbatim.
 //   POST   /.parachute/mirror/auth/pat                 — validate + store a
 //          PAT (token + remote_url + label). Validates via `git ls-remote`.
+//          Same history-on-link behavior as the poll grant (vault#483).
 //   GET    /.parachute/mirror/auth                     — current connection
-//          status (NO secrets). Returns the sanitized public shape.
+//          status (NO secrets, NO network). Returns the sanitized public shape.
 //   DELETE /.parachute/mirror/auth                     — wipe credentials,
 //          unset embedded-credential remote URL.
-//   GET    /.parachute/mirror/auth/github/repos        — list operator's
-//          GitHub repos via stored OAuth token.
+//   GET    /.parachute/mirror/auth/github/installations — install state
+//          (vault#480): which app, whether it's installed anywhere, the
+//          install link, and the per-account installations. The one
+//          explicitly-network status endpoint — `GET /auth` stays offline.
+//   GET    /.parachute/mirror/auth/github/repos        — list the repos the
+//          operator's app INSTALLATIONS grant (user + org accounts), via the
+//          stored OAuth token. Returns { installed: false, install_url,
+//          repos: [] } when the app isn't installed anywhere yet.
 //   POST   /.parachute/mirror/auth/github/create-repo  — create a new private
-//          repo on behalf of the operator.
+//          repo on behalf of the operator. 403s with the shared Contents-only
+//          app (mapped to error_type "app_lacks_admin_permission" + the
+//          guided-manual path); works for BYO apps with Administration:write.
 //
 // ---------------------------------------------------------------------------
 
@@ -336,16 +383,18 @@ export function _resetDeviceFlowSessionsForTest(): void {
 }
 
 /**
- * Errors out cleanly when the operator hasn't replaced the placeholder
- * client_id. The user-facing message explains the next step.
+ * Errors out cleanly when PARACHUTE_GITHUB_CLIENT_ID is set to a
+ * placeholder-shaped value. A real default ships in the build (the shared
+ * Parachute GitHub App — see github-device-flow.ts), so this is only
+ * reachable via a misconfigured override.
  */
 function placeholderClientIdResponse(): Response {
   return Response.json(
     {
-      error: "GitHub OAuth not configured",
+      error: "GitHub auth misconfigured",
       error_type: "placeholder_client_id",
       message:
-        "This Parachute Vault build doesn't have a registered GitHub OAuth App client_id. Set the PARACHUTE_GITHUB_CLIENT_ID environment variable (see src/github-device-flow.ts for setup steps) or use the Personal Access Token path instead.",
+        "PARACHUTE_GITHUB_CLIENT_ID is set to a placeholder value. Unset it to use the built-in shared Parachute GitHub App, set it to your own app's client_id, or use the Personal Access Token path instead.",
     },
     { status: 503 },
   );
@@ -488,12 +537,12 @@ export async function handleAuthGithubPoll(
     }
     // Clean up the polling session.
     deviceFlowSessions.delete(body.polling_id);
-    // Apply to git remote if mirror is currently running on an external
-    // path that's a git repo. The credentials become active on next push;
-    // the operator doesn't have to restart vault. We don't have an owner/
-    // repo yet (the operator hasn't picked a repo) — that wiring happens
-    // in the create-repo or repo-picked path. So at this point we just
-    // store credentials; the URL gets set when the operator picks a repo.
+    // vault#483: linking implies backup intent — enable history for a
+    // never-configured vault (consent-respecting; see the helper). No
+    // remote URL is set here — we don't have an owner/repo yet (the
+    // operator hasn't picked a repo); that wiring happens in select-repo,
+    // which is also where auto_push flips on (Cut 3).
+    const history_enabled = await maybeEnableHistoryOnLink(manager);
     return Response.json(
       {
         state: "granted",
@@ -503,6 +552,7 @@ export async function handleAuthGithubPoll(
           name: user.name,
           avatar_url: user.avatar_url,
         },
+        history_enabled,
       },
       { headers: { "Access-Control-Allow-Origin": "*" } },
     );
@@ -536,6 +586,14 @@ export async function handleAuthGithubPoll(
 export async function handleAuthPat(
   req: Request,
   manager: MirrorManager,
+  // Test seam for the `git ls-remote` validation probe (default
+  // `probeGitLsRemote`, which spawns real git against the supplied remote).
+  // Inject a fn returning `{ok: true}` to exercise the post-validation save
+  // path (credential persist + history-on-link, vault#483) hermetically.
+  probeOverride?: (
+    url: string,
+    timeoutMs: number,
+  ) => Promise<{ ok: boolean; error?: string }>,
 ): Promise<Response> {
   let body: { token?: unknown; remote_url?: unknown; label?: unknown };
   try {
@@ -597,6 +655,26 @@ export async function handleAuthPat(
     );
   }
 
+  // Preflight: the validation probe (`git ls-remote`) and every later push
+  // shell `git`. On a git-less server, surface the friendly, actionable
+  // 503 instead of letting the probe's `Bun.spawn` throw a raw
+  // "Executable not found in $PATH: \"git\"".
+  try {
+    ensureGitAvailable();
+  } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      return Response.json(
+        {
+          error: "git not installed",
+          error_type: "git_not_installed",
+          message: err.message,
+        },
+        { status: 503 },
+      );
+    }
+    throw err;
+  }
+
   // Validate via `git ls-remote <embedded-auth-url>` — uses the same
   // x-access-token shape we'd embed at push time so the probe exercises
   // the actual auth path. If the operator pasted a URL that already has
@@ -610,7 +688,7 @@ export async function handleAuthPat(
           u.password = token;
           return u.toString();
         })();
-  const probeResult = await probeGitLsRemote(authedUrl, 10_000);
+  const probeResult = await (probeOverride ?? probeGitLsRemote)(authedUrl, 10_000);
   if (!probeResult.ok) {
     return Response.json(
       {
@@ -647,6 +725,15 @@ export async function handleAuthPat(
     );
   }
 
+  // vault#483: linking implies backup intent — enable history for a
+  // never-configured vault BEFORE the Cut-3/Cut-6 steps below, so a fresh
+  // vault gets the whole intended flow in one save: history on (the reload's
+  // start() applies the just-written PAT remote to `origin`), then Cut 3
+  // sees an enabled mirror and flips auto_push on, then Cut 6 fires the
+  // initial push. An explicitly-disabled mirror short-circuits all of it
+  // (history stays off → maybeEnableAutoPush no-ops on disabled).
+  const history_enabled = await maybeEnableHistoryOnLink(manager);
+
   // Push the new URL onto the mirror's git remote if it's currently
   // resolved + on disk. Non-fatal if the mirror isn't running.
   await applyCredentialsToMirror(manager);
@@ -666,6 +753,7 @@ export async function handleAuthPat(
   return Response.json(
     {
       ...sanitizeCredentials(next),
+      history_enabled,
       auto_push_was_already_enabled: autoPushChange.was_already_enabled,
       auto_push_enabled: autoPushChange.auto_push_now_enabled,
       initial_push: initialPush,
@@ -764,8 +852,102 @@ export async function handleAuthDelete(manager: MirrorManager): Promise<Response
 }
 
 /**
- * `GET /.parachute/mirror/auth/github/repos` — list operator's repos via
- * the stored OAuth token. Requires `active_method === "github_oauth"`.
+ * `GET /.parachute/mirror/auth/github/installations` — install state for
+ * the connect flow (vault#480). Answers three UI questions in one call:
+ * which app is in play (shared default vs BYO), is it installed ANYWHERE
+ * for this operator, and which accounts (user/orgs) carry installations.
+ *
+ * Deliberately a separate, explicitly-network endpoint: `GET /auth` stays
+ * a pure local read of the stored credential. The SPA calls this when it
+ * renders the connect flow / repo picker, not on every status poll.
+ *
+ * Response:
+ *   200 {
+ *     app: { client_id, slug, is_shared_default },
+ *     installed: boolean,            // installations.length > 0
+ *     install_url: string,           // github.com/apps/<slug>/installations/new
+ *     installations: [{ id, account_login, account_type, repository_selection }]
+ *   }
+ *   400 { error, error_type: "github_not_connected", message } — no stored
+ *       github_oauth credential; the device flow hasn't been run (or a PAT
+ *       is active instead — install state is a GitHub-App concept). 400,
+ *       not 401, matching the sibling repos handler: a 401 here would trip
+ *       the SPA's authedFetch token-refresh machinery and clear a
+ *       perfectly valid cached admin token over a non-auth condition.
+ *   502 { error, message } — GitHub unreachable / API error.
+ */
+export async function handleAuthGithubInstallations(
+  manager: MirrorManager,
+  fetchImpl?: FetchLike,
+): Promise<Response> {
+  const creds = readCredentials(manager.getVaultName());
+  if (!creds || creds.active_method !== "github_oauth" || !creds.github_oauth) {
+    return Response.json(
+      {
+        error: "Not connected to GitHub",
+        error_type: "github_not_connected",
+        message:
+          "No GitHub sign-in is stored for this vault. Run the device flow first (POST /.parachute/mirror/auth/github/device-code).",
+      },
+      { status: 400 },
+    );
+  }
+  const clientId = getGithubClientId();
+  const slug = getGithubAppSlug();
+  let installations;
+  try {
+    installations = await listInstallations(creds.github_oauth.access_token, fetchImpl);
+  } catch (err) {
+    return Response.json(
+      {
+        error: "Installation check failed",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 502 },
+    );
+  }
+  return Response.json(
+    {
+      app: {
+        client_id: clientId,
+        slug,
+        is_shared_default:
+          clientId === GITHUB_CLIENT_ID_DEFAULT && slug === GITHUB_APP_SLUG_DEFAULT,
+      },
+      installed: installations.length > 0,
+      install_url: installUrlForSlug(slug),
+      installations: installations.map((i) => ({
+        id: i.id,
+        account_login: i.account.login,
+        account_type: i.account.type,
+        repository_selection: i.repository_selection,
+      })),
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
+/**
+ * `GET /.parachute/mirror/auth/github/repos` — list the repos the
+ * operator's app installations grant, via the stored OAuth token. Requires
+ * `active_method === "github_oauth"`.
+ *
+ * Source (vault#480): `GET /user/installations` → per-installation
+ * `GET /user/installations/{id}/repositories`, unioned. This replaces the
+ * old `GET /user/repos?type=owner` source, which (a) excluded org-owned
+ * repos by construction and (b) showed all-public-repos when the app wasn't
+ * installed at all (every GitHub App reads public repos) — Aaron walked
+ * into exactly that "looks connected, shows the wrong repos" state live.
+ *
+ * Response:
+ *   200 installed:    { installed: true, repos: [{ ...GitHubRepoInfo,
+ *                       account_login, installation_id }], truncated }
+ *   200 not installed: { installed: false, install_url, repos: [],
+ *                       truncated: false } — machine-readable
+ *                       authorized-but-not-installed state; the UI shows
+ *                       the guided-install step, no string-matching needed.
+ *   400 { error, message } — no github_oauth credential stored.
+ *   502 { error, message } — GitHub unreachable / API error.
  */
 export async function handleAuthGithubRepos(
   manager: MirrorManager,
@@ -781,9 +963,58 @@ export async function handleAuthGithubRepos(
       { status: 400 },
     );
   }
-  let result;
+  const token = creds.github_oauth.access_token;
+  let installations;
+  try {
+    installations = await listInstallations(token, fetchImpl);
+  } catch (err) {
+    return Response.json(
+      {
+        error: "Repo list failed",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 502 },
+    );
+  }
+
+  if (installations.length === 0) {
+    // Authorized but not installed — the device-flow grant alone reaches no
+    // repos. Distinct, machine-readable state (NOT an empty repo list that
+    // looks like "you have no repos").
+    return Response.json(
+      {
+        installed: false,
+        install_url: installUrlForSlug(getGithubAppSlug()),
+        repos: [],
+        truncated: false,
+      },
+      { headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+
+  const repos: Array<GitHubRepoInfo & { account_login: string; installation_id: number }> = [];
+  let truncated = false;
   try {
-    result = await listRepos(creds.github_oauth.access_token, {}, fetchImpl);
+    for (const installation of installations) {
+      const result = await listInstallationRepos(token, installation.id, {}, fetchImpl);
+      // `GET /user/installations/{id}/repositories` takes no `sort` param
+      // (unlike the old `GET /user/repos?sort=updated` picker source), so
+      // order within each account group ourselves: most-recently-updated
+      // first, so the repo the operator probably wants sits near the top.
+      // ISO-8601 timestamps compare lexicographically. Per-group (not
+      // across the union) so the SPA's account grouping stays contiguous.
+      const sorted = [...result.repos].sort((a, b) =>
+        b.updated_at.localeCompare(a.updated_at),
+      );
+      for (const repo of sorted) {
+        repos.push({
+          ...repo,
+          account_login: installation.account.login,
+          installation_id: installation.id,
+        });
+      }
+      if (result.truncated) truncated = true;
+    }
   } catch (err) {
     return Response.json(
       {
@@ -794,7 +1025,7 @@ export async function handleAuthGithubRepos(
     );
   }
   return Response.json(
-    { repos: result.repos, truncated: result.truncated },
+    { installed: true, repos, truncated },
     { headers: { "Access-Control-Allow-Origin": "*" } },
   );
 }
@@ -803,6 +1034,15 @@ export async function handleAuthGithubRepos(
  * `POST /.parachute/mirror/auth/github/create-repo` — create a new repo on
  * the operator's account, return the new RepoInfo. The SPA flows straight
  * from this into the "repo selected" state.
+ *
+ * With the shared Parachute app this 403s by design (vault#480):
+ * `POST /user/repos` needs Administration:write; the shared app is frozen
+ * at Contents-only. The 403 maps to error_type "app_lacks_admin_permission"
+ * with the guided-manual path (create at github.com/new → add it to the
+ * installation → refresh the picker). The endpoint stays functional for
+ * BYO-app operators whose app grants Administration:write — and per the
+ * install docs, app-created repos auto-join the installation, so their
+ * create→push flow works end-to-end.
  */
 export async function handleAuthGithubCreateRepo(
   req: Request,
@@ -845,6 +1085,20 @@ export async function handleAuthGithubCreateRepo(
       fetchImpl,
     );
   } catch (err) {
+    if (err instanceof GitHubApiError && err.status === 403) {
+      // Expected with the shared Contents-only app: POST /user/repos needs
+      // Administration:write. Actionable, machine-readable mapping — the UI
+      // renders the guided-manual checklist off error_type, not a string.
+      return Response.json(
+        {
+          error: "Create not permitted for this GitHub App",
+          error_type: "app_lacks_admin_permission",
+          message:
+            "The Parachute GitHub App can't create repositories (it only has Contents permission — creating repos needs Administration). Create it manually instead: 1) create a private, uninitialized repo at github.com/new, 2) add it to the app installation (GitHub → Settings → Applications → Configure), 3) refresh the repo list here and pick it.",
+        },
+        { status: 403 },
+      );
+    }
     return Response.json(
       { error: "Create failed", message: (err as Error).message ?? String(err) },
       { status: 502 },
@@ -900,6 +1154,18 @@ export async function handleAuthGithubSelectRepo(
     name,
   );
 
+  // vault#483: linking implies backup intent — the choose-repo re-entry can
+  // be the FIRST credential-linked action for this vault (a credential saved
+  // before history-on-link existed, on a never-configured vault: the #483
+  // "linked but silently inert" state). Run history-on-link here too, BEFORE
+  // the Cut-3/Cut-6 steps below and mirroring handleAuthPat's ordering:
+  // history on (the reload's start() resolves mirror_path so the remote
+  // write below actually lands), then Cut 3 sees an enabled mirror and flips
+  // auto_push, then Cut 6 fires the initial push. An explicitly-disabled
+  // mirror short-circuits all of it (history stays off → maybeEnableAutoPush
+  // no-ops on disabled).
+  const history_enabled = await maybeEnableHistoryOnLink(manager);
+
   // Apply to the mirror dir if running. If the mirror isn't running (no
   // mirror_path), we still consider this a success — the credentials are
   // stored, and the URL will get applied next time the mirror starts.
@@ -933,6 +1199,7 @@ export async function handleAuthGithubSelectRepo(
       // Echo the redacted form back so the SPA can show "pushing to <repo>".
       // No raw token in the response.
       remote: `https://github.com/${owner}/${name}.git`,
+      history_enabled,
       auto_push_was_already_enabled: autoPushChange.was_already_enabled,
       auto_push_enabled: autoPushChange.auto_push_now_enabled,
       initial_push: initialPush,
@@ -941,6 +1208,73 @@ export async function handleAuthGithubSelectRepo(
   );
 }
 
+/**
+ * vault#483 fix 1 — linking implies backup intent. Outcome flag for the
+ * credential-save responses:
+ *   - `true` — history (the mirror) is on: either this link just enabled it
+ *     (never-configured vault) or it was already enabled.
+ *   - `"left_disabled"` — a mirror config exists with `enabled: false`; we
+ *     refuse to silently flip an explicit operator choice. The UI should
+ *     offer the one-click "Turn on history now?" enable.
+ *   - `false` — we tried to enable history but the mirror didn't come up
+ *     (e.g. git missing). Config intent is persisted (PUT semantics); the
+ *     mirror status carries the actionable error.
+ */
+export type HistoryOnLink = true | false | "left_disabled";
+
+/**
+ * When a GitHub credential lands (device-flow grant or PAT save), turn
+ * history on for a vault that has NEVER had a mirror configured — nobody
+ * links GitHub to a vault for any reason other than backing it up. Aaron hit
+ * this live (vault#483): pre-#440 vaults have no mirror-config file, so
+ * linking stored a credential and then... nothing, with the only path out
+ * buried in advanced settings.
+ *
+ * Consent-respecting by design:
+ *   - **No config file** (never configured) → enable the internal mirror
+ *     with the standard defaults (enabled, internal, events, auto_commit on,
+ *     auto_push off — the same shape #440 gives new vaults). Writes through
+ *     `manager.reload()` — the exact path the PUT handler uses — so persist +
+ *     lifecycle-start stay one code path.
+ *   - **Config file exists with enabled:false** → explicit operator choice;
+ *     do NOT flip it. Return `"left_disabled"` so the UI can offer one-click
+ *     enable instead.
+ *   - **Config file exists with enabled:true** → nothing to do.
+ *
+ * The file-existence check (not just the parsed read) is the load-bearing
+ * distinction: an existing-but-malformed file parses to `undefined`, same as
+ * absent — but it still represents operator-touched state, so we treat it as
+ * "exists, not known-enabled" and leave it alone.
+ */
+async function maybeEnableHistoryOnLink(
+  manager: MirrorManager,
+): Promise<HistoryOnLink> {
+  const vaultName = manager.getVaultName();
+  if (!existsSync(mirrorConfigPath(vaultName))) {
+    try {
+      const status = await manager.reload({
+        ...defaultMirrorConfig(),
+        enabled: true,
+      });
+      if (!status.enabled) {
+        console.warn(
+          `[mirror-auth] history-on-link: enabled the mirror config for vault "${vaultName}" but it didn't start: ${status.last_error ?? "unknown error"}`,
+        );
+        return false;
+      }
+      return true;
+    } catch (err) {
+      console.warn(
+        `[mirror-auth] history-on-link: could not enable the mirror for vault "${vaultName}" (non-fatal): ${(err as Error).message ?? err}`,
+      );
+      return false;
+    }
+  }
+  const persisted = readMirrorConfigForVault(vaultName);
+  if (persisted?.enabled) return true;
+  return "left_disabled";
+}
+
 /**
  * Cut 3: when credentials save, flip `auto_push` from false → true on
  * the persisted config. Operators wiring credentials almost certainly
@@ -1063,15 +1397,32 @@ export async function applyCredentialsToMirror(
 //     "mode": "merge" | "replace",
 //     "credentials": null
 //       | { "kind": "pat", "token": "ghp_..." }
-//       | { "kind": "none" }
+//       | { "kind": "none" },
+//     "enable_sync": true   // optional, DEFAULT TRUE
 //   }
 //
 // `credentials: null` means "use the stored mirror credentials." Passing
-// `{kind: "pat", token}` is the one-shot path — token doesn't get persisted.
+// `{kind: "pat", token}` is the one-shot path — token doesn't get persisted
+// for the CLONE, but IS persisted when sync is enabled (it's the push
+// credential for the now-configured mirror).
+//
+// `enable_sync` (vault#416) — DEFAULT TRUE when omitted. After a successful
+// import, auto-enable mirror push-back to the SAME repo, reusing the import's
+// credentials. Makes "import a repo" and "back up to that repo going forward"
+// one fluid flow. The UI ships a checked-by-default checkbox the operator can
+// uncheck. Edge cases (handled in `enableSyncToImportedRepo`, never fail the
+// whole import):
+//   - `auth: none` (public repo, no push creds) → skip + warn (can't push
+//     without a credential).
+//   - A mirror already points at a DIFFERENT remote → skip + warn (don't
+//     clobber the operator's existing backup target).
+//   - A mirror already points at the SAME remote → no-op success.
+//   - Sync setup throws → import result still returned (success);
+//     `sync_enabled: false` + a warning. Import success is never lost.
 //
 // Response:
 //   200 { notes_imported, tags_imported, attachments_imported,
-//         notes_deleted?, warnings }
+//         notes_deleted?, warnings, sync_enabled, sync_warning? }
 //   400 { error, error_type, message }  — validation / not-a-vault-export
 //   409 { error, error_type, message }  — concurrent import for this vault
 //   502 { error, message }              — clone failed (auth, network, …)
@@ -1089,16 +1440,29 @@ export async function applyCredentialsToMirror(
  *
  * `spawnOverride` is a test seam: lets the test inject a fake git binary.
  * Production callers omit it; `cloneAndImport` falls back to `defaultGitSpawn`.
+ *
+ * `whichOverride` is a test seam for the git-presence preflight (default
+ * `Bun.which` inside `cloneAndImport`). Inject a fn returning `null` to
+ * exercise the git_not_installed 503 path without uninstalling git.
+ *
+ * `managerOverride` is a test seam for the post-import sync-enable step
+ * (vault#416). Production callers omit it; the route resolves the per-vault
+ * manager via `getMirrorManager(vaultName)` (same registry the auth /
+ * run-now / push-now routes use). Tests inject a manager so they can assert
+ * on the config it ends up with without standing up the full registry.
  */
 export async function handleMirrorImport(
   req: Request,
   vaultName: string,
   spawnOverride?: GitSpawn,
+  whichOverride?: (cmd: string) => string | null,
+  managerOverride?: MirrorManager,
 ): Promise<Response> {
   let body: {
     remote_url?: unknown;
     mode?: unknown;
     credentials?: unknown;
+    enable_sync?: unknown;
   };
   try {
     body = (await req.json()) as Record<string, unknown>;
@@ -1191,6 +1555,25 @@ export async function handleMirrorImport(
     );
   }
 
+  // vault#416: `enable_sync` defaults TRUE when omitted — the default-on UX.
+  // Only a literal `false` opts out; any other type is a validation error so
+  // a malformed body never silently flips the default.
+  let enableSync = true;
+  if ("enable_sync" in body && body.enable_sync !== undefined) {
+    if (typeof body.enable_sync !== "boolean") {
+      return Response.json(
+        {
+          error: "enable_sync invalid",
+          error_type: "validation",
+          field: "enable_sync",
+          message: "enable_sync must be a boolean (defaults to true when omitted).",
+        },
+        { status: 400 },
+      );
+    }
+    enableSync = body.enable_sync;
+  }
+
   // Resolve the target vault's store + assets dir. The route is gated on
   // `vault:<name>:admin`, so we trust vaultName is real by the time we
   // reach this code path; defensively re-resolve in case the vault was
@@ -1208,8 +1591,21 @@ export async function handleMirrorImport(
       store,
       assetsDir: assets,
       spawn: spawnOverride,
+      which: whichOverride,
     });
   } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      // 503 Service Unavailable — the server isn't configured to do this
+      // yet (git missing). The message tells the operator how to fix it.
+      return Response.json(
+        {
+          error: "git not installed",
+          error_type: "git_not_installed",
+          message: err.message,
+        },
+        { status: 503 },
+      );
+    }
     if (err instanceof ImportConflictError) {
       return Response.json(
         {
@@ -1250,7 +1646,368 @@ export async function handleMirrorImport(
     );
   }
 
+  // ---- vault#416: auto-enable sync to the imported repo (default-on) -------
+  //
+  // The import SUCCEEDED above. From here on, every failure is non-fatal —
+  // we never lose a successful import to a sync-setup error. `result` already
+  // carries `sync_enabled: false` (set by importResultFromStats); we flip it
+  // true only when sync is actually wired (or already wired to this remote).
+  if (enableSync) {
+    try {
+      const manager =
+        managerOverride ?? getMirrorManager(vaultName) ?? undefined;
+      const outcome = await enableSyncToImportedRepo({
+        vaultName,
+        remoteUrl: remote_url,
+        auth,
+        manager,
+      });
+      result.sync_enabled = outcome.sync_enabled;
+      if (outcome.warning) result.sync_warning = outcome.warning;
+    } catch (err) {
+      // Defense-in-depth: enableSyncToImportedRepo is written to not throw
+      // (it catches its own write/credential/reload errors), but a future
+      // edit or an unexpected throw must NOT take down a successful import.
+      const msg = redactToken((err as Error).message ?? String(err));
+      console.warn(
+        `[mirror-import] sync-enable threw after a successful import (non-fatal): ${msg}`,
+      );
+      result.sync_enabled = false;
+      result.sync_warning =
+        "Import succeeded, but enabling Sync failed. Set up Sync separately from the Git remote section.";
+    }
+  }
+
   return Response.json(result, {
     headers: { "Access-Control-Allow-Origin": "*" },
   });
 }
+
+// ---------------------------------------------------------------------------
+// vault#416 — sync-enable after a successful import.
+// ---------------------------------------------------------------------------
+
+/**
+ * After a successful import, turn the imported-from repo into a configured,
+ * credential-backed, auto-pushing mirror — reusing the import's credentials.
+ * This is the back half of the default-on "import → also sync back" flow.
+ *
+ * Reuses the SAME machinery the manual mirror-setup flow uses:
+ *   - `writeCredentials` to persist the push credential (per-vault, vault#399).
+ *   - `MirrorConfig` + `manager.reload()` to enable `auto_push` and restart
+ *     the lifecycle — which calls `applyCredentialsToRemote` to set `origin`
+ *     from the stored credentials (exactly like handleAuthPat /
+ *     handleAuthGithubSelectRepo do).
+ *
+ * Mirror location is left `internal` (vault-managed dir under the vault's
+ * data dir) — the import didn't ask the operator to pick an external path,
+ * and `auto_push + internal + credentials` is the supported "push to a
+ * GitHub/GitLab remote" shape (see mirror-config.ts validation note). The
+ * remote lives in credentials, not the config; that's why we persist
+ * credentials AND flip auto_push.
+ *
+ * Never throws — every failure path returns `{ sync_enabled: false, warning }`.
+ * The import already succeeded by the time this runs; a sync-setup error must
+ * not be surfaced as an import failure.
+ *
+ * Edge cases (returns `sync_enabled: false` + a warning, no broken mirror
+ * left behind):
+ *   - **No push-capable credential** — `auth: none`, OR `credentialsFile`
+ *     with no stored credential that covers this remote's host. Can't push
+ *     without a credential; skip rather than configure a mirror that would
+ *     just fail every push.
+ *   - **A mirror already targets a DIFFERENT remote** — don't clobber the
+ *     operator's existing backup target. Detected by comparing the existing
+ *     stored credential's remote host/path against the import remote.
+ *   - **A mirror already targets the SAME remote** — no-op success.
+ */
+export async function enableSyncToImportedRepo(opts: {
+  vaultName: string;
+  remoteUrl: string;
+  auth: ImportAuth;
+  /**
+   * The per-vault mirror manager. Undefined only in the boot-race window
+   * where the registry factory hasn't been installed; we then skip (warn)
+   * rather than persisting a half-configured mirror with no live manager.
+   */
+  manager: MirrorManager | undefined;
+}): Promise<{ sync_enabled: boolean; warning?: string }> {
+  const { vaultName, remoteUrl, auth, manager } = opts;
+
+  if (!manager) {
+    return {
+      sync_enabled: false,
+      warning:
+        "Sync not enabled — the vault's mirror manager wasn't ready. Set up Sync from the Git remote section.",
+    };
+  }
+
+  // --- Resolve the push credential we'll persist for this remote. ----------
+  // We need a credential that can PUSH to `remoteUrl`. The clone-time auth
+  // shapes map onto push credentials as follows:
+  //   - pat            → persist the supplied PAT against this remote.
+  //   - none           → no push credential; cannot enable a working sync.
+  //   - credentialsFile → reuse the already-stored credential, but only if it
+  //                       actually covers this remote's host (a stored PAT for
+  //                       a different host can't push here).
+  let credentialToWrite: MirrorCredentials | null = null;
+
+  if (auth.kind === "none") {
+    return {
+      sync_enabled: false,
+      warning:
+        "Sync not enabled — pushing changes back needs write credentials (a PAT or GitHub sign-in). Set up Sync separately to enable it.",
+    };
+  }
+
+  if (auth.kind === "pat") {
+    // Persist the supplied PAT against this remote — the same x-access-token
+    // embedding the manual PAT route stores, so bare `git push` works.
+    const embedded = embedTokenInRemoteUrl(remoteUrl, auth.token);
+    if (!embedded) {
+      return {
+        sync_enabled: false,
+        warning:
+          "Sync not enabled — the remote URL couldn't be parsed to embed the access token. Set up Sync separately from the Git remote section.",
+      };
+    }
+    credentialToWrite = {
+      ...(readCredentials(vaultName) ?? emptyCredentials()),
+      active_method: "pat",
+      pat: {
+        token: auth.token,
+        remote_url: embedded,
+        label: "Imported-repo sync",
+      },
+    };
+  }
+
+  // For credentialsFile we DON'T overwrite — we reuse what's already stored,
+  // but must verify it covers this remote (host match). Resolve the existing
+  // credential's effective remote so the conflict check below has something
+  // to compare against.
+  const existing = readCredentials(vaultName);
+
+  // --- Conflict / idempotency check against any already-configured mirror. --
+  // The mirror's remote lives in credentials, not in MirrorConfig. Compare
+  // the existing stored credential's remote against the import remote.
+  const persistedConfig = readMirrorConfigForVault(vaultName);
+  const mirrorAlreadyConfigured = !!persistedConfig && persistedConfig.enabled;
+  const existingRemote = existing ? effectiveRemoteOf(existing) : null;
+
+  if (mirrorAlreadyConfigured && existingRemote) {
+    if (sameRemote(existingRemote, remoteUrl)) {
+      // Same remote — make sure auto_push is on, then no-op success. We don't
+      // need to rewrite credentials (credentialsFile) or can refresh the PAT
+      // (pat path) — either way the mirror already points here.
+      if (auth.kind === "pat" && credentialToWrite) {
+        try {
+          writeCredentials(vaultName, credentialToWrite);
+        } catch (err) {
+          return {
+            sync_enabled: false,
+            warning: `Import succeeded; mirror already targets this repo but the credential refresh failed: ${redactToken((err as Error).message ?? String(err))}`,
+          };
+        }
+      }
+      return await applyEnabledAutoPush(manager);
+    }
+    // Different remote — don't clobber the operator's existing backup target.
+    return {
+      sync_enabled: false,
+      warning: `Sync not enabled — this vault already syncs to a different repo (${redactRemoteUrl(existingRemote)}). Leaving your existing backup target untouched. Change it from the Git remote section if you want to switch.`,
+    };
+  }
+
+  // A mirror is already configured + enabled with an active credential, but we
+  // couldn't read its remote to compare (github_oauth stores no owner/repo at
+  // the credential level — its remote lives on the mirror dir's `origin`). To
+  // avoid clobbering an existing GitHub-connected backup target by switching
+  // `active_method` to a PAT, refuse unless the existing credential is OAuth
+  // and this is the same GitHub host (then the manual select-repo flow already
+  // points origin where it should; we treat that as "already set up — leave
+  // it"). Conservative: don't auto-switch an existing connected mirror.
+  if (
+    mirrorAlreadyConfigured &&
+    existing?.active_method === "github_oauth" &&
+    existing.github_oauth
+  ) {
+    return {
+      sync_enabled: false,
+      warning:
+        "Sync not enabled — this vault already syncs via a connected GitHub account. Leaving your existing backup target untouched. Switch it from the Git remote section if you want to point sync at this repo instead.",
+    };
+  }
+
+  // --- No conflicting mirror. Wire it up. ----------------------------------
+  if (auth.kind === "credentialsFile") {
+    // Reuse the stored credential — but only if it can push to this remote.
+    const covers = existing && existingRemote && sameRemote(existingRemote, remoteUrl);
+    const hasOauthForGithub =
+      existing?.active_method === "github_oauth" &&
+      !!existing.github_oauth &&
+      isGithubRemote(remoteUrl);
+    if (!covers && !hasOauthForGithub) {
+      return {
+        sync_enabled: false,
+        warning:
+          "Sync not enabled — no saved credential can push to this repo. Connect GitHub or paste a Personal Access Token in the Git remote section to enable Sync.",
+      };
+    }
+    if (existing?.active_method === "github_oauth" && hasOauthForGithub) {
+      // OAuth path: persist origin via the github authed URL, same as the
+      // select-repo flow. Parse owner/repo from the import remote.
+      const ownerRepo = parseGithubOwnerRepo(remoteUrl);
+      if (!ownerRepo) {
+        return {
+          sync_enabled: false,
+          warning:
+            "Sync not enabled — couldn't parse owner/repo from the GitHub URL. Pick the repo from the Git remote section to enable Sync.",
+        };
+      }
+      const status = manager.getStatus();
+      const authedUrl = githubAuthedRemoteUrl(
+        existing.github_oauth!.access_token,
+        ownerRepo.owner,
+        ownerRepo.repo,
+      );
+      if (status.mirror_path) {
+        await applyToGitRemote(status.mirror_path, authedUrl);
+      }
+      // Stash a PAT-shaped credential so a restart re-applies the right
+      // origin without needing the operator to re-pick the repo. (The OAuth
+      // token works through the same x-access-token shape.) This mirrors how
+      // applyCredentialsToRemote refreshes github origins on restart.
+      credentialToWrite = {
+        ...existing,
+        active_method: "github_oauth",
+      };
+    }
+    // covers === true → existing PAT already targets this remote; nothing to
+    // re-persist. Fall through to enabling auto_push.
+  }
+
+  if (credentialToWrite) {
+    try {
+      writeCredentials(vaultName, credentialToWrite);
+    } catch (err) {
+      return {
+        sync_enabled: false,
+        warning: `Import succeeded, but saving the sync credential failed: ${redactToken((err as Error).message ?? String(err))}. Set up Sync separately from the Git remote section.`,
+      };
+    }
+  }
+
+  return await applyEnabledAutoPush(manager);
+}
+
+/**
+ * Flip the mirror config to `enabled: true, auto_push: true` (internal
+ * location) and reload the manager — which applies the just-persisted
+ * credentials to `origin` and starts the event-driven export loop. Returns
+ * the sync outcome; reload failures are non-fatal (import already succeeded).
+ */
+async function applyEnabledAutoPush(
+  manager: MirrorManager,
+): Promise<{ sync_enabled: boolean; warning?: string }> {
+  const current = manager.getEffectiveConfig();
+  const next: MirrorConfig = {
+    ...current,
+    enabled: true,
+    // Keep the operator's existing location if they'd set external; default
+    // internal for the fresh case. Internal + credentials is the supported
+    // "push to a hosted remote" shape.
+    location: current.location,
+    auto_push: true,
+  };
+  try {
+    await manager.reload(next);
+  } catch (err) {
+    return {
+      sync_enabled: false,
+      warning: `Import succeeded, but enabling Sync failed: ${redactToken((err as Error).message ?? String(err))}. Set up Sync separately from the Git remote section.`,
+    };
+  }
+  // reload → start sets status.enabled iff bootstrap succeeded. If bootstrap
+  // failed (e.g. git-less host, though import would've 503'd earlier), surface
+  // that rather than claiming sync is on.
+  const status = manager.getStatus();
+  if (!status.enabled) {
+    return {
+      sync_enabled: false,
+      warning: status.last_error
+        ? `Import succeeded, but the mirror couldn't start: ${redactToken(status.last_error)}`
+        : "Import succeeded, but the mirror couldn't start. Check the Git remote section.",
+    };
+  }
+  return { sync_enabled: true };
+}
+
+/**
+ * Embed an x-access-token credential into an HTTPS remote URL, the same shape
+ * the manual PAT route persists. Returns null when the URL can't be parsed or
+ * isn't http(s) (SSH / local-path remotes can't carry a token in userinfo —
+ * those rely on the operator's ssh-agent, so there's no push credential for
+ * us to embed). When the URL already carries userinfo, trust it verbatim.
+ */
+function embedTokenInRemoteUrl(remoteUrl: string, token: string): string | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(remoteUrl);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  if (parsed.username || parsed.password) return remoteUrl;
+  parsed.username = "x-access-token";
+  parsed.password = token;
+  return parsed.toString();
+}
+
+/**
+ * The remote a stored credential effectively pushes to:
+ *   - pat → its `remote_url` (userinfo-embedded; comparison strips userinfo).
+ *   - github_oauth → null here (no owner/repo stored at the credential level;
+ *     the origin is set when a repo is picked). Callers treat null as "no
+ *     known remote to conflict with."
+ */
+function effectiveRemoteOf(creds: MirrorCredentials): string | null {
+  if (creds.active_method === "pat" && creds.pat) return creds.pat.remote_url;
+  return null;
+}
+
+/**
+ * Compare two remote URLs ignoring userinfo (embedded tokens) + a trailing
+ * `.git` + a trailing slash, case-insensitively on host. "Same repo" for the
+ * clobber check. Falls back to a trimmed string compare for non-URL remotes
+ * (SSH shorthand, local paths).
+ */
+function sameRemote(a: string, b: string): boolean {
+  const norm = (u: string): string => {
+    try {
+      const url = new URL(u);
+      const host = url.host.toLowerCase();
+      const path = url.pathname.replace(/\.git$/, "").replace(/\/+$/, "");
+      return `${url.protocol}//${host}${path}`;
+    } catch {
+      return u.trim().replace(/\.git$/, "").replace(/\/+$/, "");
+    }
+  };
+  return norm(a) === norm(b);
+}
+
+/** True when a remote URL is on github.com (host-exact, case-insensitive). */
+function isGithubRemote(remoteUrl: string): boolean {
+  try {
+    return new URL(remoteUrl).host.toLowerCase() === "github.com";
+  } catch {
+    return false;
+  }
+}
+
+/** Parse `owner` + `repo` out of a github.com HTTPS URL. Null when it doesn't match. */
+function parseGithubOwnerRepo(remoteUrl: string): { owner: string; repo: string } | null {
+  const match = remoteUrl.match(/github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?(?:\/)?$/i);
+  if (!match) return null;
+  return { owner: match[1]!, repo: match[2]! };
+}