Skip to content

Commit 8d5fa2c

Browse files
author
iTechSmart Dev
committed
feat: ProofLink SDK v0.1
Cryptographic receipt SDK for autonomous AI actions. Every AI action gets a receipt — verifiable, hash-chained, Bitcoin-anchored via OpenTimestamps. Languages: Python 3.8+ | Node.js 18+ Receipts: sealed via append.py on host Verify: https://verify.itechsmart.dev Real receipts from smoke tests: - Python: https://verify.itechsmart.dev/28ba7d8d31bfa3d6 - Node: https://verify.itechsmart.dev/15d0585a52c79231 Autonomous AI needs receipts.
0 parents  commit 8d5fa2c

13 files changed

Lines changed: 927 additions & 0 deletions

File tree

‎.github/workflows/test.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Test ProofLink SDK
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test-node:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: actions/setup-node@v4
15+
with:
16+
node-version: '18'
17+
- name: Run Node smoke tests
18+
run: node node/test.js
19+
20+
test-python:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v4
24+
- uses: actions/setup-python@v5
25+
with:
26+
python-version: '3.10'
27+
- name: Install Python deps
28+
run: pip install requests
29+
- name: Run Python smoke tests
30+
run: python3 python/tests/test_client.py

‎.gitignore‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.egg-info/
6+
.eggs/
7+
build/
8+
dist/
9+
.pytest_cache/
10+
.tox/
11+
.venv/
12+
venv/
13+
14+
# Node
15+
node_modules/
16+
npm-debug.log*
17+
yarn-debug.log*
18+
yarn-error.log*
19+
.npm/
20+
21+
# Editors
22+
.vscode/
23+
.idea/
24+
*.swp
25+
.DS_Store
26+
27+
# Local test artifacts
28+
.firecrawl/
29+
*.local.json

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 iTechSmart Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# ProofLink SDK
2+
3+
> Cryptographic receipts for autonomous AI actions.
4+
5+
Every autonomous action gets a receipt. **SHA-256 hash-chained, Bitcoin-anchored, publicly verifiable** at [verify.itechsmart.dev](https://verify.itechsmart.dev).
6+
7+
[![Test](https://github.com/Iteksmart/prooflink-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/Iteksmart/prooflink-sdk/actions/workflows/test.yml)
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9+
10+
## What it does
11+
12+
ProofLink turns "the agent did X" into a receipt you can prove later. Each receipt is:
13+
14+
- **Hash-chained** — every receipt links to the previous one's SHA-256
15+
- **Bitcoin-anchored** — submitted to 4 OpenTimestamps calendars, settled in the next Bitcoin block
16+
- **Publicly verifiable** — anyone can replay the chain at [verify.itechsmart.dev](https://verify.itechsmart.dev)
17+
- **Tamper-evident** — modifying a past receipt breaks every receipt that follows
18+
19+
The SDK is a **thin wrapper**. The cryptography lives in `append.py` (the canonical seal logic) and the verify API. The SDK adds idiomatic language bindings — it does not reimplement.
20+
21+
## Two modes
22+
23+
| Mode | Available methods | Where it runs |
24+
|---|---|---|
25+
| **Server** (append.py present) | `seal`, `verify`, `chain_status`, `submit_to_ledger` | iTechSmart UAIO host or any host with `/opt/itechsmart/audit_ledger/append.py` |
26+
| **Client** (verify API only) | `verify`, `chain_status` | Anywhere with HTTPS access to `verify.itechsmart.dev` |
27+
28+
`seal()` raises a clear error in client mode — read-only methods still work.
29+
30+
## Install
31+
32+
### Python
33+
34+
```bash
35+
pip install prooflink
36+
```
37+
38+
### Node
39+
40+
```bash
41+
npm install @itechsmart/prooflink
42+
```
43+
44+
## Quick start
45+
46+
### Python
47+
48+
```python
49+
from prooflink import ProofLinkClient
50+
51+
client = ProofLinkClient()
52+
53+
# Seal a receipt (server mode only)
54+
receipt = client.seal({
55+
'category': 'container_restart',
56+
'actor': 'system:supervisor',
57+
'subject': 'suite-nginx',
58+
'action': 'restarted after OOM kill',
59+
'outcome': 'service healthy 12s after restart',
60+
'details': {'pid': 12345, 'oom_score': 800},
61+
})
62+
print(receipt['hash']) # 64-char SHA-256
63+
print(f"https://verify.itechsmart.dev/{receipt['hash']}")
64+
65+
# Verify any receipt by hash (any mode)
66+
entry = client.verify(receipt['hash'])
67+
68+
# Chain status (any mode)
69+
status = client.chain_status()
70+
# {'chain_intact': True, 'total': 15741, 'breaks': 0}
71+
```
72+
73+
### Node
74+
75+
```javascript
76+
const { ProofLinkClient } = require('@itechsmart/prooflink')
77+
// or: import { ProofLinkClient } from '@itechsmart/prooflink'
78+
79+
const client = new ProofLinkClient()
80+
81+
const receipt = await client.seal({
82+
category: 'container_restart',
83+
actor: 'system:supervisor',
84+
subject: 'suite-nginx',
85+
action: 'restarted after OOM kill',
86+
outcome: 'service healthy 12s after restart',
87+
details: { pid: 12345, oomScore: 800 },
88+
})
89+
console.log(receipt.hash)
90+
console.log(`https://verify.itechsmart.dev/${receipt.hash}`)
91+
92+
const status = await client.chainStatus()
93+
// { chain_intact: true, total: 15741, breaks: 0 }
94+
```
95+
96+
## Receipt schema
97+
98+
Every receipt has the same shape, regardless of language binding:
99+
100+
```json
101+
{
102+
"id": "437f2bbd7fb221ac",
103+
"timestamp": "2026-06-02T22:14:08.231054+00:00",
104+
"category": "container_restart",
105+
"actor": "system:supervisor",
106+
"subject": "suite-nginx",
107+
"action": "restarted after OOM kill",
108+
"outcome": "service healthy 12s after restart",
109+
"details": { "pid": 12345, "oom_score": 800 },
110+
"hash_sha256": "437f2bbd7fb221ac7ce8ff917f84135e7607c5f5b1282354f4c4ac6e0ef8560b",
111+
"prev_hash": "<previous receipt's hash_sha256>",
112+
"tamper_detected": false,
113+
"human_input": false,
114+
"auto_resolved": true
115+
}
116+
```
117+
118+
`seal()` returns the short form `{ok, id, hash}`. Full receipts are returned by `verify()`.
119+
120+
## Configuration
121+
122+
| Param | Default | Purpose |
123+
|---|---|---|
124+
| `append_py` | `/opt/itechsmart/audit_ledger/append.py` | Path to the canonical seal CLI |
125+
| `verify_url` | `https://verify.itechsmart.dev` | Base URL of the verify API |
126+
| `python_bin` | `python3` | Python interpreter for the seal subprocess |
127+
| `timeout` | 30s | Per-seal subprocess timeout |
128+
| `no_ots` | `False` (per-call) | Skip Bitcoin anchoring (~70x faster seal; receipt still hashed and chained) |
129+
130+
## Status of the verify API
131+
132+
| Endpoint | Status |
133+
|---|---|
134+
| `GET /api/chain` | ✅ Live — returns `{chain_intact, total, breaks}` |
135+
| `GET /api/receipts?hash=...` | ⚠ Currently returns HTML — JSON response in progress (sprint item H3) |
136+
| `GET /api/stats` | ⚠ Same as above |
137+
138+
Until H3 lands, `verify(hash)` may return parsed HTML scaffolding rather than the receipt JSON. `chain_status()` is the production-stable read path.
139+
140+
## License
141+
142+
MIT — see [LICENSE](LICENSE).
143+
144+
## Author
145+
146+
iTechSmart Inc. — djuane@itechsmart.dev

‎node/index.d.ts‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
// TypeScript declarations for @itechsmart/prooflink.
2+
3+
export interface SealAction {
4+
category: string
5+
actor: string
6+
subject: string
7+
action: string
8+
outcome?: string
9+
details?: Record<string, unknown> | string
10+
humanInput?: boolean
11+
autoResolved?: boolean
12+
verifyUrl?: string
13+
hash?: string
14+
noOts?: boolean
15+
}
16+
17+
export interface SealResult {
18+
ok: true
19+
id: string // 16-char hex
20+
hash: string // 64-char SHA-256
21+
}
22+
23+
export interface ChainStatus {
24+
chain_intact: boolean
25+
total: number
26+
breaks: number
27+
}
28+
29+
export interface Receipt {
30+
id: string
31+
timestamp: string
32+
category: string
33+
actor: string
34+
subject: string
35+
action: string
36+
outcome: string
37+
details: Record<string, unknown>
38+
hash_sha256: string
39+
prev_hash?: string
40+
verify_url?: string
41+
tamper_detected: boolean
42+
human_input: boolean
43+
auto_resolved: boolean
44+
recomputed?: boolean
45+
recomputed_at?: string
46+
}
47+
48+
export interface ProofLinkClientOptions {
49+
appendPy?: string
50+
verifyUrl?: string
51+
pythonBin?: string
52+
timeout?: number
53+
}
54+
55+
export class ProofLinkError extends Error {}
56+
57+
export class ProofLinkClient {
58+
constructor(options?: ProofLinkClientOptions)
59+
readonly localSealAvailable: boolean
60+
readonly appendPy: string
61+
readonly verifyUrl: string
62+
readonly pythonBin: string
63+
readonly timeout: number
64+
65+
seal(action: SealAction, opts?: { noOts?: boolean }): Promise<SealResult>
66+
submitToLedger(payload: SealAction, opts?: { noOts?: boolean }): Promise<SealResult>
67+
verify(hash: string): Promise<Receipt>
68+
chainStatus(): Promise<ChainStatus>
69+
}

0 commit comments

Comments
 (0)