{"_id":"@agentholdings/agent-passport","_rev":"2-8fe4c1d8fdbca6a6333d64e6519c40e5","name":"@agentholdings/agent-passport","dist-tags":{"latest":"0.1.5"},"versions":{"0.1.0":{"name":"@agentholdings/agent-passport","version":"0.1.0","keywords":["openclaw","plugin","security","trust","scanner","supply-chain-security","drift-detection","agent-passport"],"license":"SEE LICENSE IN LICENSE","_id":"@agentholdings/agent-passport@0.1.0","maintainers":[{"name":"markneville","email":"mark@markneville.dev"}],"homepage":"https://github.com/agentpassportai/agent-passport-plugin","bugs":{"url":"https://github.com/agentpassportai/agent-passport-plugin/issues"},"dist":{"shasum":"d6bf1f5c0b0155e3cbd3bf76bc22f001d0df8762","tarball":"https://registry.npmjs.org/@agentholdings/agent-passport/-/agent-passport-0.1.0.tgz","fileCount":33,"integrity":"sha512-Mp+GivGa7vfHq7zlC4JalWNJl1kkFzRP9Rq/33jh5/9SL4npttFuc9cQfpJtuERzSzQQ2VdOZ2VS67R+jL4bfA==","signatures":[{"sig":"MEUCIGf5ZDTTo0F71oV3QPJGjqj7ZZr/FdEh1D/R4b1XNDrBAiEA9oVN3qx8erv/9gfTKeqkzwbM2tHEkWbZ4rGdcTz1QW0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":223460},"type":"module","gitHead":"2ea0372df756d9dd94203547cd3df210ce80a5e1","scripts":{"pack:dry":"npm pack --dry-run","drift:sweep":"node ./scripts/drift-alerts.mjs --mode sweep","drift:alerts":"node ./scripts/drift-alerts.mjs","scan:regression":"node ./scripts/scanner-regression.mjs","drift:alerts:json":"node ./scripts/drift-alerts.mjs --format json","scan:regression:cli":"node ./scripts/scanner-regression-cli-smoke.mjs","scan:regression:case":"node ./scripts/scanner-regression.mjs --case","scan:regression:help":"node ./scripts/scanner-regression.mjs --help","scan:regression:json":"node ./scripts/scanner-regression.mjs --json","scan:regression:list":"node ./scripts/scanner-regression.mjs --list-cases","scan:regression:quiet":"node ./scripts/scanner-regression.mjs --quiet","scan:regression:counts":"node ./scripts/scanner-regression.mjs --counts-only","scan:regression:strict":"node ./scripts/scanner-regression.mjs --strict-categories","scan:regression:update":"node ./scripts/scanner-regression.mjs --update-snapshots","scan:regression:summary":"node ./scripts/scanner-regression.mjs --summary-only","scan:regression:artifact":"node ./scripts/scanner-regression.mjs --output ./tmp/scanner-regression.json","scan:regression:fail-fast":"node ./scripts/scanner-regression.mjs --fail-fast","scan:regression:quiet:clean":"node ./scripts/scanner-regression.mjs --quiet --no-summary-footer"},"_npmUser":{"name":"markneville","email":"mark@markneville.dev"},"openclaw":{"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/agentpassportai/agent-passport-plugin.git","type":"git"},"_npmVersion":"10.9.4","description":"Scanner-first trust layer for poisoned skills, plugins, drift review, and runtime policy in OpenClaw","directories":{},"_nodeVersion":"22.22.1","dependencies":{"openclaw":"2026.3.22","@sinclair/typebox":"^0.34.41"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agent-passport_0.1.0_1774373807579_0.46306427237295855","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@agentholdings/agent-passport","version":"0.1.5","type":"module","description":"Scanner-first trust layer for poisoned skills, plugins, drift review, and runtime policy in OpenClaw","license":"SEE LICENSE IN LICENSE","repository":{"type":"git","url":"git+https://github.com/agentpassportai/agent-passport-plugin.git"},"homepage":"https://github.com/agentpassportai/agent-passport-plugin","bugs":{"url":"https://github.com/agentpassportai/agent-passport-plugin/issues"},"keywords":["openclaw","plugin","security","trust","scanner","supply-chain-security","drift-detection","agent-passport"],"openclaw":{"extensions":["./src/index.ts"],"compat":{"pluginApi":">=1.2.0","builtWithOpenClawVersion":"2026.3.24"}},"dependencies":{"@sinclair/typebox":"^0.34.41","openclaw":"2026.3.24"},"scripts":{"pack:dry":"npm pack --dry-run","test":"node --import tsx --test --test-concurrency=1 tests/index.test.ts","typecheck":"tsc --ignoreConfig --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node src/audit.ts src/policy/inbound-dispatch.ts src/provenance.ts src/skill-inspection.ts src/trust-summary.ts src/workspace-audit.ts src/scanner/index.ts src/scanner/report.ts src/scanner/rules/*.ts tests/inbound-dispatch.test.ts tests/skill-inspection.test.ts tests/trust-summary.test.ts tests/workspace-audit.test.ts"},"devDependencies":{"@types/node":"^25.5.0","tsx":"^4.21.0","typescript":"^6.0.2"},"_id":"@agentholdings/agent-passport@0.1.5","gitHead":"0b13fff13485cf139fd7fc7ab63eea720b6b01ae","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-8nfAT66X5nl/MCLcuthxTw5i3TmggqN/eDRxXML3hJFScZNl+1lTtpm8l2ZypwAXTYZ8grxZswdWSTsyfhuOUg==","shasum":"374505c66e1e4806ae13a643a7973f8283c7f234","tarball":"https://registry.npmjs.org/@agentholdings/agent-passport/-/agent-passport-0.1.5.tgz","fileCount":39,"unpackedSize":296265,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDwG+uOtjBVVzFMDSXsNjpcJLdTUQsKc3LReeaKLTcbOAIhAP6Jyv5x+nJXcj6hwwV+Al1XFOon/5lVJE1BaL1HDSu2"}]},"_npmUser":{"name":"markneville","email":"mark@markneville.dev"},"directories":{},"maintainers":[{"name":"markneville","email":"mark@markneville.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-passport_0.1.5_1774642358099_0.02762467935850732"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-24T17:36:47.446Z","modified":"2026-03-27T20:12:38.399Z","0.1.0":"2026-03-24T17:36:47.738Z","0.1.5":"2026-03-27T20:12:38.271Z"},"bugs":{"url":"https://github.com/agentpassportai/agent-passport-plugin/issues"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/agentpassportai/agent-passport-plugin","keywords":["openclaw","plugin","security","trust","scanner","supply-chain-security","drift-detection","agent-passport"],"repository":{"type":"git","url":"git+https://github.com/agentpassportai/agent-passport-plugin.git"},"description":"Scanner-first trust layer for poisoned skills, plugins, drift review, and runtime policy in OpenClaw","maintainers":[{"name":"markneville","email":"mark@markneville.dev"}],"readme":"# Agent Passport\n\nNPM package: `@agentholdings/agent-passport`  \nClawHub package: `agent-passport-plugin`  \nPlugin id: `agent-passport`\n\nAgent Passport is a trust layer for OpenClaw packages and actions.\n\n**Scan before trust. Authorize before install, enable, or update where hooks exist. Re-review when artifacts drift.**\n\nIt is built to catch poisoned skills, plugins, and package updates before they quietly become trusted. Trust decisions are tied to the contents you reviewed, not just a name or path.\n\nThe three names are intentional:\n- install from npm with `@agentholdings/agent-passport`\n- find it on ClawHub as `agent-passport-plugin`\n- enable or inspect it inside OpenClaw as `agent-passport`\n\nClawHub package names must match `package.json` and share a namespace with skill slugs. `agent-passport` was already taken there, so the ClawHub listing uses `agent-passport-plugin` while npm and the runtime plugin id stay cleaner for normal OpenClaw use.\n\nSecurity scope and local state are documented in [SECURITY-SCOPE.md](./SECURITY-SCOPE.md).\n\n## Why this exists\n\nClawHavoc-style poisoned skills, plugins, and package flows are the real problem.\n\nA dangerous artifact does not need to look like malware in the old sense. It can hide in:\n- install instructions\n- shell snippets in docs\n- bootstrap scripts\n- manifest defaults\n- staged payloads\n- suspicious egress or credential collection behavior\n\nAgent Passport exists to make that reviewable before trust, then keep trust from quietly going stale after the artifact changes.\n\n## What Agent Passport is\n\nAgent Passport is built around a few core ideas:\n- fingerprint the artifact you reviewed\n- bind review decisions to content, not just a path string\n- do not let old trust silently survive meaningful drift\n- separate scanner truth from runtime policy truth\n- be honest about what Passport can and cannot intercept\n\n## Hard product rules\n\nThese are non-negotiable.\n\n- Do not block Telegram or the primary control lane by default.\n- Do not pretend Passport intercepts every dangerous action in OpenClaw.\n- Do not claim package trust based only on a file path.\n- Do not let prior trust silently survive artifact drift.\n- Do use real hook surfaces when enforcing policy.\n\n## What is available today\n\nThese parts are already implemented.\n\n### Scanner and review\n- local artifact scanner with explainable findings\n- artifact fingerprinting\n- review decisions bound to exact fingerprint\n- verdicts: `safe`, `suspicious`, `dangerous`\n- recommendations such as `allow`, `review-before-trust`, and `block-package`\n\n### Plugin governance\n- local plugin install wrapper over real `openclaw plugins install`\n- plugin enable wrapper over real `openclaw plugins enable`\n- plugin update wrapper over real `openclaw plugins update`\n- install ledger for recorded plugin source, fingerprint, recommendation, and review state\n- drift-aware re-review for plugin enable and update\n- plugin-level operator actions by plugin id\n\n### Skill governance\n- tracked workspace skill visibility based on real ClawHub metadata\n- local-first quarantine inspection helper for staging skill artifacts before trust\n- slug-level review actions for installed skills\n- skill drift detection against the last Passport-reviewed fingerprint\n- single-skill and workspace-wide skill update wrappers over real OpenClaw skill update flows\n- skills re-review queue when installed contents drift\n\n### Operator workflow\n- single-item truth views for plugins and skills\n- combined `/passport workspace-state` view across plugins and skills\n- ranked `/passport workspace-audit` incident-response view with remediation targets\n- trust-tier and provenance summaries in the normal plugin, skill, and workspace state views\n- Telegram action buttons from the workspace view\n- proactive drift sweep and drift alerts\n- cron/shell-friendly alerts CLI\n\n### Local state\nPassport stores its review and operating state locally in the workspace unless configured otherwise:\n- scan review decisions are fingerprint-bound\n- plugin install records capture source path, manifest path, fingerprint, and review state\n- skill review records capture slug, skill directory, fingerprint, and review state\n- consent grants and requests are local and temporary\n- drift queue state is local and used only to surface re-review work\n- audit logs are local JSONL records and should be treated as sensitive operator data\n\n### Runtime containment\nPassport also has runtime consent and audit controls on supported surfaces:\n- `before_dispatch` for canonical inbound audit and risk classification on OpenClaw `2026.3.24+`\n- `message_sending`\n- `message.send`\n- `sessions_send`\n\n`before_dispatch` is audit-first in Passport today. It records canonical inbound routing metadata and flags higher-risk group or prompt-injection-shaped traffic without claiming inbound enforcement.\n\nThese hooks now register with explicit early priority so Passport's consent gate and inbound audit run deterministically before lower-priority plugin handlers on the same surfaces.\n\n## What Agent Passport does not claim\n\nAgent Passport does **not** claim:\n- universal pre-install interception\n- universal pre-exec interception\n- universal pre-network interception\n- universal pre-file-write or pre-delete interception\n- complete containment of every malicious plugin or skill path\n- remote preinstall scanning of ClawHub content before OpenClaw fetches it\n\nCurrent scope:\n\n**Agent Passport helps detect and constrain poisoned skills and plugins on the paths it can actually see and control.**\n\n## Scanner model\n\nThe scanner is local, rule-based, and explainable. Operators should be able to see why something was flagged.\n\n### Current high-signal categories\n- `remote-script-execution`\n- `bootstrap-installer`\n- `credential-harvest`\n- `suspicious-egress`\n- `prompt-directed-shell-execution`\n- `manifest-lifecycle`\n- `staged-payload`\n- `persistence-autorun`\n\n### Artifact-aware interpretation\nThe scanner distinguishes artifact shape and explains findings differently for:\n- `skill`\n- `plugin`\n- `package`\n- `hybrid`\n- `unknown`\n\nThat lets Passport explain why a signal matters for this kind of artifact instead of just saying something looks bad.\n\n### Example outcomes\n- clean plugin → `allow`\n- docs-risk plugin → `review-before-trust`\n- suspicious skill → `review-before-trust`\n- runtime-risk plugin → `block-package`\n\n## Trust model\n\nTrust follows content.\n\nThat means:\n- scan an artifact\n- compute fingerprint\n- record `review`, `trust`, or `block`\n- reuse that decision only for the same fingerprint\n- if contents drift later, old trust no longer counts for the new fingerprint\n\nThis is why drift matters so much in Passport. “We reviewed it once” is not good enough if the thing changed.\n\n## Plugin workflow\n\nPlugins are the most complete lifecycle right now.\n\n### Real plugin commands\n- `/passport install-plugin <local-path> [--link] [--pin] [--enable] [--dry-run]`\n- `/passport enable-plugin <local-path> [--dry-run]`\n- `/passport update-plugin <pluginId> [--dry-run]`\n- `/passport installs [pluginId]`\n- `/passport plugin-state <pluginId>`\n- `/passport trust-plugin <pluginId>`\n- `/passport review-plugin <pluginId>`\n- `/passport block-plugin <pluginId>`\n- `/passport drift-plugin <pluginId>`\n- `/passport rereview-queue`\n\n### Plugin state model\nPlugin views combine:\n- latest recorded install\n- current fingerprint\n- current review state\n- recorded vs current recommendation\n- drift status\n- recommended next actions\n\n### Drift policy\nIf the current source fingerprint no longer matches the fingerprint captured at install time:\n- prior trust is no longer enough for enable/update\n- Passport moves the plugin into re-review flow\n- new trust must be recorded for the new fingerprint\n\n## Skill workflow\n\nSkills are handled as skills, not treated like plugin clones.\n\nOpenClaw skills are ClawHub slug-based, not local-path plugin installs. Passport focuses on installed-state truth, review state, and drift-aware re-review.\n\n### Real skill commands\n- `/passport inspect-skill <path> [--label <label>] [--max-files <n>] [--max-bytes <n>]`\n- `/passport skills`\n- `/passport skill-state <slug>`\n- `/passport trust-skill <slug>`\n- `/passport review-skill <slug>`\n- `/passport block-skill <slug>`\n- `/passport drift-skill <slug>`\n- `/passport skills-rereview`\n- `/passport update-skill <slug> [--dry-run]`\n- `/passport update-skills [--dry-run]`\n\n### Skill truth model\nFor tracked skills, Passport can show:\n- installed version\n- workspace path\n- current fingerprint\n- current review state\n- scanner verdict and recommendation\n- last Passport-reviewed fingerprint\n- whether the installed skill drifted and needs re-review\n\n### Honest limitation\nPassport does **not** yet claim remote preinstall scanning of ClawHub packages before fetch. The current promise is post-install truth, review, and drift governance for installed skills.\n\n## Workspace operator view\n\n`/passport workspace-state` is the top-level operator view.\n\n`/passport workspace-audit` is the incident-response view. It re-ranks tracked plugins and skills by risk, highlights remediation targets, and gives a concrete next-step list after a ClawHavoc-style event.\n\nIt rolls up tracked plugins and tracked skills into one summary, then shows the items that currently need attention.\n\nOn Telegram it also supports lightweight interaction:\n- refresh workspace\n- inspect top plugin or skill detail\n- review, trust, or block the top plugin or skill\n- return to the workspace view after inspection\n\nThat gives operators one place to inspect and act instead of bouncing between unrelated commands.\n\n## Example workflows\n\n### 1. Clean plugin\nInstall a local plugin that scans cleanly.\n\n```bash\n/passport scan /path/to/clean-plugin\n/passport install-plugin /path/to/clean-plugin --dry-run\n```\n\nExpected shape:\n- verdict: `safe`\n- recommendation: `allow`\n- install wrapper shows the real `openclaw plugins install` command it would run\n- if you trust and install it for real, Passport records the install fingerprint and can later detect drift\n\nWhy this matters:\n- Passport stays out of the way when the artifact is boring and clean\n- the install is still fingerprinted and recorded so trust has memory later\n\n### 2. Suspicious skill\nInspect a skill that looks sketchy and review it before trusting it.\n\n```bash\n/passport scan /path/to/suspicious-skill\n/passport review /path/to/suspicious-skill\n```\n\nExpected shape:\n- verdict: usually `suspicious`\n- recommendation: `review-before-trust`\n- findings point at risky shell guidance, bootstrap steps, or other operator-trust issues\n- `review` records that a human looked at this exact fingerprint\n- `trust` is a stronger statement than `review` and should be used deliberately\n\nWhy this matters:\n- many bad artifacts are dangerous because they trick the operator, not because they exploit a runtime hook\n- Passport treats docs and setup instructions as part of the trust surface\n\n### 3. Drift and re-review\nShow that prior trust does not silently survive an artifact change.\n\nTypical flow:\n\n```bash\n/passport plugin-state <pluginId>\n/passport drift-plugin <pluginId>\n/passport workspace-state\n```\n\nExpected shape after the source changes:\n- plugin moves to `rereview-required`\n- old trust is no longer enough for enable or update\n- drift output shows recorded fingerprint vs current fingerprint\n- workspace view surfaces the changed item and lets the operator inspect or act\n\nIf the operator decides the new fingerprint is acceptable:\n\n```bash\n/passport review-plugin <pluginId>\n/passport trust-plugin <pluginId>\n```\n\nWhy this matters:\n- Passport trust follows content, not nostalgia\n- this is the difference between a real governance loop and a one-time checkbox\n\n## Drift and alerts\n\nPassport includes a proactive drift layer.\n\n### Commands\n- `/passport drift-sweep`\n- `/passport drift-alerts`\n\n### CLI\n```bash\nopenclaw passport-audit\nopenclaw passport-inspect-skill /path/to/skill\n```\n\nUse the in-product Passport commands above as the primary operator surface. The explicit OpenClaw CLI entrypoints are there for automation and shell-driven workflows.\n\n## Install and local development\n\n### Local plugin path\nInstall from a local checkout with the standard OpenClaw plugin command:\n\n```bash\nopenclaw plugins install /path/to/agent-passport-plugin --link\nopenclaw plugins enable agent-passport\n```\n\n### Local verification\nFrom the repo root, use `npm pack --dry-run` to confirm the published surface is clean before release.\n\n## Commands\n\n### Core\n- `/passport status`\n- `/passport requests [pending|approved|denied|all]`\n- `/passport scan <path>`\n- `/passport preflight <path>`\n- `/passport authorize <install|enable|update> <path>`\n- `/passport run <install|enable|update> <path> -- <command>`\n- `/passport trust <path>`\n- `/passport review <path>`\n- `/passport block <path>`\n- `/passport approve <requestId>`\n- `/passport deny <requestId>`\n\n### Plugins\n- `/passport install-plugin <local-path> [--link] [--pin] [--enable] [--dry-run]`\n- `/passport enable-plugin <local-path> [--dry-run]`\n- `/passport update-plugin <pluginId> [--dry-run]`\n- `/passport installs [pluginId]`\n- `/passport plugin-state <pluginId>`\n- `/passport trust-plugin <pluginId>`\n- `/passport review-plugin <pluginId>`\n- `/passport block-plugin <pluginId>`\n- `/passport drift-plugin <pluginId>`\n- `/passport rereview-queue`\n\n### Skills\n- `/passport inspect-skill <path> [--label <label>] [--max-files <n>] [--max-bytes <n>]`\n- `/passport skills`\n- `/passport skill-state <slug>`\n- `/passport trust-skill <slug>`\n- `/passport review-skill <slug>`\n- `/passport block-skill <slug>`\n- `/passport drift-skill <slug>`\n- `/passport skills-rereview`\n- `/passport update-skill <slug> [--dry-run]`\n- `/passport update-skills [--dry-run]`\n\n### Workspace\n- `/passport workspace-state`\n- `/passport workspace-audit [--plugins-only|--skills-only] [--max <n>]`\n- `/passport drift-sweep`\n- `/passport drift-alerts`\n\n## Public Surface\n\nThe default public-facing story should stay read-only and review-oriented:\n- scan, status, state, drift, and explain flows are the safest public entry points\n- install, enable, update, trust, review, block, and consent-grant flows are explicit operator actions\n- mutating flows are higher-risk and should be used deliberately, not treated as ambient assistant behavior\n\nIf you are documenting or publishing Passport on ClawHub, this distinction matters more than the command count.\n\n## Tools\n- `agent_passport_status`\n- `agent_passport_scan_path`\n- `agent_passport_inspect_skill_artifact`\n- `agent_passport_explain`\n- `agent_passport_grant_consent`\n- `agent_passport_list_consents`\n- `agent_passport_revoke_consent`\n- `agent_passport_request_consent`\n- `agent_passport_list_requests`\n- `agent_passport_review_request`\n- `agent_passport_review_scan`\n- `agent_passport_preflight_artifact`\n- `agent_passport_authorize_artifact_action`\n- `agent_passport_run_artifact_action`\n- `agent_passport_install_openclaw_plugin`\n- `agent_passport_enable_openclaw_plugin`\n- `agent_passport_update_openclaw_plugin`\n- `agent_passport_list_plugin_installs`\n- `agent_passport_plugin_state`\n- `agent_passport_review_plugin`\n- `agent_passport_check_plugin_drift`\n- `agent_passport_list_rereview_queue`\n- `agent_passport_workspace_state`\n- `agent_passport_workspace_audit`\n- `agent_passport_skill_state`\n- `agent_passport_list_skills_state`\n- `agent_passport_review_skill`\n- `agent_passport_check_skill_drift`\n- `agent_passport_update_openclaw_skill`\n- `agent_passport_update_all_openclaw_skills`\n- `agent_passport_list_skills_rereview_queue`\n- `agent_passport_drift_sweep`\n- `agent_passport_drift_alerts`\n- `agent_passport_list_scan_reviews`\n\n## Recommended posture\n\n- default mode: `warn` or `audit`\n- keep the control lane trusted or audit-only\n- put scanner output and explanation first\n- use runtime containment as a supported backstop, not the headline\n\n## Bottom line\n\nAgent Passport is a scanner-first trust layer for poisoned skills and plugins, with review state, drift-aware re-review, install and update authorization where hooks exist, and runtime containment on the paths Passport can actually control.\n","readmeFilename":"README.md"}