just-git 1.2.12 → 1.3.0

package/dist/server/index.d.ts

@@ -1,19 +1,222 @@
-import { f as GitRepo, X as Rejection } from '../hooks-4DvkF2xT.js';
+import { a3 as RawObject, a5 as Ref, f as GitRepo, X as Rejection, N as NetworkPolicy } from '../hooks-BtbyLyYE.js';
 
-interface GitServerConfig {
+type MaybeAsync<T> = T | Promise<T>;
+/** Options for {@link StorageAdapter.createRepo}. */
+interface CreateRepoOptions {
+    /** Name of the default branch (default: `"main"`). Used for HEAD initialization. */
+    defaultBranch?: string;
+}
+/** Unresolved ref entry as stored by the storage backend. */
+interface RawRefEntry {
+    name: string;
+    ref: Ref;
+}
+/**
+ * Ref operations available inside an {@link Storage.atomicRefUpdate} callback.
+ * The storage backend provides isolation; the shared adapter runs git-aware CAS logic inside.
+ */
+interface RefOps {
+    getRef(name: string): MaybeAsync<Ref | null>;
+    putRef(name: string, ref: Ref): MaybeAsync<void>;
+    removeRef(name: string): MaybeAsync<void>;
+}
+/**
+ * Storage backend interface. Implementations provide raw key-value
+ * CRUD for objects and refs, plus an atomic ref operation primitive.
+ *
+ * All git-aware logic (object hashing, pack ingestion, symref resolution,
+ * CAS semantics) lives in the shared adapter built by {@link createStorageAdapter}.
+ *
+ * All methods may return synchronously or asynchronously.
+ */
+interface Storage {
+    hasRepo(repoId: string): MaybeAsync<boolean>;
+    insertRepo(repoId: string): MaybeAsync<void>;
+    /** Delete the repo record and all associated objects and refs. */
+    deleteRepo(repoId: string): MaybeAsync<void>;
+    getObject(repoId: string, hash: string): MaybeAsync<RawObject | null>;
+    putObject(repoId: string, hash: string, type: string, content: Uint8Array): MaybeAsync<void>;
+    /** Bulk insert. Implementations should use their optimal batch strategy. */
+    putObjects(repoId: string, objects: ReadonlyArray<{
+        hash: string;
+        type: string;
+        content: Uint8Array;
+    }>): MaybeAsync<void>;
+    hasObject(repoId: string, hash: string): MaybeAsync<boolean>;
+    findObjectsByPrefix(repoId: string, prefix: string): MaybeAsync<string[]>;
+    getRef(repoId: string, name: string): MaybeAsync<Ref | null>;
+    putRef(repoId: string, name: string, ref: Ref): MaybeAsync<void>;
+    removeRef(repoId: string, name: string): MaybeAsync<void>;
+    /** Return all refs under a prefix, unresolved (symrefs not followed). */
+    listRefs(repoId: string, prefix?: string): MaybeAsync<RawRefEntry[]>;
+    /**
+     * Run ref operations atomically. The storage backend wraps the callback in
+     * whatever isolation mechanism it supports (transaction, lock, etc.).
+     * The shared adapter uses this for compare-and-swap with symref resolution.
+     */
+    atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => MaybeAsync<T>): MaybeAsync<T>;
+}
+
+/**
+ * Default session type, produced by the built-in session builder when
+ * no custom `session` config is provided to `createServer`.
+ *
+ * HTTP requests produce `{ transport: "http", request }`.
+ * SSH sessions produce `{ transport: "ssh", username }`.
+ */
+interface Session {
+    transport: "http" | "ssh";
+    /** Authenticated username, when available. */
+    username?: string;
+    /** The HTTP request, present only when `transport` is `"http"`. */
+    request?: Request;
+}
+/**
+ * User-provided session builder that transforms raw transport input
+ * into a typed session object threaded through all hooks.
+ *
+ * TypeScript infers `S` from the return types of the builder functions,
+ * so hooks receive the custom type without explicit generic annotations.
+ *
+ * ```ts
+ * const server = createServer({
+ *   storage: new BunSqliteStorage(db),
+ *   session: {
+ *     http: (req) => ({
+ *       userId: parseJwt(req).sub,
+ *       roles: parseJwt(req).roles,
+ *     }),
+ *     ssh: (info) => ({
+ *       userId: info.username ?? "anonymous",
+ *       roles: (info.metadata?.roles as string[]) ?? [],
+ *     }),
+ *   },
+ *   hooks: {
+ *     preReceive: ({ session }) => {
+ *       // session is { userId: string, roles: string[] } — inferred!
+ *       if (!session?.roles.includes("push"))
+ *         return { reject: true, message: "forbidden" };
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface SessionBuilder<S> {
+    /**
+     * Build a session from an HTTP request.
+     *
+     * Return `S` to proceed, or return a `Response` to short-circuit
+     * the request (e.g. 401 with `WWW-Authenticate` header). This is
+     * the primary mechanism for HTTP auth — no separate middleware needed.
+     */
+    http: (request: Request) => S | Response | Promise<S | Response>;
+    /** Build a session from SSH session info. */
+    ssh: (info: SshSessionInfo) => S | Promise<S>;
+}
+/** Information about the SSH session passed to `handleSession`. */
+interface SshSessionInfo {
+    /** SSH username from authentication. */
+    username?: string;
+    /**
+     * Arbitrary metadata from the SSH auth layer.
+     * Stash key fingerprints, client IPs, roles, etc. here —
+     * the session builder can extract and type them.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Bidirectional channel for SSH session I/O.
+ *
+ * Adapters create this from their SSH library's channel/stream.
+ * The handler reads the client request from `readable` and writes
+ * the server response to `writable`.
+ *
+ * For receive-pack (push), `readable` must close when the client
+ * finishes sending. For upload-pack (fetch/clone), the handler
+ * reads protocol-aware pkt-lines and does not require EOF.
+ */
+interface SshChannel {
+    /** Client data (from client stdout via SSH channel). */
+    readonly readable: ReadableStream<Uint8Array>;
+    /** Server response (to client stdin via SSH channel). */
+    readonly writable: WritableStream<Uint8Array>;
+    /** Write a diagnostic/error message to the client's stderr. */
+    writeStderr?(data: Uint8Array): void;
+}
+/** Node.js `http.IncomingMessage`-compatible request interface. */
+interface NodeHttpRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: string, listener: (...args: any[]) => void): any;
+}
+/** Node.js `http.ServerResponse`-compatible response interface. */
+interface NodeHttpResponse {
+    writeHead(statusCode: number, headers?: Record<string, string | string[]>): any;
+    write(chunk: any): any;
+    end(data?: string): any;
+}
+/**
+ * Declarative push rules applied before user-provided hooks.
+ *
+ * These are git-level constraints that don't depend on the session.
+ * For session-dependent logic (auth, logging), use hooks directly.
+ */
+interface ServerPolicy {
+    /** Branches that cannot be force-pushed to or deleted. */
+    protectedBranches?: string[];
+    /** Reject all non-fast-forward pushes globally. */
+    denyNonFastForward?: boolean;
+    /** Reject all ref deletions globally. */
+    denyDeletes?: boolean;
+    /** Reject deletion and overwrite of tags. Tags are treated as immutable. */
+    denyDeleteTags?: boolean;
+}
+interface GitServerConfig<S = Session> {
     /**
-     * Resolve an incoming request path to a repository.
+     * Storage backend for git object and ref persistence.
      *
-     * Return values:
-     * - `GitRepo` — use this repo for the request
-     * - `null` — respond with 404
-     * - `Response` — send this response as-is (useful for 401/403 with
-     *   custom headers like `WWW-Authenticate`)
+     * The server calls `createStorageAdapter(storage)` internally to build the
+     * git-aware adapter. Users provide the storage backend; they never see
+     * the `StorageAdapter` interface.
      */
-    resolveRepo: (repoPath: string, request: Request) => GitRepo | Response | null | Promise<GitRepo | Response | null>;
+    storage: Storage;
+    /**
+     * Map a request path to a repo ID.
+     *
+     * Called for both HTTP and SSH requests. Return a string repo ID
+     * to serve, or `null` to respond with 404 / reject.
+     *
+     * Default: identity — the URL path segment is the repo ID.
+     */
+    resolve?: (path: string) => string | null | Promise<string | null>;
+    /**
+     * Automatically create repos on first access.
+     *
+     * When `true`, uses `"main"` as the default branch.
+     * When `{ defaultBranch }`, uses the specified branch name.
+     * When `false` or omitted, unknown repos return 404.
+     */
+    autoCreate?: boolean | {
+        defaultBranch?: string;
+    };
     /** Server-side hooks. All optional. */
-    hooks?: ServerHooks;
-    /** Base path prefix to strip from URLs (e.g. "/git"). */
+    hooks?: ServerHooks<S>;
+    /**
+     * Declarative push policy. Rules run before user-provided hooks.
+     *
+     * For session-dependent logic (auth, post-push actions), use `hooks`.
+     */
+    policy?: ServerPolicy;
+    /**
+     * Custom session builder. When provided, the server calls
+     * `session.http(request)` for HTTP and `session.ssh(info)` for SSH
+     * to produce the session object threaded through all hooks.
+     *
+     * When omitted, the built-in `Session` type is used.
+     */
+    session?: SessionBuilder<S>;
+    /** Base path prefix to strip from HTTP URLs (e.g. "/git"). */
     basePath?: string;
     /**
      * Cache generated packfiles for identical full-clone requests.
@@ -44,36 +247,116 @@ interface GitServerConfig {
      * Override to integrate with your own logging, or set to `false` to
      * suppress all error output.
      */
-    onError?: false | ((err: unknown, request: Request) => void);
+    onError?: false | ((err: unknown, session?: S) => void);
 }
 interface GitServer {
-    /** Standard fetch-API handler: (Request) => Response */
-    fetch: (request: Request) => Promise<Response>;
+    /** Standard fetch-API handler for HTTP: (Request) => Response */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Handle a single git-over-SSH session.
+     *
+     * Call this when the SSH client execs a git command (typically
+     * `git-upload-pack` or `git-receive-pack`). Returns the exit code
+     * to send to the client.
+     *
+     * ```ts
+     * import { Server } from "ssh2";
+     *
+     * new Server({ hostKeys: [key] }, (client) => {
+     *   client.on("authentication", (ctx) => { ctx.accept(); });
+     *   client.on("session", (accept) => {
+     *     accept().on("exec", (accept, reject, info) => {
+     *       const stream = accept();
+     *       const channel: SshChannel = {
+     *         readable: new ReadableStream({
+     *           start(c) {
+     *             stream.on("data", (d: Buffer) => c.enqueue(new Uint8Array(d)));
+     *             stream.on("end", () => c.close());
+     *           },
+     *         }),
+     *         writable: new WritableStream({ write(chunk) { stream.write(chunk); } }),
+     *         writeStderr(data) { stream.stderr.write(data); },
+     *       };
+     *       server.handleSession(info.command, channel, { username: ctx.username })
+     *         .then((code) => { stream.exit(code); stream.close(); });
+     *     });
+     *   });
+     * });
+     * ```
+     */
+    handleSession(command: string, channel: SshChannel, session?: SshSessionInfo): Promise<number>;
+    /**
+     * Node.js `http.createServer` compatible handler.
+     *
+     * ```ts
+     * import http from "node:http";
+     * http.createServer(server.nodeHandler).listen(4280);
+     * ```
+     */
+    nodeHandler(req: NodeHttpRequest, res: NodeHttpResponse): void;
+    /** Create a new repo. Throws if the repo already exists. */
+    createRepo(id: string, options?: CreateRepoOptions): Promise<GitRepo>;
+    /** Get a repo by ID, or `null` if it doesn't exist. */
+    repo(id: string): Promise<GitRepo | null>;
+    /** Delete a repo and all its data. */
+    deleteRepo(id: string): Promise<void>;
+    /**
+     * Graceful shutdown. After calling, new HTTP requests receive 503
+     * and new SSH sessions get exit 128. Resolves when all in-flight
+     * operations complete and the pack cache is released.
+     *
+     * Pass an `AbortSignal` to set a timeout — when aborted, the
+     * promise resolves immediately even if operations are still running.
+     * Idempotent: subsequent calls return the same drain promise.
+     */
+    close(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Whether `close()` has been called. */
+    readonly closed: boolean;
+    /**
+     * Build a {@link NetworkPolicy} that routes HTTP requests to this
+     * server in-process, bypassing the network stack entirely.
+     *
+     * Pass the returned policy as `network` to {@link createGit}:
+     *
+     * ```ts
+     * const git = createGit({ network: server.asNetwork() });
+     * await git.exec("clone http://git/my-repo /work");
+     * ```
+     *
+     * @param baseUrl - Base URL used in clone/push/fetch commands.
+     *   Only the hostname matters (for the `allowed` list). The URL
+     *   never hits the network — it's resolved by the server's
+     *   `resolve` function. Defaults to `"http://git"`.
+     */
+    asNetwork(baseUrl?: string): NetworkPolicy;
 }
-interface ServerHooks {
+interface ServerHooks<S = Session> {
     /**
      * Called after objects are unpacked but before any refs update.
      * Receives ALL ref updates as a batch. Return a Rejection to abort
      * the entire push. Auth, branch protection, and repo-wide policy
      * belong here.
      */
-    preReceive?: (event: PreReceiveEvent) => void | Rejection | Promise<void | Rejection>;
+    preReceive?: (event: PreReceiveEvent<S>) => void | Rejection | Promise<void | Rejection>;
     /**
      * Called per-ref, after preReceive passes.
      * Return a Rejection to block this specific ref update while
      * allowing others. Per-branch rules belong here.
      */
-    update?: (event: UpdateEvent) => void | Rejection | Promise<void | Rejection>;
+    update?: (event: UpdateEvent<S>) => void | Rejection | Promise<void | Rejection>;
     /**
      * Called after all ref updates succeed. Cannot reject.
      * CI triggers, webhooks, notifications belong here.
      */
-    postReceive?: (event: PostReceiveEvent) => void | Promise<void>;
+    postReceive?: (event: PostReceiveEvent<S>) => void | Promise<void>;
     /**
      * Called when a client wants to fetch or push (during ref advertisement).
-     * Return a filtered ref list to hide branches, or void to advertise all.
+     * Return a filtered ref list to hide branches, a Rejection to deny
+     * access entirely, or void to advertise all refs.
      */
-    advertiseRefs?: (event: AdvertiseRefsEvent) => RefAdvertisement[] | void | Promise<RefAdvertisement[] | void>;
+    advertiseRefs?: (event: AdvertiseRefsEvent<S>) => RefAdvertisement[] | void | Rejection | Promise<RefAdvertisement[] | void | Rejection>;
 }
 /** A single ref update within a push. */
 interface RefUpdate {
@@ -91,33 +374,41 @@ interface RefUpdate {
     isDelete: boolean;
 }
 /** Fired after objects are unpacked but before refs are updated. */
-interface PreReceiveEvent {
+interface PreReceiveEvent<S = Session> {
     repo: GitRepo;
-    repoPath: string;
+    /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
+    repoId: string;
     updates: readonly RefUpdate[];
-    request: Request;
+    /** Session info. Present for HTTP and SSH; absent for in-process pushes. */
+    session?: S;
 }
 /** Fired per-ref after preReceive passes. */
-interface UpdateEvent {
+interface UpdateEvent<S = Session> {
     repo: GitRepo;
-    repoPath: string;
+    /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
+    repoId: string;
     update: RefUpdate;
-    request: Request;
+    /** Session info. Present for HTTP and SSH; absent for in-process pushes. */
+    session?: S;
 }
 /** Fired after all ref updates succeed. */
-interface PostReceiveEvent {
+interface PostReceiveEvent<S = Session> {
     repo: GitRepo;
-    repoPath: string;
+    /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
+    repoId: string;
     updates: readonly RefUpdate[];
-    request: Request;
+    /** Session info. Present for HTTP and SSH; absent for in-process pushes. */
+    session?: S;
 }
 /** Fired during ref advertisement (info/refs). */
-interface AdvertiseRefsEvent {
+interface AdvertiseRefsEvent<S = Session> {
     repo: GitRepo;
-    repoPath: string;
+    /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
+    repoId: string;
     refs: RefAdvertisement[];
     service: "git-upload-pack" | "git-receive-pack";
-    request: Request;
+    /** Session info. Present for HTTP and SSH; absent for in-process requests. */
+    session?: S;
 }
 /** A ref name and hash advertised to clients during fetch/push discovery. */
 interface RefAdvertisement {
@@ -126,47 +417,43 @@ interface RefAdvertisement {
 }
 
 /**
- * Framework-agnostic Git Smart HTTP request handler.
+ * Unified Git server: Smart HTTP + SSH session handling.
  *
- * Uses web-standard Request/Response, works with Bun.serve, Hono,
- * Cloudflare Workers, or any framework that speaks fetch API.
- */
-
-/**
- * Create a Git Smart HTTP server handler.
+ * Uses web-standard Request/Response for HTTP, and web-standard
+ * ReadableStream/WritableStream for SSH. Works with Bun.serve, Hono,
+ * Cloudflare Workers, or any framework that speaks fetch API. SSH
+ * works with any SSH library (ssh2, etc.) through a thin adapter.
  *
  * ```ts
- * const server = createGitServer({
- *   resolveRepo: async (repoPath, request) => storage.repo(repoPath),
+ * const server = createServer({
+ *   storage: new MemoryStorage(),
+ *   autoCreate: true,
  * });
+ * await server.createRepo("my-repo");
+ *
+ * // HTTP
  * Bun.serve({ fetch: server.fetch });
  * ```
  */
-declare function createGitServer(config: GitServerConfig): GitServer;
-interface NodeHttpRequest {
-    method?: string;
-    url?: string;
-    headers: Record<string, string | string[] | undefined>;
-    on(event: string, listener: (...args: any[]) => void): any;
-}
-interface NodeHttpResponse {
-    writeHead(statusCode: number, headers?: Record<string, string | string[]>): any;
-    write(chunk: any): any;
-    end(data?: string): any;
-}
+
 /**
- * Adapt a `GitServer` to Node.js's `http.createServer` callback.
- *
- * Converts between Node's `IncomingMessage`/`ServerResponse` and the
- * web-standard `Request`/`Response` used by the server handler.
+ * Create a unified Git server that handles both HTTP and SSH.
  *
  * ```ts
- * import http from "node:http";
- * const httpServer = http.createServer(toNodeHandler(server));
- * httpServer.listen(4280);
+ * const server = createServer({
+ *   storage: new MemoryStorage(),
+ *   autoCreate: true,
+ * });
+ * await server.createRepo("my-repo");
+ *
+ * // HTTP — pass to Bun.serve, Hono, Cloudflare Workers, etc.
+ * Bun.serve({ fetch: server.fetch });
+ *
+ * // SSH — wire up with ssh2 or any SSH library
+ * server.handleSession(command, channel, { username });
  * ```
  */
-declare function toNodeHandler(server: GitServer): (req: NodeHttpRequest, res: NodeHttpResponse) => void;
+declare function createServer<S = Session>(config: GitServerConfig<S>): GitServer;
 /**
  * Compose multiple hook sets into a single `ServerHooks` object.
  *
@@ -175,94 +462,241 @@ declare function toNodeHandler(server: GitServer): (req: NodeHttpRequest, res: N
  * - **Post-hooks** (`postReceive`): run all in order. Each is individually
  *   try/caught so one failure doesn't prevent the rest from running.
  * - **Filter hooks** (`advertiseRefs`): chain — each hook receives the
- *   refs returned by the previous one. Returning void passes through
- *   unchanged.
+ *   refs returned by the previous one. Short-circuits on `Rejection`.
+ *   Returning void passes through unchanged.
  */
-declare function composeHooks(...hookSets: (ServerHooks | undefined)[]): ServerHooks;
+declare function composeHooks<S = Session>(...hookSets: (ServerHooks<S> | undefined)[]): ServerHooks<S>;
 
 /**
- * Opinionated hook presets built on top of the minimal ServerHooks interface.
+ * Server-side Git protocol helpers.
+ *
+ * Transport-agnostic ref advertisement, upload-pack response building,
+ * and receive-pack request/response parsing. The HTTP-specific service
+ * header wrapping is layered on top of the shared ref list builder.
  */
 
-type ResolveRepo = GitServerConfig["resolveRepo"];
+interface AdvertisedRef {
+    name: string;
+    hash: string;
+}
 /**
- * Wrap a `resolveRepo` function with an authorization check that
- * gates **all** access (clone, fetch, and push).
+ * Build the pkt-line ref list with capabilities. Transport-agnostic —
+ * used directly by SSH/in-process transports and wrapped by
+ * `buildRefAdvertisement` for HTTP.
  *
- * The `authorize` callback receives the raw `Request` and returns:
- * - `true` — request is allowed, delegate to the inner `resolveRepo`
- * - `false` — respond with 403 Forbidden
- * - `Response` — send as-is (e.g. 401 with `WWW-Authenticate` header)
+ * Format:
+ *   pkt-line("<hash> <refname>\0<capabilities>\n")  // first ref
+ *   pkt-line("<hash> <refname>\n")                   // subsequent refs
+ *   flush
+ */
+declare function buildRefListPktLines(refs: AdvertisedRef[], capabilities: string[], headTarget?: string): Uint8Array;
+interface PushCommand {
+    oldHash: string;
+    newHash: string;
+    refName: string;
+}
+
+/**
+ * High-level server operations.
  *
- * For push-only authorization, use `createStandardHooks({ authorizePush })`.
- * The two compose naturally:
+ * Transport-agnostic: each operation accepts a `GitRepo` and returns
+ * structured results. `applyReceivePack` encapsulates the full push
+ * lifecycle (hooks + ref application) for use by any transport adapter.
+ */
+
+interface PackCacheEntry {
+    packData: Uint8Array;
+    objectCount: number;
+    deltaCount: number;
+}
+/**
+ * Bounded LRU-ish cache for generated packfiles.
  *
- * ```ts
- * const server = createGitServer({
- *   resolveRepo: withAuth(
- *     (req) => req.headers.get("Authorization") === `Bearer ${token}`,
- *     (repoPath) => storage.repo(repoPath),
- *   ),
- *   hooks: createStandardHooks({ protectedBranches: ["main"] }),
- * });
- * ```
+ * Keyed on `(repoId, sorted wants)` — only caches full clones
+ * (requests with no `have` lines). Incremental fetches always
+ * compute fresh packs.
+ *
+ * Entries are automatically invalidated when refs change: since the
+ * cache key includes the exact want hashes, a ref update changes
+ * the want set on the next client request, producing a cache miss.
  */
-declare function withAuth(authorize: (request: Request) => boolean | Response | Promise<boolean | Response>, resolveRepo: ResolveRepo): ResolveRepo;
-interface StandardHooksConfig {
-    /** Branches that cannot be force-pushed to or deleted. */
-    protectedBranches?: string[];
-    /** Reject all non-fast-forward pushes globally. */
-    denyNonFastForward?: boolean;
-    /** Reject all ref deletions globally. */
-    denyDeletes?: boolean;
-    /** Reject deletion and overwrite of tags. Tags are treated as immutable. */
-    denyDeleteTags?: boolean;
-    /** Return false to reject the entire push (e.g. check Authorization header). */
-    authorizePush?: (request: Request) => boolean | Promise<boolean>;
-    /** Called after refs are updated. */
-    onPush?: (event: PostReceiveEvent) => void | Promise<void>;
+declare class PackCache {
+    private entries;
+    private currentBytes;
+    private maxBytes;
+    private hits;
+    private misses;
+    constructor(maxBytes?: number);
+    /** Build a cache key. Returns null for requests with haves (not cacheable). */
+    static key(repoId: string, wants: string[], haves: string[]): string | null;
+    get(key: string): PackCacheEntry | undefined;
+    set(key: string, entry: PackCacheEntry): void;
+    clear(): void;
+    get stats(): {
+        entries: number;
+        bytes: number;
+        hits: number;
+        misses: number;
+    };
+}
+interface RefsData {
+    refs: RefAdvertisement[];
+    headTarget?: string;
 }
 /**
- * Build a standard set of server hooks from a simple config.
+ * Collect the structured ref list from a repo (no wire encoding).
+ * The handler can pass this through an advertiseRefs hook to filter,
+ * then call `buildRefAdvertisementBytes` to produce the wire format.
+ */
+declare function collectRefs(repo: GitRepo): Promise<RefsData>;
+/**
+ * Build the HTTP-wrapped ref advertisement (includes `# service=...` header).
+ */
+declare function buildRefAdvertisementBytes(refs: RefAdvertisement[], service: "git-upload-pack" | "git-receive-pack", headTarget?: string): Uint8Array;
+/**
+ * Build the transport-agnostic ref list (no HTTP service header).
+ * Used by SSH and in-process transports.
+ */
+declare function buildRefListBytes(refs: RefAdvertisement[], service: "git-upload-pack" | "git-receive-pack", headTarget?: string): Uint8Array;
+interface AdvertiseResult {
+    refs: RefAdvertisement[];
+    headTarget?: string;
+}
+/**
+ * Collect refs and run the `advertiseRefs` hook. Returns either the
+ * (possibly filtered) ref list, or a `Rejection` if the hook denied access.
  *
- * Covers the most common policies (branch protection, fast-forward
- * enforcement, authorization, post-push callbacks) so users don't
- * have to wire hooks manually for typical setups.
+ * Both HTTP and SSH code paths use this — the caller handles the
+ * transport-specific response (HTTP 403 vs SSH exit 128).
  */
-declare function createStandardHooks(config: StandardHooksConfig): ServerHooks;
-
+declare function advertiseRefsWithHooks<S>(repo: GitRepo, repoId: string, service: "git-upload-pack" | "git-receive-pack", hooks?: ServerHooks<S>, session?: S): Promise<AdvertiseResult | Rejection>;
+interface UploadPackOptions {
+    /** Pack cache instance. When provided, full clones (no haves) are cached. */
+    cache?: PackCache;
+    /** Repo path used as part of the cache key. Required when cache is set. */
+    cacheKey?: string;
+    /** Skip delta compression — faster pack generation, larger output. */
+    noDelta?: boolean;
+    /** Delta window size (default 10). Ignored when noDelta is true. */
+    deltaWindow?: number;
+}
 /**
- * Abstract storage backend for multi-repo git object and ref storage.
+ * Handle a `POST /git-upload-pack` request.
  *
- * Implemented by `BunSqliteStorage`, `BetterSqlite3Storage`, and `PgStorage`.
+ * Returns `Uint8Array` for buffered responses (cache hits, deltified packs)
+ * or `ReadableStream<Uint8Array>` for streaming no-delta responses.
  */
-interface Storage {
-    /** Get a `GitRepo` scoped to a specific repo. */
-    repo(repoId: string): GitRepo;
-    /** Delete all objects and refs for a repo. */
-    deleteRepo(repoId: string): Promise<void>;
+declare function handleUploadPack(repo: GitRepo, requestBody: Uint8Array, options?: UploadPackOptions): Promise<Uint8Array | ReadableStream<Uint8Array>>;
+interface ReceivePackResult {
+    updates: RefUpdate[];
+    unpackOk: boolean;
+    capabilities: string[];
+    /** Whether the request body contained a valid pkt-line flush packet. */
+    sawFlush: boolean;
 }
+/**
+ * Ingest a receive-pack request: parse commands, ingest the packfile,
+ * and compute enriched RefUpdate objects. Does NOT apply ref updates —
+ * call `applyReceivePack` to run hooks and apply refs.
+ */
+declare function ingestReceivePack(repo: GitRepo, requestBody: Uint8Array): Promise<ReceivePackResult>;
+/**
+ * Streaming variant of `ingestReceivePack`. Accepts pre-parsed push
+ * commands and a raw pack byte stream. Uses `readPackStreaming` →
+ * `ingestPackStream` so pack bytes are consumed incrementally without
+ * buffering the entire pack in memory.
+ *
+ * The HTTP handler continues using `ingestReceivePack` (runtime buffers
+ * POST bodies anyway). The SSH handler calls this directly after parsing
+ * pkt-line commands.
+ */
+declare function ingestReceivePackFromStream(repo: GitRepo, commands: PushCommand[], capabilities: string[], packStream: AsyncIterable<Uint8Array>, sawFlush?: boolean): Promise<ReceivePackResult>;
+interface ApplyReceivePackOptions<S = unknown> {
+    repo: GitRepo;
+    repoId: string;
+    ingestResult: ReceivePackResult;
+    hooks?: ServerHooks<S>;
+    /** Session info threaded through to hooks. */
+    session?: S;
+}
+interface RefResult {
+    ref: string;
+    ok: boolean;
+    error?: string;
+}
+interface ApplyReceivePackResult {
+    refResults: RefResult[];
+    applied: RefUpdate[];
+}
+/**
+ * Run the full receive-pack lifecycle: preReceive hook, per-ref update
+ * hook with ref format validation, CAS ref application, and postReceive
+ * hook. Transport-agnostic — works for HTTP, SSH, or in-process pushes.
+ *
+ * Returns per-ref results and the list of successfully applied updates.
+ * Does NOT handle unpack failures — the caller should check
+ * `ingestResult.unpackOk` and short-circuit before calling this.
+ */
+declare function applyReceivePack<S = unknown>(options: ApplyReceivePackOptions<S>): Promise<ApplyReceivePackResult>;
+
+/**
+ * SSH protocol helpers for the unified Git server.
+ *
+ * Provides the pkt-line stream reader, command parser, and
+ * receive-pack streaming logic used by `createServer`'s
+ * `handleSession` method. Not a public entry point — see
+ * `createServer` for usage.
+ */
+
+type GitSshService = "git-upload-pack" | "git-receive-pack";
+/**
+ * Parse a git SSH exec command into service and repo path.
+ *
+ * Handles `git-upload-pack '/path'`, `git upload-pack '/path'`,
+ * and unquoted variants.
+ */
+declare function parseGitSshCommand(command: string): {
+    service: GitSshService;
+    repoPath: string;
+} | null;
 
 /**
- * In-memory git storage with multi-repo support.
+ * In-memory storage backend with multi-repo support.
  *
  * Useful for tests, ephemeral servers, and benchmarking.
  * Data is lost when the process exits.
  *
  * ```ts
- * const storage = new MemoryStorage();
- * const server = createGitServer({
- *   resolveRepo: async (repoPath) => storage.repo(repoPath),
+ * const server = createServer({
+ *   storage: new MemoryStorage(),
  * });
+ * await server.createRepo("my-repo");
  * ```
  */
 declare class MemoryStorage implements Storage {
+    private repos;
     private objects;
     private refs;
-    repo(repoId: string): GitRepo;
-    deleteRepo(repoId: string): Promise<void>;
-    private getObjects;
-    private getRefs;
+    hasRepo(repoId: string): boolean;
+    insertRepo(repoId: string): void;
+    deleteRepo(repoId: string): void;
+    getObject(repoId: string, hash: string): RawObject | null;
+    putObject(repoId: string, hash: string, type: string, content: Uint8Array): void;
+    putObjects(repoId: string, objects: ReadonlyArray<{
+        hash: string;
+        type: string;
+        content: Uint8Array;
+    }>): void;
+    hasObject(repoId: string, hash: string): boolean;
+    findObjectsByPrefix(repoId: string, prefix: string): string[];
+    getRef(repoId: string, name: string): Ref | null;
+    putRef(repoId: string, name: string, ref: Ref): void;
+    removeRef(repoId: string, name: string): void;
+    listRefs(repoId: string, prefix?: string): RawRefEntry[];
+    atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => T): T;
+    repoIds(): string[];
+    private getObjMap;
+    private getRefMap;
 }
 
 /** Minimal prepared statement interface matching `bun:sqlite`. */
@@ -278,20 +712,35 @@ interface BunSqliteDatabase {
     transaction<F extends (...args: any[]) => any>(fn: F): (...args: Parameters<F>) => ReturnType<F>;
 }
 /**
- * SQLite-backed git storage using `bun:sqlite`.
+ * SQLite-backed storage using `bun:sqlite`.
  *
  * ```ts
  * import { Database } from "bun:sqlite";
- * const storage = new BunSqliteStorage(new Database("repos.db"));
+ * const storage = createStorageAdapter(new BunSqliteStorage(new Database("repos.db")));
  * ```
  */
 declare class BunSqliteStorage implements Storage {
     private db;
     private stmts;
-    private ingestTx;
+    private batchInsertTx;
     constructor(db: BunSqliteDatabase);
-    repo(repoId: string): GitRepo;
-    deleteRepo(repoId: string): Promise<void>;
+    hasRepo(repoId: string): boolean;
+    insertRepo(repoId: string): void;
+    deleteRepo(repoId: string): void;
+    getObject(repoId: string, hash: string): RawObject | null;
+    putObject(repoId: string, hash: string, type: string, content: Uint8Array): void;
+    putObjects(repoId: string, objects: ReadonlyArray<{
+        hash: string;
+        type: string;
+        content: Uint8Array;
+    }>): void;
+    hasObject(repoId: string, hash: string): boolean;
+    findObjectsByPrefix(repoId: string, prefix: string): string[];
+    getRef(repoId: string, name: string): Ref | null;
+    putRef(repoId: string, name: string, ref: Ref): void;
+    removeRef(repoId: string, name: string): void;
+    listRefs(repoId: string, prefix?: string): RawRefEntry[];
+    atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => T): T;
 }
 
 /** Minimal prepared statement interface matching `better-sqlite3`. */
@@ -307,20 +756,35 @@ interface BetterSqlite3Database {
     transaction<F extends (...args: any[]) => any>(fn: F): (...args: Parameters<F>) => ReturnType<F>;
 }
 /**
- * SQLite-backed git storage using `better-sqlite3`.
+ * SQLite-backed storage using `better-sqlite3`.
  *
  * ```ts
  * import Database from "better-sqlite3";
- * const storage = new BetterSqlite3Storage(new Database("repos.db"));
+ * const storage = createStorageAdapter(new BetterSqlite3Storage(new Database("repos.db")));
  * ```
  */
 declare class BetterSqlite3Storage implements Storage {
     private db;
     private stmts;
-    private ingestTx;
+    private batchInsertTx;
     constructor(db: BetterSqlite3Database);
-    repo(repoId: string): GitRepo;
-    deleteRepo(repoId: string): Promise<void>;
+    hasRepo(repoId: string): boolean;
+    insertRepo(repoId: string): void;
+    deleteRepo(repoId: string): void;
+    getObject(repoId: string, hash: string): RawObject | null;
+    putObject(repoId: string, hash: string, type: string, content: Uint8Array): void;
+    putObjects(repoId: string, objects: ReadonlyArray<{
+        hash: string;
+        type: string;
+        content: Uint8Array;
+    }>): void;
+    hasObject(repoId: string, hash: string): boolean;
+    findObjectsByPrefix(repoId: string, prefix: string): string[];
+    getRef(repoId: string, name: string): Ref | null;
+    putRef(repoId: string, name: string, ref: Ref): void;
+    removeRef(repoId: string, name: string): void;
+    listRefs(repoId: string, prefix?: string): RawRefEntry[];
+    atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => T): T;
 }
 
 /** Minimal database interface for PostgreSQL. Use {@link wrapPgPool} to adapt a `pg` Pool. */
@@ -357,10 +821,7 @@ interface PgPoolClient {
  */
 declare function wrapPgPool(pool: PgPool): PgDatabase;
 /**
- * PostgreSQL-backed git storage with multi-repo support.
- *
- * Creates and manages `git_objects` and `git_refs` tables in the
- * provided database. Multiple repos are partitioned by `repo_id`.
+ * PostgreSQL-backed storage.
  *
  * Use the static `create` factory (schema setup is async):
  *
@@ -368,19 +829,29 @@ declare function wrapPgPool(pool: PgPool): PgDatabase;
  * import { Pool } from "pg";
  * const pool = new Pool({ connectionString: "..." });
  * const storage = await PgStorage.create(wrapPgPool(pool));
- * const server = createGitServer({
- *   resolveRepo: async (repoPath) => storage.repo(repoPath),
- * });
  * ```
  */
 declare class PgStorage implements Storage {
     private db;
     private constructor();
     static create(db: PgDatabase): Promise<PgStorage>;
-    /** Get a `GitRepo` scoped to a specific repo. */
-    repo(repoId: string): GitRepo;
-    /** Delete all objects and refs for a repo. */
+    hasRepo(repoId: string): Promise<boolean>;
+    insertRepo(repoId: string): Promise<void>;
     deleteRepo(repoId: string): Promise<void>;
+    getObject(repoId: string, hash: string): Promise<RawObject | null>;
+    putObject(repoId: string, hash: string, type: string, content: Uint8Array): Promise<void>;
+    putObjects(repoId: string, objects: ReadonlyArray<{
+        hash: string;
+        type: string;
+        content: Uint8Array;
+    }>): Promise<void>;
+    hasObject(repoId: string, hash: string): Promise<boolean>;
+    findObjectsByPrefix(repoId: string, prefix: string): Promise<string[]>;
+    getRef(repoId: string, name: string): Promise<Ref | null>;
+    putRef(repoId: string, name: string, ref: Ref): Promise<void>;
+    removeRef(repoId: string, name: string): Promise<void>;
+    listRefs(repoId: string, prefix?: string): Promise<RawRefEntry[]>;
+    atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => Promise<T> | T): Promise<T>;
 }
 
-export { type AdvertiseRefsEvent, type BetterSqlite3Database, type BetterSqlite3Statement, BetterSqlite3Storage, type BunSqliteDatabase, type BunSqliteStatement, BunSqliteStorage, type GitServer, type GitServerConfig, MemoryStorage, type PgDatabase, type PgPool, type PgPoolClient, PgStorage, type PostReceiveEvent, type PreReceiveEvent, type RefAdvertisement, type RefUpdate, Rejection, type ServerHooks, type StandardHooksConfig, type Storage, type UpdateEvent, composeHooks, createGitServer, createStandardHooks, toNodeHandler, withAuth, wrapPgPool };
+export { type AdvertiseRefsEvent, type AdvertiseResult, type ApplyReceivePackOptions, type ApplyReceivePackResult, type BetterSqlite3Database, type BetterSqlite3Statement, BetterSqlite3Storage, type BunSqliteDatabase, type BunSqliteStatement, BunSqliteStorage, type CreateRepoOptions, type GitServer, type GitServerConfig, type MaybeAsync, MemoryStorage, type NodeHttpRequest, type NodeHttpResponse, type PgDatabase, type PgPool, type PgPoolClient, PgStorage, type PostReceiveEvent, type PreReceiveEvent, type RawRefEntry, type ReceivePackResult, type RefAdvertisement, type RefOps, type RefResult, type RefUpdate, Rejection, type ServerHooks, type ServerPolicy, type Session, type SessionBuilder, type SshChannel, type SshSessionInfo, type Storage, type UpdateEvent, advertiseRefsWithHooks, applyReceivePack, buildRefAdvertisementBytes, buildRefListBytes, buildRefListPktLines, collectRefs, composeHooks, createServer, handleUploadPack, ingestReceivePack, ingestReceivePackFromStream, parseGitSshCommand, wrapPgPool };