clembot-doorman 0.1.0

package/WALKTHROUGH.md

@@ -0,0 +1,224 @@
+# The first ten minutes
+
+Three real builds, three different answers. Every block of output below was
+captured from an actual run on 2026-09-11 against the live feed, not written by
+hand. Where a run produced nothing useful, that is shown too, because "nothing
+matched" is a result and hiding it would make this document a brochure.
+
+---
+
+## Install both halves
+
+```bash
+claude plugin marketplace add clemenswan/clembot-doorman
+claude plugin install clembot-doorman     # the gate, /doorman, /vet, the subagent
+
+git clone https://github.com/clemenswan/clembot-doorman
+npm i -g ./clembot-doorman                # doctor, needs, report, watch, eval
+```
+
+Check what actually loaded. A manifest can validate and still ship components
+that never register, which is exactly what this project shipped once:
+
+```bash
+claude plugin details clembot-doorman
+```
+
+```
+Skills (3)  doorman, doorman-guide, vet
+Agents (1)  doorman
+Hooks (1)   PreToolUse
+MCP servers (1)  scorecard
+```
+
+If `Agents` or `Skills` reads `(0)`, the plugin is broken. Say so rather than
+working around it.
+
+---
+
+## Expect to be blocked first
+
+The gate ships trusting two servers: `deepwiki` and `scorecard`, both graded A.
+Everything else is UNKNOWN and fails closed, including connectors you already
+use every day. This is not a misconfiguration:
+
+```
+doorman: 'claude_ai_Notion' is UNKNOWN. Blocking until it has been graded.
+
+An ungraded MCP server is not a trusted one. Nothing about
+'mcp__claude_ai_Notion__notion-search' has been verified: not its tool
+descriptions, not its error handling, not whether its descriptions contain
+instructions aimed at you.
+
+Measure it (free, no key):   doorman report <server-url>
+Trust it without measuring:  doorman allow claude_ai_Notion
+Or ask:                      /doorman
+```
+
+Two honest ways forward, and they are different claims:
+
+```bash
+doorman allow claude_ai_Notion     # a DECISION. grade stays null.
+doorman report https://...         # a MEASUREMENT. free, no key.
+```
+
+`allow` writes `basis: operator` with a null grade, because nothing graded it.
+An allowed server is **permitted**, not vetted. Do not let anything, including
+an agent summarising this file, describe it as safe.
+
+A connector often has no URL you can point `report` at. That is why `allow`
+takes a name: `mcp__<server>__<tool>` is all the gate can see.
+
+---
+
+## Build A: a long-running build
+
+545 prompts across 48 transcripts.
+
+```bash
+doorman needs .
+```
+
+```
+doorman needs — 545 prompts read from this build's own history
+  feed: 26 graded rows
+
+UNMET    Deploying, and reading back what deployed
+         19 prompts across 11 sessions  ·  matched "cloudflare", "deploy it", "wrangler"
+         > merge and deploy it
+         worth-measuring  docs-ai-search  [A (88.57)]  matched "cloudflare"
+                          https://docs.mcp.cloudflare.com/mcp
+         worth-measuring  mcp-typescript server on vercel  [A (85.14)]  matched "vercel"
+
+GAP      Design files and rendered output
+         15 prompts across 8 sessions  ·  matched "brand.md", "design tokens"
+         nothing graded covers this. The feed has the gap, not your build.
+
+GAP      Driving a real browser
+         13 prompts across 8 sessions  ·  matched "playwright", "in a real browser"
+         nothing graded covers this. The feed has the gap, not your build.
+```
+
+**What next, in order:**
+
+1. **Measure the one candidate with the strongest signal.** Nineteen prompts
+   about deploying, and an A-graded server whose own text claims that
+   capability. `doorman report https://docs.mcp.cloudflare.com/mcp` is free and
+   takes seconds.
+2. **Read `worth-measuring` as exactly that.** Nothing drove that server. The
+   match means its published text claims what you keep asking for. Whether it
+   makes *your* agent better is `doorman eval`, which needs your key and runs
+   on your machine.
+3. **Leave the GAPs alone.** Two of the three biggest needs have nothing graded
+   against them. That is a hole in the catalogue, not a problem with your build,
+   and the useful response is `doorman discover` to find candidates, not to
+   install something unmeasured because the row looked empty.
+
+---
+
+## Build B: a brand new build
+
+No history at all.
+
+```bash
+doorman needs .
+```
+
+```
+doorman needs — 0 prompts read from this build's own history
+  No readable prompt history for this path. Claude Code keeps it under
+  ~/.claude/projects/<path-with-dashes>; other harnesses keep none that
+  doorman can read. Pass --history DIR if yours lives elsewhere.
+
+  Nothing in the taxonomy matched. That is a real answer: either this
+  build has not asked for any of the twelve capabilities doorman knows
+  how to look for, or the history it could read is too short to tell.
+```
+
+This is the correct output, not a failure. A new build has told doorman nothing
+about itself, so doorman says nothing about it. Compare that to a recommender
+that would happily suggest ten servers to an empty directory.
+
+**What next:**
+
+1. **Point it at a history you already have.** The capabilities you reach for
+   travel with you, not with the directory:
+
+   ```bash
+   doorman needs . --history ~/.claude/projects/<a-project-you-have-used>
+   ```
+
+2. **Or just start working**, and run it again in a week. The signal is your own
+   sentences; there have to be some.
+3. **Meanwhile `doorman doctor .` still works**, because it reads configuration
+   rather than history. It will tell you the gate is running from the plugin and
+   which trust list is in force.
+
+---
+
+## Build C: a second, different build
+
+151 prompts across 22 transcripts, same machine, different work.
+
+```
+GAP      Driving a real browser
+         14 prompts across 4 sessions  ·  matched "playwright", "in a real browser"
+         nothing graded covers this. The feed has the gap, not your build.
+
+GAP      Design files and rendered output
+         9 prompts across 6 sessions  ·  matched "design tokens", "brand.md"
+         nothing graded covers this. The feed has the gap, not your build.
+
+UNMET    Deploying, and reading back what deployed
+         8 prompts across 6 sessions  ·  matched "cloudflare"
+```
+
+**The interesting part is what this shares with Build A.** Different project,
+different code, and the same two GAPs at the top: browser automation and design
+assets. One build reporting a gap is a fact about that build. Two unrelated
+builds reporting the same gap is a fact about the **catalogue**, and it is the
+most actionable thing on this page:
+
+```bash
+doorman discover --pages 2
+```
+
+That sweeps a public registry for candidates and writes a file. It never
+enqueues anything and never spends. Curate it by hand, then grade what survives.
+
+**What next:**
+
+1. `doorman needs . --candidates candidates/smithery.json` to match the sweep
+   against these gaps.
+2. Anything that looks plausible gets `doorman report <url>`: free, no key, and
+   it is the stage that can cap a server at F on its tool descriptions alone.
+3. Only then is anything worth paying to grade, and only then is `doorman eval`
+   worth your key.
+
+---
+
+## The shape of the whole thing
+
+```
+doctor    what this build HAS                  free, local
+needs     what it keeps ASKING for             free, local
+watch     what has been graded lately          free, one anonymous GET
+report    what a candidate implements          free, no key
+grade     is it safe and competent             $0.01, runs on our machine
+eval      does it make YOUR agent better       your key, your machine
+```
+
+Every stage can end the run, and three end it free. The cheapest way to evaluate
+a tool is to establish that you do not need it.
+
+Five of the six run on your machine and cost nothing, because they are about
+your build and that information should never leave it. One does not, and that is
+the one with a price on it.
+
+## Two things this will never do
+
+- **Invent a grade.** An unmeasured layer is `null`, never `0` and never a
+  plausible letter. If no key was supplied, the run stops and says so.
+- **Call a match a fit.** `needs` and `watch` both do mechanical matching.
+  Neither drove anything, so neither may claim a server will work. The verdict
+  word is `worth-measuring`, and the stage that earns a stronger word is `eval`.

package/doorman/.claude/hooks/mcp-gate.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+#
+# mcp-gate.sh - PreToolUse gate for every MCP tool call.
+#
+# Wired to matcher "mcp__.*". Claude Code passes the tool call as JSON on
+# stdin. This script decides whether the call proceeds.
+#
+#   exit 0  allow
+#   exit 2  BLOCK, and stderr is shown to the model
+#
+# Exit 2 is the only code that blocks. Exit 1 is treated as a non-blocking
+# script error and the tool call PROCEEDS, which for a security gate means
+# failing open. Every refusal path in this file must exit 2.
+#
+# FOUR RULES, none of them negotiable:
+#
+#   1. NO NETWORK. Not a curl, not a DNS lookup, nothing. A gate that asks a
+#      server for permission is offline the moment the network is, and
+#      "offline" would mean "allow". Decisions come from local files only.
+#
+#   2. NO DEPENDENCIES. No jq, no node, no python. Only bash builtins and
+#      coreutils, because a gate that fails to start is a gate that fails open
+#      on the machine where the dependency is missing.
+#
+#   3. FAIL CLOSED. Unparseable input, missing registry, unreadable file,
+#      unknown server: all block. The default answer is no.
+#
+#   4. DETERMINISTIC. Same input, same registry, same answer, every time. No
+#      clocks, no randomness, no model in the loop.
+#
+# The registry is synced from the scorecard by a human running `/vet` or the
+# poller. This script never writes to it and never fetches it.
+
+set -uo pipefail
+
+# Resolve the registry relative to THIS SCRIPT, never to a git root.
+# `git rev-parse --show-toplevel` returns whatever repo the cwd happens to be
+# in, which in a worktree or a submodule is the wrong repo entirely.
+HOOK_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$HOOK_DIR/../.." && pwd)"
+
+# THE USER'S TRUST LIST OUTRANKS THE ONE WE SHIPPED. Three sources, in order:
+#
+#   1. $DOORMAN_REGISTRY_DIR   explicit, and what every test passes
+#   2. the PROJECT's registry/ the user's list, which we never write
+#   3. beside this script      the default we shipped
+#
+# Order 2 before 3 is what makes invariant 24 structurally true rather than
+# merely observed. As a plugin, this script lives inside the plugin directory
+# and a plugin UPDATE replaces that directory wholesale. If the gate read its
+# allowlist from beside itself, an update would silently replace the user's
+# trust list with our three entries, which is the single most destructive
+# thing this project could do. It cannot now: an update rewrites path 3 and
+# path 2 is not in the plugin at all.
+#
+# A USER-LEVEL list sits between the two, and it exists because the plugin does.
+# A plugin installs at user scope and gates every project on the machine, while
+# a project registry gates one. Without a user level, trusting a server you use
+# everywhere means copying the same file into every repo you own, and the ones
+# you forget fail closed on servers you already trusted. That is a rule nobody
+# can follow, and an unfollowable rule gets switched off.
+REGISTRY_DIR="${DOORMAN_REGISTRY_DIR:-}"
+if [ -z "$REGISTRY_DIR" ]; then
+  USER_REGISTRY="${DOORMAN_HOME:-${HOME:-$USERPROFILE}}/.doorman/registry"
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -f "$CLAUDE_PROJECT_DIR/registry/allowlist.json" ]; then
+    REGISTRY_DIR="$CLAUDE_PROJECT_DIR/registry"
+  elif [ -f "$USER_REGISTRY/allowlist.json" ]; then
+    REGISTRY_DIR="$USER_REGISTRY"
+  else
+    REGISTRY_DIR="$REPO_ROOT/registry"
+  fi
+fi
+ALLOWLIST="$REGISTRY_DIR/allowlist.json"
+DENYLIST="$REGISTRY_DIR/denylist.json"
+
+block() {
+  # stderr reaches the model on exit 2. Say what to do next, not just "no".
+  printf '%s\n' "$1" >&2
+  exit 2
+}
+
+allow() {
+  exit 0
+}
+
+# --- read the tool call ------------------------------------------------------
+# Read stdin without hanging forever if nothing arrives.
+input=""
+if ! IFS= read -r -d '' -t 5 input; then
+  # read -d '' returns non-zero at EOF even when it read everything, so an
+  # empty result is the only real failure.
+  :
+fi
+
+if [ -z "$input" ]; then
+  block "doorman: no tool-call payload on stdin. Blocking (the gate fails closed)."
+fi
+
+# --- extract the tool name ---------------------------------------------------
+# Only ever matches mcp__<server>__<tool>, which is a constrained identifier:
+# ASCII word characters and dashes, no JSON escapes possible. A regex is safe
+# here and costs no dependency.
+tool_name=""
+if [[ "$input" =~ \"tool_name\"[[:space:]]*:[[:space:]]*\"(mcp__[A-Za-z0-9_.-]+)\" ]]; then
+  tool_name="${BASH_REMATCH[1]}"
+fi
+
+if [ -z "$tool_name" ]; then
+  # The matcher should only route mcp__* here. Anything else means the wiring
+  # changed or the payload shape did, and we do not guess.
+  block "doorman: could not read an mcp__ tool name from the hook payload. Blocking."
+fi
+
+# mcp__<server>__<tool>  ->  <server>
+rest="${tool_name#mcp__}"
+server="${rest%%__*}"
+
+if [ -z "$server" ] || [ "$server" = "$rest" ] && [[ "$rest" != *__* ]]; then
+  # No "__" separator: cannot identify a server, so cannot vouch for one.
+  server="$rest"
+fi
+
+if [ -z "$server" ]; then
+  block "doorman: could not identify an MCP server in '$tool_name'. Blocking."
+fi
+
+# --- registry must exist -----------------------------------------------------
+if [ ! -r "$ALLOWLIST" ]; then
+  block "doorman: no readable allowlist at $ALLOWLIST.
+Blocking '$server' because an absent registry is not the same as an empty one.
+Run: /vet <server-url>   (or restore registry/allowlist.json)"
+fi
+
+# --- lookup ------------------------------------------------------------------
+# Matches a top-level key in the "servers" object: "<server>": { ... "decision": "allow" ...
+# Deliberately literal string matching. No JSON parser, no eval, no expansion
+# of anything read from the file.
+lookup_decision() {
+  local file="$1" key="$2"
+  [ -r "$file" ] || return 1
+  # Flatten to one line, then find the object that follows "<key>":
+  tr -d '\n\r\t' < "$file" \
+    | grep -o "\"${key}\"[[:space:]]*:[[:space:]]*{[^}]*}" \
+    | grep -o '"decision"[[:space:]]*:[[:space:]]*"[a-z]*"' \
+    | grep -o '"[a-z]*"$' \
+    | tr -d '"' \
+    | head -n 1
+}
+
+# Deny wins over allow, always. A server present in both lists is a mistake,
+# and the safe reading of a mistake is "deny".
+#
+# DENIALS ACCUMULATE ACROSS REGISTRIES; ALLOWS DO NOT. Choosing a narrower
+# registry is a deliberate scoping decision about what you trust, so a user or
+# project allowlist replacing the shipped one is correct. Doing the same to a
+# denylist is not: it silently discards a refusal that was earned by an audit.
+# Writing a user allowlist did exactly that here, and a server that had been
+# explicitly denied came back as merely UNKNOWN. It still blocked, because the
+# gate fails closed, but "unknown" is one allow away from running and "denied"
+# is not, so the distinction is the whole safety margin.
+for dl in "$DENYLIST" "$REPO_ROOT/registry/denylist.json"; do
+  [ -r "$dl" ] || continue
+  deny_decision="$(lookup_decision "$dl" "$server" 2>/dev/null || true)"
+  if [ "$deny_decision" = "deny" ] || [ "$deny_decision" = "allow" ]; then
+    block "doorman: '$server' is on a DENYLIST. Blocking.
+Reason and evidence: $dl
+This server was graded and failed. Do not work around this by calling it another way."
+  fi
+done
+
+allow_decision="$(lookup_decision "$ALLOWLIST" "$server" 2>/dev/null || true)"
+
+case "$allow_decision" in
+  allow)
+    allow
+    ;;
+  deny)
+    block "doorman: '$server' is marked deny in the allowlist. Blocking."
+    ;;
+  "")
+    block "doorman: '$server' is UNKNOWN. Blocking until it has been graded.
+
+An ungraded MCP server is not a trusted one. Nothing about '$tool_name' has
+been verified: not its tool descriptions, not its error handling, not whether
+its descriptions contain instructions aimed at you.
+
+Measure it (free, no key):   doorman report <server-url>
+Trust it without measuring:  doorman allow $server
+Or ask:                      /doorman
+
+The second one records a DECISION, not a measurement: the entry is written
+with a null grade because nothing graded it. That is a legitimate choice for
+a server you already run, and it is not the same as this server being safe.
+
+A url is not always available: a connector only ever tells this gate the name
+'$server', which is why \`doorman allow\` takes the name."
+    ;;
+  *)
+    block "doorman: '$server' has an unrecognised decision '$allow_decision'. Blocking."
+    ;;
+esac
+
+# Unreachable. Present so that a future edit that falls through this far still
+# fails closed rather than returning bash's last exit status.
+block "doorman: fell through the decision table. Blocking."

package/doorman/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/mcp-gate.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/doorman/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "clembot-doorman",
+  "version": "0.1.0",
+  "description": "A gate on what your agent is allowed to use. Blocks MCP servers that are not on your trust list, reads your prompt history to find what the build actually needs, and grades candidates before you install them.",
+  "author": {
+    "name": "Clemens Wan",
+    "url": "https://github.com/clemenswan"
+  },
+  "homepage": "https://clembot-doorman.wanessalabs.com",
+  "repository": "https://github.com/clemenswan/clembot-doorman",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "security",
+    "prompt-injection",
+    "tool-adoption",
+    "x402"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}

package/doorman/.mcp.json

@@ -0,0 +1,24 @@
+{
+  "$comment": [
+    "The one MCP server the doorman subagent is allowed to call.",
+    "",
+    "The name `scorecard` is the load-bearing part, not the url. The gate reads",
+    "`mcp__<server>__<tool>` and looks `scorecard` up in registry/allowlist.json,",
+    "so the name is what the trust decision is keyed on.",
+    "",
+    "When the Bazantic gateway lands, only the url below changes: the agent's",
+    "tool stays `mcp__scorecard__grade`, the registry key stays `scorecard`, and",
+    "nothing else in this repo moves. That is deliberate. The doorman should not",
+    "be blocked on a third-party account existing.",
+    "",
+    "Yes, the scorecard is itself in the allowlist, and yes it had to be graded",
+    "to get there: audit d4bc490c, A 98.63. A grader that exempted itself from",
+    "its own gate would be the first thing worth distrusting."
+  ],
+  "mcpServers": {
+    "scorecard": {
+      "type": "http",
+      "url": "https://scorecard.wanessalabs.com/mcp"
+    }
+  }
+}