@colony2/gitvend 0.0.4 → 0.0.5

package/README.md

@@ -16,7 +16,7 @@ The gateway supports GitHub and GitHub Enterprise-compatible endpoints. It needs
 no database or GitHub App. Agents connect over HTTPS; GitHub's own access and
 branch rules continue to apply.
 
-[Set up and use the gateway →](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/gateway.md)
+[Set up and use the gateway →](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/gateway.md)
 
 ## JobDB plugin
 
@@ -29,7 +29,7 @@ The plugin keeps its signing key on the JobDB host, and the gateway verifies the
 resulting tokens with the matching public key. Workers receive neither the
 signing key nor the upstream GitHub token.
 
-[Set up the JobDB plugin →](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/jobdb-secret-provider.md)
+[Set up the JobDB plugin →](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/jobdb-secret-provider.md)
 
 ## Install
 
@@ -52,13 +52,13 @@ that includes `jobdb-gitvend-secret-provider` when using the plugin; older packa
 may contain only `gitvend`.
 
 For a container deployment, use the published image with the
-[Docker Compose guide](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/docker-compose.md).
+[Docker Compose guide](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/docker-compose.md).
 
 ## Guides
 
-- [Gateway setup, Git usage, and operations](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/gateway.md)
-- [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/gateway.md#repository-creation-defaults)
-- [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/jobdb-secret-provider.md)
-- [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/permission-syntax.md)
-- [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/docker-compose.md)
-- [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/development.md)
+- [Gateway setup, Git usage, and operations](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/gateway.md)
+- [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/gateway.md#repository-creation-defaults)
+- [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/jobdb-secret-provider.md)
+- [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/permission-syntax.md)
+- [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/docker-compose.md)
+- [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.5/docs/development.md)

package/docs/development.md

@@ -83,6 +83,30 @@ Git features. See the [design](git-proxy-design.md) for requirements and tradeof
 [c2r](https://github.com/colony-2/c2r) informed the provisioning approach; Gitvend
 uses a direct GitHub adapter and copies no c2r source.
 
+### Git interoperability regression coverage
+
+Linux and macOS CI run the full race suite and vet, including actual Git clients
+and `git-http-backend`. The test jobs print the Git version they exercised.
+The local backend alone does not reproduce every GitHub response format; tests
+also inject the upload-pack service preamble observed from GitHub.
+
+| Behavior | Regression coverage |
+| --- | --- |
+| Upload-pack discovery | Bare v2 and service-header-prefixed v2; real discovery, clone and fetch; malformed headers and downgrades rejected. |
+| Push transport | Twelve real-Git scenarios: full/shallow checkout × new/existing branch × small/default-buffer-overflow/configured-buffer-overflow pack. Each attempts a denied push before an allowed one and verifies the remote ref. |
+| First push and upstream refusal | A large first push provisions and populates a new repository; shallow pushes to an upstream that refuses missing history remain rejected and do not create refs. |
+| HTTP authentication probes | Flush-only requests with fixed-length, chunked and gzip bodies; JWT and write authorization required; no upstream calls or repository creation. |
+| Shallow push metadata | Preserve declarations before ref commands and leave pack bytes unread; reject malformed or misplaced declarations and enforce command byte/ref limits. |
+| Malformed probes | Reject truncation, read errors, trailing commands, additional flushes and pack data. |
+
+When a production compatibility failure is reported, first add a test that
+reproduces its wire format or real-client behavior and fails on the existing code.
+For parser changes, include both accepted traffic and malformed/unauthorized
+variants, then seed the wire fuzzer with the new valid format. Statement coverage
+alone cannot establish protocol compatibility. These tests use local upstreams;
+they do not replace a deployment smoke test against GitHub with the operator's
+actual credentials and repository settings.
+
 ## Release automation
 
 The [release workflow](../.github/workflows/release.yaml) follows [c2j's release pattern](https://github.com/colony-2/c2j/blob/main/.github/workflows/release.yaml). Successful pushes to `main` in the `colony-2` organization run the test suite, automatically bump and push a version tag (patch by default), build both executables for four platforms, and publish GitHub release archives and checksums. It then publishes `@colony2/gitvend` to npm with `gitvend` and `jobdb-gitvend-secret-provider` commands after installing and smoke-testing the installed commands against the published assets. It also publishes Linux amd64/arm64 container images to `ghcr.io/colony-2/gitvend` with the release tag and `latest`, using `GITHUB_TOKEN` with package-write permission.

package/docs/gateway.md

@@ -355,6 +355,12 @@ jq -c 'select(.audit.operation == "git-receive-pack") | .audit' audit.jsonl
 
 Push audit distinguishes `accepted`, `rejected`, `partial` and `unknown`; HTTP 200 alone is not success. Creation outcomes are `created`, `reconciled`, `configuration_failed`, `rejected` or `unknown` and do not claim that a subsequent push succeeded. A crash can leave an admission with no final record. Log delivery is best-effort, with retention and durability handled by your logging infrastructure. Inspect the remote refs before retrying an interrupted push; gitvend never retries a push automatically.
 
+Large pushes can begin with a flush-only HTTP authentication probe. These are
+logged as `git-receive-pack-probe`; an accepted probe means the gateway accepted
+the credential and found writable refs. It does not verify upstream permissions,
+create a repository, or update any refs. The subsequent push is authorized and
+audited separately as `git-receive-pack`.
+
 ### Multiple instances
 
 Run any number of instances behind the same HTTPS endpoint with matching configuration, trusted keys and credentials. No shared disk, database, distributed lock or sticky session is required. Configuration/key rotations must reach each instance; a reload on one instance does not update others. `max_concurrent` and request limits apply per instance. If you need fleet-wide rate limits or creation budgets, enforce them outside gitvend. A metrics export endpoint is not implemented.
@@ -430,7 +436,9 @@ legacy single-dash long flags. For credential helpers, Git appends the final ope
 
 ## Compatibility
 
-Supported object format is SHA-1. SSH, Git LFS, Git protocol v0/v1 fetch, signed push certificates, push options, named shallow exclusions, ref-in-want, offloaded pack/bundle URLs and provider-managed ref namespaces are rejected or not advertised. Branch writes can include workflow files; CI execution and secrets remain governed by the forge's configuration. GitHub branch rules continue to apply to the shared upstream identity.
+Supported object format is SHA-1. Pushes from shallow clones and streamed large
+pushes are supported; the upstream still validates object connectivity and can
+reject a push with missing history. SSH, Git LFS, Git protocol v0/v1 fetch, signed push certificates, push options, named shallow exclusions, ref-in-want, offloaded pack/bundle URLs and provider-managed ref namespaces are rejected or not advertised. Branch writes can include workflow files; CI execution and secrets remain governed by the forge's configuration. GitHub branch rules continue to apply to the shared upstream identity.
 
 Use a disposable repository to confirm your upstream token, organization creation
 policy, workflow permissions and GitHub Enterprise version before rolling out to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colony2/gitvend",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Git HTTPS gateway with signed repository and branch permissions",
   "license": "UNLICENSED",
   "homepage": "https://github.com/colony-2/gitvend",