macwarden 1.0.1 → 1.1.1

package/schemas/output/recommend.schema.json

@@ -0,0 +1,498 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ZilverZtream/macwarden/blob/main/schemas/output/recommend.schema.json",
+  "title": "macwarden recommend --json output",
+  "description": "Normative source: SPEC.md, Commands > 9. recommend. A recommendation only; commands is empty whenever the evidence does not support narrowing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "command",
+    "ok",
+    "warnings",
+    "result",
+    "error"
+  ],
+  "properties": {
+    "schema": {
+      "const": 1
+    },
+    "command": {
+      "const": "recommend"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/warning"
+      }
+    },
+    "result": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$ref": "#/$defs/result"
+        },
+        {
+          "$ref": "#/$defs/help"
+        }
+      ]
+    },
+    "error": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$ref": "#/$defs/error"
+        }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "ok": {
+            "const": true
+          }
+        },
+        "required": [
+          "ok"
+        ]
+      },
+      "then": {
+        "properties": {
+          "result": {
+            "oneOf": [
+              {
+                "$ref": "#/$defs/result"
+              },
+              {
+                "$ref": "#/$defs/help"
+              }
+            ]
+          },
+          "error": {
+            "type": "null"
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "result": {
+            "type": "null"
+          },
+          "error": {
+            "$ref": "#/$defs/error"
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "step",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8
+        },
+        "step": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "warning": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "type": "string",
+              "minLength": 1
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "rootKeyId": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]{0,19})$",
+      "description": "uint64 as a canonical decimal string (range up to 18446744073709551615 is enforced by the decoder)."
+    },
+    "grade": {
+      "enum": [
+        "ADMIN",
+        "SPEND",
+        "OPERATE",
+        "RECEIVE",
+        "READ",
+        "UNASSESSED"
+      ]
+    },
+    "registryEntry": {
+      "type": "object",
+      "required": [
+        "nodePubkey",
+        "label",
+        "rootKeyId",
+        "permissions",
+        "caveats",
+        "grade",
+        "fingerprint",
+        "outPath",
+        "createdAt",
+        "verified",
+        "status",
+        "revokedAt",
+        "revokeEvidence",
+        "replaces",
+        "replacedBy"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "nodePubkey": {
+          "type": "string",
+          "pattern": "^0[23][0-9a-fA-F]{64}$"
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[A-Za-z][A-Za-z0-9._-]{0,63}$"
+        },
+        "rootKeyId": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)$"
+        },
+        "permissions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "caveats": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "grade": {
+          "enum": [
+            "ADMIN",
+            "SPEND",
+            "OPERATE",
+            "RECEIVE",
+            "READ",
+            "UNASSESSED"
+          ]
+        },
+        "fingerprint": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^fp:[0-9a-f]{16}$"
+        },
+        "outPath": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "createdAt": {
+          "type": "string"
+        },
+        "verified": {
+          "type": "boolean"
+        },
+        "status": {
+          "enum": [
+            "active",
+            "revoked"
+          ]
+        },
+        "revokedAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "revokeEvidence": {
+          "enum": [
+            "rejected",
+            "by-id-only",
+            null
+          ]
+        },
+        "replaces": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^(0|[1-9][0-9]*)$"
+        },
+        "replacedBy": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^(0|[1-9][0-9]*)$"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "fingerprint": {
+                "type": "null"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "verified": {
+                "const": false
+              },
+              "outPath": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "help": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "usage"
+      ],
+      "properties": {
+        "usage": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^macwarden recommend "
+          }
+        }
+      }
+    },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "node",
+        "selector",
+        "label",
+        "rootKeyId",
+        "credentials",
+        "observed",
+        "unmapped",
+        "recommended",
+        "recommendedUris",
+        "current",
+        "unneeded",
+        "observation",
+        "commands"
+      ],
+      "properties": {
+        "node": {
+          "type": "string",
+          "pattern": "^0[23][0-9a-fA-F]{64}$"
+        },
+        "selector": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "rootKeyId": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/rootKeyId"
+            }
+          ]
+        },
+        "credentials": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^id:[0-9a-f]{16}$"
+          }
+        },
+        "observed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "method",
+              "calls",
+              "lastUsed",
+              "permissions"
+            ],
+            "properties": {
+              "method": {
+                "type": "string"
+              },
+              "calls": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "lastUsed": {
+                "type": "string"
+              },
+              "permissions": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "unmapped": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        },
+        "recommended": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        },
+        "recommendedUris": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^uri:"
+          }
+        },
+        "current": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "unneeded": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          }
+        },
+        "observation": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "seconds",
+            "since",
+            "until",
+            "sessions",
+            "short",
+            "accepted"
+          ],
+          "properties": {
+            "seconds": {
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              ]
+            },
+            "since": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "until": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "sessions": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "short": {
+              "type": "boolean"
+            },
+            "accepted": {
+              "type": "boolean"
+            }
+          }
+        },
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/output/respond.schema.json

@@ -36,6 +36,9 @@
         },
         {
           "$ref": "#/$defs/result"
+        },
+        {
+          "$ref": "#/$defs/help"
         }
       ]
     },
@@ -65,7 +68,14 @@
       "then": {
         "properties": {
           "result": {
-            "$ref": "#/$defs/result"
+            "oneOf": [
+              {
+                "$ref": "#/$defs/result"
+              },
+              {
+                "$ref": "#/$defs/help"
+              }
+            ]
           },
           "error": {
             "type": "null"
@@ -431,6 +441,23 @@
         }
       }
     },
+    "help": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "usage"
+      ],
+      "properties": {
+        "usage": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^macwarden respond "
+          }
+        }
+      }
+    },
     "result": {
       "type": "object",
       "additionalProperties": false,

package/schemas/output/revoke.schema.json

@@ -36,6 +36,9 @@
         },
         {
           "$ref": "#/$defs/result"
+        },
+        {
+          "$ref": "#/$defs/help"
         }
       ]
     },
@@ -65,7 +68,14 @@
       "then": {
         "properties": {
           "result": {
-            "$ref": "#/$defs/result"
+            "oneOf": [
+              {
+                "$ref": "#/$defs/result"
+              },
+              {
+                "$ref": "#/$defs/help"
+              }
+            ]
           },
           "error": {
             "type": "null"
@@ -285,6 +295,23 @@
         }
       ]
     },
+    "help": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "usage"
+      ],
+      "properties": {
+        "usage": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^macwarden revoke "
+          }
+        }
+      }
+    },
     "result": {
       "oneOf": [
         {

package/schemas/output/rotate.schema.json

@@ -36,6 +36,9 @@
         },
         {
           "$ref": "#/$defs/result"
+        },
+        {
+          "$ref": "#/$defs/help"
         }
       ]
     },
@@ -65,7 +68,14 @@
       "then": {
         "properties": {
           "result": {
-            "$ref": "#/$defs/result"
+            "oneOf": [
+              {
+                "$ref": "#/$defs/result"
+              },
+              {
+                "$ref": "#/$defs/help"
+              }
+            ]
           },
           "error": {
             "type": "null"
@@ -285,6 +295,23 @@
         }
       ]
     },
+    "help": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "usage"
+      ],
+      "properties": {
+        "usage": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^macwarden rotate "
+          }
+        }
+      }
+    },
     "result": {
       "oneOf": [
         {

package/schemas/output/scan.schema.json

@@ -14,7 +14,7 @@
       "type": "array", "maxItems": 1, "items": { "const": "shallow-history" }
     },
     "result": {
-      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/result" }]
+      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/result" }, { "$ref": "#/$defs/help" }]
     },
     "error": {
       "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/error" }]
@@ -25,7 +25,7 @@
       "if": { "properties": { "ok": { "const": true } }, "required": ["ok"] },
       "then": {
         "properties": {
-          "result": { "$ref": "#/$defs/result" },
+          "result": { "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/help" }] },
           "error": { "type": "null" }
         }
       },
@@ -38,6 +38,11 @@
     }
   ],
   "$defs": {
+    "help": {
+      "description": "macwarden scan --help --json: the command synopsis lines (SPEC.md, Output > Help).",
+      "type": "object", "additionalProperties": false, "required": ["usage"],
+      "properties": { "usage": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^macwarden scan " } } }
+    },
     "agentLocation": {
       "type": "object",
       "additionalProperties": false,
@@ -80,6 +85,8 @@
         "root-key-0",
         "trailing-bytes",
         "bad-time-before",
+        "identifier-exceeds-bounds",
+        "caveats-exceed-bounds",
         "unassessed-uri",
         "unassessed-permission",
         "no-permissions",
@@ -144,7 +151,7 @@
         },
         "context": { "description": "Only when the credential is a string value inside an MCP server entry of a JSON config (an AI agent configuration).", "const": "mcp-config" },
         "alsoAt": {
-          "description": "Only with --git-history: the same file content was also added at other paths. One finding stands for all of them: count is how many other paths, paths lists up to five.",
+          "description": "With --git-history (a finding with commit): the same file content was also added at other paths. On a work-tree finding (no commit): the same file is also reachable under other hard-link names within the same path argument. One finding stands for all of them: count is how many other paths, paths lists up to five.",
           "type": "object",
           "additionalProperties": false,
           "required": ["count", "paths"],