NotaryOS — Cryptographic Receipts for Agent Actions
Seal your agent's actions with Ed25519 signatures. Issue tamper-evident receipts, verify them publicly, and maintain an auditable chain of every decision.
License
BSL-1.1 (Business Source License). See https://github.com/hellothere012/notaryos/blob/main/LICENSE
Trust Statement
By 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
Data Flow
The 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.
| Tier | Payload Transmitted | Raw Payload Retained | Hash Stored | Signature Stored |
|---|
| Demo (no key) | Yes | No | Yes | Yes |
| Free |
Yes | Metadata only | Yes | Yes |
| Pro | Yes | Configurable | Yes | Yes |
| Enterprise | Yes | Zero retention | Yes | Yes |
The included sanitize.py module strips fields matching known sensitive patterns before transmission. Use it before every seal() call when handling user data.
External Endpoints
| URL | Method | Data Sent | Purpose |
|---|
| INLINECODE3 | POST | action_type, payload JSON | Issue signed receipt |
| INLINECODE4 |
POST | receipt JSON | Verify signature |
|
api.agenttownsquare.com/v1/notary/status | GET | None | Health check |
|
api.agenttownsquare.com/v1/notary/r/{hash} | GET | None | Receipt lookup |
|
api.agenttownsquare.com/v1/notary/public-key | GET | None | Ed25519 public key |
No other endpoints are contacted. No telemetry, analytics, or tracking.
Setup
CODEBLOCK0
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.
CODEBLOCK1
Seal an Action
CODEBLOCK2
What to Seal
Default (always safe)
| Action Type | When to Seal |
|---|
| INLINECODE10 | Created or modified a file |
| INLINECODE11 |
Deleted a file |
|
command.executed | Ran a shell command |
|
config.changed | Modified system configuration |
Extended (sanitize payload first)
| Action Type | When to Seal |
|---|
| INLINECODE14 | Sent an email (strip body, keep subject) |
| INLINECODE15 |
Made an external API call (strip auth headers) |
|
data.accessed | Accessed sensitive data (log access, not content) |
|
message.sent | Sent a message (strip body if private) |
Always run sanitize_payload() on extended actions before sealing.
Payload Guidelines
Include: File paths, counts, timestamps, branch names, public identifiers, action summaries.
Exclude: Authentication credentials, financial numbers, government IDs, message bodies, file contents, health information. The sanitize_payload() helper handles this automatically.
Verify a Receipt
CODEBLOCK3
Lookup by Hash
CODEBLOCK4
Counterfactual Receipts
Record when your agent chose NOT to act:
CODEBLOCK5
Receipt Chaining
CODEBLOCK6
Error Handling
CODEBLOCK7
Dependencies
- -
sanitize.py (included): Zero external dependencies — uses only Python standard library (typing). Pure function, no I/O, no network, no side effects. 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
Key Points
- -
NOTARY_API_KEY is optional — a demo key is auto-injected when not set (10 req/min) - Set
NOTARY_API_KEY for production rates (get a key at https://notaryos.org/sign-up) - Both
sanitize.py and the notaryos SDK use only the Python standard library (zero third-party deps) - Payloads transmitted via HTTPS to INLINECODE27
- Use
sanitize_payload() to strip sensitive fields before sealing - Verification is free and public — no API key needed
- Ed25519 signatures (same scheme as SSH and TLS)
Links
- - Docs: https://notaryos.org/docs
- Privacy: https://notaryos.org/privacy
- Explorer: https://notaryos.org/explore
- API Docs: https://notaryos.org/api-docs
- PyPI: https://pypi.org/project/notaryos/
- npm: https://www.npmjs.com/package/notaryos
- GitHub: https://github.com/hellothere012/notaryos
- License: https://github.com/hellothere012/notaryos/blob/main/LICENSE
NotaryOS — 智能体操作的加密收据
使用Ed25519签名对智能体的操作进行认证。生成防篡改收据，可公开验证，并维护每一步决策的可审计链。
许可证
BSL-1.1（商业源代码许可证）。参见 https://github.com/hellothere012/notaryos/blob/main/LICENSE
信任声明
使用此技能时，操作元数据（操作类型、时间戳以及负载的SHA-256哈希值）将通过HTTPS发送至 api.agenttownsquare.com。原始负载的保留取决于您的层级——请参见下方数据流部分。验证免费且无需账户。完整隐私政策：https://notaryos.org/privacy
数据流
SDK通过HTTPS POST将您的负载发送至NotaryOS API。服务器使用SHA-256对负载进行哈希处理，使用Ed25519对哈希值进行签名，并返回收据。
| 层级 | 负载传输 | 原始负载保留 | 哈希存储 | 签名存储 |
|---|
| 演示（无密钥） | 是 | 否 | 是 | 是 |
| 免费 |
是 | 仅元数据 | 是 | 是 |
| 专业版 | 是 | 可配置 | 是 | 是 |
| 企业版 | 是 | 零保留 | 是 | 是 |
附带的 sanitize.py 模块在传输前会剥离匹配已知敏感模式的字段。处理用户数据时，请在每次 seal() 调用前使用它。
外部端点
| URL | 方法 | 发送数据 | 用途 |
|---|
| api.agenttownsquare.com/v1/notary/issue | POST | action_type, payload JSON | 签发签名收据 |
| api.agenttownsquare.com/v1/notary/verify |
POST | receipt JSON | 验证签名 |
| api.agenttownsquare.com/v1/notary/status | GET | 无 | 健康检查 |
| api.agenttownsquare.com/v1/notary/r/{hash} | GET | 无 | 收据查询 |
| api.agenttownsquare.com/v1/notary/public-key | GET | 无 | Ed25519公钥 |
不会联系其他端点。无遥测、分析或跟踪。
设置
bash
pip install notaryos
无需API密钥。 当未设置 NOTARYAPIKEY 时，SDK会自动注入一个免费演示密钥（10次请求/分钟）。如需生产环境速率，请在 https://notaryos.org/sign-up 获取密钥，并在您的环境或OpenClaw配置中设置 NOTARYAPIKEY。
python
from notaryos import NotaryClient
notary = NotaryClient() # 立即可用——如果未设置NOTARYAPIKEY，则使用演示密钥
密封操作
python
from notaryos import NotaryClient
from sanitize import sanitize_payload
notary = NotaryClient()
receipt = notary.seal(
file.created,
sanitize_payload({
path: /src/main.py,
lines_added: 42,
branch: feature/auth
})
)
print(receipt.receipt_hash)
print(receipt.signature)
何时密封
默认（始终安全）
| 操作类型 | 何时密封 |
|---|
| file.created | 创建或修改了文件 |
| file.deleted |
删除了文件 |
| command.executed | 运行了shell命令 |
| config.changed | 修改了系统配置 |
扩展（先净化负载）
| 操作类型 | 何时密封 |
|---|
| email.sent | 发送了邮件（剥离正文，保留主题） |
| api.called |
进行了外部API调用（剥离认证头） |
| data.accessed | 访问了敏感数据（记录访问，而非内容） |
| message.sent | 发送了消息（如为私密消息则剥离正文） |
在密封扩展操作前，始终运行 sanitize_payload()。
负载指南
包含： 文件路径、计数、时间戳、分支名称、公共标识符、操作摘要。
排除： 认证凭据、财务数字、政府ID、消息正文、文件内容、健康信息。sanitize_payload() 辅助函数会自动处理此问题。
验证收据
python
from notaryos import verify_receipt
isvalid = verifyreceipt(receipt.to_dict()) # True 或 False，无需认证
按哈希查询
python
notary = NotaryClient()
result = notary.lookup(e1d66b0bdf3f8a7e...)
if result[found] and result[verification][valid]:
print(收据真实且未被篡改)
反事实收据
记录您的智能体选择不执行操作的情况：
python
receipt = notary.seal(trade.declined, {
reason: riskthresholdexceeded,
action_considered: trade.execute,
decision: blocked
})
收据链
python
r1 = notary.seal(file.read, {file: report.pdf})
r2 = notary.seal(summary.generated, {
source: report.pdf,
length: 500
}, previousreceipthash=r1.receipt_hash)
错误处理
python
from notaryos import AuthenticationError, RateLimitError, ValidationError
try:
receipt = notary.seal(action, {key: value})
except RateLimitError:
pass # 演示：10次请求/分钟，升级请访问notaryos.org
except AuthenticationError:
pass # 无效密钥
except ValidationError:
pass # 错误请求
依赖项
- - sanitize.py（已包含）： 零外部依赖——仅使用Python标准库（typing）。纯函数，无I/O，无网络，无副作用。
- notaryos SDK（通过pip安装）： 也仅使用Python标准库——零第三方依赖。来源：https://pypi.org/project/notaryos/ | GitHub：https://github.com/hellothere012/notaryos
要点
- - NOTARYAPIKEY 是可选的——未设置时会自动注入演示密钥（10次请求/分钟）
- 为生产环境速率设置 NOTARYAPIKEY（在 https://notaryos.org/sign-up 获取密钥）
- sanitize.py 和 notaryos SDK均仅使用Python标准库（零第三方依赖）
- 负载通过HTTPS传输至 api.agenttownsquare.com
- 在密封前使用 sanitize_payload() 剥离敏感字段
- 验证免费且公开——无需API密钥
- Ed25519签名（与SSH和TLS相同的方案）
链接
- - 文档：https://notaryos.org/docs
- 隐私：https://notaryos.org/privacy
- 浏览器：https://notaryos.org/explore
- API文档：https://notaryos.org/api-docs
- PyPI：https://pypi.org/project/notaryos/
- npm：https://www.npmjs.com/package/notaryos
- GitHub：https://github.com/hellothere012/notaryos
- 许可证：https://github.com/hellothere012/notaryos/blob/main/LICENSE
