@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 +9 -9
- package/docs/gateway.md +4 -2
- package/docs/jobdb-secret-provider.md +39 -30
- package/examples/jobdb-gitvend-issuer.yaml +0 -1
- package/package.json +1 -1
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.
|
|
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.
|
|
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.
|
|
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.
|
|
60
|
-
- [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
61
|
-
- [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
62
|
-
- [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
63
|
-
- [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
64
|
-
- [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
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
|
|
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
|
|
43
|
-
|
|
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
|
|
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 `
|
|
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/
|
|
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
|
|
186
|
+
## Cell ownership and authorization
|
|
186
187
|
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
"
|
|
193
|
-
"
|
|
194
|
-
"
|
|
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.
|
|
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,
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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
|
|
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 `
|
|
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. |
|
package/package.json
CHANGED