@colony2/gitvend 0.0.7 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,7 +16,7 @@ The gateway supports GitHub and GitHub Enterprise-compatible endpoints. It needs
16
16
  no database or GitHub App. Agents connect over HTTPS; GitHub's own access and
17
17
  branch rules continue to apply.
18
18
 
19
- [Set up and use the gateway →](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/gateway.md)
19
+ [Set up and use the gateway →](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/gateway.md)
20
20
 
21
21
  ## JobDB plugin
22
22
 
@@ -29,7 +29,7 @@ The plugin keeps its signing key on the JobDB host, and the gateway verifies the
29
29
  resulting tokens with the matching public key. Workers receive neither the
30
30
  signing key nor the upstream GitHub token.
31
31
 
32
- [Set up the JobDB plugin →](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/jobdb-secret-provider.md)
32
+ [Set up the JobDB plugin →](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/jobdb-secret-provider.md)
33
33
 
34
34
  ## Install
35
35
 
@@ -52,13 +52,13 @@ that includes `jobdb-gitvend-secret-provider` when using the plugin; older packa
52
52
  may contain only `gitvend`.
53
53
 
54
54
  For a container deployment, use the published image with the
55
- [Docker Compose guide](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/docker-compose.md).
55
+ [Docker Compose guide](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/docker-compose.md).
56
56
 
57
57
  ## Guides
58
58
 
59
- - [Gateway setup, Git usage, and operations](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/gateway.md)
60
- - [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/gateway.md#repository-creation-defaults)
61
- - [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/jobdb-secret-provider.md)
62
- - [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/permission-syntax.md)
63
- - [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/docker-compose.md)
64
- - [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.7/docs/development.md)
59
+ - [Gateway setup, Git usage, and operations](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/gateway.md)
60
+ - [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/gateway.md#repository-creation-defaults)
61
+ - [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/jobdb-secret-provider.md)
62
+ - [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/permission-syntax.md)
63
+ - [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/docker-compose.md)
64
+ - [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.9/docs/development.md)
package/docs/gateway.md CHANGED
@@ -132,10 +132,12 @@ Expected response: `ok`. This is a liveness check; it does not verify a JWT or c
132
132
  The remote URL has this structure:
133
133
 
134
134
  ```text
135
- https://GATEWAY/PROVIDER_ALIAS/OWNER/REPOSITORY.git
135
+ https://GATEWAY/PROVIDER_ALIAS/OWNER/REPOSITORY[.git]
136
136
  https://git-gateway.example:8443/github/fooorg/project.git
137
137
  ```
138
138
 
139
+ The `.git` suffix is optional for discovery, fetch and push. Both URL forms use the same repository identity, credentials and permissions; `[.git]` above denotes optional text, not literal brackets.
140
+
139
141
  The `github` segment is the configured provider alias. Permission strings use the configured upstream authority (`github.com`), not that alias or the gateway hostname. Repository permission patterns omit the `.git` suffix. Add more provider entries for distinct GitHub-compatible endpoints or owner/credential mappings; overlapping host/owner routes are rejected. Other forge APIs require an adapter.
140
142
 
141
143
  ### Running behind a TLS terminator
@@ -415,7 +417,7 @@ Start with `gitvend version`, `/healthz`, and `git ls-remote --heads` as shown a
415
417
  | `Git protocol v2 required` | Set `protocol.version=2`; ensure an ingress proxy preserves the `Git-Protocol` header. Pushes still use standard receive-pack. |
416
418
  | HTTP 403 / `push denied for ...` | Inspect the exact destination ref, matching `r` plus `w`/`d` grants, issuer/owner limits and gateway denies. The sample denies writes to main/master. |
417
419
  | No refs shown; clone cannot find main or remote HEAD | The requested branch may be absent or hidden. Use an explicitly permitted branch with `--branch`; new scratch repos may have only `agents/47/start`. |
418
- | HTTP 404 / unsupported route or missing repository | Use `/alias/owner/repo.git`, check allowed owners, and verify the upstream identity can see the repository. Only authorized push discovery can create a missing repo. |
420
+ | HTTP 404 / unsupported route or missing repository | Use `/alias/owner/repo` or `/alias/owner/repo.git`, check allowed owners, and verify the upstream identity can see the repository. Only authorized push discovery can create a missing repo. |
419
421
  | Missing repo is not created | Check `allow_creation`, `c`, overlapping branch `rw`, owner limits and upstream organization permissions. Check the audit logs for an unconfirmed create attempt. |
420
422
  | HTTP 429 / gateway busy | The concurrent-request limit is reached. Wait for active requests to finish and retry. |
421
423
  | HTTP 409 / creation visibility violation | A creation attempt resolved to unexpected visibility. Investigate the upstream name/visibility; gitvend will not alter it automatically. |
@@ -17,7 +17,7 @@ It returns only requested, authorized secret names:
17
17
 
18
18
  These are signed JWT **tokens**, not signing keys. Both lists accept the standard
19
19
  [Gitvend permission syntax](permission-syntax.md), including `r`, `w`, `d`, `c`,
20
- ref selectors, and denies. A base-token request does not need cell metadata.
20
+ ref selectors, and denies. A base-token request does not need cell context.
21
21
  Matching denies still win across both lists and the gateway's deny rules.
22
22
 
23
23
  ## Install
@@ -39,8 +39,10 @@ contain only the gateway; use a release that includes the plugin.
39
39
  The npm installer places a native executable at the plugin command path, so
40
40
  JobDB does not need Node.js or `PATH` in the plugin environment.
41
41
 
42
- Use a JobDB version with secret-provider plugin support. JobDB must be able to
43
- execute the installed command and read the issuer configuration and signing key.
42
+ Use JobDB v0.0.72 or later, with verified cell context in its secret-provider
43
+ plugin protocol. JobDB must be able to execute the installed command and read
44
+ the issuer configuration and signing key. Older hosts can still receive base
45
+ tokens, but cannot authorize cell tokens without verified cell context.
44
46
 
45
47
  ## Configure the issuer
46
48
 
@@ -62,7 +64,6 @@ issuer: jobdb
62
64
  audience: gitvend
63
65
  key_id: jobdb
64
66
  signing_key_file: signing.key
65
- cell_metadata_field: repo
66
67
  tenants:
67
68
  YOUR_TENANT_ID:
68
69
  base_permissions:
@@ -108,8 +109,8 @@ principals:
108
109
 
109
110
  `base_permissions` applies to both tokens, including the target repository.
110
111
  `target_permissions` grants additional authority only for the repository selected
111
- by metadata. For example, this tenant policy allows all accessible GitHub reads
112
- and read/write/create on the target cell if it belongs to `colony-2`:
112
+ by verified cell ownership. For example, this tenant policy allows all accessible
113
+ GitHub reads and read/write/create on the target cell if it belongs to `colony-2`:
113
114
 
114
115
  ```yaml
115
116
  base_permissions:
@@ -118,7 +119,7 @@ target_permissions:
118
119
  - github.com/colony-2/*:rwc
119
120
  ```
120
121
 
121
- For `AppMetadata.repo = "https://github.com/colony-2/my-cell.git"`, the cell JWT
122
+ For `Lease.Cell.CellRepo = "github.com/colony-2/my-cell"`, the cell JWT
122
123
  contains `github.com/*:r` and `github.com/colony-2/my-cell:rwc`. It does not grant
123
124
  writes or creation to any other cell. A target rule such as
124
125
  `github.com/colony-2/*#work/*:rw` retains its branch selector after narrowing.
@@ -172,7 +173,7 @@ jobdb sqlite --db ./jobdb.db --secret-providers-file /absolute/path/to/providers
172
173
  ```
173
174
 
174
175
  Other providers, including SQLite, can coexist in the same provider file; the first entry for each secret name wins. See
175
- [the provider guide](https://github.com/colony-2/jobdb/blob/f403447cb58a7195e32a55fb7f417e09da70f388/docs/GUIDE-SECRET-PROVIDERS.md) for collection behavior.
176
+ [the provider guide](https://github.com/colony-2/jobdb/blob/v0.0.72/docs/GUIDE-SECRET-PROVIDERS.md) for collection behavior.
176
177
  An omission here cannot veto a grant from a different provider.
177
178
 
178
179
  The worker requests either or both names through JobDB's normal secret-resolution
@@ -182,39 +183,47 @@ the gateway's Git URL, for example
182
183
  Follow the [agent authentication instructions](gateway.md#configure-git-authentication)
183
184
  to configure the Git credential helper.
184
185
 
185
- ## Cell metadata and authorization
186
+ ## Cell ownership and authorization
186
187
 
187
- The default `cell_metadata_field` is `repo`, matching c2j's target repository
188
- metadata. It is a top-level field in `SecretResolveRequest.AppMetadata`, e.g.:
188
+ Cell tokens use `SecretResolveRequest.Lease.Cell.CellRepo`, supplied by the
189
+ JobDB broker from the job's stored cell ownership. The verified context includes
190
+ a stable cell ID, a cell name, and a repository locator, for example:
189
191
 
190
192
  ```json
191
193
  {
192
- "cell_id": "cell-123",
193
- "cell_name": "cell-one",
194
- "repo": "https://github.com/example-org/cell-one.git"
194
+ "cellId": "cell-123",
195
+ "cell": "cell-one",
196
+ "cellRepo": "github.com/example-org/cell-one"
195
197
  }
196
198
  ```
197
199
 
198
200
  Accepted repository forms are `https://host/owner/repo[.git]` and
199
201
  `host/owner/repo[.git]`. Owner/repository casing is normalized. Credentials, query
200
202
  strings, fragments, encoded paths, extra path segments and permission syntax are
201
- rejected. Configure a different field if your application uses another name;
202
- its value must still identify a repository, not an opaque cell ID. SSH URLs and
203
- cell-ID-to-repository lookups are not implemented.
203
+ rejected. SSH URLs and cell-ID-to-repository lookups are not implemented.
204
204
 
205
205
  The provider matches that repository against the **verified tenant's** configured
206
206
  target rules, then replaces each matching rule's repository pattern with the
207
207
  exact repository while preserving its actions, ref selector and deny flag.
208
- Missing, malformed or unauthorized metadata omits the cell token while leaving
209
- an independently authorized base token available. Unknown names and tenants are
210
- also omitted.
211
-
212
- Application metadata may be submitter-controlled. The configured target patterns
213
- are an authorization ceiling: authorized jobs in that tenant may select any
214
- matching cell. If individual jobs or principals must be confined to different
215
- cells within a tenant, a trusted job/principal-to-cell authorization lookup is
216
- needed before widening this model. Metadata by itself does not establish such
217
- a binding. `cell_id` and `cell_name` do not override `repo`.
208
+ Missing verified cell ID, missing or malformed repository, an empty target list,
209
+ or no matching target allow rule omits the cell token while leaving an independently
210
+ authorized base token available. Unknown names and unauthorized tenants/principals
211
+ are also omitted.
212
+
213
+ `AppMetadata` is never used to select a repository, even if verified cell context
214
+ is missing. Conflicting `repo`, `cellRepo`, cell IDs or names in application
215
+ metadata cannot override the verified cell. The deprecated `cell_metadata_field`
216
+ configuration option is accepted for compatibility but ignored; remove it from
217
+ new configurations. Jobs no longer need legacy repository metadata.
218
+
219
+ When a requested cell token is omitted, the provider emits a fixed diagnostic to
220
+ stderr identifying the missing cell context or tenant/principal/target-policy
221
+ condition. The JobDB CLI forwards it to the provider log. Diagnostics contain no
222
+ raw request fields, metadata, credentials or configuration values. The plugin
223
+ protocol has no per-secret diagnostic field and redacts error details, so these
224
+ reasons are available in the host log rather than the secret response. Library
225
+ embedders can capture them through Go's default `slog` logger; hosts using the
226
+ plugin SDK must configure `ProcessConfig.Logger` to forward process output.
218
227
 
219
228
  ## Private repository reads
220
229
 
@@ -273,8 +282,8 @@ new path and key ID; provision the corresponding gateway public key beforehand.
273
282
  Reloading does not revoke already issued JWTs or replace credentials cached by
274
283
  JobDB workflows. Use fresh secret resolution to obtain updated permissions.
275
284
  Diagnostics go to stderr without keys, JWTs, raw configuration, or raw errors;
276
- the JobDB host may suppress plugin output. Watching uses local filesystem events,
277
- with no periodic polling after successful loads. Network filesystems and changes
285
+ the JobDB CLI forwards them to its provider log. Watching uses local filesystem
286
+ events, with no periodic polling after successful loads. Network filesystems and changes
278
287
  to symlink targets outside the watched directories require a different update
279
288
  mechanism or restarting the plugin host.
280
289
 
@@ -295,7 +304,7 @@ mechanism or restarting the plugin host.
295
304
  | Command is missing after npm install | Use a release that includes the plugin, check `PATH`, and ensure npm install scripts ran. After fixing download/install-script errors, run `npm rebuild @colony2/gitvend`. |
296
305
  | Configuration validation fails | Check YAML field names, permission syntax, tenant IDs, and the signing-key path relative to the issuer file. |
297
306
  | Neither token is returned | Check the verified tenant/principal, requested secret names, and job lease authority. Unknown names and unauthorized tenants are omitted. |
298
- | Base token works but cell token is missing | Check `AppMetadata.repo`, `cell_metadata_field`, and whether a target allow rule matches that exact repository. |
307
+ | Base token works but cell token is missing | Check the provider log's `gitvend_cell_token unavailable` diagnostic, verified `Lease.Cell.CellID`/`CellRepo`, and whether a target allow rule matches that exact repository. Upgrade older JobDB hosts to pass cell context; application metadata cannot substitute for it. |
299
308
  | Gateway rejects a token | Check issuer, key ID, audience, signing key, clock tolerance, lifetime limits, and gateway owner allowlists. |
300
309
  | Cell push cannot create a repository | The target rules need `c` plus a readable/writable branch. Check the gateway's `allow_creation`, upstream permissions, and creation settings. |
301
310
  | Config changed but a worker still has old permissions | Obtain fresh secrets through JobDB. Already issued JWTs retain their permissions until expiry, and invalid replacements leave the last valid config active. |
@@ -7,7 +7,6 @@ max_token_bytes: 4096
7
7
  max_lifetime_seconds: 900
8
8
  gateway_leeway_seconds: 30
9
9
  clock_margin_seconds: 1
10
- cell_metadata_field: repo
11
10
  tenants:
12
11
  example:
13
12
  base_permissions:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@colony2/gitvend",
3
- "version": "0.0.7",
3
+ "version": "0.0.9",
4
4
  "description": "Git HTTPS gateway with signed repository and branch permissions",
5
5
  "license": "UNLICENSED",
6
6
  "homepage": "https://github.com/colony-2/gitvend",