feat(p12a): services git distants (PAT/app_password) + clone HTTPS

Modèle de données : - migration #11 git_credentials (secrets chiffrés SecretBox : secret_encrypted ; colonnes ssh/oauth posées pour P12b/P12c) ; #12 repos ALTER remote_url/git_service/credential_id (pas de FK) - types partagés api.ts (GitCredentialSummary sans secret + hasSecret/secretLast4, CRUD, RemoteRepoSummary, Clone*) ; protocole additif : topic 'clones' + message clone_update (CloneOperation) Backend : - core/git-credentials.ts (GitCredentialsManager(db, box)) : CRUD chiffré, test() (GET /user), getSecret()/authContext() internes, NULLification de repos.credential_id à la suppression - core/git-clients/ (github/gitlab/gitea) via fetch, sans dépendance : verify()+listRepos() paginés, erreurs typées AUTH_FAILED/RATE_LIMITED/UNREACHABLE, SSRF base_url http(s) - core/git-auth.ts : withGitAuth (GIT_ASKPASS éphémère 0o700, secret par env, GIT_TERMINAL_PROMPT=0, jamais dans l'URL/.git/config, nettoyage finally) - core/git.ts cloneRepo (spawn git clone --progress, parse progression, timeout) - core/clone-manager.ts (EventEmitter) : clone async, dest confiné sous scanRoots + non existant, auto-enregistrement via addRepo + métadonnées de provenance, nettoyage du clone partiel, events topic 'clones' - routes/git-connections.ts (CRUD + /test + /:id/repos + POST /repos/clone 202 + GET /repos/clone/:id) ; app.ts câble box→GitCredentialsManager + CloneManager→gateway ; gateway relaie 'clones' Frontend : - ws-client subscribeClones ; stores git-connections + clone (suivi WS) - components/settings/GitConnectionsSection (liste + formulaire pat/app_password, secret jamais ré-affiché) inséré dans SettingsView ; CloneRepoModal (connexion → repos distants paginés → dest scanRoots[0] → barre de progression WS → redirection) ; bouton « Cloner » dans DashboardView ; i18n EN+FR Tests : git-credentials (round-trip SecretBox, résumé sans secret, NULLification) ; acceptance-p12.mjs (clone bare local file:// → clone_update done + repo enregistré + secret ABSENT de l'API, de la DB et du .git/config) Sous-phases restantes : P12b (SSH), P12c (OAuth device flow).
2026-06-27 14:27:18 +02:00
parent e8d10b7ec0
commit 08695a707d
22 changed files with 1583 additions and 10 deletions
--- a/packages/server/src/core/clone-manager.ts
+++ b/packages/server/src/core/clone-manager.ts
@@ -0,0 +1,118 @@
+// Orchestration des clones (P12). Asynchrone : POST /repos/clone répond 202 avec un operationId,
+// la progression est poussée en WS (topic 'clones') et lisible en REST (survit au refresh). À la fin,
+// le repo cloné est auto-enregistré via WorktreeManager.addRepo (réutilise unicité/validation/event).
+// `dest` est strictement confiné SOUS une racine de scan + non existant (mkdir implicite par git).
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { rm, stat } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import type { CloneOperation, GitService } from '@arboretum/shared';
+import type { Db } from '../db/index.js';
+import { isSafeAbsolutePath, cloneRepo } from './git.js';
+import { readScanRoots } from './scan-settings.js';
+import { withGitAuth } from './git-auth.js';
+import type { GitAuth } from './git-clients/index.js';
+import type { GitCredentialsManager } from './git-credentials.js';
+import type { WorktreeManager } from './worktree-manager.js';
+import { recordAudit } from './audit-log.js';
+
+export interface CloneManagerEvents {
+  clone_update: [CloneOperation];
+}
+
+function httpError(statusCode: number, code: string, message: string): Error & { statusCode: number; code: string } {
+  return Object.assign(new Error(message), { statusCode, code });
+}
+
+export class CloneManager extends EventEmitter<CloneManagerEvents> {
+  private readonly ops = new Map<string, CloneOperation>();
+
+  constructor(
+    private readonly db: Db,
+    private readonly worktrees: WorktreeManager,
+    private readonly credentials: GitCredentialsManager,
+  ) {
+    super();
+  }
+
+  get(id: string): CloneOperation | null {
+    return this.ops.get(id) ?? null;
+  }
+
+  /**
+   * Démarre un clone (validation synchrone du dest → throw 4xx ; clone asynchrone ensuite).
+   * Retourne l'operationId à suivre via WS/REST. `actor` pour l'audit.
+   */
+  async start(opts: { credentialId: string; remoteUrl: string; dest: string }, actor: string): Promise<string> {
+    const dest = resolve(opts.dest);
+    if (!isSafeAbsolutePath(dest)) throw httpError(400, 'BAD_REQUEST', 'dest must be an absolute, normalized path');
+    if (typeof opts.remoteUrl !== 'string' || opts.remoteUrl.trim() === '') throw httpError(400, 'BAD_REQUEST', 'remoteUrl is required');
+    const ctx = this.credentials.authContext(opts.credentialId);
+    if (!ctx) throw httpError(404, 'NOT_FOUND', 'No usable credential with this id');
+
+    // Confinement : dest DOIT être sous une racine de scan configurée (jamais d'écriture arbitraire).
+    const roots = readScanRoots(this.db);
+    if (roots.length === 0) throw httpError(400, 'NO_SCAN_ROOT', 'Configure a scan folder first (Settings → Discovery)');
+    const underRoot = roots.some((r) => {
+      const root = resolve(r);
+      return dest === root || dest.startsWith(root + sep);
+    });
+    if (!underRoot) throw httpError(400, 'OUTSIDE_SCAN_ROOT', 'dest must be inside a configured scan folder');
+
+    // Le parent doit exister ; le dest ne doit pas exister (git clone le crée).
+    const parent = dest.slice(0, dest.lastIndexOf(sep)) || sep;
+    try {
+      const st = await stat(parent);
+      if (!st.isDirectory()) throw httpError(400, 'BAD_DEST', 'Parent of dest is not a directory');
+    } catch (err) {
+      if ((err as { statusCode?: number }).statusCode) throw err;
+      throw httpError(404, 'NOT_FOUND', `Parent directory does not exist: ${parent}`);
+    }
+    if (await stat(dest).then(() => true).catch(() => false)) throw httpError(409, 'DEST_EXISTS', `Destination already exists: ${dest}`);
+
+    const id = randomUUID();
+    const op: CloneOperation = { id, state: 'pending', progress: null, phase: null, error: null, repoId: null, dest };
+    this.ops.set(id, op);
+    recordAudit(this.db, { actor, action: 'repo.clone', resourceId: id, details: { service: ctx.service, dest } });
+    // Lancement asynchrone (ne bloque pas la réponse 202).
+    void this.run(op, opts.remoteUrl, opts.credentialId, ctx);
+    return id;
+  }
+
+  private update(op: CloneOperation, patch: Partial<CloneOperation>): void {
+    Object.assign(op, patch);
+    this.emit('clone_update', { ...op });
+  }
+
+  private async run(
+    op: CloneOperation,
+    remoteUrl: string,
+    credentialId: string,
+    ctx: { service: GitService; baseUrl: string | null; auth: GitAuth },
+  ): Promise<void> {
+    this.update(op, { state: 'running' });
+    let lastPct = -10;
+    const onProgress = (p: { phase: string; percent: number | null }): void => {
+      // throttle : on ne pousse que sur changement de phase ou +3% pour éviter le flood WS.
+      if (p.percent == null || p.percent - lastPct >= 3 || p.phase !== op.phase) {
+        lastPct = p.percent ?? lastPct;
+        this.update(op, { phase: p.phase, progress: p.percent });
+      }
+    };
+    try {
+      await withGitAuth(ctx.service, ctx.auth, (env) =>
+        cloneRepo({ url: remoteUrl, dest: op.dest, env, onProgress }),
+      );
+      // auto-enregistrement du repo cloné + métadonnées de provenance.
+      const repo = await this.worktrees.addRepo({ path: op.dest });
+      this.db
+        .prepare('UPDATE repos SET remote_url = ?, git_service = ?, credential_id = ? WHERE id = ?')
+        .run(remoteUrl, ctx.service, credentialId, repo.id);
+      this.update(op, { state: 'done', progress: 100, repoId: repo.id });
+    } catch (err) {
+      // nettoyage du clone partiel (best-effort).
+      await rm(op.dest, { recursive: true, force: true }).catch(() => {});
+      this.update(op, { state: 'error', error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+}
--- a/packages/server/src/core/git-auth.ts
+++ b/packages/server/src/core/git-auth.ts
@@ -0,0 +1,40 @@
+// Préparation d'un environnement d'authentification git ÉPHÉMÈRE (P12). HTTPS (pat/app_password) :
+// les identifiants sont fournis via GIT_ASKPASS (script 0o700 lisant deux variables d'env), JAMAIS
+// dans l'URL ni dans `.git/config`. GIT_TERMINAL_PROMPT=0 (pas d'invite bloquante). Le script est
+// supprimé en `finally` ; le secret ne transite que par l'env du process enfant (jamais loggé).
+import { mkdtemp, writeFile, rm, chmod } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { GitService } from '@arboretum/shared';
+import type { GitAuth } from './git-clients/index.js';
+
+// Identité HTTPS par défaut quand l'utilisateur n'a pas fourni de username (token-as-password).
+const SERVICE_DEFAULT_USER: Record<GitService, string> = { github: 'x-access-token', gitlab: 'oauth2', gitea: 'oauth2' };
+
+export async function withGitAuth<T>(
+  service: GitService,
+  auth: GitAuth,
+  fn: (env: NodeJS.ProcessEnv) => Promise<T>,
+): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), 'arb-gitauth-'));
+  const askpass = join(dir, 'askpass.sh');
+  const user = auth.username || SERVICE_DEFAULT_USER[service];
+  await writeFile(
+    askpass,
+    "#!/bin/sh\ncase \"$1\" in\n  Username*) printf '%s' \"$ARB_GIT_USER\" ;;\n  *) printf '%s' \"$ARB_GIT_PASS\" ;;\nesac\n",
+    { mode: 0o700 },
+  );
+  await chmod(askpass, 0o700);
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    GIT_ASKPASS: askpass,
+    GIT_TERMINAL_PROMPT: '0',
+    ARB_GIT_USER: user,
+    ARB_GIT_PASS: auth.secret,
+  };
+  try {
+    return await fn(env);
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}
--- a/packages/server/src/core/git-clients/index.ts
+++ b/packages/server/src/core/git-clients/index.ts
@@ -0,0 +1,156 @@
+// Clients des services git distants (Gitea / GitLab / GitHub) — P12. Uniquement `fetch` global
+// (Node ≥ 22), AUCUNE dépendance (pas d'octokit/gitbeaker). Chaque client expose verify() (test de
+// connectivité/auth) et listRepos() (paginé). Erreurs typées : AUTH_FAILED / RATE_LIMITED / UNREACHABLE.
+import type { GitAuthType, GitService, RemoteRepoSummary } from '@arboretum/shared';
+
+const REQUEST_TIMEOUT_MS = 12_000;
+const PER_PAGE = 30;
+
+export interface GitAuth {
+  authType: GitAuthType;
+  username: string | null;
+  secret: string;
+}
+
+export class GitServiceError extends Error {
+  constructor(
+    public readonly errorCode: string,
+    message?: string,
+  ) {
+    super(message ?? errorCode);
+    this.name = 'GitServiceError';
+  }
+}
+
+export interface GitClient {
+  verify(auth: GitAuth): Promise<{ login: string }>;
+  listRepos(auth: GitAuth, page: number, search?: string): Promise<{ repos: RemoteRepoSummary[]; nextPage: number | null }>;
+}
+
+/** En-têtes d'auth selon le type. app_password → Basic (username:secret) ; pat → en-tête propre au service. */
+function authHeaders(service: GitService, auth: GitAuth): Record<string, string> {
+  if (auth.authType === 'app_password') {
+    const basic = Buffer.from(`${auth.username ?? ''}:${auth.secret}`).toString('base64');
+    return { Authorization: `Basic ${basic}` };
+  }
+  // pat
+  if (service === 'gitlab') return { 'PRIVATE-TOKEN': auth.secret };
+  if (service === 'gitea') return { Authorization: `token ${auth.secret}` };
+  return { Authorization: `Bearer ${auth.secret}` }; // github
+}
+
+/** Refuse une base self-hosted non http(s) (anti-SSRF schéma) ; renvoie l'origine normalisée sans `/` final. */
+function normalizeBase(baseUrl: string): string {
+  let u: URL;
+  try {
+    u = new URL(baseUrl);
+  } catch {
+    throw new GitServiceError('BAD_BASE_URL', 'base_url must be a valid http(s) URL');
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new GitServiceError('BAD_BASE_URL', 'base_url must be http(s)');
+  return `${u.origin}${u.pathname}`.replace(/\/+$/, '');
+}
+
+async function fetchJson(url: string, headers: Record<string, string>): Promise<{ json: unknown; headers: Headers }> {
+  let res: Response;
+  try {
+    res = await fetch(url, { headers: { Accept: 'application/json', ...headers }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  } catch {
+    throw new GitServiceError('UNREACHABLE', 'Could not reach the git service');
+  }
+  if (res.status === 429) throw new GitServiceError('RATE_LIMITED', 'Rate limited by the git service');
+  if (res.status === 401 || res.status === 403) {
+    // 403 + quota épuisé = rate limit (GitHub) ; sinon échec d'auth.
+    if (res.headers.get('x-ratelimit-remaining') === '0') throw new GitServiceError('RATE_LIMITED', 'Rate limited by the git service');
+    throw new GitServiceError('AUTH_FAILED', 'Authentication failed');
+  }
+  if (!res.ok) throw new GitServiceError(`HTTP_${res.status}`, `Unexpected response ${res.status}`);
+  return { json: await res.json().catch(() => null), headers: res.headers };
+}
+
+function githubBase(baseUrl: string | null): string {
+  return baseUrl ? normalizeBase(baseUrl) : 'https://api.github.com';
+}
+function gitlabBase(baseUrl: string | null): string {
+  return `${baseUrl ? normalizeBase(baseUrl) : 'https://gitlab.com'}/api/v4`;
+}
+function giteaBase(baseUrl: string | null): string {
+  if (!baseUrl) throw new GitServiceError('BAD_BASE_URL', 'Gitea requires a base_url (self-hosted instance)');
+  return `${normalizeBase(baseUrl)}/api/v1`;
+}
+
+const githubClient = (baseUrl: string | null): GitClient => {
+  const base = githubBase(baseUrl);
+  return {
+    async verify(auth) {
+      const { json } = await fetchJson(`${base}/user`, authHeaders('github', auth));
+      return { login: String((json as { login?: string })?.login ?? '') };
+    },
+    async listRepos(auth, page) {
+      const { json } = await fetchJson(`${base}/user/repos?per_page=${PER_PAGE}&page=${page}&sort=updated`, authHeaders('github', auth));
+      const arr = Array.isArray(json) ? (json as Array<Record<string, unknown>>) : [];
+      const repos = arr.map((r): RemoteRepoSummary => ({
+        fullName: String(r.full_name ?? ''),
+        cloneUrl: String(r.clone_url ?? ''),
+        private: Boolean(r.private),
+        description: (r.description as string | null) ?? null,
+        defaultBranch: (r.default_branch as string | null) ?? null,
+      }));
+      return { repos, nextPage: arr.length === PER_PAGE ? page + 1 : null };
+    },
+  };
+};
+
+const gitlabClient = (baseUrl: string | null): GitClient => {
+  const base = gitlabBase(baseUrl);
+  return {
+    async verify(auth) {
+      const { json } = await fetchJson(`${base}/user`, authHeaders('gitlab', auth));
+      return { login: String((json as { username?: string })?.username ?? '') };
+    },
+    async listRepos(auth, page) {
+      const { json, headers } = await fetchJson(
+        `${base}/projects?membership=true&per_page=${PER_PAGE}&page=${page}&order_by=last_activity_at`,
+        authHeaders('gitlab', auth),
+      );
+      const arr = Array.isArray(json) ? (json as Array<Record<string, unknown>>) : [];
+      const repos = arr.map((r): RemoteRepoSummary => ({
+        fullName: String(r.path_with_namespace ?? ''),
+        cloneUrl: String(r.http_url_to_repo ?? ''),
+        private: r.visibility !== 'public',
+        description: (r.description as string | null) ?? null,
+        defaultBranch: (r.default_branch as string | null) ?? null,
+      }));
+      const next = headers.get('x-next-page');
+      return { repos, nextPage: next ? Number(next) : null };
+    },
+  };
+};
+
+const giteaClient = (baseUrl: string | null): GitClient => {
+  const base = giteaBase(baseUrl);
+  return {
+    async verify(auth) {
+      const { json } = await fetchJson(`${base}/user`, authHeaders('gitea', auth));
+      return { login: String((json as { login?: string })?.login ?? '') };
+    },
+    async listRepos(auth, page) {
+      const { json } = await fetchJson(`${base}/user/repos?page=${page}&limit=${PER_PAGE}`, authHeaders('gitea', auth));
+      const arr = Array.isArray(json) ? (json as Array<Record<string, unknown>>) : [];
+      const repos = arr.map((r): RemoteRepoSummary => ({
+        fullName: String(r.full_name ?? ''),
+        cloneUrl: String(r.clone_url ?? ''),
+        private: Boolean(r.private),
+        description: (r.description as string | null) ?? null,
+        defaultBranch: (r.default_branch as string | null) ?? null,
+      }));
+      return { repos, nextPage: arr.length === PER_PAGE ? page + 1 : null };
+    },
+  };
+};
+
+export function getGitClient(service: GitService, baseUrl: string | null): GitClient {
+  if (service === 'github') return githubClient(baseUrl);
+  if (service === 'gitlab') return gitlabClient(baseUrl);
+  return giteaClient(baseUrl);
+}
--- a/packages/server/src/core/git-credentials.ts
+++ b/packages/server/src/core/git-credentials.ts
@@ -0,0 +1,180 @@
+// Gestion des credentials des services git distants (P12). Les secrets (PAT/app password) sont
+// chiffrés par SecretBox AVANT insertion et ne ressortent JAMAIS via l'API (résumés sans secret).
+// getSecret()/authFor() sont INTERNES (clone, listRepos, test) — jamais routés.
+import { randomUUID } from 'node:crypto';
+import type {
+  CreateGitCredentialRequest,
+  GitCredentialSummary,
+  GitService,
+  TestCredentialResponse,
+  UpdateGitCredentialRequest,
+} from '@arboretum/shared';
+import type { Db } from '../db/index.js';
+import type { SecretBox } from './secret-box.js';
+import { getGitClient, GitServiceError, type GitAuth } from './git-clients/index.js';
+import { recordAudit } from './audit-log.js';
+
+interface GitCredentialRow {
+  id: string;
+  label: string;
+  service: GitService;
+  base_url: string | null;
+  auth_type: GitCredentialSummary['authType'];
+  username: string | null;
+  secret_encrypted: string | null;
+  ssh_key_path: string | null;
+  oauth_access_encrypted: string | null;
+  oauth_refresh_encrypted: string | null;
+  oauth_expires_at: string | null;
+  created_at: string;
+  last_tested_at: string | null;
+  test_result: string | null;
+}
+
+function httpError(statusCode: number, code: string, message: string): Error & { statusCode: number; code: string } {
+  return Object.assign(new Error(message), { statusCode, code });
+}
+
+export class GitCredentialsManager {
+  constructor(
+    private readonly db: Db,
+    private readonly box: SecretBox,
+  ) {}
+
+  private getRow(id: string): GitCredentialRow | null {
+    return (this.db.prepare('SELECT * FROM git_credentials WHERE id = ?').get(id) as unknown as GitCredentialRow | undefined) ?? null;
+  }
+
+  private toSummary(row: GitCredentialRow): GitCredentialSummary {
+    let secretLast4: string | null = null;
+    if (row.secret_encrypted) {
+      try {
+        const s = this.box.decrypt(row.secret_encrypted);
+        secretLast4 = s.length >= 4 ? s.slice(-4) : '••••';
+      } catch {
+        secretLast4 = null;
+      }
+    }
+    return {
+      id: row.id,
+      label: row.label,
+      service: row.service,
+      baseUrl: row.base_url,
+      authType: row.auth_type,
+      username: row.username,
+      hasSecret: row.secret_encrypted != null,
+      secretLast4,
+      createdAt: row.created_at,
+      lastTestedAt: row.last_tested_at,
+      testResult: row.test_result,
+    };
+  }
+
+  list(): GitCredentialSummary[] {
+    const rows = this.db.prepare('SELECT * FROM git_credentials ORDER BY created_at ASC').all() as unknown as GitCredentialRow[];
+    return rows.map((r) => this.toSummary(r));
+  }
+
+  get(id: string): GitCredentialSummary | null {
+    const row = this.getRow(id);
+    return row ? this.toSummary(row) : null;
+  }
+
+  create(opts: CreateGitCredentialRequest): GitCredentialSummary {
+    // P12a : seules les méthodes HTTPS (pat / app_password) sont supportées pour l'instant.
+    if (opts.authType !== 'pat' && opts.authType !== 'app_password') {
+      throw httpError(400, 'UNSUPPORTED_AUTH', 'Only pat and app_password are supported for now (SSH/OAuth: later phases)');
+    }
+    if (!opts.label?.trim()) throw httpError(400, 'BAD_REQUEST', 'label is required');
+    if (opts.service !== 'gitea' && opts.service !== 'gitlab' && opts.service !== 'github') {
+      throw httpError(400, 'BAD_REQUEST', 'service must be gitea, gitlab or github');
+    }
+    if (opts.service === 'gitea' && !opts.baseUrl) throw httpError(400, 'BAD_REQUEST', 'Gitea requires a base_url');
+    if (!opts.secret) throw httpError(400, 'BAD_REQUEST', 'secret (token) is required');
+    const row: GitCredentialRow = {
+      id: randomUUID(),
+      label: opts.label.trim(),
+      service: opts.service,
+      base_url: opts.baseUrl?.trim() || null,
+      auth_type: opts.authType,
+      username: opts.username?.trim() || null,
+      secret_encrypted: this.box.encrypt(opts.secret),
+      ssh_key_path: null,
+      oauth_access_encrypted: null,
+      oauth_refresh_encrypted: null,
+      oauth_expires_at: null,
+      created_at: new Date().toISOString(),
+      last_tested_at: null,
+      test_result: null,
+    };
+    this.db
+      .prepare(
+        `INSERT INTO git_credentials (id, label, service, base_url, auth_type, username, secret_encrypted, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(row.id, row.label, row.service, row.base_url, row.auth_type, row.username, row.secret_encrypted, row.created_at);
+    return this.toSummary(row);
+  }
+
+  update(id: string, patch: UpdateGitCredentialRequest): GitCredentialSummary {
+    const row = this.getRow(id);
+    if (!row) throw httpError(404, 'NOT_FOUND', 'No credential with this id');
+    if (patch.label !== undefined) row.label = patch.label.trim() || row.label;
+    if (patch.baseUrl !== undefined) row.base_url = patch.baseUrl.trim() || null;
+    if (patch.username !== undefined) row.username = patch.username.trim() || null;
+    if (patch.secret) row.secret_encrypted = this.box.encrypt(patch.secret);
+    this.db
+      .prepare('UPDATE git_credentials SET label = ?, base_url = ?, username = ?, secret_encrypted = ? WHERE id = ?')
+      .run(row.label, row.base_url, row.username, row.secret_encrypted, id);
+    return this.toSummary(row);
+  }
+
+  /** Supprime un credential et NULLifie repos.credential_id (pas de FK). */
+  remove(id: string): boolean {
+    const res = this.db.prepare('DELETE FROM git_credentials WHERE id = ?').run(id);
+    if (res.changes === 0) return false;
+    this.db.prepare('UPDATE repos SET credential_id = NULL WHERE credential_id = ?').run(id);
+    return true;
+  }
+
+  /** Secret déchiffré — INTERNE (clone/listRepos/test). Jamais exposé par une route. */
+  getSecret(id: string): string | null {
+    const row = this.getRow(id);
+    if (!row?.secret_encrypted) return null;
+    try {
+      return this.box.decrypt(row.secret_encrypted);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Contexte d'auth (service, base, secret déchiffré) pour le client API / le clone. */
+  authContext(id: string): { service: GitService; baseUrl: string | null; auth: GitAuth } | null {
+    const row = this.getRow(id);
+    if (!row) return null;
+    const secret = this.getSecret(id);
+    if (secret == null) return null;
+    return { service: row.service, baseUrl: row.base_url, auth: { authType: row.auth_type, username: row.username, secret } };
+  }
+
+  /** Teste la connectivité/auth (GET /user) et mémorise le diagnostic. */
+  async test(id: string): Promise<TestCredentialResponse> {
+    const ctx = this.authContext(id);
+    if (!ctx) throw httpError(404, 'NOT_FOUND', 'No credential with this id');
+    const now = new Date().toISOString();
+    try {
+      const { login } = await getGitClient(ctx.service, ctx.baseUrl).verify(ctx.auth);
+      this.db.prepare('UPDATE git_credentials SET last_tested_at = ?, test_result = ? WHERE id = ?').run(now, 'ok', id);
+      return { ok: true, user: login };
+    } catch (err) {
+      const code = err instanceof GitServiceError ? err.errorCode : 'UNREACHABLE';
+      this.db.prepare('UPDATE git_credentials SET last_tested_at = ?, test_result = ? WHERE id = ?').run(now, code, id);
+      return { ok: false, error: code };
+    }
+  }
+}
+
+/** Helper d'audit partagé (jamais de secret dans details). */
+export function auditCredential(db: Db, actor: string, action: string, id: string | null): void {
+  recordAudit(db, { actor, action, resourceId: id });
+}
--- a/packages/server/src/core/git.ts
+++ b/packages/server/src/core/git.ts
@@ -1,6 +1,6 @@
 // Couche git sûre : tout passe par execFile (JAMAIS de shell), arguments en tableau, `--` avant
 // les chemins/refs utilisateur. Fonctions pures sans état, prenant un cwd déjà validé par l'appelant.
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { resolve, sep } from 'node:path';
 import type { WorktreeGitStatus, WorktreeBranchAction, WorktreeBranchMode, FileChange } from '@arboretum/shared';

@@ -605,3 +605,50 @@ export function isDirtyWorktreeError(err: unknown): boolean {
  const msg = `${(err as GitError)?.stderr ?? ''} ${(err as Error)?.message ?? ''}`;
  return /contains modified or untracked files|is dirty|use --force/i.test(msg);
 }
+
+const GIT_CLONE_TIMEOUT_MS = 10 * 60_000; // 10 min : un clone réseau peut être long.
+
+export interface CloneProgress {
+  phase: string;
+  /** pourcentage 0–100 si git le rapporte, sinon null. */
+  percent: number | null;
+}
+
+/**
+ * Clone un dépôt via `git clone --progress` (P12). `spawn` (et non execFile) pour streamer la
+ * progression depuis stderr. `env` éphémère (cf. withGitAuth) porte l'auth — JAMAIS dans l'URL.
+ * `--` sépare l'URL/dest des options. L'appelant valide `dest` (sous scanRoots, non existant).
+ */
+export function cloneRepo(opts: {
+  url: string;
+  dest: string;
+  env?: NodeJS.ProcessEnv;
+  branch?: string;
+  onProgress?: (p: CloneProgress) => void;
+  signal?: AbortSignal;
+}): Promise<void> {
+  return new Promise((resolveP, reject) => {
+    const args = ['clone', '--progress'];
+    if (opts.branch) args.push('--branch', opts.branch);
+    args.push('--', opts.url, opts.dest);
+    const child = spawn('git', args, {
+      env: { ...(opts.env ?? process.env), GIT_TERMINAL_PROMPT: '0', LC_ALL: 'C' },
+      stdio: ['ignore', 'ignore', 'pipe'],
+      timeout: GIT_CLONE_TIMEOUT_MS,
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    let stderr = '';
+    child.stderr.on('data', (d: Buffer) => {
+      const s = d.toString();
+      stderr += s;
+      if (stderr.length > 64 * 1024) stderr = stderr.slice(-64 * 1024); // borne mémoire
+      const m = /([A-Za-z][A-Za-z ]+):\s+(\d+)%/.exec(s);
+      if (m && m[1] && m[2] && opts.onProgress) opts.onProgress({ phase: m[1].trim(), percent: Number(m[2]) });
+    });
+    child.on('error', (err) => reject(err));
+    child.on('close', (code) => {
+      if (code === 0) resolveP();
+      else reject(new Error(stderr.trim().split('\n').pop() || `git clone exited with code ${code}`));
+    });
+  });
+}