@colony2/gitvend 0.0.3 → 0.0.5

package/docs/jobdb-secret-provider.md

@@ -0,0 +1,303 @@
+# Gitvend secret-provider plugin for JobDB
+
+The JobDB plugin gives workers short-lived Gitvend credentials for their jobs.
+You configure permissions per tenant and additional permissions for the target
+cell repository. JobDB starts the plugin when needed and passes verified job and
+lease information. The plugin signs tokens locally; the gateway needs only the
+matching public key. Workers never receive the GitHub token or private signing key.
+
+Set up a [Gitvend gateway](gateway.md) first, or configure it alongside the plugin.
+The plugin runs on the JobDB host; it does not replace the gateway.
+It returns only requested, authorized secret names:
+
+| Secret name | JWT permissions |
+| --- | --- |
+| `gitvend_base_token` | The configured tenant `base_permissions`, unchanged. |
+| `gitvend_cell_token` | Base permissions plus matching `target_permissions`, narrowed to the exact target cell repository. |
+
+These are signed JWT **tokens**, not signing keys. Both lists accept the standard
+[Gitvend permission syntax](permission-syntax.md), including `r`, `w`, `d`, `c`,
+ref selectors, and denies. A base-token request does not need cell metadata.
+Matching denies still win across both lists and the gateway's deny rules.
+
+## Install
+
+On the host where JobDB runs, install the package:
+
+```sh
+npm install -g @colony2/gitvend
+jobdb-gitvend-secret-provider --help
+```
+
+The package supplies prebuilt `gitvend` and `jobdb-gitvend-secret-provider`
+executables for Linux/macOS on amd64/arm64. npm requires Node.js 22+, `tar`, and
+enabled install scripts. For installation without Node.js, download a
+[release archive](https://github.com/colony-2/gitvend/releases) containing both
+executables, verify its checksum, and put them on `PATH`. Older releases may
+contain only the gateway; use a release that includes the plugin.
+
+The npm installer places a native executable at the plugin command path, so
+JobDB does not need Node.js or `PATH` in the plugin environment.
+
+Use a JobDB version with secret-provider plugin support. JobDB must be able to
+execute the installed command and read the issuer configuration and signing key.
+
+## Configure the issuer
+
+Configuration uses YAML. Unknown fields, duplicate keys and multiple documents
+are rejected. JSON-shaped mappings also load as YAML.
+
+Generate a signing key on the trusted JobDB host:
+
+```sh
+mkdir -p gitvend-issuer
+gitvend keygen --private gitvend-issuer/signing.key --public gitvend-issuer/signing.pub
+```
+
+Save this as `gitvend-issuer/issuer.yaml`, replacing `YOUR_TENANT_ID` with the
+actual JobDB tenant ID:
+
+```yaml
+issuer: jobdb
+audience: gitvend
+key_id: jobdb
+signing_key_file: signing.key
+cell_metadata_field: repo
+tenants:
+  YOUR_TENANT_ID:
+    base_permissions:
+      - github.com/*:r
+    target_permissions:
+      - github.com/colony-2/*:rwc
+```
+
+This permits all GitHub reads available through the gateway, plus read/write/create
+on the target cell under `colony-2`. Use narrower base rules when tenants must not
+share private repository access. The [complete issuer example](../examples/jobdb-gitvend-issuer.yaml)
+also shows token lifetime and size settings.
+
+`signing_key_file` resolves relative to the issuer file. Keep the private key on
+the JobDB host and copy only `signing.pub` to the gateway. Add a gateway `keys`
+entry with ID `jobdb`, issuer `jobdb`, and the public key's path. Its owner
+allowlist and the upstream provider's allowed owners must cover the repositories
+in your policy. The audience must also match. Configure upstream GitHub credentials
+on the gateway separately.
+
+Validate before registering the plugin:
+
+```sh
+jobdb-gitvend-secret-provider validate --config gitvend-issuer/issuer.yaml
+```
+
+Expected output: `Configuration and signing key are valid.` This checks the local
+configuration and private key; it does not test GitHub access or gateway connectivity.
+
+## Tenant permissions
+
+Example policy for more restricted reads:
+
+```yaml
+base_permissions:
+  - github.com/public-org/*:r
+  - github.com/example-org/shared-library:r
+target_permissions:
+  - github.com/example-org/cell-*:rwc
+principals:
+  - trusted-job-submitter
+```
+
+`base_permissions` applies to both tokens, including the target repository.
+`target_permissions` grants additional authority only for the repository selected
+by metadata. For example, this tenant policy allows all accessible GitHub reads
+and read/write/create on the target cell if it belongs to `colony-2`:
+
+```yaml
+base_permissions:
+  - github.com/*:r
+target_permissions:
+  - github.com/colony-2/*:rwc
+```
+
+For `AppMetadata.repo = "https://github.com/colony-2/my-cell.git"`, the cell JWT
+contains `github.com/*:r` and `github.com/colony-2/my-cell:rwc`. It does not grant
+writes or creation to any other cell. A target rule such as
+`github.com/colony-2/*#work/*:rw` retains its branch selector after narrowing.
+Use a separate repository-wide `:c` rule for creation when writes are branch-scoped;
+Gitvend rejects `c` with a ref selector.
+
+An empty/omitted base list disables the base token. An empty/omitted target list,
+or no matching target allow rule, disables the cell token. A tenant must have
+at least one rule, with at most 128 rules across both lists. Optional `principals`
+restricts both tokens to those exact broker-verified principals; omitting it
+authorizes all principals, including absent principals, within that tenant.
+
+Creation still requires the gateway provider's `allow_creation: true` and a
+readable/writable branch. Its `creation_defaults` chooses visibility and GitHub
+features; the issuer cannot override those defaults. See
+[gateway creation settings](gateway.md#repository-creation-defaults).
+
+### Migrating the original issuer config
+
+Rename `read_permissions` to `base_permissions`. Replace `cell_write_repositories`
+with `target_permissions`, adding `:rw` to each old repository pattern to preserve
+its permissions, or `:rwc` to also allow creation. Update workers to request
+`gitvend_base_token` instead of `gitvend_read_token`; `gitvend_cell_token` is unchanged.
+Old config fields are rejected, and the old secret name is omitted rather than
+silently returning a token that may now carry write permissions. Deploy the
+new config and executable together; validate the config before restarting JobDB's
+plugin process.
+
+## Register with JobDB
+
+Find the installed command with `command -v jobdb-gitvend-secret-provider`.
+Save a `providers.json` file using absolute paths for that executable and your
+issuer configuration:
+
+```json
+{
+  "version": 1,
+  "providers": [
+    {
+      "id": "gitvend",
+      "type": "plugin",
+      "command": "/absolute/path/to/jobdb-gitvend-secret-provider",
+      "args": ["--config", "/absolute/path/to/gitvend-issuer/issuer.yaml"]
+    }
+  ]
+}
+```
+
+```sh
+jobdb sqlite --db ./jobdb.db --secret-providers-file /absolute/path/to/providers.json
+```
+
+Other providers, including SQLite, can coexist in the same provider file; the first entry for each secret name wins. See
+[the provider guide](https://github.com/colony-2/jobdb/blob/f403447cb58a7195e32a55fb7f417e09da70f388/docs/GUIDE-SECRET-PROVIDERS.md) for collection behavior.
+An omission here cannot veto a grant from a different provider.
+
+The worker requests either or both names through JobDB's normal secret-resolution
+API and uses the returned JWT as the Gitvend HTTP Basic password. It still uses
+the gateway's Git URL, for example
+`https://gitvend.example/github/example-org/cell-one.git`, with Git protocol v2.
+Follow the [agent authentication instructions](gateway.md#configure-git-authentication)
+to configure the Git credential helper.
+
+## Cell metadata and authorization
+
+The default `cell_metadata_field` is `repo`, matching c2j's target repository
+metadata. It is a top-level field in `SecretResolveRequest.AppMetadata`, e.g.:
+
+```json
+{
+  "cell_id": "cell-123",
+  "cell_name": "cell-one",
+  "repo": "https://github.com/example-org/cell-one.git"
+}
+```
+
+Accepted repository forms are `https://host/owner/repo[.git]` and
+`host/owner/repo[.git]`. Owner/repository casing is normalized. Credentials, query
+strings, fragments, encoded paths, extra path segments and permission syntax are
+rejected. Configure a different field if your application uses another name;
+its value must still identify a repository, not an opaque cell ID. SSH URLs and
+cell-ID-to-repository lookups are not implemented.
+
+The provider matches that repository against the **verified tenant's** configured
+target rules, then replaces each matching rule's repository pattern with the
+exact repository while preserving its actions, ref selector and deny flag.
+Missing, malformed or unauthorized metadata omits the cell token while leaving
+an independently authorized base token available. Unknown names and tenants are
+also omitted.
+
+Application metadata may be submitter-controlled. The configured target patterns
+are an authorization ceiling: authorized jobs in that tenant may select any
+matching cell. If individual jobs or principals must be confined to different
+cells within a tenant, a trusted job/principal-to-cell authorization lookup is
+needed before widening this model. Metadata by itself does not establish such
+a binding. `cell_id` and `cell_name` do not override `repo`.
+
+## Private repository reads
+
+The plugin does not discover GitHub visibility or user membership. `github.com/*:r` authorizes reads across the host, intersected
+with Gitvend's signing-key owner ceiling, gateway routes/denies, and the actual
+upstream GitHub token's permissions. Permission strings use `github.com`, not
+the route alias `github`.
+
+This broad setting works when all tenants receiving it are allowed to read
+everything available to those Gitvend upstream credentials. The upstream token
+cannot provide tenant-specific isolation: Gitvend selects it by provider route,
+not by the JobDB tenant or principal. With a shared upstream token, a tenant can
+read other tenants' private repositories if all those checks permit them.
+
+For different tenant read scopes, configure explicit tenant read patterns. For
+credential-level separation, use separate gateway deployments/credentials or
+non-overlapping owner routes and key ceilings as appropriate. A pattern does
+not mean “public repositories only”: matching private repositories are readable
+if the upstream token allows them. The plugin has no “public repositories only” permission option.
+
+## Lifetime and operation
+
+The signed expiry and returned `SecretValue.ExpiresAt` are identical, and
+`LeaseBound` is true. The provider uses the earlier of `AuthorizedNotAfter` and
+`LeaseExpiresAt`, subtracts gateway leeway and the clock margin, and rounds down
+to a whole second. It also caps the encoded lifetime at `max_lifetime_seconds`.
+Defaults are 900 seconds, 30 seconds of gateway leeway, a 1-second clock margin,
+and a 4096-byte token limit. Match these settings to the gateway; the provider
+cannot discover its configuration. Set the margin for your actual clock skew.
+
+Missing verified job/lease identity or deadlines fails issuance. Too little
+remaining lifetime returns `ErrSecretsUnavailable`. The request context bounds
+resolution work, not token lifetime. Backend renewal cannot extend a token minted
+through an older presenting capability; obtain a renewed handle and use JobDB's
+fresh secret resolution to refresh credentials. Already delivered JWTs remain
+valid until their expiry plus gateway leeway even if the job is canceled earlier.
+
+Every resolution issues fresh tokens. `policy_revision` is included for gateway
+auditing; the audit subject identifies the tenant/job/lease context without
+exposing the raw identifiers.
+
+## Configuration reloads and key rotation
+
+Configuration and signing-key changes reload automatically on Linux and macOS,
+including atomic file replacements. A request uses one complete configuration
+and key snapshot; subsequent requests use the replacement after validation.
+Removed tenants and permissions affect newly issued tokens.
+
+A malformed, missing or unreadable replacement leaves the last valid snapshot
+active. The plugin reports a fixed error message and retries every second until
+loading succeeds, including when a new signing-key path does not exist yet.
+Startup still requires valid files and access to watch their directories. For coordinated key
+rotation, write a new key file first, then atomically replace the config with its
+new path and key ID; provision the corresponding gateway public key beforehand.
+
+Reloading does not revoke already issued JWTs or replace credentials cached by
+JobDB workflows. Use fresh secret resolution to obtain updated permissions.
+Diagnostics go to stderr without keys, JWTs, raw configuration, or raw errors;
+the JobDB host may suppress plugin output. Watching uses local filesystem events,
+with no periodic polling after successful loads. Network filesystems and changes
+to symlink targets outside the watched directories require a different update
+mechanism or restarting the plugin host.
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `jobdb-gitvend-secret-provider --help` | Show setup instructions. |
+| `jobdb-gitvend-secret-provider validate --config issuer.yaml` | Validate local configuration and the signing key. |
+| `jobdb-gitvend-secret-provider --config issuer.yaml` | Invocation registered with JobDB; JobDB launches this process. |
+| `jobdb-gitvend-secret-provider version` | Show the installed version. |
+| `jobdb-gitvend-secret-provider completion --help` | Set up shell completion. |
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| 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`. |
+| Configuration validation fails | Check YAML field names, permission syntax, tenant IDs, and the signing-key path relative to the issuer file. |
+| Neither token is returned | Check the verified tenant/principal, requested secret names, and job lease authority. Unknown names and unauthorized tenants are omitted. |
+| Base token works but cell token is missing | Check `AppMetadata.repo`, `cell_metadata_field`, and whether a target allow rule matches that exact repository. |
+| Gateway rejects a token | Check issuer, key ID, audience, signing key, clock tolerance, lifetime limits, and gateway owner allowlists. |
+| 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. |
+| 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. |
+
+For source builds, tests, or SDK integration, see the [developer guide](development.md).

package/docs/permission-syntax.md

@@ -0,0 +1,136 @@
+# JWT permission syntax, version 1
+
+Status: implemented version 1. This defines the compact permission strings used by the [Git gateway design](git-proxy-design.md). Permissions are signed inside the JWT and evaluated locally; no permission-name or role lookup is required.
+
+## Shape
+
+```text
+[!]host/namespace/repository[#ref-selector]:actions
+```
+
+Examples:
+
+```text
+github.com/fooorg/*:r
+github.com/fooorg/blue*:rw
+github.com/*:r
+github.com/fooorg/red#(main|master|link):rw
+github.com/fooorg/red#agents/agent-47/*:rw
+github.com/fooorg/red#refs/tags/v*:r
+github.com/fooorg/agent-47-*:c
+!github.com/fooorg/*#(main|master):wd
+```
+
+The JWT contains an array of strings, not a comma-separated string. Each string is one rule. The optional leading `!` makes a deny rule; otherwise it is an allow rule. Rule order has no meaning.
+
+## Actions
+
+| Letter | Permission |
+| --- | --- |
+| `r` | Read objects by hash in the matching repository and discover/resolve matching refs. A ref selector restricts discovery, not hash reads. |
+| `w` | Create or update matching refs, including history rewrites, subject to upstream restrictions. Does not delete refs or create repositories. |
+| `d` | Delete matching refs. Does not delete the repository. |
+| `c` | Create matching repositories using the route's server-controlled creation defaults (private by default). Does not itself grant reads or ref writes. |
+
+Letters may be combined, such as `rw`, `rwd`, or `rwc`. Reject empty, duplicate or unknown action letters; issuers serialize in `rwdc` order. `w` and `d` do not imply `r`: a write also requires effective read/discovery permission on its destination, possibly from another rule. This permits a broad `:r` plus a narrow `:w` without repeating read grants. No separate force-push letter is claimed: distinguishing history rewrites from fast-forwards remains outside the initial streaming gate.
+
+`c` is valid only without a `#ref-selector`, including in combinations and denies. Repository creation has no branch identity. Actual create-on-discovery additionally requires repository read permission and an effective `r`/`w` overlap for at least one possible branch. Creation never grants authority to write other refs.
+
+## Repository matching
+
+The host is an exact, lowercase configured Git authority, optionally with a configured port. No host wildcards, scheme, userinfo, query or client-chosen server URL. For example, `github.com` maps to the configured GitHub provider, API endpoint, credential and allowed owners. Multiple credential routes must be resolved deterministically by host/namespace; ambiguous routes fail configuration validation. A host-wide grant cannot enable an unconfigured owner or exceed its issuer's local authority ceiling.
+
+Repository paths are canonical `namespace/repository` names, without the transport `.git` suffix. GitHub paths have an owner and a repository; later adapters may allow nested namespaces. Match against the adapter's canonical identity, never against the raw incoming URL. Hostnames are case-insensitive; repository case handling follows the adapter; branch and tag names are case-sensitive. Redirects and aliases are not permission matches.
+
+| Pattern | Meaning |
+| --- | --- |
+| `fooorg/red` | That exact repository. |
+| `fooorg/*` | Every repository directly in `fooorg`. |
+| `fooorg/blue*` | Repositories directly in `fooorg` whose names begin with `blue`, including `blue` itself. |
+| `*/red` | Repository `red` in any one-level namespace. |
+| `fooorg/**` | Repositories in `fooorg` and recursively nested namespaces, for adapters that support them. |
+| `*` immediately after the host | Whole-host shorthand: all canonical repository paths on that configured host, at any namespace depth. Equivalent to `**` in this position. |
+
+In ordinary path segments, `*` matches zero or more characters but never `/`. A standalone `**` path segment spans namespace levels; `fooorg/**/red` can match `fooorg/red` and `fooorg/team/red`. `**` is not allowed embedded in a segment. Every matched target must still be a valid repository identity; a glob never names a namespace itself as a repository.
+
+The whole-host `host/*` form is an explicit shorthand, not a general rule that ordinary path stars cross slashes. It supports the requested `github.com/*:r` spelling without broadening `github.com/fooorg/*` to unrelated namespaces.
+
+## Ref selectors
+
+| Selector | Meaning |
+| --- | --- |
+| No `#` | Whole repository: all supported branches and tags for `r`, `w` and `d`; repository-level scope for `c`. |
+| `#main` | Exactly `refs/heads/main`. |
+| `#(main|master|link)` | Those three branch names. |
+| `#agents/agent-47/*` | Branches with that prefix, including nested suffixes. |
+| `#*` | All branches, not tags. |
+| `#refs/heads/release/*` | Explicit fully qualified branch selector. |
+| `#refs/tags/v*` | Tags whose names begin with `v`. |
+
+Without an explicit `refs/heads/` or `refs/tags/` prefix, the selector names a branch. Ref wildcards match the **whole branch or tag name**, so `*` may span `/` here. `**` has no additional meaning in ref selectors and is rejected to avoid competing spellings. This intentionally differs from namespace path segments: the slash in a branch name is part of the branch name, not a repository boundary.
+
+Only branch and tag namespaces are supported initially. Explicit selectors beginning `refs/` must use a literal supported namespace prefix; `#refs/*` and selectors for provider-managed refs are invalid. To match a branch literally named `refs/tags/example`, use `#refs/heads/refs/tags/example`.
+
+An unrestricted repository `:rw` therefore includes tag creation/update. Issuers that intend branch-only writes must use `#*:rw`, and branch-restricted work should use a narrower selector. Repository-wide grants deliberately opt into broader scope; tags are otherwise hidden and unwritable without a matching grant. `HEAD` is handled by the gateway's symbolic-ref visibility rules, not as a separate writable ref.
+
+## Alternatives and literal characters
+
+`(a|b|c)` means a choice of glob fragments, not a regular expression. It can appear inside a namespace/repository segment or ref selector. For example, `(blue|green)*` and `#(main|release/*)` are valid. Repository alternatives cannot contain `/`; use a separate rule for different path structures. Ref alternatives may contain `/`.
+
+All matches cover the entire canonical field. `red` does not match `infra-red`; `main` does not match `main-old`; `.` is literal. There are no regex operators, character classes, nested groups or implicit substring matches. Reject empty alternatives, unmatched parentheses, unescaped bare `|`, `?`, `[` or `]`, and trailing escapes.
+
+Backslash escapes grammar characters for literal matching, including `(`, `)`, `|`, `#`, `:`, `!` and backslash itself. Parse delimiters while respecting escapes; use the action-separating colon after the resource/ref portion, not a colon in a host port. JSON must itself escape backslashes: a selector for a branch literally named `topic(test)` is encoded as `"...#topic\\(test\\):r"`. Escaping does not legalize characters prohibited by the forge or Git. Do not percent-decode permission strings or interpret them as URLs.
+
+## Combining rules
+
+For each internal action, allow if at least one matching allow grants it and no matching deny removes it. Default deny. Specificity and ordering do not override a deny. Apply configured issuer/host/owner limits and gateway hard restrictions in addition; upstream permissions remain a final independent restriction.
+
+| Internal action | Allow condition | Deny condition |
+| --- | --- | --- |
+| `repo.read` | Any repository-matching `r` rule, with or without a ref selector. | A repository-matching `r` deny **without** a ref selector. |
+| `ref.discover` | A repository/ref-matching `r` allow. | A repository/ref-matching `r` deny. |
+| `ref.create`, `ref.update` | A repository/ref-matching `w` allow. | A repository/ref-matching `w` deny. |
+| `ref.delete` | A repository/ref-matching `d` allow. | A repository/ref-matching `d` deny. |
+| `repo.create` | A repository-matching `c` allow. | A repository-matching `c` deny. |
+
+Reading a named ref requires both `repo.read` and `ref.discover`. A ref mutation requires those two plus the corresponding write action. An allowed direct hash fetch only needs `repo.read`. A repository-wide `!…:r` consequently blocks all ordinary Git use of that repository, including writes that depend on read access. A branch-scoped `!…#secret/*:r` hides matching refs and blocks writes to them, but **does not** prevent fetching their objects by known hash. That is the previously selected read model, not a parser exception.
+
+Examples of overlap:
+
+- `github.com/fooorg/*:r` plus `github.com/fooorg/blue*:w`: discover all refs throughout the organization; create/update refs only in `blue*` repositories.
+- `github.com/fooorg/red#main:r` plus `github.com/fooorg/red#agents/47/*:rw`: discover main and this agent's branches; only the agent branches are writable; hash reads remain repository-wide.
+- `github.com/*:r` plus `github.com/fooorg/red#main:rw`: all configured GitHub repositories remain readable/discoverable. The narrower rule adds main writes; it does not narrow the broad read grant.
+- `github.com/fooorg/*:rwd` plus `!github.com/fooorg/*#(main|master):wd`: keep those branches readable while preventing creation, updates and deletion, even if another allow grants them.
+
+Grants are evaluated against the current repository/ref name at request time. They cover future matching repositories and branches, subject to configured owner access. If a repository is deleted and recreated under the same name, the same matching grant still applies. There is no repository enrollment or ID pinning; the grant contains only `v` and `permissions`.
+
+## JWT example
+
+The following is the custom claim fragment; the full token also requires the identity, audience, lifetime and signature fields from the main design:
+
+```json
+{
+  "grant": {
+    "v": 1,
+    "permissions": [
+      "github.com/fooorg/red#main:r",
+      "github.com/fooorg/red#agents/47/*:rw",
+      "github.com/fooorg/agent-47-*:rc",
+      "github.com/fooorg/agent-47-*#agents/47/*:rw",
+      "!github.com/fooorg/*#(main|master):wd"
+    ]
+  }
+}
+```
+
+This can read main, discover/write the agent's branches, and provision matching scratch repositories. Creation uses the route's creation defaults, including visibility (private by default). The `rc` rule also deliberately grants all-ref discovery in those scratch repositories; remove `r` there and put it only on selected branches if narrower discovery is desired.
+
+## Implementation and acceptance
+
+Compile the signed strings into an immutable matcher after JWT verification and schema validation. Use a dedicated lexer/parser and bounded glob/alternative automata; do not feed raw token patterns into a regex engine or shell, and do not expand alternatives into an unbounded Cartesian product. Bound token bytes, rule count, pattern length and group count. Cache compiled grants by verified token digest, never just `sub` or a client-chosen `jti`, with expiry and relevant local configuration revision in the cache validity conditions.
+
+Derive internal action checks from the table above. Apply the same canonicalization and matcher to ref discovery, direct receive-pack commands and provisioning. Creation eligibility is a nonempty language intersection: permitted branch `r` and `w` patterns minus denies must overlap. Compute that with bounded automata; do not sample candidate branch names or ignore denies. If computation exceeds configured complexity bounds, reject the grant/creation eligibility with a clear error.
+
+Add a policy-explanation command for issuer/operator use that accepts a grant and concrete repository/ref/action and returns matching allows/denies and the decision. It should also flag obviously broad repository or host grants that make narrower grants redundant, without changing their meaning.
+
+Acceptance cases must cover whole-host shorthand, segment boundaries, nested namespaces, branch slashes, alternatives, escapes, case rules, tags versus branches, overlapping grants/denies, denied branch hash fetches, unknown syntax, duplicate action letters, future matching names, recreated repository names and creation eligibility. Reject a malformed rule by rejecting the entire JWT grant, never by silently dropping that rule.

package/examples/gitvend.yaml

@@ -0,0 +1,31 @@
+listen: 127.0.0.1:8443
+tls_cert: /run/secrets/gitvend.crt
+tls_key: /run/secrets/gitvend.key
+audience: gitvend
+keys:
+  - id: orchestrator-1
+    issuer: orchestrator
+    public_key_file: var/signing.pub
+    owners:
+      github.com:
+        - fooorg
+providers:
+  - alias: github
+    host: github.com
+    kind: github
+    git_base_url: https://github.com
+    api_base_url: https://api.github.com
+    allowed_owners:
+      - fooorg
+    credential:
+      kind: token
+      secret_ref: env:GITHUB_TOKEN
+    allow_creation: true
+    creation_defaults:
+      visibility: private
+      has_issues: false
+      has_projects: false
+      has_wiki: false
+      has_pull_requests: false
+denies:
+  - '!github.com/fooorg/*#(main|master):wd'

package/examples/grant.json

@@ -0,0 +1,9 @@
+{
+  "v": 1,
+  "permissions": [
+    "github.com/fooorg/project#main:r",
+    "github.com/fooorg/project#agents/47/*:rw",
+    "github.com/fooorg/agent-47-*:c",
+    "github.com/fooorg/agent-47-*#agents/47/*:rw"
+  ]
+}

package/examples/jobdb-gitvend-issuer.yaml

@@ -0,0 +1,16 @@
+issuer: jobdb
+audience: gitvend
+key_id: jobdb
+signing_key_file: signing.key
+policy_revision: "1"
+max_token_bytes: 4096
+max_lifetime_seconds: 900
+gateway_leeway_seconds: 30
+clock_margin_seconds: 1
+cell_metadata_field: repo
+tenants:
+  example:
+    base_permissions:
+      - github.com/*:r
+    target_permissions:
+      - github.com/colony-2/*:rwc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colony2/gitvend",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Git HTTPS gateway with signed repository and branch permissions",
   "license": "UNLICENSED",
   "homepage": "https://github.com/colony-2/gitvend",
@@ -24,7 +24,8 @@
     "security"
   ],
   "bin": {
-    "gitvend": "bin/cli.js"
+    "gitvend": "bin/cli.js",
+    "jobdb-gitvend-secret-provider": "bin/jobdb-gitvend-secret-provider"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -46,6 +47,8 @@
     "scripts/",
     "README.md",
     "THIRD_PARTY_NOTICES.md",
-    "LICENSES/"
+    "LICENSES/",
+    "docs/",
+    "examples/"
   ]
 }

package/scripts/postinstall.js

@@ -44,7 +44,8 @@ async function install({
   const { name, assetName, baseUrl } = releaseAsset(pkg, platform, arch);
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `${name}-`));
   const vendorDir = path.join(packageRoot, "vendor");
-  let stagedBinary;
+  const binaries = [name, "jobdb-gitvend-secret-provider"];
+  const staged = [];
   try {
     const archivePath = path.join(tempDir, assetName);
     const checksumsPath = path.join(tempDir, "checksums.txt");
@@ -53,17 +54,26 @@ async function install({
     await downloadFile(`${baseUrl}/${assetName}`, archivePath);
     await downloadFile(`${baseUrl}/checksums.txt`, checksumsPath, { maxBytes: 1024 * 1024 });
     verifyChecksum(archivePath, checksumsPath, assetName);
-    // Extract only the executable, not documentation or other archive entries.
-    execFileSync("tar", ["-xzf", archivePath, "-C", extractDir, name], { stdio: "pipe" });
-    const binary = path.join(extractDir, name);
-    if (!fs.lstatSync(binary).isFile()) throw new Error("Release binary must be a regular file");
+    // Extract and validate both commands before replacing either installed binary.
+    execFileSync("tar", ["-xzf", archivePath, "-C", extractDir, ...binaries], { stdio: "pipe" });
+    for (const name of binaries) {
+      if (!fs.lstatSync(path.join(extractDir, name)).isFile()) {
+        throw new Error("Release binary must be a regular file");
+      }
+    }
     fs.mkdirSync(vendorDir, { recursive: true });
-    stagedBinary = path.join(vendorDir, `.gitvend-${crypto.randomBytes(8).toString("hex")}`);
-    fs.copyFileSync(binary, stagedBinary, fs.constants.COPYFILE_EXCL);
-    fs.chmodSync(stagedBinary, 0o755);
-    fs.renameSync(stagedBinary, path.join(vendorDir, name));
+    for (const name of binaries) {
+      // Launch the plugin directly: JobDB restricts PATH and owns its process.
+      const destinationDir = name === "gitvend" ? vendorDir : path.join(packageRoot, "bin");
+      fs.mkdirSync(destinationDir, { recursive: true });
+      const temporary = path.join(destinationDir, `.${name}-${crypto.randomBytes(8).toString("hex")}`);
+      staged.push([temporary, path.join(destinationDir, name)]);
+      fs.copyFileSync(path.join(extractDir, name), temporary, fs.constants.COPYFILE_EXCL);
+      fs.chmodSync(temporary, 0o755);
+    }
+    for (const [temporary, destination] of staged) fs.renameSync(temporary, destination);
   } finally {
-    if (stagedBinary) fs.rmSync(stagedBinary, { force: true });
+    for (const [temporary] of staged) fs.rmSync(temporary, { force: true });
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 }