@pidgeon-ai/cli 1.37.0 → 1.39.0

package/README.md

@@ -40,6 +40,21 @@ one request open until mail arrives, and prints it with `extracted.codes` and
 describes one command, with its endpoint and its flags. Documentation:
 [pidgeon.ai/docs/cli](https://pidgeon.ai/docs/cli).
 
+## Check who sent something
+
+`pidgeon id` needs no key. It checks a message, or signs a request as one of
+your agents:
+
+```sh
+pidgeon id verify message.eml
+pidgeon id curl -I https://shop.example --as sunny
+```
+
+`verify` asks the public verifier and says whether the signature holds, which
+agent sent it, who it acts for and whether the body changed. `curl` signs the
+request the way Web Bot Auth asks and prints what it sent. `pidgeon id --help`
+lists the rest, including `init` for your own domain.
+
 ## Flags
 
 - Repeat a list flag: `--to one@example.com --to two@example.com`.

package/dist/{chunk-RWZQSI67.js → chunk-F6XZFMGH.js}

@@ -2027,7 +2027,7 @@ function sleep(ms, signal) {
   });
 }
 
-// ../id/dist/chunk-EAXZTLYY.js
+// ../id/dist/chunk-2NWPDKWJ.js
 import { createHash } from "crypto";
 import { chmod, mkdir, readFile, readdir, writeFile } from "fs/promises";
 import { homedir } from "os";
@@ -2496,6 +2496,34 @@ async function signRequest(identity, input) {
     signature: `${label}=:${Buffer.from(signature).toString("base64")}:`
   };
 }
+function signedFetch(identity, options) {
+  const base = options.fetch ?? globalThis.fetch;
+  return async (resource, init) => {
+    const request = new Request(resource, init);
+    const body = request.body ? new Uint8Array(await request.arrayBuffer()) : null;
+    const headers = {};
+    request.headers.forEach((value, name) => {
+      headers[name] = value;
+    });
+    const signature = await signRequest(identity, {
+      method: request.method,
+      url: request.url,
+      headers,
+      body,
+      agent: options.agent,
+      grants: options.grants
+    });
+    const signedHeaders = new Headers(request.headers);
+    for (const [name, value] of Object.entries(signature)) signedHeaders.set(name, value);
+    return base(request.url, {
+      method: request.method,
+      headers: signedHeaders,
+      body: body && body.length > 0 ? body : void 0,
+      redirect: request.redirect,
+      signal: request.signal
+    });
+  };
+}
 var ISSUANCE_TAG = "pidgeon-id";
 var DEFAULT_ID_URL = "https://pidgeon.ai/api/id";
 var IdApiError = class extends Error {
@@ -2562,6 +2590,10 @@ var IdClient = class {
   grant(input) {
     return this.call("POST", "/grants", input);
   }
+  /** Every token Sign in with Pidgeon issued `name`, taken back; its card and grants stand. */
+  revokeSignIns(name) {
+    return this.call("DELETE", `/agents/${encodeURIComponent(name)}/sign-ins`);
+  }
   revokeGrant(id) {
     return this.call("DELETE", `/grants/${encodeURIComponent(id)}`);
   }
@@ -2633,7 +2665,21 @@ async function fetchCard(agent, fetcher = fetch, postHost = (domain) => `https:/
   }
   return body.jws;
 }
-async function signInWithPidgeon(identity, input) {
+function signInWithPidgeon(identity, input) {
+  return signIn(
+    identity,
+    input,
+    async ({ tokenEndpoint, exchange, headers, agent }) => signRequest(identity, {
+      method: "POST",
+      url: tokenEndpoint,
+      headers,
+      body: exchange,
+      agent,
+      grants: input.grant ? [input.grant] : void 0
+    })
+  );
+}
+async function signIn(identity, input, authenticate) {
   const fetcher = input.fetch ?? fetch;
   const agent = input.agent.trim().toLowerCase();
   const site = await siteMetadata(input.site, fetcher);
@@ -2649,21 +2695,15 @@ async function signInWithPidgeon(identity, input) {
     grant_type: TOKEN_EXCHANGE,
     subject_token: card,
     subject_token_type: TOKEN_TYPE_JWT,
-    audience: site.client_id
+    audience: site.client_id,
+    ...input.delegation ? { requested_token_type: TOKEN_TYPE_JWT } : {}
   });
   const headers = { "content-type": "application/x-www-form-urlencoded" };
   const issued = await fetcher(tokenEndpoint, {
     method: "POST",
     headers: {
       ...headers,
-      ...await signRequest(identity, {
-        method: "POST",
-        url: tokenEndpoint,
-        headers,
-        body: exchange,
-        agent,
-        grants: input.grant ? [input.grant] : void 0
-      })
+      ...await authenticate({ tokenEndpoint, exchange, headers, agent, site })
     },
     body: exchange
   });
@@ -2719,8 +2759,12 @@ var HELP = `pidgeon id \u2014 a signed identity for your agents, on your own dom
   grant <name>           Grant <name> what it may do, as the domain
                            --scope bookings.change --label "manage bookings"
                            --subject customer:42  --audience delta.com  --days 30
+                           --grantor maria@example.com   ask a person instead
   revoke-grant <id>      Take a grant back now
+  revoke-sign-ins <name> End every token <name> signed in with; its card and grants stand
   sign-in <site>         Sign in to a site as an agent   --as <name>  --grant <jws>
+  verify [<file>]        Check a message's signatures (a file, or standard input). No key
+  curl [-I] <url>        Send a request signed as an agent   --as <name>
 
   --domain <domain>      Which domain, when this machine holds more than one
   --json                 Print the API's answer as JSON
@@ -2856,6 +2900,69 @@ Or add them by hand:` : "Add these records at your DNS provider:",
           'It renews itself. Sign with it: import { loadIdentity, signEmail, signedFetch } from "@pidgeon-ai/id".'
         ].join("\n");
       }
+      case "verify": {
+        const file = rest[0];
+        const message = file ? await (await import("fs/promises")).readFile(file, "utf8") : await (options.stdin ?? readStdin)();
+        if (!message.trim()) {
+          throw new UsageError("Give it a message: `pidgeon id verify < message.eml`.");
+        }
+        const response = await (options.fetch ?? fetch)(
+          `${new URL(baseUrl(env)).origin}/api/v1/verify`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ message })
+          }
+        );
+        const answer = await response.json();
+        if (!response.ok || !answer.data) {
+          throw new UsageError(
+            answer.error?.message ?? `The verifier answered ${response.status}.`
+          );
+        }
+        if (json2) return JSON.stringify(answer.data, null, 2);
+        return describeVerification(answer.data);
+      }
+      case "curl": {
+        const head = rest[0] === "-I";
+        const target = (head ? rest[1] : rest[0])?.trim();
+        if (!target) throw new UsageError("Name a URL: `pidgeon id curl -I shop.example`.");
+        const url = /^https?:\/\//.test(target) ? target : `https://${target}`;
+        const identity = await which();
+        const named = flags.get("as");
+        let agent;
+        if (typeof named === "string") {
+          agent = named.includes("@") ? named : `${named}@${identity.domain}`;
+        } else {
+          const agents = await client2(identity).list();
+          if (agents.length !== 1) {
+            throw new UsageError("Say which agent signs, with --as <name>.");
+          }
+          agent = agents[0].address;
+        }
+        const sent = {};
+        const signed = signedFetch(identity, {
+          agent,
+          fetch: async (resource, init) => {
+            new Headers(init?.headers).forEach((value, name) => {
+              if (/^(signature|signature-input|signature-agent|from|content-digest)$/.test(name)) {
+                sent[name] = value;
+              }
+            });
+            return (options.fetch ?? fetch)(resource, init);
+          }
+        });
+        const response = await signed(url, { method: head ? "HEAD" : "GET" });
+        const lines = Object.entries(sent).map(
+          ([name, value]) => `> ${capitalise(name)}: ${value}`
+        );
+        lines.push(`< ${response.status} ${response.statusText}`.trimEnd());
+        if (head) {
+          response.headers.forEach((value, name) => lines.push(`< ${capitalise(name)}: ${value}`));
+          return lines.join("\n");
+        }
+        return [...lines, "", await response.text()].join("\n");
+      }
       case "list": {
         const agents = await client2(await which()).list();
         if (json2) return JSON.stringify(agents, null, 2);
@@ -2895,14 +3002,23 @@ Or add them by hand:` : "Add these records at your DNS provider:",
         }
         const days = flags.get("days");
         const audience = flags.get("audience");
+        const grantor = flags.get("grantor");
         const grant = await client2(await which()).grant({
           agent: name,
           scope: { name: scope, label },
           subject: { type, id: idParts.join(":") },
           ...typeof audience === "string" ? { audience } : {},
+          ...typeof grantor === "string" ? { grantor: { email: grantor } } : {},
           ...typeof days === "string" ? { expires_at: new Date(Date.now() + Number(days) * 864e5).toISOString() } : {}
         });
         if (json2) return JSON.stringify(grant, null, 2);
+        if (grant.consent_url) {
+          return [
+            `Asked ${typeof grantor === "string" ? grantor : "them"} to let ${grant.agent} ${grant.scope.label} for ${grant.subject.type} ${grant.subject.id}.`,
+            `Send them this link; nothing is allowed until they answer it: ${grant.consent_url}`,
+            `Grant ${grant.id}. \`pidgeon id revoke-grant ${grant.id}\` withdraws the request.`
+          ].join("\n");
+        }
         return [
           `${grant.agent} may ${grant.scope.label} for ${grant.subject.type} ${grant.subject.id}${grant.audience ? ` at ${grant.audience}` : ""}, until ${grant.expires_at}.`,
           `Grant ${grant.id}. The agent carries it as Post-Grant; --json prints the JWS.`
@@ -2915,6 +3031,14 @@ Or add them by hand:` : "Add these records at your DNS provider:",
         if (json2) return JSON.stringify(revoked, null, 2);
         return `Grant ${revoked.id} is revoked. The next check of it fails.`;
       }
+      case "revoke-sign-ins": {
+        const name = rest[0]?.trim().toLowerCase();
+        if (!name)
+          throw new UsageError("Name the agent: `pidgeon id revoke-sign-ins support-agent`.");
+        const done = await client2(await which()).revokeSignIns(name);
+        if (json2) return JSON.stringify(done, null, 2);
+        return `${done.address}: ${done.revoked} token${done.revoked === 1 ? "" : "s"} taken back. Its card and grants stand.`;
+      }
       case "sign-in": {
         const site = rest[0];
         const name = flags.get("as");
@@ -2954,6 +3078,39 @@ ${HELP}`);
     throw error;
   }
 }
+function describeVerification(v) {
+  const signer = v.signatures.envelope.domain ?? v.signatures.declaration.domain;
+  const signed = v.signatures.envelope.result === "pass" || v.signatures.declaration.result === "pass";
+  const broken = v.signatures.envelope.result === "fail" || v.signatures.declaration.result === "fail";
+  const row = (ok, label, value) => `${ok === null ? "\xB7" : ok ? "\u2713" : "\u2717"} ${label.padEnd(10)} ${value}`;
+  return [
+    row(
+      signed && !broken,
+      "signature",
+      signed && !broken ? `valid, ${signer}` : broken ? `broken${signer ? `, ${signer}` : ""}` : "none"
+    ),
+    row(v.is_agent, "agent", v.sender?.address ?? "not declared"),
+    row(v.sender?.on_behalf_of ? true : null, "acts for", v.sender?.on_behalf_of ?? "not said"),
+    row(
+      v.body === "not_checked" ? null : v.body === "intact",
+      "body",
+      v.body === "intact" ? "as it was sent" : v.body === "changed" ? "changed since" : "not checked"
+    ),
+    "",
+    v.advice
+  ].join("\n");
+}
+function capitalise(name) {
+  return name.replace(
+    /(^|-)([a-z])/g,
+    (_, dash, letter) => dash + letter.toUpperCase()
+  );
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
 
 // src/index.ts
 var DEFAULT_BASE_URL = "https://pidgeon.ai/api/v1";
@@ -3147,4 +3304,4 @@ export {
   find,
   run
 };
-//# sourceMappingURL=chunk-RWZQSI67.js.map
+//# sourceMappingURL=chunk-F6XZFMGH.js.map