allowfy-check 0.1.1 → 0.1.2

package/README.md

@@ -1,42 +1,115 @@
-# Allowfy Check: Personal Agent Protocol conformance, including sign-in and Operations
+# Allowfy Check: the Poppy conformance tester
 
-The official validator (`test/vendor/poppy-kit`, draft 0.2) checks milestones 1 and 2. For milestone 3 and the extensions it says:
+**Is your site ready for AI agents?** Test any domain against **Poppy**, the [Personal Agent Protocol](https://personalagentprotocol.org), in one command.
 
-> Milestone 3 (sign-in and accounts) checks aren't available in this version of the validator.
+[![npm](https://img.shields.io/npm/v/allowfy-check)](https://www.npmjs.com/package/allowfy-check) [![license](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) [![checks](https://img.shields.io/badge/checks-111-4f46e5)](#what-it-checks)
 
-This add-on checks them. It runs the official checks first, then 37 more:
+```
+npx allowfy-check check https://your-domain.com
+```
+
+Customers are starting to send AI assistants to book, buy and change orders for them. Poppy is the open protocol for how those agents do it:
+- they find a business through `/.well-known/poppy.json`;
+- they prove who they are with signed assertions;
+- they hold DPoP-bound tokens;
+- they sign customers in;
+- they propose changes that customers approve.
+
+Allowfy Check tells you, requirement by requirement, what your implementation gets right and what it doesn't. It shows exactly what was sent, what came back, and the line of the spec it's held to.
+
+**No terminal?** Run the first 20 checks in your browser at **[check.allowfy.com](https://check.allowfy.com)**.
+
+## What it checks
+
+111 checks: all of the official validator's, plus 37 for the parts it doesn't cover yet.
+
+| Milestone | Checks | Covers |
+|---|---|---|
+| 1. Foundation | 42 | `poppy.json` discovery, OAuth server metadata, Sessions, DPoP (replay, key binding, `ath`, nonces) |
+| 2. Interfaces | 32 | OpenAPI, MCP servers (Bearer and DPoP), conversations |
+| 3. Sign-in and accounts | 17 | **Device Sign-In, Account Tokens, sign-out:** `invalid_scope`, `account_mismatch`, narrower scopes only, immediate sign-out |
+| 4. Operations extension | 20 | **Propose, confirm, cancel:** exact-revision approval, `terms_changed`, at most once, ownership by account, `Retry-After` |
+
+Milestones 3 and 4 come from this project. Every check quotes the requirement it tests, word for word, and links to it.
+
+## What you see
+
+```
+✗ discovery.https  poppy.json is served over HTTPS at the well-known path      spec 3
+  Requirement:  "A Company MUST publish its poppy.json document at
+                 https://{domain}/.well-known/poppy.json over HTTPS"
+  Sent:         GET https://example.com/.well-known/poppy.json
+  Got:          404 Not Found
+  Expected:     200 with the poppy.json document
+  Likely cause: Nothing is published at https://example.com/.well-known/poppy.json.
+                Some frameworks and static hosts skip dot-directories like
+                .well-known unless configured to serve them.
+✓ discovery.redirects-https  Every redirect of the well-known URL is to an HTTPS URL
+- discovery.json  poppy.json is a JSON object
+  poppy.json couldn't be loaded (see discovery.https).
+```
 
-| Milestone | Checks |
-|---|---|
-| 3. Sign-in and accounts | **Device Sign-In (4.6):** the request carries no proof and no Session; `invalid_scope`; the link's host; pending; opening the link doesn't approve; tokens; granted scopes; declined; `account_mismatch`.<br>**Account Tokens (4.8):** the same Session; a new Session; narrower scope only; same User only; not accepted at APIs.<br>**Signing out (4.9):** revoking; `invalid_grant`; immediate effect. |
-| 4. Operations extension v1 | Advertised; `operation_not_found`; proposing with 202; fields; nothing performed before confirming; readable; responses are the operation itself; reuse; agents without the extension; `terms_changed`; `user_approval_required`; account ownership (other Sessions, signed out, other Users); cancel; final; `result.summary`; confirm; at most once; `Retry-After`. |
+## Deeper checks: Sessions, sign-in and operations
 
-Each check follows the same rules as the official catalog: it has an id, a level (MUST fails, SHOULD warns), the section, and a quote copied word for word from the spec. `test/allowfy-check-catalog.test.ts` checks the quotes against `reference/`, which holds the spec text at upstream commit `39b35bd`. The results have the same shape and are printed with the official formatter.
+These need a test Personal Agent: a key pair, plus two small files you host anywhere over HTTPS.
 
-## Run
 ```
-npx allowfy-check check https://example.com --probe https://api.example.com/me \
-  --propose 'POST https://api.example.com/orders/ord_1/exchanges {"item_id":"itm_1"}' \
-  [--execute] [--decline] [--other-account] [--plain-identity ../second-agent] [--account-probe <GET url>] [--json]
+npx allowfy-check keygen --base-url https://staging.example.com/poppy-test
+# host .poppy/agent.json and .poppy/jwks.json at the URLs it prints, then:
+npx allowfy-check check https://staging.example.com \
+  --probe https://api.staging.example.com/me \
+  --propose 'POST https://api.staging.example.com/orders/ord_1/exchanges {"item_id":"itm_1"}'
 ```
-- **Test Personal Agent.** It uses the one in `.poppy/`, made with the validator's `keygen`. To check operations, its hosted `agent.json` must list `"extensions": { "operations": { "version": "1" } }`.
-- **Sign-in.** The validator prints the link and code, and you sign in in a browser.
+
+- **Sign-in.** The tool shows you the sign-in link and code, and you approve in a browser.
   - `--decline` also asks you to decline one sign-in.
-  - `--other-account` asks you to sign in once with a second test account.
-- **Safety.** `--propose` only proposes and cancels, so nothing is performed. `--execute` confirms one proposal, so the Company performs the action. Use it only in a test environment.
-- **Agents without the extension.** `--plain-identity` names a second test agent whose `agent.json` doesn't list the extension. It checks that this agent gets no operations.
+  - `--other-account` asks you to use a second test account.
+- **Proposing is safe.** `--propose` only proposes and cancels, so nothing is performed.
+- **`--execute`** also confirms one proposal, so your system performs it. Use it in a test environment only.
+- **Agents without the extension.** `--plain-identity <dir>` adds a second agent whose `agent.json` doesn't list the operations extension, to check it gets no operations.
+- **`--json`** prints machine-readable results.
+
+## In CI
+
+The exit code is 1 when a MUST check fails, so conformance can't silently break:
+
+```yaml
+# .github/workflows/poppy.yml
+name: Poppy conformance
+on: [push, pull_request]
+jobs:
+  poppy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npx allowfy-check@latest check https://staging.example.com --milestone interfaces
+```
+
+## How it relates to the official validator
+
+The Poppy project publishes an official company validator. It covers milestones 1 and 2, and says that sign-in and extensions aren't checked yet. Allowfy Check:
+- runs that validator **unmodified** (vendored under `vendor/`, Apache 2.0);
+- adds the sign-in, account and operations checks in the same style, with the same result format.
+
+It's independent: **not affiliated with the protocol's authors.** Where a result looks wrong, each failure links to the spec's feedback form.
+
+## Develop
+
+```
+npm install
+npm test          # every quote in the catalog appears word for word in reference/
+npm run build     # bundles dist/allowfy-check.mjs
+node src/index.ts check https://example.com
+```
 
-In a test suite, pass a `SignInHelper` that drives your sign-in page (see `test/allowfy-full-conformance.test.ts`).
+Node 22.18 or later runs the TypeScript sources directly. The checks live in `src/`:
+- `catalog.ts`: ids, levels and quotes;
+- `sign-in.ts`;
+- `operations.ts`.
 
-## Not yet
-- Direct Sign-In (4.5) and Mediated Sign-In (4.7).
-- Operations through MCP and conversations (4.2, 4.3).
-- Checking that every change is described in `result.summary` beyond it being present.
+Issues and pull requests are welcome.
 
-## Upstream
-The code is written to move into the official kit:
-- the entries in `catalog.ts` go into its catalog;
-- `sign-in.ts` and `operations.ts` go into `checks/`;
-- `run.ts` is wired into its `runChecks`.
+---
 
-Apache License 2.0, like the kit (`reference/LICENSE`).
+Made by **[Allowfy](https://allowfy.com)**, the door between AI agents and your business: your rules decide what agents may do, customers approve, risky actions wait for your team, and every step is on a signed record. Allowfy passes every check that applies to it.

package/allowfy-check.mjs

@@ -143,6 +143,10 @@ async function getFollowing(http, url, options = {}) {
   return { chain, final: chain[chain.length - 1], problem: "too many redirects" };
 }
 
+// tools/allowfy-check/index.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+
 // test/vendor/poppy-kit/validate/identity.ts
 import {
   existsSync,
@@ -471,6 +475,9 @@ function ath(accessToken) {
 function publicPart(jwk) {
   return { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y };
 }
+function thumbprint(jwk) {
+  return sha256(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
+}
 async function generateKey(extractable = false) {
   const pair = await crypto.subtle.generateKey(ALGORITHM, extractable, [
     "sign",
@@ -551,6 +558,101 @@ var POPPY_DIR = ".poppy";
 function poppyDir(cwd = process.cwd()) {
   return join2(cwd, POPPY_DIR);
 }
+function normalizeBaseUrl(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new UsageError(
+      `--base-url must be a full URL, such as https://staging.example.com/poppy-test (got "${input}").`
+    );
+  }
+  if (url.protocol !== "https:") {
+    throw new UsageError(
+      "--base-url must be an HTTPS URL. Companies fetch agent.json and jwks.json over HTTPS."
+    );
+  }
+  if (url.search || url.hash) throw new UsageError("--base-url can't have a query or fragment.");
+  return url.toString().replace(/\/+$/, "");
+}
+var UsageError = class extends Error {
+};
+async function keygen(baseUrlInput, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const dir = poppyDir(cwd);
+  const baseUrl = normalizeBaseUrl(baseUrlInput);
+  const keyFile = join2(dir, "private-key.jwk");
+  if (existsSync(keyFile) && !options.force) {
+    throw new UsageError(
+      `${keyFile} already exists. Run keygen with --force to replace it; you'll then need to host the new agent.json and jwks.json.`
+    );
+  }
+  mkdirSync(dir, { recursive: true });
+  const generated = await generateKey(true);
+  const kid = (await thumbprint(generated.publicJwk)).slice(0, 16);
+  const privateJwk = { ...generated.privateJwk, kid, alg: "ES256", use: "sig" };
+  const publicJwk = { ...generated.publicJwk, kid, alg: "ES256", use: "sig" };
+  const clientId = `${baseUrl}/agent.json`;
+  const agent = {
+    client_id: clientId,
+    client_name: "Poppy validator (test)",
+    jwks_uri: `${baseUrl}/jwks.json`,
+    redirect_uris: [`${baseUrl}/callback`],
+    token_endpoint_auth_method: "private_key_jwt"
+  };
+  const jwks = { keys: [publicJwk] };
+  writeFileSync(keyFile, JSON.stringify(privateJwk, null, 2) + "\n", { mode: 384 });
+  chmodSync(keyFile, 384);
+  writeFileSync(join2(dir, "agent.json"), JSON.stringify(agent, null, 2) + "\n");
+  writeFileSync(join2(dir, "jwks.json"), JSON.stringify(jwks, null, 2) + "\n");
+  const configFile = join2(dir, "config.json");
+  let userIds = {};
+  if (existsSync(configFile)) {
+    try {
+      const old = JSON.parse(readFileSync2(configFile, "utf8"));
+      if (old.client_id === clientId) userIds = old.user_ids ?? {};
+    } catch {
+    }
+  }
+  const config = { client_id: clientId, base_url: baseUrl, user_ids: userIds };
+  writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+  return {
+    dir,
+    clientId,
+    files: [
+      { local: join2(dir, "agent.json"), url: clientId },
+      { local: join2(dir, "jwks.json"), url: agent.jwks_uri }
+    ],
+    gitignore: ensureGitignored(cwd)
+  };
+}
+function ensureGitignored(cwd) {
+  let root;
+  for (let d = resolve(cwd); ; d = dirname(d)) {
+    if (existsSync(join2(d, ".git"))) {
+      root = d;
+      break;
+    }
+    if (dirname(d) === d) break;
+  }
+  if (!root) return void 0;
+  const ignored = /^\s*\/?\.poppy\/?\s*$/m;
+  for (let d = resolve(cwd); ; d = dirname(d)) {
+    const file2 = join2(d, ".gitignore");
+    if (existsSync(file2) && ignored.test(readFileSync2(file2, "utf8"))) return void 0;
+    if (d === root || dirname(d) === d) break;
+  }
+  const file = join2(cwd, ".gitignore");
+  const existing = existsSync(file) ? readFileSync2(file, "utf8") : "";
+  const prefix = existing === "" || existing.endsWith("\n") ? "" : "\n";
+  appendFileSync(
+    file,
+    `${prefix}# Poppy validator test identity and results (private key)
+.poppy/
+`
+  );
+  return file;
+}
 async function loadIdentity(cwd = process.cwd()) {
   const dir = poppyDir(cwd);
   const keyFile = join2(dir, "private-key.jwk");
@@ -4316,10 +4418,15 @@ async function main(argv) {
       "other-account": { type: "boolean" },
       milestone: { type: "string" },
       only: { type: "string", multiple: true },
-      json: { type: "boolean" }
+      json: { type: "boolean" },
+      "base-url": { type: "string" },
+      force: { type: "boolean" }
     }
   });
-  if (positionals[0] !== "check" || !positionals[1]) fail("Usage: index.ts check <https://company-domain> [options]");
+  if (positionals[0] === "keygen") return keygenCommand(values["base-url"], !!values.force);
+  if (positionals[0] !== "check" || !positionals[1]) {
+    fail("Usage:\n  allowfy-check check <https://company-domain> [options]\n  allowfy-check keygen --base-url <https://where-you-host-agent.json>");
+  }
   const target = new URL(positionals[1]).origin;
   const milestones = parseMilestones(values.milestone ?? "all");
   if (!milestones) fail("--milestone must be foundation, interfaces, sign-in, extensions, all, or 1-4.");
@@ -4352,6 +4459,29 @@ async function main(argv) {
   }
   return summarize(results).total.fail > 0 ? 1 : 0;
 }
+async function keygenCommand(baseUrl, force) {
+  if (!baseUrl) fail("keygen needs --base-url, the HTTPS URL where you'll host agent.json and jwks.json.");
+  const result = await keygen(baseUrl, { force });
+  const agentFile = join3(result.dir, "agent.json");
+  const agent = JSON.parse(readFileSync3(agentFile, "utf8"));
+  writeFileSync2(agentFile, JSON.stringify({ ...agent, extensions: { operations: { version: "1" } } }, null, 2) + "\n");
+  console.log(
+    [
+      `Created a test Personal Agent in ${result.dir}.`,
+      "",
+      "Host these two files, unchanged, at exactly these HTTPS URLs (no redirects):",
+      ...result.files.map((f) => `  ${f.local}
+    \u2192 ${f.url}`),
+      "",
+      `client_id: ${result.clientId}`,
+      "The private key stays in .poppy/private-key.jwk. Never host or commit it.",
+      result.gitignore ? `Added .poppy/ to ${result.gitignore}.` : "",
+      "Its agent.json lists the operations extension, so the operations checks can run.",
+      "This identity is for testing only. Don't add it to a production allowlist."
+    ].filter((l, i, a) => l !== "" || a[i - 1] !== "").join("\n")
+  );
+  return 0;
+}
 main(process.argv.slice(2)).then(
   (code) => process.exitCode = code,
   (error) => {

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "allowfy-check",
-  "version": "0.1.1",
-  "description": "Check a business against the Personal Agent Protocol: discovery, Sessions, DPoP, APIs, sign-in, Account Tokens and the operations extension.",
+  "version": "0.1.2",
+  "description": "Is your site ready for AI agents? Test it against Poppy (the Personal Agent Protocol): 111 checks for poppy.json, OAuth & DPoP, sign-in and operations.",
   "keywords": [
-    "personal-agent-protocol",
     "poppy",
+    "poppy-json",
+    "personal-agent-protocol",
     "ai-agents",
+    "agentic-commerce",
+    "agent-interoperability",
     "conformance",
+    "validator",
     "oauth",
     "dpop",
+    "cli",
     "allowfy"
   ],
   "homepage": "https://check.allowfy.com",