@foss.global/gitmanager 2.9.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/gitmanager",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "private": false,
   "description": "Headless Git manager for the foss.global Git platform, with a TypeScript API and Rust engine.",
   "exports": {
@@ -10,17 +10,14 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "dependencies": {
-    "@foss.global/interfaces": "^2.4.0",
+    "@foss.global/interfaces": "^3.5.0",
     "@push.rocks/smartrust": "^1.7.0"
   },
   "devDependencies": {
     "@foss.global/ci-spec": "1.1.1",
-    "@git.zone/tsbuild": "^6.0.2",
-    "@git.zone/tsdoc": "^3.0.2",
-    "@git.zone/tsrun": "^3.0.3",
-    "@git.zone/tsrust": "^4.5.1",
-    "@git.zone/tstest": "^8.0.0",
-    "@types/node": "^26.6.4"
+    "@git.zone/rsrepo": "^1.3.1",
+    "@git.zone/tsrepo": "^2.2.0",
+    "@types/node": "^26.6.6"
   },
   "files": [
     "ts/**/*",
@@ -57,11 +54,11 @@
     "last 1 chrome versions"
   ],
   "scripts": {
-    "pretest": "(tsrust)",
-    "test": "tstest test/ --verbose --logfile --timeout 60",
+    "pretest": "(rsrepo)",
+    "test": "tsrepo test test/ --verbose --logfile --timeout 60",
     "test:rust": "(cd rust && cargo test)",
-    "build": "(tsbuild tsfolders) && (tsrust)",
-    "build:release": "(tsbuild tsfolders) && (tsrust --configured-targets) && (tsrust verify)",
-    "buildDocs": "tsdoc"
+    "build": "(tsrepo build tsfolders) && (rsrepo)",
+    "build:release": "(tsrepo build tsfolders) && (rsrepo --configured-targets) && (rsrepo verify)",
+    "buildDocs": "tsrepo docs"
   }
 }

package/readme.md

@@ -2,7 +2,7 @@
 
 Headless Git manager for the foss.global Git platform.
 
-This package follows the push.rocks Rust-backed package pattern: TypeScript owns the public package API and lifecycle, while Rust owns the Git/storage/protocol engine. TypeScript controls the Rust binary through `@push.rocks/smartrust`, and builds use `@git.zone/tsrust`.
+This package follows the push.rocks Rust-backed package pattern: TypeScript owns the public package API and lifecycle, while Rust owns the Git/storage/protocol engine. TypeScript controls the Rust binary through `@push.rocks/smartrust`, and builds use `@git.zone/rsrepo`.
 
 The current implementation provides lifecycle IPC, local bare repository and mirror management, bounded read APIs, durable repository bundle transfer, public and trusted-ingress private clone/fetch, trusted-ingress receive-pack, bounded raw Git services for SSH ingress, and revision-fenced protection for exact branch refs. User identity, permissions, SSH/TLS termination, durable protected-ref policy storage, and durable post-push repository storage remain the embedding service's responsibility.
 
@@ -169,7 +169,7 @@ const result = await gitManager.pushRefs({
     { ref: 'refs/heads/old', expectedOldObjectId: oldOid, newObjectId: null }, // delete
   ],
 });
-// { org, repo, status: 'applied' | 'rejected', refs: [{ ref, status: 'ok' | 'rejected' | 'stale', reason?, message? }] }
+// { org, repo, status: 'applied' | 'rejected', refs: [{ ref, status: 'ok' | 'rejected' | 'stale', reason?, message? }], remoteMessages: string[] }
 
 await gitManager.setDefaultBranch({ org: 'mirror.org', repo: 'interfaces', defaultBranch: 'main' });
 ```
@@ -184,13 +184,48 @@ await gitManager.setDefaultBranch({ org: 'mirror.org', repo: 'interfaces', defau
   - `non-fast-forward`: the remote or the local Git refused the ref as not a fast-forward.
   - `local-rejected`: the local Git refused the ref for another reason, such as an existing ref it would not overwrite.
   - `remote-rejected`: the remote refused the ref with a reason not listed above, or with none.
+- `remoteMessages` holds the messages the remote sent during the push, such as a hook's output, for `https` and `ssh` remotes alike: the text of each `remote: ` line of Git's standard error in order, without the prefix and the trailing padding. It is `[]` when the remote sent none and is never omitted. It holds at most 100 lines and 16 KiB of text; when the remote sent more, the last element is `[remote messages truncated]` (a line cut at the byte bound keeps its first part). Credentials are redacted as in `message`. It is free text: look for a value you chose yourself, such as a nonce, and never branch on anything else in it.
 - Git sends nothing for a ref that already holds `newObjectId`, whatever its lease says, and reports it `ok` with the message `up to date` while the push's other refs are sent as usual, so a retried push whose first response was lost reads as `applied`. Such a ref is not changed, but its lease was not checked either: `ok` never means the lease matched. Deleting a ref that is already gone is `stale`.
 - The remote must advertise the `atomic` receive-pack capability. Without it Git refuses before it sends anything, and `pushRefs()` throws a `GitManagerError` with code `atomicPushUnsupported`; it never falls back to ref-by-ref updates. That holds for Smart HTTP remotes only: against a dumb-HTTP remote Git runs `http-push`, which updates ref by ref and is not atomic, so a push remote must serve Smart HTTP.
 - Each `newObjectId` must be in the managed repository; a missing one throws a `GitManagerError` with code `objectNotFound` before any connection. A push holds one or more updates of distinct full ref names under `refs/`; object IDs are full lowercase hexadecimal. GitManager sets no limit on the number of updates and never splits a push. It reads at most 128 MiB of the remote helper's output per push (the remote's ref listing and one status line per listed or pushed ref) and at most 64 KiB per line, and throws when the helper writes more. A remote that refuses the push request as too large (HTTP 413) makes `pushRefs()` throw a `GitManagerError` with code `remoteLimitExceeded`; nothing was pushed.
-- URL policy, enforced by GitManager: `https://`, or `http://` only to a loopback IP literal in its canonical spelling, `127.0.0.0/8` as four decimal octets without leading zeros or exactly `[::1]`. Other spellings of a loopback address (an uppercase scheme, octal, hexadecimal or single-integer forms, a trailing dot, other IPv6 forms) are refused rather than normalized, so Git receives exactly the URL the policy checked. Host names over `http`, `localhost` included, are refused, because a credential sent over plain `http` to a name would go wherever that name resolves. `ssh://`, `git://`, `file://`, `ext::`, local paths, scp-like URLs and URLs with user information are refused. The policy runs before any process starts, and its errors never quote the URL.
+- URL policy, enforced by GitManager: `https://`, or `http://` only to a loopback IP literal in its canonical spelling, `127.0.0.0/8` as four decimal octets without leading zeros or exactly `[::1]`. Other spellings of a loopback address (an uppercase scheme, octal, hexadecimal or single-integer forms, a trailing dot, other IPv6 forms) are refused rather than normalized, so Git receives exactly the URL the policy checked. Host names over `http`, `localhost` included, are refused, because a credential sent over plain `http` to a name would go wherever that name resolves. `git://`, `file://`, `ext::`, local paths, scp-like URLs and URLs with user information are refused. `ssh://` is the transport of an `sshKey` credential and of nothing else (see [SSH pushes](#ssh-pushes)): an `ssh://` URL without an `sshKey` credential, an `sshKey` credential with any other URL, and `caCertificates` with an `sshKey` credential throw a `GitManagerError` with code `remoteTransportMismatch`. The policy runs before any process starts, and its errors never quote the URL.
 - The credential, `caCertificates` and `timeoutMs` behave as for mirrors: the credential travels only in the Git process environment as an `Authorization` header, with no credential helper, no hooks, no redirects and no global or system Git config; error text replaces the remote URL with `<push-remote>`. The remote URL is never stored in the repository.
 - `{ signal }` aborts a push as described in [Cancellation, concurrency and stop](#cancellation-concurrency-and-stop). An abort before the updates are sent (the signal already aborted, or an abort during the local object check or the remote ref listing) changes nothing anywhere. An abort after that rejects with `transferAborted` as well, but the remote may have applied the push: the remote applies an atomic push completely or not at all, and the abort can land before or after it did. Read the remote refs again before retrying.
 - A loopback `http` push never goes through a proxy, so the credential cannot leave the machine; see the proxy note above.
+### SSH pushes
+
+An `sshKey` credential pushes to an `ssh://` remote with the remote's host key pinned:
+
+```ts
+const result = await gitManager.pushRefs({
+  org: 'canary.org',
+  repo: 'canary',
+  remoteUrl: 'ssh://git@code.example:29419/canary.org/canary.git',
+  credential: { kind: 'sshKey', privateKey: canaryKeyPem, hostKey: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...' },
+  updates: [{ ref: 'refs/heads/main', expectedOldObjectId: oldOid, newObjectId: newOid }],
+});
+if (result.refs[0].reason === 'hook-declined' && result.remoteMessages.some((line) => line.includes(nonce))) {
+  // refused by the hook that printed the nonce
+}
+```
+
+- `remoteUrl` is `ssh://<user>@<host>[:<port>]/<path>`. The user is required and may hold `[A-Za-z0-9._-]` (not starting with `-` or `.`); the host is a name, an IPv4 address or a bracketed IPv6 address in canonical form; the port defaults to 22; the path holds only `[A-Za-z0-9._/-]`. Anything else is refused, never escaped or quoted, before any process starts. The remote runs `git-receive-pack '<path>'`.
+- `hostKey` is the remote's public host key as one OpenSSH key line, `<type> <base64>` without host name or comment (`ssh-ed25519`, `ecdsa-sha2-nistp256`/`384`/`521` or `ssh-rsa`); the key blob is checked against its type. `ssh` accepts that key and no other: there is no known-hosts file, no trust on first use and no host key update. A fingerprint alone is not accepted.
+- `privateKey` is one PEM private key the OpenSSH client reads, without a passphrase: `-----BEGIN OPENSSH PRIVATE KEY-----` (what `ssh-keygen` writes), or PEM RSA, EC or PKCS #8. An encrypted key is refused.
+- The push runs the system `ssh` client, which has to be on the engine's `PATH`. The key exists for the push only, as a `0600` file in a `0700` `remote-ssh-<pid>-<nonce>` directory under `transferDir`, next to a known-hosts file holding only `hostKey`; it is removed as soon as the remote's ref advertisement is read, and on every error, abort and timeout. A directory a killed engine left behind is removed when the next engine starts. Only the file's path is on the `ssh` command line; the key is never in an argument, an environment variable, an error or a log. `ssh` runs with `-F none -T`, `BatchMode`, `IdentitiesOnly`, no agent, `PreferredAuthentications=publickey`, `StrictHostKeyChecking=yes`, `UpdateHostKeys=no`, `ConnectTimeout` (at most 30 s), `LogLevel=ERROR` and `--` before the destination, and with only `PATH` and `LC_ALL=C` in its environment.
+- The push has the same semantics as over `https`: the engine reads the remote's ref advertisement, checks every lease against it, and hands the refspecs and the advertisement to `git send-pack --stateless-rpc --atomic`, relaying its request to the remote as remote-curl does over HTTP. Each command carries the advertised old object, so the remote checks every lease again inside its atomic ref transaction; command lines stay the same size however many updates a push holds. A remote without the `atomic` capability throws `atomicPushUnsupported` before anything is sent.
+- A failure before the remote's ref advertisement is complete throws a `GitManagerError`, and nothing was pushed. The code comes from `ssh`'s exit status 255 and the fixed texts of the local OpenSSH client (pinned against the system `ssh` in `test/test.sshpush.node.ts`); the message carries `ssh`'s redacted standard error for operator logs only, never as something to judge by:
+
+  | Code | When |
+  | --- | --- |
+  | `sshHostKeyMismatch` | `Host key verification failed.`: the remote's host key is not `hostKey`; the private key was never offered. |
+  | `sshAuthenticationFailed` | `<user>@<host>: Permission denied (<methods>).`: the remote refused the key. |
+  | `remoteConnectionRefused` | `ssh: connect to host <host> port <port>: Connection refused`. |
+  | `remoteConnectionFailed` | Any other `ssh` failure (exit 255): an unknown host, a connection timeout, or a server that does not offer the type of `hostKey` (OpenSSH reports that at a level `LogLevel=ERROR` hides). |
+  | `remoteProtocolError` | The remote command ran but did not answer with a Git receive-pack advertisement with `report-status`, such as a forge that refuses SSH with a message, or a missing repository. GitManager never matches a forge's own text. |
+
+- After the advertisement, the outcome is read from `send-pack`'s report exactly as over `https`: `applied`, `rejected` with a `reason` per ref, or an error when the report does not say what the remote did.
+
 - `setDefaultBranch()` points HEAD at `refs/heads/<defaultBranch>` and returns the repository info. The branch name is given without `refs/heads/`; a branch that does not exist is refused and HEAD stays unchanged. A mirror's next `refreshMirror()` points HEAD at the source's default branch again.
 - With `allowUnborn: true` the branch may not exist yet: HEAD names it unborn, as in a new repository, until a push creates it, and clones check out nothing until then. receive-pack refuses to delete the branch HEAD names (`deletion of the current branch prohibited`), which fails a whole atomic push, so a push that renames the default branch (creates the new one and deletes the old one) needs HEAD on the new name first. If that push is refused, HEAD stays unborn; `setDefaultBranch()` without the flag to an existing branch points it back. The name is validated either way.
 
@@ -453,6 +488,22 @@ const inspection = await gitManager.inspectArchive({
 
 The metadata is recomputed from the bytes, so compare it with what the sender declared rather than trusting the declaration. Every limit is inclusive and must be a non-negative safe integer; `maxPathMetadataBytes` is 1 to 134217728 and defaults to the ceiling. A refused archive throws a `GitManagerError` with code `archiveLimitExceeded` (a requested limit) or `archiveRejected` (a format, path, or link rule), and the inspector stops reading at the first violation and closes the source. Aborting the signal or calling `stop()` kills the inspector; the call rejects only after the process exited. The inspection does not use the management channel, so several can run at once.
 
+## Git LFS pointers
+
+`listRepositoryLfsPointers()` returns the distinct Git LFS pointers (`{ oid, sizeBytes }`) in the blobs reachable from any ref; pointers that disagree about an object's size make it throw. The scan is bounded: at most 250,000 reachable objects, 100,000 pointer candidates (blobs of 1 to 1,024 bytes), 64 MiB of object listing and of object metadata, and 128 MiB of candidate content. A scan over any bound throws a `GitManagerError` with code `lfsScanLimitExceeded` and returns nothing; its message names the bound, and the pointer set is unknown rather than empty. Other failures stay plain errors.
+
+```ts
+let pointers: IGitManagerRepositoryLfsPointer[] | null;
+try {
+  pointers = await gitManager.listRepositoryLfsPointers({ org, repo });
+} catch (error) {
+  if (!(error instanceof GitManagerError) || error.code !== 'lfsScanLimitExceeded') {
+    throw error;
+  }
+  pointers = null; // too large to scan: the LFS state is unread, not empty
+}
+```
+
 ## Public API
 
 - `GitManager`: TypeScript facade for the Rust engine lifecycle.
@@ -468,7 +519,7 @@ The metadata is recomputed from the bytes, so compare it with what the sender de
 - `GitManager.importMirror()`: imports a remote repository with `git clone --mirror`. Supported remote forms are `https://`, `http://`, `ssh://`, `git://`, `file://`, and SCP-like `git@host:org/repo.git` URLs.
 - `GitManager.refreshMirror()`: atomically fetches and verifies the configured mirror source and mirrors its default branch.
 - `GitManager.importMirror()` and `GitManager.refreshMirror()` accept a `credential`, `caCertificates` and `timeoutMs`; see [Credentialed mirrors and repository size](#credentialed-mirrors-and-repository-size).
-- `GitManager.pushRefs()`: pushes leased ref updates to an `https` or loopback-IP `http` remote as one atomic transaction; see [Atomic pushes and the default branch](#atomic-pushes-and-the-default-branch).
+- `GitManager.pushRefs()`: pushes leased ref updates to an `https` or loopback-IP `http` remote, or with an `sshKey` credential to an `ssh://` remote, as one atomic transaction and returns the remote's messages; see [Atomic pushes and the default branch](#atomic-pushes-and-the-default-branch) and [SSH pushes](#ssh-pushes).
 - `GitManager.importMirror(request, { signal? })`, `GitManager.refreshMirror(request, { signal? })` and `GitManager.pushRefs(request, { signal? })` run concurrently with other commands, hold mirror repositories against writes (`repositoryBusy`) and reject with `transferAborted` when aborted; see [Cancellation, concurrency and stop](#cancellation-concurrency-and-stop).
 - `GitManager.setDefaultBranch()`: points a repository's HEAD at an existing branch, or with `allowUnborn` at one a later push creates.
 - `GitManager.getRepositorySize()`: returns the exact object count, uncompressed object bytes and on-disk object storage bytes of a repository.
@@ -481,6 +532,7 @@ The metadata is recomputed from the bytes, so compare it with what the sender de
 - `GitManager.releaseRepositoryService(ticketId)`: releases a receive-pack's guard ticket; unknown or released tickets are a no-op.
 - `GitManager.listRepositories()`: lists local repositories managed below the configured data directory.
 - `GitManager.listRefs()`: lists one coherent page of the complete ref inventory of every namespace, with peeled tags, symbolic refs, HEAD, and a digest-bound cursor.
+- `GitManager.listRepositoryLfsPointers()`: lists the distinct Git LFS pointers reachable from any ref; a scan over its bounds throws `lfsScanLimitExceeded`; see [Git LFS pointers](#git-lfs-pointers).
 - `GitManager.listTree()`: lists tree entries at a ref and optional path.
 - `GitManager.readFile()`: reads a blob as base64 after checking the blob size limit.
 - `GitManager.listCommits()`: lists commit summaries for a ref.
@@ -503,7 +555,7 @@ Read APIs and Smart HTTP use the system `git` CLI with explicit arguments, non-i
 
 ## Rust Build
 
-The package builds a Rust binary named `rustgitmanager` from `rust/` using `@git.zone/tsrust`.
+The package builds a Rust binary named `rustgitmanager` from `rust/` using `@git.zone/rsrepo`.
 
 Configured targets:
 
@@ -520,7 +572,7 @@ pnpm run test:rust
 pnpm run build
 ```
 
-`pnpm test` runs the `pretest` hook first, which builds the Rust binaries with `tsrust`, and then runs lifecycle, bounded readiness, local mirror/read API, raw upload-pack/receive-pack preparation, clone/fetch denial, trusted receive-pack denial, explicit policy initialization, protected create/delete/non-fast-forward enforcement, inherited self-test hardening, restart replay, and real push tests through `smartrust`. `test/test.refinventory.node.ts` covers every ref namespace, peeled and nested tags, symbolic and dangling symbolic refs, unborn HEAD, prefix selection and exact lookup, ref names that are not valid UTF-8, pagination of 1,001 refs, stale and foreign cursors, 50,000 loose and packed refs, and a bundle round trip across namespaces. `test/test.pushlimits.node.ts` covers fixed-length and chunked Smart HTTP pushes over the limit, a complete pack followed by late excess bytes, an over-limit SSH-style receive-pack, an SSH-style receive-pack cut after Git already moved a ref (the update stays), and a bounded `stop()` while a service's output is never read, the rejected cases proving the refs unchanged, no Git or hook process left, no uncaught stream error, the engine serving, and a later push succeeding. `test/test.repositorybundles.node.ts` covers bundles of a repository whose only refs are notes and of one without its default branch (restored with HEAD on the unborn default branch), the refusal of a repository without refs, `bundleLimitExceeded` leaving no file, `replaceRepository()` with a bundle and without one, and a failed replacement that keeps the live repository and leaves no scratch. `test/test.protectedrefs.node.ts` covers `evaluateProtectedRefUpdates()` for every rule, unprotected refs, missing old objects and invalid requests, names the one protected ref among 1,003 updates and counts the engine's Git processes through a PATH wrapper (3 for one protected update, 66 for 64 protected updates on a 2,000-commit history with 500 tags), pins the pre-receive hook's decline messages over Smart HTTP, shows that the hook refuses an update and a deletion naming a missing old object even where the rule allows force pushes and deletions, and renames a default branch in one atomic Smart HTTP push after `setDefaultBranch()` with `allowUnborn` (refused while HEAD names the deleted branch, HEAD left unborn by a declined push and recovered without the flag, a missing branch still refused without it). `test/test.ancestry.node.ts` covers ancestors, the reverse direction, siblings, merges, unrelated histories, the same commit, invalid, missing and non-commit objects, a budget exceeded on a 20,000-commit history next to the exact answer, and a stalled walk whose Git process is killed. `test/test.remotetransfer.node.ts` serves fixtures through `git http-backend` over HTTPS with a private CA and over plain HTTP on `127.0.0.1` and `[::1]`, and covers credentialed mirror imports and refreshes, the source default branch on import and refresh, `setDefaultBranch()`, the push URL policy, atomic creates, updates and deletes, stale leases that change no ref, a remote without the `atomic` capability, 5,000 creates and 5,000 deletes in one receive-pack request with no command line naming a ref, a stale lease on the last of 1,500 updates that changes no ref, a pre-receive hook that declines a push and an update hook that declines one ref (the others failing as collateral), the `reason` of every ref that is not `ok`, and the credential staying out of every command line, error and file. Its fixture can hold or refuse a receive-pack request, which covers a ref that moves between the listing and the push (the remote fails all 1,500 updates) and a `413` answer (`remoteLimitExceeded`, no ref changed). It can also withhold pack requests to stall a transfer midway, which covers aborting an import (no repository or scratch left), a refresh (refs and HEAD unchanged) and a push, a push aborted before it sends its updates that changes nothing, other commands and transfers completing while transfers stall, `repositoryBusy` (including `replaceRepository()`) and the Smart HTTP `503` while a mirror refreshes, an atomic refresh that prunes nothing when one ref update fails, a refresh that times out inside its ref transaction without leaving lock files, a refresh refused during a Smart HTTP push, the receive-pack guard ticket (refused while held, admitted after release, idempotent release, released by `stop()`, released when its preparation times out on the bridge after the engine issued it), a bounded `stop()` during a stalled transfer, and a credentialed loopback `http` push that never reaches the `http_proxy`, `all_proxy` and `ALL_PROXY` set in the engine's environment. `test/test.archiveinspection.node.ts` runs every ci-spec archive conformance vector through `inspectArchive()` as bytes and as a chunked stream, the compressed limit at its boundary, an 8 MiB streamed archive, an early refusal that closes the source, and abort, source failure and `stop()` during an inspection.
+`pnpm test` runs the `pretest` hook first, which builds the Rust binaries with `rsrepo`, and then runs lifecycle, bounded readiness, local mirror/read API, raw upload-pack/receive-pack preparation, clone/fetch denial, trusted receive-pack denial, explicit policy initialization, protected create/delete/non-fast-forward enforcement, inherited self-test hardening, restart replay, and real push tests through `smartrust`. `test/test.refinventory.node.ts` covers every ref namespace, peeled and nested tags, symbolic and dangling symbolic refs, unborn HEAD, prefix selection and exact lookup, ref names that are not valid UTF-8, pagination of 1,001 refs, stale and foreign cursors, 50,000 loose and packed refs, and a bundle round trip across namespaces. `test/test.pushlimits.node.ts` covers fixed-length and chunked Smart HTTP pushes over the limit, a complete pack followed by late excess bytes, an over-limit SSH-style receive-pack, an SSH-style receive-pack cut after Git already moved a ref (the update stays), and a bounded `stop()` while a service's output is never read, the rejected cases proving the refs unchanged, no Git or hook process left, no uncaught stream error, the engine serving, and a later push succeeding. `test/test.repositorybundles.node.ts` covers bundles of a repository whose only refs are notes and of one without its default branch (restored with HEAD on the unborn default branch), the refusal of a repository without refs, `bundleLimitExceeded` leaving no file, `replaceRepository()` with a bundle and without one, and a failed replacement that keeps the live repository and leaves no scratch. `test/test.protectedrefs.node.ts` covers `evaluateProtectedRefUpdates()` for every rule, unprotected refs, missing old objects and invalid requests, names the one protected ref among 1,003 updates and counts the engine's Git processes through a PATH wrapper (3 for one protected update, 66 for 64 protected updates on a 2,000-commit history with 500 tags), pins the pre-receive hook's decline messages over Smart HTTP, shows that the hook refuses an update and a deletion naming a missing old object even where the rule allows force pushes and deletions, and renames a default branch in one atomic Smart HTTP push after `setDefaultBranch()` with `allowUnborn` (refused while HEAD names the deleted branch, HEAD left unborn by a declined push and recovered without the flag, a missing branch still refused without it). `test/test.ancestry.node.ts` covers ancestors, the reverse direction, siblings, merges, unrelated histories, the same commit, invalid, missing and non-commit objects, a budget exceeded on a 20,000-commit history next to the exact answer, and a stalled walk whose Git process is killed. `test/test.remotetransfer.node.ts` serves fixtures through `git http-backend` over HTTPS with a private CA and over plain HTTP on `127.0.0.1` and `[::1]`, and covers credentialed mirror imports and refreshes, the source default branch on import and refresh, `setDefaultBranch()`, the push URL policy, atomic creates, updates and deletes, stale leases that change no ref, a remote without the `atomic` capability, 5,000 creates and 5,000 deletes in one receive-pack request with no command line naming a ref, a stale lease on the last of 1,500 updates that changes no ref, a pre-receive hook that declines a push and an update hook that declines one ref (the others failing as collateral), with their `remoteMessages`, the `reason` of every ref that is not `ok`, and the credential staying out of every command line, error and file. Its fixture can hold or refuse a receive-pack request, which covers a ref that moves between the listing and the push (the remote fails all 1,500 updates) and a `413` answer (`remoteLimitExceeded`, no ref changed). It can also withhold pack requests to stall a transfer midway, which covers aborting an import (no repository or scratch left), a refresh (refs and HEAD unchanged) and a push, a push aborted before it sends its updates that changes nothing, other commands and transfers completing while transfers stall, `repositoryBusy` (including `replaceRepository()`) and the Smart HTTP `503` while a mirror refreshes, an atomic refresh that prunes nothing when one ref update fails, a refresh that times out inside its ref transaction without leaving lock files, a refresh refused during a Smart HTTP push, the receive-pack guard ticket (refused while held, admitted after release, idempotent release, released by `stop()`, released when its preparation times out on the bridge after the engine issued it), a bounded `stop()` during a stalled transfer, and a credentialed loopback `http` push that never reaches the `http_proxy`, `all_proxy` and `ALL_PROXY` set in the engine's environment. `test/test.sshpush.node.ts` needs `/usr/sbin/sshd`, `ssh`, `ssh-keygen` and `git-shell`: it starts an unprivileged `sshd` on `127.0.0.1` whose authorized keys run `git-shell`, and records every `ssh` and `git` command line through PATH wrappers. It pins the OpenSSH client texts the engine classifies against the system `ssh`, and covers an accepted push with the key only as a `0600` file in a `0700` directory that is gone afterwards, leased updates and deletes, a stale lease and an up-to-date ref decided without `send-pack`, a PEM RSA key, a declining hook (`hook-declined` with the nonce in `remoteMessages`), the bounds, truncation marker and redaction of `remoteMessages`, `sshHostKeyMismatch` before the key is offered, an unoffered host key type, `sshAuthenticationFailed`, `remoteConnectionRefused`, `remoteProtocolError` for a missing repository, `atomicPushUnsupported`, the refusals of URLs, users, hosts, paths, keys and transport mismatches before `ssh` runs, an abort while `ssh` runs (directory removed), the startup sweep of a stale key directory, and no key text in any command line, error or engine log. `test/test.archiveinspection.node.ts` runs every ci-spec archive conformance vector through `inspectArchive()` as bytes and as a chunked stream, the compressed limit at its boundary, an 8 MiB streamed archive, an early refusal that closes the source, and abort, source failure and `stop()` during an inspection.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/gitmanager',
-  version: '2.9.0',
+  version: '2.11.0',
   description: 'Headless Git manager for the foss.global Git platform, with a TypeScript API and Rust engine.'
 }

package/ts/classes.gitmanager.ts

@@ -61,25 +61,25 @@ const readinessDefaultTimeoutMs = 2_000;
 const readinessMaximumTimeoutMs = 30_000;
 const remoteTransferMaximumTimeoutMs = 21_600_000;
 
-/**
- * Checks transfer options before they reach the engine, which answers a
- * malformed credential-bearing request with fixed text only. Messages never
- * quote a credential value.
- */
-const assertRemoteTransferOptions = (optionsArg: IGitManagerRemoteTransferOptions): void => {
-  const { credential, caCertificates, timeoutMs } = optionsArg;
-  if (credential !== undefined) {
-    if (
-      credential === null
-      || typeof credential !== 'object'
-      || credential.kind !== 'basic'
-      || typeof credential.username !== 'string'
-      || typeof credential.password !== 'string'
-      || Object.keys(credential).some((key) => !['kind', 'username', 'password'].includes(key))
-    ) {
-      throw new TypeError('credential must be { kind: "basic", username: string, password: string }');
-    }
+/** Whether `valueArg` is an object with exactly `kind` and the named string fields. */
+const isCredentialShape = (valueArg: unknown, kindArg: string, fieldsArg: string[]): boolean => {
+  if (valueArg === null || typeof valueArg !== 'object') {
+    return false;
   }
+  const record = valueArg as Record<string, unknown>;
+  return record.kind === kindArg
+    && fieldsArg.every((field) => typeof record[field] === 'string')
+    && Object.keys(record).every((key) => key === 'kind' || fieldsArg.includes(key));
+};
+
+const basicCredentialFields = ['username', 'password'];
+const sshKeyCredentialFields = ['privateKey', 'hostKey'];
+
+/** Checks the CA bundle and the time limit of a remote transfer. */
+const assertTransferLimits = (
+  optionsArg: Pick<IGitManagerRemoteTransferOptions, 'caCertificates' | 'timeoutMs'>,
+): void => {
+  const { caCertificates, timeoutMs } = optionsArg;
   if (
     caCertificates !== undefined
     && (!Array.isArray(caCertificates) || caCertificates.some((certificate) => typeof certificate !== 'string'))
@@ -94,6 +94,38 @@ const assertRemoteTransferOptions = (optionsArg: IGitManagerRemoteTransferOption
   }
 };
 
+/**
+ * Checks transfer options before they reach the engine, which answers a
+ * malformed credential-bearing request with fixed text only. Messages never
+ * quote a credential value.
+ */
+const assertRemoteTransferOptions = (optionsArg: IGitManagerRemoteTransferOptions): void => {
+  const { credential } = optionsArg;
+  if (credential !== undefined && !isCredentialShape(credential, 'basic', basicCredentialFields)) {
+    throw new TypeError('credential must be { kind: "basic", username: string, password: string }');
+  }
+  assertTransferLimits(optionsArg);
+};
+
+/**
+ * Checks the options of a push, whose credential may also be an SSH key, as
+ * `assertRemoteTransferOptions` does. The engine validates the key, the host
+ * key and the URL.
+ */
+const assertAtomicPushOptions = (requestArg: IGitManagerAtomicPushRequest): void => {
+  const { credential } = requestArg;
+  if (
+    credential !== undefined
+    && !isCredentialShape(credential, 'basic', basicCredentialFields)
+    && !isCredentialShape(credential, 'sshKey', sshKeyCredentialFields)
+  ) {
+    throw new TypeError(
+      'credential must be { kind: "basic", username: string, password: string } or { kind: "sshKey", privateKey: string, hostKey: string }',
+    );
+  }
+  assertTransferLimits(requestArg);
+};
+
 /**
  * Checks the shape of push updates before they reach the engine, which
  * answers a malformed request with fixed text only. Ref names and object IDs
@@ -463,7 +495,22 @@ export class GitManager extends plugins.EventEmitter {
    * throws `remoteLimitExceeded`, and nothing is pushed. `remoteUrl` must
    * be `https`, or `http` to a loopback IP address (`127.0.0.0/8`, `[::1]`;
    * never a host name such as `localhost`), without user information; the
-   * credential travels as for `importMirror`. A ref that already holds its
+   * credential travels as for `importMirror`.
+   *
+   * With an `sshKey` credential, and only with one, `remoteUrl` is
+   * `ssh://<user>@<host>[:<port>]/<path>` and the push runs over the system
+   * `ssh` client: the key exists for the push only, as a file readable by the
+   * engine alone, and the remote must present exactly the pinned `hostKey`.
+   * A failure before the remote's ref advertisement throws one of
+   * `sshHostKeyMismatch`, `sshAuthenticationFailed`,
+   * `remoteConnectionRefused`, `remoteConnectionFailed` or
+   * `remoteProtocolError`, and nothing is pushed. An `sshKey` credential
+   * without an `ssh://` URL, an `ssh://` URL without one, and
+   * `caCertificates` with one throw `remoteTransportMismatch` before anything
+   * runs. `remoteMessages` holds the remote's `remote:` lines, such as a
+   * hook's output, for every transport.
+   *
+   * A ref that already holds its
    * `newObjectId` is reported `ok` without its lease being checked; it is not
    * changed, so `ok` never means the lease matched. Any refusal the remote
    * reports per ref returns status `rejected`, with the refused refs `stale`
@@ -484,7 +531,7 @@ export class GitManager extends plugins.EventEmitter {
     optionsArg: IGitManagerTransferControlOptions = {},
   ): Promise<IGitManagerAtomicPushResult> {
     this.assertRunning();
-    assertRemoteTransferOptions(requestArg);
+    assertAtomicPushOptions(requestArg);
     assertAtomicPushUpdates(requestArg.updates);
     return this.bridge.pushRefs(requestArg, optionsArg);
   }
@@ -733,6 +780,13 @@ export class GitManager extends plugins.EventEmitter {
     return this.bridge.listRefs(requestArg);
   }
 
+  /**
+   * Lists the distinct Git LFS pointers reachable from any ref. A scan that
+   * exceeds one of its bounds (250,000 reachable objects, 100,000 blobs of
+   * 1 to 1,024 bytes, 64 MiB of object listing or metadata, 128 MiB of
+   * candidate content) throws a `GitManagerError` with code
+   * `lfsScanLimitExceeded`, whose message names the bound.
+   */
   public async listRepositoryLfsPointers(
     requestArg: IGitManagerRepositorySelector,
   ): Promise<IGitManagerRepositoryLfsPointer[]> {

package/ts/classes.gitmanagererror.ts

@@ -12,6 +12,13 @@ const gitManagerErrorCodes: ReadonlySet<string> = new Set<TGitManagerErrorCode>(
   'remoteLimitExceeded',
   'transferAborted',
   'repositoryBusy',
+  'lfsScanLimitExceeded',
+  'sshHostKeyMismatch',
+  'sshAuthenticationFailed',
+  'remoteConnectionRefused',
+  'remoteConnectionFailed',
+  'remoteProtocolError',
+  'remoteTransportMismatch',
 ]);
 
 export const isGitManagerErrorCode = (valueArg: unknown): valueArg is TGitManagerErrorCode =>

package/ts/models.ts

@@ -177,6 +177,32 @@ export interface IGitManagerArchiveInspection {
  *   remote; read its refs again.
  * - `repositoryBusy`: a mirror transfer holds the repository, or a write to
  *   it is in progress when a mirror transfer starts; nothing was changed.
+ * - `lfsScanLimitExceeded`: the Git LFS pointer scan of
+ *   `listRepositoryLfsPointers()` exceeded one of its bounds; the message
+ *   names the bound. The pointer set is unknown, never empty.
+ *
+ * An SSH push (`pushRefs()` with an `sshKey` credential) that fails before
+ * the remote's ref advertisement is complete throws one of the following;
+ * nothing was pushed. They are classified from the exit status 255 and the
+ * fixed texts of the local OpenSSH client, and the message carries ssh's
+ * redacted standard error for operator logs only.
+ *
+ * - `sshHostKeyMismatch`: the remote's host key is not the pinned `hostKey`;
+ *   the key was never offered.
+ * - `sshAuthenticationFailed`: the remote refused the SSH key.
+ * - `remoteConnectionRefused`: the remote host refused the TCP connection.
+ * - `remoteConnectionFailed`: any other failure of the SSH connection, such
+ *   as an unknown host, a timeout of the connection, or a server that does
+ *   not offer the pinned key's type.
+ * - `remoteProtocolError`: the remote command ran but did not answer with a
+ *   Git receive-pack advertisement (or one without `report-status`), such as
+ *   a forge that refuses SSH with a message or a missing repository.
+ *
+ * - `remoteTransportMismatch`: a push's credential or options do not fit the
+ *   transport of its `remoteUrl`: an `sshKey` credential without an
+ *   `ssh://` URL, an `ssh://` URL without an `sshKey` credential, or
+ *   `caCertificates` with an `sshKey` credential. Refused before anything
+ *   runs; nothing was pushed.
  */
 export type TGitManagerErrorCode =
   | 'invalidObjectId'
@@ -189,7 +215,14 @@ export type TGitManagerErrorCode =
   | 'atomicPushUnsupported'
   | 'remoteLimitExceeded'
   | 'transferAborted'
-  | 'repositoryBusy';
+  | 'repositoryBusy'
+  | 'lfsScanLimitExceeded'
+  | 'sshHostKeyMismatch'
+  | 'sshAuthenticationFailed'
+  | 'remoteConnectionRefused'
+  | 'remoteConnectionFailed'
+  | 'remoteProtocolError'
+  | 'remoteTransportMismatch';
 
 export interface IGitManagerRepositoryLfsPointer {
   oid: string;
@@ -381,6 +414,7 @@ export type {
   IGitManagerRefRequest,
   IGitManagerRefreshMirrorRequest,
   IGitManagerRemoteBasicCredential,
+  IGitManagerRemoteSshKeyCredential,
   IGitManagerRemoteTransferOptions,
   IGitManagerRepositoryInfo,
   IGitManagerRepositorySelector,
@@ -390,6 +424,7 @@ export type {
   IGitManagerTagRequest,
   IGitManagerTreeEntry,
   IGitManagerTreeRequest,
+  TGitManagerAtomicPushCredential,
   TGitManagerAtomicPushRefReason,
   TGitManagerAtomicPushRefStatus,
   TGitManagerDiffFileStatus,

package/ts/rust-gitmanager-bridge.ts

@@ -450,7 +450,7 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
   public async listRepositoryLfsPointers(
     requestArg: IGitManagerRepositorySelector,
   ): Promise<IGitManagerRepositoryLfsPointer[]> {
-    return this.bridge.sendCommand('listRepositoryLfsPointers', requestArg);
+    return this.bridge.sendCommand('listRepositoryLfsPointers', requestArg).catch(rethrowCodedError);
   }
 
   public async mergeRepository(

package/native-notices/crates/aho-corasick-1.1.4/copying

@@ -1,3 +0,0 @@
-This project is dual-licensed under the Unlicense and MIT licenses.
-
-You may use this code under the terms of either license.

package/native-notices/crates/aho-corasick-1.1.4/license-mit

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2015 Andrew Gallant
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

package/native-notices/crates/aho-corasick-1.1.4/unlicense

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <http://unlicense.org/>