@sjawhar/pi-envoy 17.31.2 → 17.32.0

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/dist/dispatch.js CHANGED
@@ -26246,6 +26246,7 @@ var EXCHANGE_CLIENT_ID = "dispatch-token-exchange";
26246
26246
  var FORM_SESSION = "session";
26247
26247
  var FORM_LAUNCHER_CREDENTIAL = "launcher_credential";
26248
26248
  var FORM_LAUNCHER_CREDENTIAL_DECLINED = "false";
26249
+ var FORM_PROJECTS = "projects";
26249
26250
  var SUBJECT_TOKEN_TYPE_KUBERNETES = "urn:envoy:params:oauth:token-type:kubernetes-service-account";
26250
26251
  var SUBJECT_TOKEN_TYPE_GOOGLE = "urn:envoy:params:oauth:token-type:google-identity";
26251
26252
  var SUBJECT_TOKEN_TYPE_PERSON = "urn:envoy:params:oauth:token-type:person-google-identity";
@@ -27739,6 +27740,7 @@ class BrokerTokenClient {
27739
27740
  #subject;
27740
27741
  #actor;
27741
27742
  #session;
27743
+ #projects;
27742
27744
  #launcherCredential;
27743
27745
  #renewBeforeMs;
27744
27746
  #now;
@@ -27755,6 +27757,7 @@ class BrokerTokenClient {
27755
27757
  this.#subject = options.subject;
27756
27758
  this.#actor = options.actor;
27757
27759
  this.#session = options.session ?? "";
27760
+ this.#projects = [...options.projects ?? []];
27758
27761
  this.#launcherCredential = options.launcherCredential ?? true;
27759
27762
  this.#renewBeforeMs = options.renewBeforeMs ?? DEFAULT_RENEW_BEFORE_MS;
27760
27763
  this.#now = options.now ?? Date.now;
@@ -27805,6 +27808,8 @@ class BrokerTokenClient {
27805
27808
  };
27806
27809
  if (this.#session !== "")
27807
27810
  form[FORM_SESSION] = this.#session;
27811
+ if (this.#projects.length > 0)
27812
+ form[FORM_PROJECTS] = this.#projects.join(" ");
27808
27813
  if (!this.#launcherCredential) {
27809
27814
  form[FORM_LAUNCHER_CREDENTIAL] = FORM_LAUNCHER_CREDENTIAL_DECLINED;
27810
27815
  }
@@ -28109,6 +28114,8 @@ var IDENTITY_VAR = "AGENT_SECRETS_MACHINE_IDENTITY";
28109
28114
  var MACHINE_TOKEN_FILE_VAR = "AGENT_SECRETS_MACHINE_TOKEN_FILE";
28110
28115
  var MACHINE_AUDIENCE_VAR = "AGENT_SECRETS_MACHINE_AUDIENCE";
28111
28116
  var SESSION_VAR = "AGENT_SECRETS_SESSION";
28117
+ var PROJECTS_VAR = "AGENT_SECRETS_PROJECTS";
28118
+ var MAX_PROJECTS = 16;
28112
28119
  var POOL_AUDIENCE_VAR = "AGENT_SECRETS_POOL_AUDIENCE";
28113
28120
  var POOL_ACCOUNT_VAR = "AGENT_SECRETS_POOL_ACCOUNT";
28114
28121
  var IDENTITY_KUBERNETES = "kubernetes";
@@ -28120,6 +28127,7 @@ var BROKER_VARIABLES = [
28120
28127
  MACHINE_TOKEN_FILE_VAR,
28121
28128
  MACHINE_AUDIENCE_VAR,
28122
28129
  SESSION_VAR,
28130
+ PROJECTS_VAR,
28123
28131
  POOL_AUDIENCE_VAR,
28124
28132
  POOL_ACCOUNT_VAR,
28125
28133
  SIGNIN_DIR_VAR,
@@ -28169,6 +28177,24 @@ function tradeSession(env, own = "") {
28169
28177
  const acting = own.trim();
28170
28178
  return acting !== "" ? acting : value(env, SESSION_VAR);
28171
28179
  }
28180
+ function tradeProjects(env) {
28181
+ const keys = value(env, PROJECTS_VAR).split(/\s+/).filter((key) => key !== "");
28182
+ if (keys.length > MAX_PROJECTS) {
28183
+ throw new Error(`${PROJECTS_VAR}: ${keys.length} projects are named, and a token names at most ${MAX_PROJECTS}`);
28184
+ }
28185
+ for (const key of keys) {
28186
+ if (!PROJECT_KEY_PATTERN.test(key)) {
28187
+ throw new Error(`${PROJECTS_VAR}: "${key}" is not a project key: ${PROJECT_KEY_RULE}`);
28188
+ }
28189
+ }
28190
+ const sorted = keys.sort();
28191
+ for (let at = 1;at < sorted.length; at += 1) {
28192
+ if (sorted[at] === sorted[at - 1]) {
28193
+ throw new Error(`${PROJECTS_VAR}: ${sorted[at]} is named twice, and a list names each project once`);
28194
+ }
28195
+ }
28196
+ return sorted;
28197
+ }
28172
28198
  async function brokerTokenClient(env, own = "") {
28173
28199
  const brokerUrl = value(env, BROKER_URL_VAR);
28174
28200
  const machine = machineIdentity(env);
@@ -28194,7 +28220,8 @@ async function brokerTokenClient(env, own = "") {
28194
28220
  key: await importDpopKey(record.box_key, `${record.person}'s box key`),
28195
28221
  subject: personIdentity(record, flow),
28196
28222
  actor: machine,
28197
- session: own.trim() || signInSessionName(record)
28223
+ session: own.trim() || signInSessionName(record),
28224
+ projects: tradeProjects(env)
28198
28225
  });
28199
28226
  return { client, signIn: { person: record.person, thumbprint: record.thumbprint } };
28200
28227
  }
package/dist/envoy.js CHANGED
@@ -34229,6 +34229,7 @@ var EXCHANGE_CLIENT_ID = "dispatch-token-exchange";
34229
34229
  var FORM_SESSION = "session";
34230
34230
  var FORM_LAUNCHER_CREDENTIAL = "launcher_credential";
34231
34231
  var FORM_LAUNCHER_CREDENTIAL_DECLINED = "false";
34232
+ var FORM_PROJECTS = "projects";
34232
34233
  var SUBJECT_TOKEN_TYPE_KUBERNETES = "urn:envoy:params:oauth:token-type:kubernetes-service-account";
34233
34234
  var SUBJECT_TOKEN_TYPE_GOOGLE = "urn:envoy:params:oauth:token-type:google-identity";
34234
34235
  var SUBJECT_TOKEN_TYPE_PERSON = "urn:envoy:params:oauth:token-type:person-google-identity";
@@ -35732,6 +35733,7 @@ class BrokerTokenClient {
35732
35733
  #subject;
35733
35734
  #actor;
35734
35735
  #session;
35736
+ #projects;
35735
35737
  #launcherCredential;
35736
35738
  #renewBeforeMs;
35737
35739
  #now;
@@ -35748,6 +35750,7 @@ class BrokerTokenClient {
35748
35750
  this.#subject = options.subject;
35749
35751
  this.#actor = options.actor;
35750
35752
  this.#session = options.session ?? "";
35753
+ this.#projects = [...options.projects ?? []];
35751
35754
  this.#launcherCredential = options.launcherCredential ?? true;
35752
35755
  this.#renewBeforeMs = options.renewBeforeMs ?? DEFAULT_RENEW_BEFORE_MS;
35753
35756
  this.#now = options.now ?? Date.now;
@@ -35798,6 +35801,8 @@ class BrokerTokenClient {
35798
35801
  };
35799
35802
  if (this.#session !== "")
35800
35803
  form[FORM_SESSION] = this.#session;
35804
+ if (this.#projects.length > 0)
35805
+ form[FORM_PROJECTS] = this.#projects.join(" ");
35801
35806
  if (!this.#launcherCredential) {
35802
35807
  form[FORM_LAUNCHER_CREDENTIAL] = FORM_LAUNCHER_CREDENTIAL_DECLINED;
35803
35808
  }
@@ -36102,6 +36107,8 @@ var IDENTITY_VAR = "AGENT_SECRETS_MACHINE_IDENTITY";
36102
36107
  var MACHINE_TOKEN_FILE_VAR = "AGENT_SECRETS_MACHINE_TOKEN_FILE";
36103
36108
  var MACHINE_AUDIENCE_VAR = "AGENT_SECRETS_MACHINE_AUDIENCE";
36104
36109
  var SESSION_VAR = "AGENT_SECRETS_SESSION";
36110
+ var PROJECTS_VAR = "AGENT_SECRETS_PROJECTS";
36111
+ var MAX_PROJECTS = 16;
36105
36112
  var POOL_AUDIENCE_VAR = "AGENT_SECRETS_POOL_AUDIENCE";
36106
36113
  var POOL_ACCOUNT_VAR = "AGENT_SECRETS_POOL_ACCOUNT";
36107
36114
  var IDENTITY_KUBERNETES = "kubernetes";
@@ -36113,6 +36120,7 @@ var BROKER_VARIABLES = [
36113
36120
  MACHINE_TOKEN_FILE_VAR,
36114
36121
  MACHINE_AUDIENCE_VAR,
36115
36122
  SESSION_VAR,
36123
+ PROJECTS_VAR,
36116
36124
  POOL_AUDIENCE_VAR,
36117
36125
  POOL_ACCOUNT_VAR,
36118
36126
  SIGNIN_DIR_VAR,
@@ -36162,6 +36170,24 @@ function tradeSession(env, own = "") {
36162
36170
  const acting = own.trim();
36163
36171
  return acting !== "" ? acting : value(env, SESSION_VAR);
36164
36172
  }
36173
+ function tradeProjects(env) {
36174
+ const keys = value(env, PROJECTS_VAR).split(/\s+/).filter((key) => key !== "");
36175
+ if (keys.length > MAX_PROJECTS) {
36176
+ throw new Error(`${PROJECTS_VAR}: ${keys.length} projects are named, and a token names at most ${MAX_PROJECTS}`);
36177
+ }
36178
+ for (const key of keys) {
36179
+ if (!PROJECT_KEY_PATTERN.test(key)) {
36180
+ throw new Error(`${PROJECTS_VAR}: "${key}" is not a project key: ${PROJECT_KEY_RULE}`);
36181
+ }
36182
+ }
36183
+ const sorted = keys.sort();
36184
+ for (let at = 1;at < sorted.length; at += 1) {
36185
+ if (sorted[at] === sorted[at - 1]) {
36186
+ throw new Error(`${PROJECTS_VAR}: ${sorted[at]} is named twice, and a list names each project once`);
36187
+ }
36188
+ }
36189
+ return sorted;
36190
+ }
36165
36191
  async function brokerTokenClient(env, own = "") {
36166
36192
  const brokerUrl = value(env, BROKER_URL_VAR);
36167
36193
  const machine = machineIdentity(env);
@@ -36187,7 +36213,8 @@ async function brokerTokenClient(env, own = "") {
36187
36213
  key: await importDpopKey(record.box_key, `${record.person}'s box key`),
36188
36214
  subject: personIdentity(record, flow),
36189
36215
  actor: machine,
36190
- session: own.trim() || signInSessionName(record)
36216
+ session: own.trim() || signInSessionName(record),
36217
+ projects: tradeProjects(env)
36191
36218
  });
36192
36219
  return { client, signIn: { person: record.person, thumbprint: record.thumbprint } };
36193
36220
  }
@@ -47722,7 +47749,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
47722
47749
 
47723
47750
  // package.json
47724
47751
  var name = "@sjawhar/pi-envoy";
47725
- var version2 = "17.31.2";
47752
+ var version2 = "17.32.0";
47726
47753
  var package_default = {
47727
47754
  name,
47728
47755
  version: version2,
@@ -74,12 +74,6 @@ agent-secrets LEGION_SLACK_BOT_TOKEN -- \
74
74
  sh -c 'printf "Authorization: Bearer %s" "$LEGION_SLACK_BOT_TOKEN" | curl -sS -H @- https://slack.com/api/auth.test'
75
75
  ```
76
76
 
77
- The repository uses the same form for a GitHub App token in `docs/deployment.md`:
78
-
79
- ```sh
80
- agent-secrets LEGION_IMPLEMENT_APP --reason=… -- sh -c 'printf %s "$LEGION_IMPLEMENT_APP"'
81
- ```
82
-
83
77
  ## A secret behind the airlock
84
78
 
85
79
  Your deployment can hold a secret's value back and give your command a stand-in. You see it in the
@@ -130,13 +124,42 @@ Your transcript keeps everything a command prints.
130
124
 
131
125
  - Never echo or print the value, and never run `curl -v`, `curl --trace` or a shell with `set -x`
132
126
  around it: each of those writes the header, and so the value, to your output.
133
- - Check a value's shape by its length and its prefix alone. For a secret behind the airlock, that
134
- reads the placeholder's shape and not the value's:
127
+ - Check a plain value's shape by its length and its prefix alone:
135
128
 
136
129
  ```sh
137
130
  agent-secrets NAME --reason 'check the shape of this credential' -- sh -c 'echo "${#NAME}"; case "$NAME" in ghp_*) echo prefix-ok;; *) echo prefix-no;; esac'
138
131
  ```
139
132
 
133
+ - A value may be a JSON document, with the credential one level down or deeper: a GitHub App
134
+ secret asked for without `--github-token` is the JSON object of installations, and its tokens
135
+ are inside it. Check a JSON value's shape by its key paths and the length of each leaf, and
136
+ never by printing a leaf. A probe that masks one key prints every other key's value, the
137
+ nested ones too, so print no value at all, masked or not. These print the key paths, then each
138
+ leaf's path with its length. For a value that is not JSON, jq exits 5 and writes
139
+ `jq: error (at <unknown>): the value is not JSON` to stderr (jaq writes
140
+ `Error: "the value is not JSON"`), and nothing of the value: `try … catch` keeps jq's own parse
141
+ error out, which quotes the text (`… (while parsing '<the value>')`):
142
+
143
+ ```sh
144
+ agent-secrets NAME --reason 'check the shape of this credential' -- \
145
+ jq -n 'env.NAME | try fromjson catch error("the value is not JSON") | [paths(type != "object" and type != "array") | join(".")]'
146
+ agent-secrets NAME --reason 'check the shape of this credential' -- \
147
+ jq -n 'env.NAME | try fromjson catch error("the value is not JSON") | [paths(type != "object" and type != "array") as $p | {path: ($p | join(".")), length: (getpath($p) | tostring | length)}]'
148
+ ```
149
+
150
+ - Take a credential out of a JSON value inside the command, and pass it on there without
151
+ printing it. `jq -e` exits 1 when the path holds nothing, so the command stops rather than
152
+ sending an empty credential:
153
+
154
+ ```sh
155
+ agent-secrets NAME --reason '…' -- sh -c '
156
+ token=$(printf %s "$NAME" | jq -er ".path.to.token" 2>/dev/null) || { echo "no token at .path.to.token" >&2; exit 1; }
157
+ curl -sS -H "Authorization: Bearer $token" https://api.example.com/'
158
+ ```
159
+
160
+ For a GitHub App secret, `--github-owner <account> --github-token` hands the command that one
161
+ account's token under the secret's name, with no JSON to take apart.
162
+ - For a secret behind the airlock, every one of these reads the placeholder and not the value.
140
163
  - Compare two values only as equal or not equal. Never print, slice or diff their characters.
141
164
 
142
165
  ## Read the answer, not the status alone
@@ -155,9 +178,10 @@ after it means the command could not start, and the status is 1.
155
178
  Without the grant line the status is the client's own:
156
179
 
157
180
  - **1** — a refusal or a failure that the message names: a name the broker does not serve
158
- (`UNKNOWN_SECRET`), a broker it cannot reach, a machine that is not logged in to the broker, a
159
- request cancelled or expired, `REQUEST_PENDING`, a grant that is no longer live, or a command
160
- that is not on `PATH`.
181
+ (`UNKNOWN_SECRET`), a secret that waits for its first value (`PENDING_VALUE`), a broker it cannot
182
+ reach, a machine that is not logged in to the broker, a request cancelled or expired,
183
+ `REQUEST_PENDING`, a grant that is no longer live, or a command that is not on `PATH`, which is
184
+ refused before the broker is asked anything, so it reaches no approver.
161
185
  - **2** — a usage error: no broker identity at all (no key in the key dir and no helper socket), no
162
186
  `AGENT_SECRETS_URL`, no `--`, no `NAME`, or a flag value the client refuses.
163
187
  - **75** — the request still waits for a person. The message names who decides it, where, and the
@@ -211,6 +235,17 @@ prompt, a skill, or the issue you work on. There is no list to browse and nothin
211
235
  secret exists is recorded against your session with the reason you signed, and it reaches a
212
236
  person's Inbox unless the model judge decides it first.
213
237
  - `UNKNOWN_SECRET` and a denial are final. Do not ask again, and do not try a name of your own.
238
+ - `PENDING_VALUE` is not final: the secret exists, and its owner is storing its value with
239
+ `agent-secrets secret create` now. No request was made and no approver asked. Ask again in a few
240
+ minutes. After ten minutes the broker stops calling it pending and refuses the name
241
+ `UNKNOWN_SECRET`: the create that made it deletes it when its prompt ends, at ten minutes or,
242
+ where its owner was still typing then, when that entry ends; a create that was killed deletes
243
+ nothing, and the secret stays in the store with no value. Tell its
244
+ owner, who sees it as `versions: none` in `agent-secrets secret show NAME`. The owner frees the
245
+ name with `gcloud secrets delete <id> --project <project number>` (`<id>` is the part after
246
+ `secrets/` of the `secret_name` that `show` prints), or stores the value with
247
+ `agent-secrets secret set NAME`. `agent-secrets secret delete NAME` only schedules the deletion
248
+ 30 days out, and until then the name stays taken, so the next `secret create` of it is refused.
214
249
  - A secret that a service owns goes to that service's own pods and VMs and to nothing else:
215
250
  `Evaluate` in `packages/envoy/internal/broker/policy/policy.go` grants a service-owned secret at
216
251
  once when the session's own service is the secret's owner, and denies every other session, with
@@ -253,7 +288,10 @@ the Application Default Credentials, else the gcloud login; on AWS, `--profile`,
253
288
  the email of the person the credential names, and is refused where it names none, as a token
254
289
  minted for `cloud-platform` alone does: give `--owner <email>` there. Both read the value from
255
290
  standard input or from a prompt with echo off, never from an argument. Type it at the prompt, so it
256
- reaches no shell history.
291
+ reaches no shell history. On Google Cloud, `create` makes the secret before it asks for the value,
292
+ so a store that refuses the create asks for none. Until the value is added, a failure or a signal
293
+ deletes that empty secret again, except where the store's answer leaves open whether it stored the
294
+ value: then `create` keeps the secret, exits 1, and names `agent-secrets secret show NAME` to check.
257
295
 
258
296
  ## A worked example: one page of a Slack thread
259
297
 
@@ -104,7 +104,7 @@ Every topic starts with `notifications.`.
104
104
  Envoy also subscribes you to the lifecycle subject `pr.<n>`, which NATS `>` alone does not match, because `>` needs one or more trailing tokens.
105
105
 
106
106
  - Read the `warnings` that `envoy_subscribe` returns, and confirm the active topics with `envoy_list`.
107
- A warning names the spelling Envoy publishes, or a token that is not a GitHub topic kind; fix the topic it names.
107
+ A warning names the spelling Envoy publishes, a token that is not a GitHub topic kind, or a pull request's bare subject `pr.<n>` that no topic of yours extends to its reviews; fix the topic it names.
108
108
  "No GitHub event ... in the stream's retention window" means nothing came from that repository in the last 72 hours:
109
109
  check that the GitHub App that sends Envoy its webhooks is installed on that repository before you rely on a wake.
110
110
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "17.31.2",
3
+ "version": "17.32.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {