{"skill":{"slug":"notaryos","displayName":"NotaryOS","summary":"Seal AI agent actions with Ed25519 cryptographic receipts. Verify what your agent did and prove what it chose not to do.","description":"---\nname: notaryos\ndescription: Seal AI agent actions with Ed25519 cryptographic receipts. Verify what your agent did and prove what it chose not to do.\nversion: 2.4.0\nmetadata:\n  openclaw:\n    emoji: \"\\U0001F6E1\\uFE0F\"\n    requires:\n      bins:\n        - python3\n    primaryEnv: NOTARY_API_KEY\n    homepage: https://github.com/hellothere012/notaryos\n    files:\n      - \"sanitize.py\"\n    install:\n      - kind: uv\n        package: notaryos\n        bins: []\n---\n\n# NotaryOS — Cryptographic Receipts for Agent Actions\n\nSeal your agent's actions with Ed25519 signatures. Issue tamper-evident receipts, verify them publicly, and maintain an auditable chain of every decision.\n\n## License\n\nBSL-1.1 (Business Source License). See https://github.com/hellothere012/notaryos/blob/main/LICENSE\n\n## Trust Statement\n\nBy using this skill, action metadata (action type, timestamps, and a SHA-256 hash of the payload) is sent to `api.agenttownsquare.com` via HTTPS. Raw payload retention depends on your tier — see the Data Flow section below. Verification is free and requires no account. Full privacy policy: https://notaryos.org/privacy\n\n## Data Flow\n\nThe SDK sends your payload to the NotaryOS API via HTTPS POST. The server hashes the payload with SHA-256, signs the hash with Ed25519, and returns a receipt.\n\n| Tier | Payload Transmitted | Raw Payload Retained | Hash Stored | Signature Stored |\n|------|-------------------|---------------------|-------------|-----------------|\n| Demo (no key) | Yes | No | Yes | Yes |\n| Free | Yes | Metadata only | Yes | Yes |\n| Pro | Yes | Configurable | Yes | Yes |\n| Enterprise | Yes | Zero retention | Yes | Yes |\n\nThe included `sanitize.py` module strips fields matching known sensitive patterns before transmission. Use it before every `seal()` call when handling user data.\n\n## External Endpoints\n\n| URL | Method | Data Sent | Purpose |\n|-----|--------|-----------|---------|\n| `api.agenttownsquare.com/v1/notary/issue` | POST | action_type, payload JSON | Issue signed receipt |\n| `api.agenttownsquare.com/v1/notary/verify` | POST | receipt JSON | Verify signature |\n| `api.agenttownsquare.com/v1/notary/status` | GET | None | Health check |\n| `api.agenttownsquare.com/v1/notary/r/{hash}` | GET | None | Receipt lookup |\n| `api.agenttownsquare.com/v1/notary/public-key` | GET | None | Ed25519 public key |\n\nNo other endpoints are contacted. No telemetry, analytics, or tracking.\n\n## Setup\n\n```bash\npip install notaryos\n```\n\n> **No API key required.** The SDK auto-injects a free demo key (10 req/min) when `NOTARY_API_KEY` is not set. For production rates, get a key at https://notaryos.org/sign-up and set `NOTARY_API_KEY` in your environment or OpenClaw config.\n\n```python\nfrom notaryos import NotaryClient\n\nnotary = NotaryClient()  # works immediately — uses demo key if NOTARY_API_KEY is not set\n```\n\n## Seal an Action\n\n```python\nfrom notaryos import NotaryClient\nfrom sanitize import sanitize_payload\n\nnotary = NotaryClient()\n\nreceipt = notary.seal(\n    \"file.created\",\n    sanitize_payload({\n        \"path\": \"/src/main.py\",\n        \"lines_added\": 42,\n        \"branch\": \"feature/auth\"\n    })\n)\n\nprint(receipt.receipt_hash)\nprint(receipt.signature)\n```\n\n## What to Seal\n\n### Default (always safe)\n\n| Action Type | When to Seal |\n|---|---|\n| `file.created` | Created or modified a file |\n| `file.deleted` | Deleted a file |\n| `command.executed` | Ran a shell command |\n| `config.changed` | Modified system configuration |\n\n### Extended (sanitize payload first)\n\n| Action Type | When to Seal |\n|---|---|\n| `email.sent` | Sent an email (strip body, keep subject) |\n| `api.called` | Made an external API call (strip auth headers) |\n| `data.accessed` | Accessed sensitive data (log access, not content) |\n| `message.sent` | Sent a message (strip body if private) |\n\nAlways run `sanitize_payload()` on extended actions before sealing.\n\n## Payload Guidelines\n\n**Include:** File paths, counts, timestamps, branch names, public identifiers, action summaries.\n\n**Exclude:** Authentication credentials, financial numbers, government IDs, message bodies, file contents, health information. The `sanitize_payload()` helper handles this automatically.\n\n## Verify a Receipt\n\n```python\nfrom notaryos import verify_receipt\n\nis_valid = verify_receipt(receipt.to_dict())  # True or False, no auth needed\n```\n\n## Lookup by Hash\n\n```python\nnotary = NotaryClient()\nresult = notary.lookup(\"e1d66b0bdf3f8a7e...\")\n\nif result[\"found\"] and result[\"verification\"][\"valid\"]:\n    print(\"Receipt is authentic and untampered\")\n```\n\n## Counterfactual Receipts\n\nRecord when your agent chose NOT to act:\n\n```python\nreceipt = notary.seal(\"trade.declined\", {\n    \"reason\": \"risk_threshold_exceeded\",\n    \"action_considered\": \"trade.execute\",\n    \"decision\": \"blocked\"\n})\n```\n\n## Receipt Chaining\n\n```python\nr1 = notary.seal(\"file.read\", {\"file\": \"report.pdf\"})\nr2 = notary.seal(\"summary.generated\", {\n    \"source\": \"report.pdf\",\n    \"length\": 500\n}, previous_receipt_hash=r1.receipt_hash)\n```\n\n## Error Handling\n\n```python\nfrom notaryos import AuthenticationError, RateLimitError, ValidationError\n\ntry:\n    receipt = notary.seal(\"action\", {\"key\": \"value\"})\nexcept RateLimitError:\n    pass  # demo: 10 req/min, upgrade at notaryos.org\nexcept AuthenticationError:\n    pass  # invalid key\nexcept ValidationError:\n    pass  # bad request\n```\n\n## Dependencies\n\n- **`sanitize.py` (included):** Zero external dependencies — uses only Python standard library (`typing`). Pure function, no I/O, no network, no side effects.\n- **`notaryos` SDK (installed via pip):** Also uses only the Python standard library — zero third-party dependencies. Source: https://pypi.org/project/notaryos/ | GitHub: https://github.com/hellothere012/notaryos\n\n## Key Points\n\n- `NOTARY_API_KEY` is **optional** — a demo key is auto-injected when not set (10 req/min)\n- Set `NOTARY_API_KEY` for production rates (get a key at https://notaryos.org/sign-up)\n- Both `sanitize.py` and the `notaryos` SDK use only the Python standard library (zero third-party deps)\n- Payloads transmitted via HTTPS to `api.agenttownsquare.com`\n- Use `sanitize_payload()` to strip sensitive fields before sealing\n- Verification is free and public — no API key needed\n- Ed25519 signatures (same scheme as SSH and TLS)\n\n## Links\n\n- Docs: https://notaryos.org/docs\n- Privacy: https://notaryos.org/privacy\n- Explorer: https://notaryos.org/explore\n- API Docs: https://notaryos.org/api-docs\n- PyPI: https://pypi.org/project/notaryos/\n- npm: https://www.npmjs.com/package/notaryos\n- GitHub: https://github.com/hellothere012/notaryos\n- License: https://github.com/hellothere012/notaryos/blob/main/LICENSE\n","tags":{"agent-safety":"2.4.0","audit":"2.4.0","compliance":"2.4.0","cryptographic":"2.4.0","ed25519":"2.4.0","latest":"2.4.0","receipts":"2.4.0","security":"2.4.0"},"stats":{"comments":0,"downloads":680,"installsAllTime":0,"installsCurrent":0,"stars":1,"versions":5},"createdAt":1773573101443,"updatedAt":1779000168999},"latestVersion":{"version":"2.4.0","createdAt":1774087062599,"changelog":"Remove requires.env gate (key is optional), add Dependencies section, tighten demo key language, resolve 3 scanner dimension flags","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"hellothere012","userId":"s17fsxzh1hn7b05q41ag6maz4x884fdw","displayName":"hellothere012","image":"https://avatars.githubusercontent.com/u/213331555?v=4"},"moderation":null}