@capybara-hq/kernel 0.1.0-rc.27 → 0.1.0-rc.28

package/dist/git/gateway.route.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { FastifyInstance } from "fastify";
+import type { GitGateway } from "./gateway.js";
+/** The Fastify route template of the git gateway (`GIT_GATEWAY_PREFIX` + `*`). */
+export declare const GIT_GATEWAY_ROUTE = "/git/v1/*";
+/**
+ * Registers the git gateway (`GET` / `POST /git/v1/*`, sandbox git credentials spec §5) as a raw
+ * Fastify route in its own encapsulated scope, like the channel webhook (P-4): outside Nest, so
+ * neither the global `AuthGuard` nor the CSRF check applies (git sends neither; the run ticket is
+ * checked by {@link GitGateway}). It is not an API route and not a Platform operation (git
+ * smart-HTTP for sandboxes, authenticated by run tickets). Inside this scope only, the two git
+ * request types are handed to the handler as the raw stream (no buffering, no body limit: the
+ * gateway counts bytes against `tools.git.maxBytesPerRun`); any other type is refused by Fastify.
+ * HEAD and every other method answer 404. Registered by the api role; call before `app.init()`.
+ */
+export declare function registerGitGatewayRoute(fastify: FastifyInstance, gateway: Pick<GitGateway, "handle">, log: Pick<Logger, "error">): Promise<void>;

package/dist/git/gateway.route.js

@@ -0,0 +1,41 @@
+import { redactPath } from "../http/error.filter.js";
+/** The Fastify route template of the git gateway (`GIT_GATEWAY_PREFIX` + `*`). */
+export const GIT_GATEWAY_ROUTE = "/git/v1/*";
+/** The request content types of git smart-HTTP POSTs. */
+const GIT_REQUEST_TYPES = [
+    "application/x-git-upload-pack-request",
+    "application/x-git-receive-pack-request",
+];
+/**
+ * Registers the git gateway (`GET` / `POST /git/v1/*`, sandbox git credentials spec §5) as a raw
+ * Fastify route in its own encapsulated scope, like the channel webhook (P-4): outside Nest, so
+ * neither the global `AuthGuard` nor the CSRF check applies (git sends neither; the run ticket is
+ * checked by {@link GitGateway}). It is not an API route and not a Platform operation (git
+ * smart-HTTP for sandboxes, authenticated by run tickets). Inside this scope only, the two git
+ * request types are handed to the handler as the raw stream (no buffering, no body limit: the
+ * gateway counts bytes against `tools.git.maxBytesPerRun`); any other type is refused by Fastify.
+ * HEAD and every other method answer 404. Registered by the api role; call before `app.init()`.
+ */
+export async function registerGitGatewayRoute(fastify, gateway, log) {
+    await fastify.register(async (scope) => {
+        scope.removeAllContentTypeParsers();
+        scope.addContentTypeParser(GIT_REQUEST_TYPES, (_req, payload, done) => done(null, payload));
+        scope.setErrorHandler((err, req, reply) => {
+            const status = typeof err.statusCode === "number" ? err.statusCode : 500;
+            if (status >= 500)
+                log.error("git gateway request failed", { path: redactPath(req.url), err });
+            return reply
+                .code(status >= 400 && status < 500 ? 404 : 500)
+                .header("content-type", "text/plain; charset=utf-8")
+                .send(status >= 400 && status < 500
+                ? "Capybara: not a git smart-HTTP endpoint.\n"
+                : "Capybara: internal error.\n");
+        });
+        scope.route({
+            method: ["GET", "POST"],
+            url: GIT_GATEWAY_ROUTE,
+            exposeHeadRoute: false,
+            handler: (req, reply) => gateway.handle(req, reply),
+        });
+    });
+}

package/dist/git/git.module.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The git gateway (sandbox git credentials spec §5, §6): run tickets ({@link GitTickets}), whose
+ * connector serves a git host for an actor ({@link GitSources}) and the commit identity
+ * ({@link GitIdentities}), the gateway's relay ({@link GitGateway}, served by the api role's raw
+ * route `/git/v1/*`) and the run-end cleanup ({@link GitRunEnd}). It needs only the global infra
+ * and the connector credentials (`CredentialsModule`, not `ToolsModule`), so the api role (the
+ * gateway route) and the runtime and tool code (which issue tickets) can import it without a cycle.
+ */
+export declare class GitModule {
+}

package/dist/git/git.module.js

@@ -0,0 +1,31 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { CredentialsModule } from "../tools/credentials.module.js";
+import { GitGateway } from "./gateway.js";
+import { GitIdentities } from "./identity.js";
+import { GitRunEnd } from "./run-end.js";
+import { GitSources } from "./sources.js";
+import { GitTickets } from "./tickets.js";
+/**
+ * The git gateway (sandbox git credentials spec §5, §6): run tickets ({@link GitTickets}), whose
+ * connector serves a git host for an actor ({@link GitSources}) and the commit identity
+ * ({@link GitIdentities}), the gateway's relay ({@link GitGateway}, served by the api role's raw
+ * route `/git/v1/*`) and the run-end cleanup ({@link GitRunEnd}). It needs only the global infra
+ * and the connector credentials (`CredentialsModule`, not `ToolsModule`), so the api role (the
+ * gateway route) and the runtime and tool code (which issue tickets) can import it without a cycle.
+ */
+let GitModule = class GitModule {
+};
+GitModule = __decorate([
+    Module({
+        imports: [CredentialsModule],
+        providers: [GitTickets, GitSources, GitIdentities, GitGateway, GitRunEnd],
+        exports: [GitTickets, GitSources, GitIdentities, GitGateway, GitRunEnd],
+    })
+], GitModule);
+export { GitModule };

package/dist/git/identity.d.ts

@@ -0,0 +1,80 @@
+import type { KernelConfig } from "../config/schema.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import type { NetPolicy } from "../net/public-address.js";
+import { type ConnectorAuth, Credentials } from "../tools/credentials.js";
+/**
+ * Commit identity for git in sandboxes (sandbox git credentials spec §5.4, decision 8): the
+ * person's GitHub display name and noreply address, read once through their connection.
+ */
+/** A commit identity (`GIT_AUTHOR_*` / `GIT_COMMITTER_*`). */
+export interface GitIdentity {
+    name: string;
+    email: string;
+}
+/** What is cached per (org, connector, account, host): never a token. */
+export interface GitHubUser {
+    /** The GitHub display name, null when unset. */
+    name: string | null;
+    login: string;
+    id: number;
+}
+/** How long a read GitHub user is cached (24 h). */
+export declare const GIT_IDENTITY_TTL_SECONDS: number;
+/**
+ * Test seam (`KernelAppOptions.overrides`): the API base of a git host in place of
+ * {@link gitIdentityApiBase}, e.g. a loopback fake for `github.com`.
+ */
+export declare const GIT_IDENTITY_API_BASE: unique symbol;
+export type GitIdentityApiBase = (host: string) => string | null;
+/**
+ * The REST API base of a git host: `github.com` → `https://api.github.com`, `<sub>.ghe.com` →
+ * `https://api.<sub>.ghe.com`; any other host has no identity (null).
+ */
+export declare function gitIdentityApiBase(host: string): string | null;
+/**
+ * The kernel's outbound rules for git hosts and their APIs: the deployment's egress proxy, its
+ * private host exemptions (`marketplaces.allowPrivateHosts`) and loopback http only under
+ * `tools.oauthAllowInsecureLoopback` (tests), as for OAuth URLs. Redirects are never followed.
+ */
+export declare function gitNetPolicy(config: KernelConfig): NetPolicy;
+/** The fields kept from a `GET /user` answer, or null when it does not look like a user. */
+export declare function parseGitHubUser(body: unknown): GitHubUser | null;
+export declare class GitIdentities {
+    private readonly db;
+    private readonly credentials;
+    private readonly config;
+    /** Read by `@Cacheable`. */
+    readonly cacheService: CacheService;
+    private readonly log;
+    private readonly apiBase?;
+    constructor(db: KernelDb, credentials: Pick<Credentials, "gitAuthorization" | "gitUnauthorized" | "checkRevision">, config: Pick<KernelConfigService, "get">, 
+    /** Read by `@Cacheable`. */
+    cacheService: CacheService, log: Pick<KernelLogger, "warn">, apiBase?: GitIdentityApiBase | undefined);
+    /**
+     * The commit identity of `accountId` through the connector's credential on `host`: the GitHub
+     * `name` (else the login) and `<id>+<login>@users.noreply.<host>`. Null for a host without an
+     * identity API (not github.com or `*.ghe.com`), a connector of another org or without that host,
+     * a missing credential or an API failure (git then uses the sandbox's own config).
+     *
+     * Cached per (org, connector, subject, host, credential revision): the subject is the account
+     * for a personal connector and `org` for an org-credential one (the bot's identity is the same
+     * for every member, read once); the revision (`Credentials.checkRevision`, hashed) changes when
+     * the credential is set, refreshed or cleared, so a reconnect reads the user again.
+     */
+    gitIdentity(orgId: string, connectorId: string, accountId: string, host: string): Promise<GitIdentity | null>;
+    /**
+     * `GET /user` on the host's API with the connector's credential (one forced refresh after a
+     * 401), cached 24 h under the first five arguments (see {@link gitIdentity}); failures are not
+     * cached. The cached value holds no token; the log lines name the connector and the status,
+     * never a header. Called by {@link gitIdentity} only.
+     */
+    gitHubUser(orgId: string, connectorId: string, _subject: string, host: string, _revision: string, req: {
+        base: string;
+        auth: ConnectorAuth;
+        username: string;
+        accountId: string;
+    }): Promise<GitHubUser | null>;
+}

package/dist/git/identity.js

@@ -0,0 +1,209 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { Cacheable } from "../infra/cache/cacheable.decorator.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { CredentialMissing, Credentials } from "../tools/credentials.js";
+/** How long a read GitHub user is cached (24 h). */
+export const GIT_IDENTITY_TTL_SECONDS = 24 * 60 * 60;
+/**
+ * Test seam (`KernelAppOptions.overrides`): the API base of a git host in place of
+ * {@link gitIdentityApiBase}, e.g. a loopback fake for `github.com`.
+ */
+export const GIT_IDENTITY_API_BASE = Symbol("GIT_IDENTITY_API_BASE");
+const GHE_COM = /^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.ghe\.com$/;
+/**
+ * The REST API base of a git host: `github.com` → `https://api.github.com`, `<sub>.ghe.com` →
+ * `https://api.<sub>.ghe.com`; any other host has no identity (null).
+ */
+export function gitIdentityApiBase(host) {
+    if (host === "github.com")
+        return "https://api.github.com";
+    const m = GHE_COM.exec(host);
+    return m === null ? null : `https://api.${m[1]}.ghe.com`;
+}
+/**
+ * The kernel's outbound rules for git hosts and their APIs: the deployment's egress proxy, its
+ * private host exemptions (`marketplaces.allowPrivateHosts`) and loopback http only under
+ * `tools.oauthAllowInsecureLoopback` (tests), as for OAuth URLs. Redirects are never followed.
+ */
+export function gitNetPolicy(config) {
+    return {
+        allowInsecureLoopback: config.tools.oauthAllowInsecureLoopback,
+        allowPrivateHosts: config.marketplaces.allowPrivateHosts,
+        trustedOrigins: [],
+        ...(config.net.httpsProxy !== undefined && {
+            proxy: { url: config.net.httpsProxy, noProxy: config.net.noProxy },
+        }),
+    };
+}
+/** Bounds of a `GET /user` answer. */
+const USER_MAX_BYTES = 256 * 1024;
+const LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9_-]{0,98}[A-Za-z0-9])?$/;
+const NAME_MAX = 200;
+/** A display name safe for an environment variable: no control characters, bounded. */
+function cleanName(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = [...v]
+        .map((ch) => {
+        const c = ch.charCodeAt(0);
+        return c < 0x20 || c === 0x7f ? " " : ch;
+    })
+        .join("")
+        .trim()
+        .slice(0, NAME_MAX)
+        .trim();
+    return s === "" ? null : s;
+}
+/** The fields kept from a `GET /user` answer, or null when it does not look like a user. */
+export function parseGitHubUser(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    if (typeof b.login !== "string" || !LOGIN_RE.test(b.login))
+        return null;
+    if (typeof b.id !== "number" || !Number.isSafeInteger(b.id) || b.id <= 0)
+        return null;
+    return { name: cleanName(b.name), login: b.login, id: b.id };
+}
+let GitIdentities = class GitIdentities {
+    db;
+    credentials;
+    config;
+    cacheService;
+    log;
+    apiBase;
+    constructor(db, credentials, config, 
+    /** Read by `@Cacheable`. */
+    cacheService, log, apiBase) {
+        this.db = db;
+        this.credentials = credentials;
+        this.config = config;
+        this.cacheService = cacheService;
+        this.log = log;
+        this.apiBase = apiBase;
+    }
+    /**
+     * The commit identity of `accountId` through the connector's credential on `host`: the GitHub
+     * `name` (else the login) and `<id>+<login>@users.noreply.<host>`. Null for a host without an
+     * identity API (not github.com or `*.ghe.com`), a connector of another org or without that host,
+     * a missing credential or an API failure (git then uses the sandbox's own config).
+     *
+     * Cached per (org, connector, subject, host, credential revision): the subject is the account
+     * for a personal connector and `org` for an org-credential one (the bot's identity is the same
+     * for every member, read once); the revision (`Credentials.checkRevision`, hashed) changes when
+     * the credential is set, refreshed or cleared, so a reconnect reads the user again.
+     */
+    async gitIdentity(orgId, connectorId, accountId, host) {
+        const base = (this.apiBase ?? gitIdentityApiBase)(host);
+        if (base === null)
+            return null;
+        const row = await this.db.db
+            .selectFrom("connectors")
+            .select(["auth", "git_hosts"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const entry = (row?.git_hosts ?? []).find((h) => h.host === host);
+        if (row === undefined || entry === undefined)
+            return null;
+        const auth = row.auth;
+        const bot = auth.type !== "none" && auth.ownership === "org";
+        const subject = bot ? "org" : accountId;
+        const revision = createHash("sha256")
+            .update(await this.credentials.checkRevision(orgId, connectorId, bot ? null : accountId))
+            .digest("hex")
+            .slice(0, 16);
+        const user = await this.gitHubUser(orgId, connectorId, subject, host, revision, {
+            base,
+            auth,
+            username: entry.username,
+            accountId,
+        });
+        if (user === null)
+            return null;
+        return {
+            name: user.name ?? user.login,
+            email: `${user.id}+${user.login}@users.noreply.${host}`,
+        };
+    }
+    /**
+     * `GET /user` on the host's API with the connector's credential (one forced refresh after a
+     * 401), cached 24 h under the first five arguments (see {@link gitIdentity}); failures are not
+     * cached. The cached value holds no token; the log lines name the connector and the status,
+     * never a header. Called by {@link gitIdentity} only.
+     */
+    async gitHubUser(orgId, connectorId, _subject, host, _revision, req) {
+        const { base, auth, accountId, username } = req;
+        const config = this.config.get();
+        const get = async (authorization) => safeFetch(`${base}/user`, {
+            headers: {
+                Authorization: authorization,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "capybara-git-gateway",
+            },
+            signal: AbortSignal.timeout(Math.min(config.tools.timeoutMs, 30_000)),
+        }, gitNetPolicy(config), { maxBytes: USER_MAX_BYTES });
+        try {
+            const authorization = await this.credentials.gitAuthorization(orgId, connectorId, auth, accountId, username);
+            let res = await get(authorization);
+            if (res.status === 401) {
+                await res.body?.cancel().catch(() => { });
+                await this.credentials.gitUnauthorized(orgId, connectorId, auth, accountId, authorization);
+                res = await get(await this.credentials.gitAuthorization(orgId, connectorId, auth, accountId, username));
+            }
+            if (res.status !== 200) {
+                await res.body?.cancel().catch(() => { });
+                this.log.warn("git identity: the user lookup failed", {
+                    connectorId,
+                    host,
+                    status: res.status,
+                });
+                return null;
+            }
+            const user = parseGitHubUser(await res.json());
+            if (user === null) {
+                this.log.warn("git identity: the user lookup answered no user", { connectorId, host });
+            }
+            return user;
+        }
+        catch (e) {
+            if (!(e instanceof CredentialMissing)) {
+                this.log.warn("git identity: the user lookup failed", {
+                    connectorId,
+                    host,
+                    error: e instanceof Error ? e.name : "unknown",
+                });
+            }
+            return null;
+        }
+    }
+};
+__decorate([
+    Cacheable({ key: "git-identity:#{0}:#{1}:#{2}:#{3}:#{4}", ttl: GIT_IDENTITY_TTL_SECONDS })
+], GitIdentities.prototype, "gitHubUser", null);
+GitIdentities = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(Credentials)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(CacheService)),
+    __param(4, Inject(KERNEL_LOGGER)),
+    __param(5, Optional()),
+    __param(5, Inject(GIT_IDENTITY_API_BASE))
+], GitIdentities);
+export { GitIdentities };

package/dist/git/pkt-line.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Git pkt-lines (gitprotocol-common: a 4-hex-digit length that counts itself, then the payload;
+ * `0000` is the flush-pkt) as far as the git gateway needs them: the ref update commands at the
+ * start of a `git-receive-pack` request body, and the refusals git prints to the person running
+ * the command (sandbox git credentials spec §5.3).
+ */
+/** The flush-pkt. */
+export declare const FLUSH_PKT: Buffer<ArrayBuffer>;
+/** One pkt-line holding `data` (a longer payload is clipped to fit). */
+export declare function pktLine(data: string | Buffer): Buffer;
+/** One ref update of a push: `<old> <new> <ref>`. */
+export interface RefCommand {
+    oldId: string;
+    newId: string;
+    ref: string;
+}
+/** The command list at the start of a receive-pack request. */
+export interface ReceivePackCommands {
+    commands: RefCommand[];
+    /** The capabilities the client asked for (after the NUL of the first command). */
+    capabilities: string[];
+    /** Every byte read from the body so far (the commands and whatever followed in the chunk). */
+    prefix: Buffer;
+}
+/** Why the command list could not be read: the body is not a push the gateway can decide. */
+export declare class ReceivePackParseError extends Error {
+    constructor(message: string);
+}
+/** Bounds of the command list the gateway reads before it decides. */
+export declare const MAX_COMMANDS = 1000;
+export declare const MAX_COMMAND_BYTES: number;
+/**
+ * Reads the ref update commands at the start of a receive-pack request body, up to the first
+ * flush-pkt, from `chunks` (the body's async iterator; nothing after the chunk that holds the
+ * flush-pkt is read). `shallow` lines are skipped; a signed push (`push-cert`), a malformed line,
+ * a body that ends early or a list over {@link MAX_COMMANDS} / {@link MAX_COMMAND_BYTES} throws
+ * {@link ReceivePackParseError}. An empty list (a bare flush-pkt: git's auth probe) is valid.
+ */
+export declare function readReceivePackCommands(chunks: AsyncIterator<Buffer | string>): Promise<ReceivePackCommands>;
+/**
+ * A ref advertisement git turns into `fatal: remote error: <message>` (an `ERR` pkt-line as the
+ * first packet: git dies on it before it reads anything else).
+ */
+export declare function advertisementError(message: string): Buffer;
+/**
+ * The answer to a refused receive-pack request, in the form the client asked for, so git prints
+ * the message and marks each ref rejected:
+ * - side-band(-64k): `message` on band 2 (git prints `remote: <message>`), then the report on
+ *   band 1 (`unpack ok` + `ng <ref> <reason>`; git prints `! [remote rejected] … (<reason>)`);
+ * - report-status(-v2) without side-band: the report alone;
+ * - neither: an `ERR` pkt-line (git reports the push failed).
+ */
+export declare function receivePackRefusal(capabilities: readonly string[], refs: readonly string[], message: string, reason: string): Buffer;

package/dist/git/pkt-line.js

@@ -0,0 +1,146 @@
+/**
+ * Git pkt-lines (gitprotocol-common: a 4-hex-digit length that counts itself, then the payload;
+ * `0000` is the flush-pkt) as far as the git gateway needs them: the ref update commands at the
+ * start of a `git-receive-pack` request body, and the refusals git prints to the person running
+ * the command (sandbox git credentials spec §5.3).
+ */
+/** The flush-pkt. */
+export const FLUSH_PKT = Buffer.from("0000", "latin1");
+/** The largest pkt-line (header included). */
+const MAX_PKT = 65520;
+/** One pkt-line holding `data` (a longer payload is clipped to fit). */
+export function pktLine(data) {
+    const body = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+    const clipped = body.subarray(0, MAX_PKT - 4);
+    return Buffer.concat([
+        Buffer.from((clipped.length + 4).toString(16).padStart(4, "0"), "latin1"),
+        clipped,
+    ]);
+}
+/** Why the command list could not be read: the body is not a push the gateway can decide. */
+export class ReceivePackParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReceivePackParseError";
+    }
+}
+/** Bounds of the command list the gateway reads before it decides. */
+export const MAX_COMMANDS = 1000;
+export const MAX_COMMAND_BYTES = 1024 * 1024;
+const OBJECT_ID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+const SHALLOW = /^shallow [0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+/**
+ * Reads the ref update commands at the start of a receive-pack request body, up to the first
+ * flush-pkt, from `chunks` (the body's async iterator; nothing after the chunk that holds the
+ * flush-pkt is read). `shallow` lines are skipped; a signed push (`push-cert`), a malformed line,
+ * a body that ends early or a list over {@link MAX_COMMANDS} / {@link MAX_COMMAND_BYTES} throws
+ * {@link ReceivePackParseError}. An empty list (a bare flush-pkt: git's auth probe) is valid.
+ */
+export async function readReceivePackCommands(chunks) {
+    let buf = Buffer.alloc(0);
+    let pos = 0;
+    const commands = [];
+    let capabilities = [];
+    for (;;) {
+        // parse every complete pkt-line in the buffer
+        while (buf.length - pos >= 4) {
+            const lenHex = buf.toString("latin1", pos, pos + 4);
+            if (!/^[0-9a-f]{4}$/i.test(lenHex))
+                throw new ReceivePackParseError("bad pkt-line length");
+            const len = Number.parseInt(lenHex, 16);
+            if (len === 0)
+                return { commands, capabilities, prefix: buf };
+            if (len < 4)
+                throw new ReceivePackParseError("unexpected special pkt-line");
+            if (buf.length - pos < len)
+                break;
+            let line = buf.toString("utf8", pos + 4, pos + len);
+            pos += len;
+            if (line.endsWith("\n"))
+                line = line.slice(0, -1);
+            if (commands.length === 0) {
+                const nul = line.indexOf("\0");
+                if (nul >= 0) {
+                    capabilities = line
+                        .slice(nul + 1)
+                        .split(" ")
+                        .filter((c) => c !== "");
+                    line = line.slice(0, nul);
+                }
+            }
+            if (line.startsWith("push-cert")) {
+                throw new ReceivePackParseError("signed pushes are not supported through the gateway");
+            }
+            if (SHALLOW.test(line))
+                continue;
+            const parts = line.split(" ");
+            const [oldId, newId, ref] = parts;
+            if (parts.length !== 3 ||
+                oldId === undefined ||
+                newId === undefined ||
+                ref === undefined ||
+                !OBJECT_ID.test(oldId) ||
+                !OBJECT_ID.test(newId) ||
+                !ref.startsWith("refs/")) {
+                throw new ReceivePackParseError("malformed ref update command");
+            }
+            commands.push({ oldId, newId, ref });
+            if (commands.length > MAX_COMMANDS)
+                throw new ReceivePackParseError("too many ref updates");
+        }
+        if (buf.length > MAX_COMMAND_BYTES)
+            throw new ReceivePackParseError("command list too long");
+        const next = await chunks.next();
+        if (next.done)
+            throw new ReceivePackParseError("the request ended before the command list");
+        const chunk = typeof next.value === "string" ? Buffer.from(next.value) : next.value;
+        buf = Buffer.concat([buf, chunk]);
+    }
+}
+/**
+ * A ref advertisement git turns into `fatal: remote error: <message>` (an `ERR` pkt-line as the
+ * first packet: git dies on it before it reads anything else).
+ */
+export function advertisementError(message) {
+    return pktLine(`ERR ${oneLine(message)}\n`);
+}
+/**
+ * The answer to a refused receive-pack request, in the form the client asked for, so git prints
+ * the message and marks each ref rejected:
+ * - side-band(-64k): `message` on band 2 (git prints `remote: <message>`), then the report on
+ *   band 1 (`unpack ok` + `ng <ref> <reason>`; git prints `! [remote rejected] … (<reason>)`);
+ * - report-status(-v2) without side-band: the report alone;
+ * - neither: an `ERR` pkt-line (git reports the push failed).
+ */
+export function receivePackRefusal(capabilities, refs, message, reason) {
+    const caps = new Set(capabilities);
+    const report = caps.has("report-status") || caps.has("report-status-v2");
+    const sideBand = caps.has("side-band-64k") || caps.has("side-band");
+    const why = oneLine(reason);
+    const reportPkts = Buffer.concat([
+        pktLine("unpack ok\n"),
+        ...refs.map((ref) => pktLine(`ng ${ref} ${why}\n`)),
+        FLUSH_PKT,
+    ]);
+    if (sideBand) {
+        // side-band (without -64k) carries at most 1000 bytes per packet
+        const max = caps.has("side-band-64k") ? MAX_PKT - 5 : 995;
+        const band = (n, data) => {
+            const out = [];
+            for (let i = 0; i < data.length; i += max) {
+                out.push(pktLine(Buffer.concat([Buffer.from([n]), data.subarray(i, i + max)])));
+            }
+            return out;
+        };
+        return Buffer.concat([
+            ...band(2, Buffer.from(`${oneLine(message)}\n`, "utf8")),
+            ...(report ? band(1, reportPkts) : []),
+            FLUSH_PKT,
+        ]);
+    }
+    if (report)
+        return reportPkts;
+    return pktLine(`ERR ${oneLine(message)}\n`);
+}
+/** A message on one line (pkt-line payloads git prints are line-based). */
+const oneLine = (s) => s.replace(/[\r\n]+/g, " ").trim();

package/dist/git/run-end.d.ts

@@ -0,0 +1,29 @@
+import type { Redis } from "ioredis";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { GitTickets } from "./tickets.js";
+/**
+ * What a run's end does for the git gateway (sandbox git credentials spec §9): revokes the run's
+ * tickets and writes the `git.fetch` summaries. `RunFinish` calls it in `afterCommit` of the
+ * transaction that set the terminal status (set first, then revoke: `GitTickets.resolve` already
+ * refuses a run that is not active, so revocation is cleanup and defense in depth).
+ */
+/** The Redis hash of a run's fetch counters: fields `<host>/<repo>|n` and `<host>/<repo>|bytes`. */
+export declare const gitFetchKey: (runId: string) => string;
+/**
+ * Counters of a run that never ends cleanly (a lost end hook) expire after this. A fetch still in
+ * flight after the run ended writes a counter nobody summarises: it expires by this TTL too.
+ */
+export declare const FETCH_COUNTER_TTL_SECONDS: number;
+/** Adds one fetch request and its bytes to the run's counters (atomic, with a TTL). */
+export declare function recordGitFetch(redis: Redis, runId: string, host: string, repo: string, bytes: number, countRequest: boolean): Promise<void>;
+export declare class GitRunEnd {
+    private readonly tickets;
+    private readonly db;
+    private readonly redis;
+    private readonly log;
+    constructor(tickets: Pick<GitTickets, "revokeRun">, db: KernelDb, redis: Redis, log: Pick<KernelLogger, "warn">);
+    /** Run end: revokes the run's tickets and writes one `git.fetch` audit row per repository. */
+    onRunFinished(runId: string): Promise<void>;
+    private writeFetchSummaries;
+}