shakun-kernel 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- shakun_kernel-0.1.0/LICENSE +19 -0
- shakun_kernel-0.1.0/PKG-INFO +285 -0
- shakun_kernel-0.1.0/README.md +267 -0
- shakun_kernel-0.1.0/pyproject.toml +31 -0
- shakun_kernel-0.1.0/setup.cfg +4 -0
- shakun_kernel-0.1.0/shakun_kernel/__init__.py +26 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/__init__.py +3 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/__main__.py +42 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/caller_resolver.py +67 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/delegation_wire.py +61 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/dispatcher.py +213 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/nonce_store.py +133 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/server.py +136 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/signature_resolver.py +173 -0
- shakun_kernel-0.1.0/shakun_kernel/daemon/signed_invocation.py +66 -0
- shakun_kernel-0.1.0/shakun_kernel/factory.py +236 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/__init__.py +0 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/attestation.py +275 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/authorization.py +156 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/caller.py +42 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/clock.py +75 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/delegation.py +215 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/event_chain.py +47 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/identity.py +17 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/identity_keys.py +140 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/kernel.py +2570 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/revocation_store.py +96 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/rotation.py +132 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/schemas.py +263 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/validation.py +14 -0
- shakun_kernel-0.1.0/shakun_kernel/kernel/verification.py +89 -0
- shakun_kernel-0.1.0/shakun_kernel/storage/__init__.py +0 -0
- shakun_kernel-0.1.0/shakun_kernel/storage/sqlite_store.py +311 -0
- shakun_kernel-0.1.0/shakun_kernel/transport/__init__.py +0 -0
- shakun_kernel-0.1.0/shakun_kernel/transport/http.py +163 -0
- shakun_kernel-0.1.0/shakun_kernel.egg-info/PKG-INFO +285 -0
- shakun_kernel-0.1.0/shakun_kernel.egg-info/SOURCES.txt +56 -0
- shakun_kernel-0.1.0/shakun_kernel.egg-info/dependency_links.txt +1 -0
- shakun_kernel-0.1.0/shakun_kernel.egg-info/requires.txt +7 -0
- shakun_kernel-0.1.0/shakun_kernel.egg-info/top_level.txt +1 -0
- shakun_kernel-0.1.0/tests/test_attestation.py +897 -0
- shakun_kernel-0.1.0/tests/test_bootstrap.py +165 -0
- shakun_kernel-0.1.0/tests/test_caller.py +31 -0
- shakun_kernel-0.1.0/tests/test_caller_resolver.py +56 -0
- shakun_kernel-0.1.0/tests/test_concurrency.py +69 -0
- shakun_kernel-0.1.0/tests/test_daemon_startup.py +98 -0
- shakun_kernel-0.1.0/tests/test_delegation.py +546 -0
- shakun_kernel-0.1.0/tests/test_delegation_over_http.py +269 -0
- shakun_kernel-0.1.0/tests/test_delegation_wire.py +85 -0
- shakun_kernel-0.1.0/tests/test_dispatcher.py +92 -0
- shakun_kernel-0.1.0/tests/test_event_chain.py +88 -0
- shakun_kernel-0.1.0/tests/test_factory.py +357 -0
- shakun_kernel-0.1.0/tests/test_http_transport.py +184 -0
- shakun_kernel-0.1.0/tests/test_kernel.py +1723 -0
- shakun_kernel-0.1.0/tests/test_signature_resolver.py +150 -0
- shakun_kernel-0.1.0/tests/test_signed_invocation.py +121 -0
- shakun_kernel-0.1.0/tests/test_sqlite_nonce_store.py +115 -0
- shakun_kernel-0.1.0/tests/test_sqlite_revocation_store.py +109 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
Copyright 2026 Tripti
|
|
8
|
+
|
|
9
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
10
|
+
you may not use this file except in compliance with the License.
|
|
11
|
+
You may obtain a copy of the License at
|
|
12
|
+
|
|
13
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
14
|
+
|
|
15
|
+
Unless required by applicable law or agreed to in writing, software
|
|
16
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
17
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
18
|
+
See the License for the specific language governing permissions and
|
|
19
|
+
limitations under the License.
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: shakun-kernel
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Trust infrastructure for intelligent systems
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/shakun-labs/shakun-kernel
|
|
7
|
+
Project-URL: Repository, https://github.com/shakun-labs/shakun-kernel
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Dist: cryptography
|
|
12
|
+
Requires-Dist: fastapi
|
|
13
|
+
Requires-Dist: uvicorn
|
|
14
|
+
Provides-Extra: dev
|
|
15
|
+
Requires-Dist: pytest; extra == "dev"
|
|
16
|
+
Requires-Dist: httpx; extra == "dev"
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# Shakun
|
|
20
|
+
|
|
21
|
+
Trust infrastructure for intelligent systems.
|
|
22
|
+
|
|
23
|
+
The current implementation provides a kernel for cryptographic identity,
|
|
24
|
+
scoped delegation, authorization, revocation, and tamper-evident event
|
|
25
|
+
history.
|
|
26
|
+
|
|
27
|
+
Shakun provides kernel-level primitives for cryptographic identity, scoped delegation, authorization, revocation, and tamper-evident event history for AI agents.
|
|
28
|
+
|
|
29
|
+
Agent runtimes remain responsible for reasoning and execution. Shakun provides the trust boundary around those operations: it authenticates the calling identity, evaluates applicable authority against governed state, enforces revocation and temporal constraints, and records governed state transitions as events.
|
|
30
|
+
|
|
31
|
+
The implementation is independent of the agent runtime. An agent may be implemented using LangGraph, another framework, or a custom execution loop, while the Shakun kernel remains responsible for identity and authority semantics.
|
|
32
|
+
|
|
33
|
+
## Design model
|
|
34
|
+
|
|
35
|
+
Shakun treats trust state as governed kernel state rather than as an application-level concern.
|
|
36
|
+
|
|
37
|
+
A governed operation has an authenticated principal and an applicable authority context. The kernel evaluates that context against its current identity, scope, delegation, revocation, temporal, and mission state. If the transition is permitted, the resulting event is appended to the kernel event history.
|
|
38
|
+
|
|
39
|
+
The resulting model is:
|
|
40
|
+
|
|
41
|
+
identity → authority → authorization → state transition → evidence
|
|
42
|
+
|
|
43
|
+
Identity establishes who is acting. Authority establishes what may be exercised. Authorization evaluates whether that authority is valid for the requested operation and current state. The state transition produces kernel-controlled evidence.
|
|
44
|
+
|
|
45
|
+
The kernel does not govern an agent's internal reasoning or attempt to determine whether an agent's behavior is predictable. It governs the boundary at which an agent's actions become consequential to kernel-managed state.
|
|
46
|
+
|
|
47
|
+
## Terminology
|
|
48
|
+
|
|
49
|
+
| Term | Meaning |
|
|
50
|
+
|---|---|
|
|
51
|
+
| Identity | A kernel-registered principal associated with a public-key history. |
|
|
52
|
+
| Caller | The identity authenticated for a particular invocation. |
|
|
53
|
+
| Scope | A kernel-governed authority boundary. |
|
|
54
|
+
| Delegation | A signed grant allowing one identity to exercise authority associated with another identity subject to specified constraints. |
|
|
55
|
+
| Authorization | The kernel decision determining whether an authenticated caller may perform an operation under the applicable authority. |
|
|
56
|
+
| Revocation | Persistent state invalidating previously granted authority. |
|
|
57
|
+
| Mission | A governed unit of execution to which authority and evidence may be bound. |
|
|
58
|
+
| Event | A kernel-produced record of a governed state transition. |
|
|
59
|
+
| SignedInvocation | The authenticated request envelope used by the HTTP transport binding. |
|
|
60
|
+
|
|
61
|
+
## Kernel model
|
|
62
|
+
|
|
63
|
+
### Identity
|
|
64
|
+
|
|
65
|
+
Each agent principal is represented by a kernel-registered identity associated with an Ed25519 public key. Key history is retained so that signatures can be verified against the key that was valid at the relevant time.
|
|
66
|
+
|
|
67
|
+
### Authority
|
|
68
|
+
|
|
69
|
+
Authority is represented through scopes and signed delegation records. A delegation identifies the delegator, delegate, scope, validity interval, and optional mission binding.
|
|
70
|
+
|
|
71
|
+
A delegated caller does not acquire unrestricted authority. The kernel evaluates the delegation against the requested operation, scope, mission, expiry, and current revocation state.
|
|
72
|
+
|
|
73
|
+
### Revocation
|
|
74
|
+
|
|
75
|
+
Revocation is persistent kernel state. Authorization checks current revocation state rather than treating delegation validity as a property of the delegation object alone.
|
|
76
|
+
|
|
77
|
+
The current implementation provides a durable SQLite-backed revocation store.
|
|
78
|
+
|
|
79
|
+
### Evidence
|
|
80
|
+
|
|
81
|
+
Governed state transitions produce kernel events. Events are append-only and hash-chained. Each event commits to the hash of its predecessor, beginning from a fixed genesis value.
|
|
82
|
+
|
|
83
|
+
The kernel reconstructs and verifies the chain when rebuilding state. A broken chain causes reconstruction to fail rather than silently accepting modified history.
|
|
84
|
+
|
|
85
|
+
### Concurrency
|
|
86
|
+
|
|
87
|
+
State transitions are serialized by a kernel-wide reentrant lock. This provides a single linear transition order and prevents concurrent event appends from producing divergent chain predecessors.
|
|
88
|
+
|
|
89
|
+
### Transport
|
|
90
|
+
|
|
91
|
+
The HTTP daemon provides an authenticated transport binding for the kernel. The transport authenticates the caller before parsing the request body and passes transport-independent authentication data to the resolver.
|
|
92
|
+
|
|
93
|
+
Delegation is carried as application data inside the authenticated request body. Its own signature establishes the delegation's authority grant; the request signature establishes that the authenticated caller presented that delegation for the particular operation and body.
|
|
94
|
+
|
|
95
|
+
Shakun does not require the agent runtime itself to implement these trust-state semantics.
|
|
96
|
+
|
|
97
|
+
## Architecture
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
┌─────────────────────────────────────────────┐
|
|
101
|
+
│ Agent framework │
|
|
102
|
+
│ (custom loop, LangGraph, etc.) │
|
|
103
|
+
└──────────────────────┬──────────────────────┘
|
|
104
|
+
│ signed requests
|
|
105
|
+
┌──────────────────────▼──────────────────────┐
|
|
106
|
+
│ Daemon │
|
|
107
|
+
│ request authentication · delegation │
|
|
108
|
+
│ ·verification · replay protection · HTTP │
|
|
109
|
+
└──────────────────────┬──────────────────────┘
|
|
110
|
+
│
|
|
111
|
+
┌──────────────────────▼──────────────────────┐
|
|
112
|
+
│ Kernel │
|
|
113
|
+
│ identity · scope · delegation · revocation │
|
|
114
|
+
│ missions · tamper-evident event log │
|
|
115
|
+
└──────────────────────┬──────────────────────┘
|
|
116
|
+
│
|
|
117
|
+
┌──────────────────────▼──────────────────────┐
|
|
118
|
+
│ Persistence │
|
|
119
|
+
│ SQLite (WAL) · in-memory │
|
|
120
|
+
└─────────────────────────────────────────────┘
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The kernel is the authority over governed trust state. The daemon is a transport boundary and does not own authorization state. Agent frameworks remain outside the trust-state boundary.
|
|
124
|
+
|
|
125
|
+
The separation is:
|
|
126
|
+
|
|
127
|
+
- agent runtime — reasoning and execution
|
|
128
|
+
- daemon — transport authentication and protocol adaptation
|
|
129
|
+
- kernel — identity, authority, authorization, revocation, state transitions, and evidence
|
|
130
|
+
- persistence — durable representation of kernel state
|
|
131
|
+
|
|
132
|
+
Transport-specific representations are adapted before reaching kernel authorization logic. Kernel authorization therefore does not depend on HTTP-specific request objects.
|
|
133
|
+
|
|
134
|
+
## Request processing
|
|
135
|
+
|
|
136
|
+
A request is processed in the following order:
|
|
137
|
+
|
|
138
|
+
1. The transport reads the request bytes without interpreting the body.
|
|
139
|
+
2. The transport constructs the transport-independent authentication adapter.
|
|
140
|
+
3. The resolver validates the signed invocation metadata.
|
|
141
|
+
4. The resolver validates timestamp constraints and resolves the caller's key using key history.
|
|
142
|
+
5. The resolver verifies the body digest and request signature.
|
|
143
|
+
6. The resolver checks replay state.
|
|
144
|
+
7. Only after authentication succeeds is the request body parsed.
|
|
145
|
+
8. The dispatcher resolves the signed operation.
|
|
146
|
+
9. For delegated operations, the delegation is reconstructed and supplied through an `AuthorizationContext`.
|
|
147
|
+
10. The kernel verifies the delegation, evaluates revocation and authorization state, and performs the governed transition.
|
|
148
|
+
11. The resulting event is appended to the kernel event history.
|
|
149
|
+
|
|
150
|
+
Authentication failure is returned through a uniform transport-level error. Internal exception details are not exposed through the transport.
|
|
151
|
+
|
|
152
|
+
## Delegation
|
|
153
|
+
|
|
154
|
+
Delegation is represented as a signed `DelegationRecord`.
|
|
155
|
+
|
|
156
|
+
The wire representation is a flat JSON object containing the complete delegation record. The representation is explicitly defined rather than derived from Python dataclass layout so that independent implementations can reproduce the same protocol structure.
|
|
157
|
+
|
|
158
|
+
A delegation contains:
|
|
159
|
+
|
|
160
|
+
- protocol version
|
|
161
|
+
- delegation identifier
|
|
162
|
+
- delegator identity
|
|
163
|
+
- delegate identity
|
|
164
|
+
- issuer identity
|
|
165
|
+
- scope
|
|
166
|
+
- optional mission binding
|
|
167
|
+
- issuance time
|
|
168
|
+
- expiry time
|
|
169
|
+
- optional revocation reference
|
|
170
|
+
- delegation signature
|
|
171
|
+
|
|
172
|
+
The delegation signature is verified independently of the request signature.
|
|
173
|
+
|
|
174
|
+
When transmitted over HTTP, the delegation is included in the request body. Consequently, the request body digest and request signature bind the presented delegation to the particular invocation.
|
|
175
|
+
|
|
176
|
+
The two signatures establish separate facts:
|
|
177
|
+
|
|
178
|
+
- the delegation signature establishes that the authority grant was issued by the appropriate authority;
|
|
179
|
+
- the invocation signature establishes that the authenticated caller presented that delegation for the particular request.
|
|
180
|
+
|
|
181
|
+
## Interoperability
|
|
182
|
+
|
|
183
|
+
Shakun defines interoperability at multiple boundaries.
|
|
184
|
+
|
|
185
|
+
At the runtime boundary, the kernel is independent of the agent framework. An agent can use a custom execution loop, LangGraph, or another runtime while using the same kernel authorization model.
|
|
186
|
+
|
|
187
|
+
At the protocol boundary, authenticated invocations and delegation records have explicit wire representations. A client implementation does not need to be written in Python; it needs to implement the protocol semantics and cryptographic operations defined by the Shakun protocol.
|
|
188
|
+
|
|
189
|
+
The current implementation therefore supports interoperability between independent implementations at the protocol level, subject to implementation of the defined protocol semantics.
|
|
190
|
+
|
|
191
|
+
## Running it
|
|
192
|
+
|
|
193
|
+
Install the reference implementation:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
git clone https://github.com/shakun-labs/shakun-kernel.git
|
|
197
|
+
cd shakun
|
|
198
|
+
pip install -r requirements.txt
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Delegation
|
|
202
|
+
Runs an end-to-end delegation flow: identity setup, scoped delegation, governed execution, revocation, and subsequent authorization failure.
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
python3 -m examples.delegation_demo
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Evidence
|
|
209
|
+
Demonstrates kernel-produced evidence and evidence validation.
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
python3 -m examples.governance_execution_demo
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Restart and recovery
|
|
216
|
+
Runs the kernel across process restarts and verifies reconstruction of governed state and event-chain integrity.
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
python3 -m examples.restart_consistency_demo
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Minimal example (in-process)
|
|
223
|
+
|
|
224
|
+
from shakun import create_shakun, CallerContext
|
|
225
|
+
|
|
226
|
+
kernel = create_shakun(storage="sqlite", sqlite_path="./example.db")
|
|
227
|
+
|
|
228
|
+
# A fresh kernel is bootstrapped with a root identity.
|
|
229
|
+
caller = CallerContext(kernel.genesis_identity())
|
|
230
|
+
|
|
231
|
+
# Authorization is evaluated by the kernel for each governed operation.
|
|
232
|
+
kernel.syscall_create_scope("example_scope", caller=caller)
|
|
233
|
+
|
|
234
|
+
mission = kernel.syscall_create_mission(
|
|
235
|
+
"record governed execution state",
|
|
236
|
+
scope_id="example_scope",
|
|
237
|
+
caller=caller,
|
|
238
|
+
)
|
|
239
|
+
kernel.syscall_start_mission(mission["mission_id"], caller=caller)
|
|
240
|
+
|
|
241
|
+
Delegating scoped authority to another identity — the full flow is in
|
|
242
|
+
`examples/delegation_demo.py`, and `docs/GETTING_STARTED.md` walks through it step
|
|
243
|
+
by step.
|
|
244
|
+
|
|
245
|
+
The daemon adds authenticated, signature-verified access to the same syscalls
|
|
246
|
+
over HTTP, including delegated requests. See `docs/GETTING_STARTED.md`.
|
|
247
|
+
|
|
248
|
+
## Kernel invariants
|
|
249
|
+
|
|
250
|
+
The kernel enforces a small set of invariants, specified in full in
|
|
251
|
+
[`docs/KERNEL_SYSCALL_SPEC.md`](docs/KERNEL_SYSCALL_SPEC.md).
|
|
252
|
+
|
|
253
|
+
| Invariant | Definition |
|
|
254
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
255
|
+
| Identity | Every governed action is attributed to a kernel-registered cryptographic identity. |
|
|
256
|
+
| Authority | Authorization is evaluated against the caller's applicable scope and delegation state. |
|
|
257
|
+
| Delegation | Delegations are signed protocol objects and are independently verified. |
|
|
258
|
+
| Revocation | Revocation state is durable and evaluated during authorization. |
|
|
259
|
+
| Events | Governed transitions produce append-only, hash-chained events. |
|
|
260
|
+
| Time | Temporal constraints and event ordering are evaluated using kernel-defined time semantics. |
|
|
261
|
+
| Concurrency | State transitions are serialized into a single linear order. |
|
|
262
|
+
| Recovery | Kernel state is reconstructed from persistent state and the event history is verified before normal operation resumes. |
|
|
263
|
+
|
|
264
|
+
## Status
|
|
265
|
+
|
|
266
|
+
Reference implementation of the Shakun kernel and daemon.
|
|
267
|
+
|
|
268
|
+
The current release covers:
|
|
269
|
+
|
|
270
|
+
- cryptographic identity
|
|
271
|
+
- scoped delegation
|
|
272
|
+
- durable revocation
|
|
273
|
+
- tamper-evident event logging
|
|
274
|
+
- authenticated and replay-protected HTTP transport
|
|
275
|
+
- delegated authority over HTTP
|
|
276
|
+
|
|
277
|
+
The implementation is covered by 299 passing tests. Tests provide evidence of implementation correctness; they do not constitute deployment maturity, interoperability certification, or security certification.
|
|
278
|
+
|
|
279
|
+
### Scope
|
|
280
|
+
|
|
281
|
+
The current implementation is a single-kernel reference implementation. Distributed operation, multi-node execution, and additional client implementations are outside the scope of the current release.
|
|
282
|
+
|
|
283
|
+
## License
|
|
284
|
+
|
|
285
|
+
Apache 2.0 — see `LICENSE`.
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
# Shakun
|
|
2
|
+
|
|
3
|
+
Trust infrastructure for intelligent systems.
|
|
4
|
+
|
|
5
|
+
The current implementation provides a kernel for cryptographic identity,
|
|
6
|
+
scoped delegation, authorization, revocation, and tamper-evident event
|
|
7
|
+
history.
|
|
8
|
+
|
|
9
|
+
Shakun provides kernel-level primitives for cryptographic identity, scoped delegation, authorization, revocation, and tamper-evident event history for AI agents.
|
|
10
|
+
|
|
11
|
+
Agent runtimes remain responsible for reasoning and execution. Shakun provides the trust boundary around those operations: it authenticates the calling identity, evaluates applicable authority against governed state, enforces revocation and temporal constraints, and records governed state transitions as events.
|
|
12
|
+
|
|
13
|
+
The implementation is independent of the agent runtime. An agent may be implemented using LangGraph, another framework, or a custom execution loop, while the Shakun kernel remains responsible for identity and authority semantics.
|
|
14
|
+
|
|
15
|
+
## Design model
|
|
16
|
+
|
|
17
|
+
Shakun treats trust state as governed kernel state rather than as an application-level concern.
|
|
18
|
+
|
|
19
|
+
A governed operation has an authenticated principal and an applicable authority context. The kernel evaluates that context against its current identity, scope, delegation, revocation, temporal, and mission state. If the transition is permitted, the resulting event is appended to the kernel event history.
|
|
20
|
+
|
|
21
|
+
The resulting model is:
|
|
22
|
+
|
|
23
|
+
identity → authority → authorization → state transition → evidence
|
|
24
|
+
|
|
25
|
+
Identity establishes who is acting. Authority establishes what may be exercised. Authorization evaluates whether that authority is valid for the requested operation and current state. The state transition produces kernel-controlled evidence.
|
|
26
|
+
|
|
27
|
+
The kernel does not govern an agent's internal reasoning or attempt to determine whether an agent's behavior is predictable. It governs the boundary at which an agent's actions become consequential to kernel-managed state.
|
|
28
|
+
|
|
29
|
+
## Terminology
|
|
30
|
+
|
|
31
|
+
| Term | Meaning |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Identity | A kernel-registered principal associated with a public-key history. |
|
|
34
|
+
| Caller | The identity authenticated for a particular invocation. |
|
|
35
|
+
| Scope | A kernel-governed authority boundary. |
|
|
36
|
+
| Delegation | A signed grant allowing one identity to exercise authority associated with another identity subject to specified constraints. |
|
|
37
|
+
| Authorization | The kernel decision determining whether an authenticated caller may perform an operation under the applicable authority. |
|
|
38
|
+
| Revocation | Persistent state invalidating previously granted authority. |
|
|
39
|
+
| Mission | A governed unit of execution to which authority and evidence may be bound. |
|
|
40
|
+
| Event | A kernel-produced record of a governed state transition. |
|
|
41
|
+
| SignedInvocation | The authenticated request envelope used by the HTTP transport binding. |
|
|
42
|
+
|
|
43
|
+
## Kernel model
|
|
44
|
+
|
|
45
|
+
### Identity
|
|
46
|
+
|
|
47
|
+
Each agent principal is represented by a kernel-registered identity associated with an Ed25519 public key. Key history is retained so that signatures can be verified against the key that was valid at the relevant time.
|
|
48
|
+
|
|
49
|
+
### Authority
|
|
50
|
+
|
|
51
|
+
Authority is represented through scopes and signed delegation records. A delegation identifies the delegator, delegate, scope, validity interval, and optional mission binding.
|
|
52
|
+
|
|
53
|
+
A delegated caller does not acquire unrestricted authority. The kernel evaluates the delegation against the requested operation, scope, mission, expiry, and current revocation state.
|
|
54
|
+
|
|
55
|
+
### Revocation
|
|
56
|
+
|
|
57
|
+
Revocation is persistent kernel state. Authorization checks current revocation state rather than treating delegation validity as a property of the delegation object alone.
|
|
58
|
+
|
|
59
|
+
The current implementation provides a durable SQLite-backed revocation store.
|
|
60
|
+
|
|
61
|
+
### Evidence
|
|
62
|
+
|
|
63
|
+
Governed state transitions produce kernel events. Events are append-only and hash-chained. Each event commits to the hash of its predecessor, beginning from a fixed genesis value.
|
|
64
|
+
|
|
65
|
+
The kernel reconstructs and verifies the chain when rebuilding state. A broken chain causes reconstruction to fail rather than silently accepting modified history.
|
|
66
|
+
|
|
67
|
+
### Concurrency
|
|
68
|
+
|
|
69
|
+
State transitions are serialized by a kernel-wide reentrant lock. This provides a single linear transition order and prevents concurrent event appends from producing divergent chain predecessors.
|
|
70
|
+
|
|
71
|
+
### Transport
|
|
72
|
+
|
|
73
|
+
The HTTP daemon provides an authenticated transport binding for the kernel. The transport authenticates the caller before parsing the request body and passes transport-independent authentication data to the resolver.
|
|
74
|
+
|
|
75
|
+
Delegation is carried as application data inside the authenticated request body. Its own signature establishes the delegation's authority grant; the request signature establishes that the authenticated caller presented that delegation for the particular operation and body.
|
|
76
|
+
|
|
77
|
+
Shakun does not require the agent runtime itself to implement these trust-state semantics.
|
|
78
|
+
|
|
79
|
+
## Architecture
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
┌─────────────────────────────────────────────┐
|
|
83
|
+
│ Agent framework │
|
|
84
|
+
│ (custom loop, LangGraph, etc.) │
|
|
85
|
+
└──────────────────────┬──────────────────────┘
|
|
86
|
+
│ signed requests
|
|
87
|
+
┌──────────────────────▼──────────────────────┐
|
|
88
|
+
│ Daemon │
|
|
89
|
+
│ request authentication · delegation │
|
|
90
|
+
│ ·verification · replay protection · HTTP │
|
|
91
|
+
└──────────────────────┬──────────────────────┘
|
|
92
|
+
│
|
|
93
|
+
┌──────────────────────▼──────────────────────┐
|
|
94
|
+
│ Kernel │
|
|
95
|
+
│ identity · scope · delegation · revocation │
|
|
96
|
+
│ missions · tamper-evident event log │
|
|
97
|
+
└──────────────────────┬──────────────────────┘
|
|
98
|
+
│
|
|
99
|
+
┌──────────────────────▼──────────────────────┐
|
|
100
|
+
│ Persistence │
|
|
101
|
+
│ SQLite (WAL) · in-memory │
|
|
102
|
+
└─────────────────────────────────────────────┘
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The kernel is the authority over governed trust state. The daemon is a transport boundary and does not own authorization state. Agent frameworks remain outside the trust-state boundary.
|
|
106
|
+
|
|
107
|
+
The separation is:
|
|
108
|
+
|
|
109
|
+
- agent runtime — reasoning and execution
|
|
110
|
+
- daemon — transport authentication and protocol adaptation
|
|
111
|
+
- kernel — identity, authority, authorization, revocation, state transitions, and evidence
|
|
112
|
+
- persistence — durable representation of kernel state
|
|
113
|
+
|
|
114
|
+
Transport-specific representations are adapted before reaching kernel authorization logic. Kernel authorization therefore does not depend on HTTP-specific request objects.
|
|
115
|
+
|
|
116
|
+
## Request processing
|
|
117
|
+
|
|
118
|
+
A request is processed in the following order:
|
|
119
|
+
|
|
120
|
+
1. The transport reads the request bytes without interpreting the body.
|
|
121
|
+
2. The transport constructs the transport-independent authentication adapter.
|
|
122
|
+
3. The resolver validates the signed invocation metadata.
|
|
123
|
+
4. The resolver validates timestamp constraints and resolves the caller's key using key history.
|
|
124
|
+
5. The resolver verifies the body digest and request signature.
|
|
125
|
+
6. The resolver checks replay state.
|
|
126
|
+
7. Only after authentication succeeds is the request body parsed.
|
|
127
|
+
8. The dispatcher resolves the signed operation.
|
|
128
|
+
9. For delegated operations, the delegation is reconstructed and supplied through an `AuthorizationContext`.
|
|
129
|
+
10. The kernel verifies the delegation, evaluates revocation and authorization state, and performs the governed transition.
|
|
130
|
+
11. The resulting event is appended to the kernel event history.
|
|
131
|
+
|
|
132
|
+
Authentication failure is returned through a uniform transport-level error. Internal exception details are not exposed through the transport.
|
|
133
|
+
|
|
134
|
+
## Delegation
|
|
135
|
+
|
|
136
|
+
Delegation is represented as a signed `DelegationRecord`.
|
|
137
|
+
|
|
138
|
+
The wire representation is a flat JSON object containing the complete delegation record. The representation is explicitly defined rather than derived from Python dataclass layout so that independent implementations can reproduce the same protocol structure.
|
|
139
|
+
|
|
140
|
+
A delegation contains:
|
|
141
|
+
|
|
142
|
+
- protocol version
|
|
143
|
+
- delegation identifier
|
|
144
|
+
- delegator identity
|
|
145
|
+
- delegate identity
|
|
146
|
+
- issuer identity
|
|
147
|
+
- scope
|
|
148
|
+
- optional mission binding
|
|
149
|
+
- issuance time
|
|
150
|
+
- expiry time
|
|
151
|
+
- optional revocation reference
|
|
152
|
+
- delegation signature
|
|
153
|
+
|
|
154
|
+
The delegation signature is verified independently of the request signature.
|
|
155
|
+
|
|
156
|
+
When transmitted over HTTP, the delegation is included in the request body. Consequently, the request body digest and request signature bind the presented delegation to the particular invocation.
|
|
157
|
+
|
|
158
|
+
The two signatures establish separate facts:
|
|
159
|
+
|
|
160
|
+
- the delegation signature establishes that the authority grant was issued by the appropriate authority;
|
|
161
|
+
- the invocation signature establishes that the authenticated caller presented that delegation for the particular request.
|
|
162
|
+
|
|
163
|
+
## Interoperability
|
|
164
|
+
|
|
165
|
+
Shakun defines interoperability at multiple boundaries.
|
|
166
|
+
|
|
167
|
+
At the runtime boundary, the kernel is independent of the agent framework. An agent can use a custom execution loop, LangGraph, or another runtime while using the same kernel authorization model.
|
|
168
|
+
|
|
169
|
+
At the protocol boundary, authenticated invocations and delegation records have explicit wire representations. A client implementation does not need to be written in Python; it needs to implement the protocol semantics and cryptographic operations defined by the Shakun protocol.
|
|
170
|
+
|
|
171
|
+
The current implementation therefore supports interoperability between independent implementations at the protocol level, subject to implementation of the defined protocol semantics.
|
|
172
|
+
|
|
173
|
+
## Running it
|
|
174
|
+
|
|
175
|
+
Install the reference implementation:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
git clone https://github.com/shakun-labs/shakun-kernel.git
|
|
179
|
+
cd shakun
|
|
180
|
+
pip install -r requirements.txt
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Delegation
|
|
184
|
+
Runs an end-to-end delegation flow: identity setup, scoped delegation, governed execution, revocation, and subsequent authorization failure.
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
python3 -m examples.delegation_demo
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Evidence
|
|
191
|
+
Demonstrates kernel-produced evidence and evidence validation.
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
python3 -m examples.governance_execution_demo
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Restart and recovery
|
|
198
|
+
Runs the kernel across process restarts and verifies reconstruction of governed state and event-chain integrity.
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
python3 -m examples.restart_consistency_demo
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Minimal example (in-process)
|
|
205
|
+
|
|
206
|
+
from shakun import create_shakun, CallerContext
|
|
207
|
+
|
|
208
|
+
kernel = create_shakun(storage="sqlite", sqlite_path="./example.db")
|
|
209
|
+
|
|
210
|
+
# A fresh kernel is bootstrapped with a root identity.
|
|
211
|
+
caller = CallerContext(kernel.genesis_identity())
|
|
212
|
+
|
|
213
|
+
# Authorization is evaluated by the kernel for each governed operation.
|
|
214
|
+
kernel.syscall_create_scope("example_scope", caller=caller)
|
|
215
|
+
|
|
216
|
+
mission = kernel.syscall_create_mission(
|
|
217
|
+
"record governed execution state",
|
|
218
|
+
scope_id="example_scope",
|
|
219
|
+
caller=caller,
|
|
220
|
+
)
|
|
221
|
+
kernel.syscall_start_mission(mission["mission_id"], caller=caller)
|
|
222
|
+
|
|
223
|
+
Delegating scoped authority to another identity — the full flow is in
|
|
224
|
+
`examples/delegation_demo.py`, and `docs/GETTING_STARTED.md` walks through it step
|
|
225
|
+
by step.
|
|
226
|
+
|
|
227
|
+
The daemon adds authenticated, signature-verified access to the same syscalls
|
|
228
|
+
over HTTP, including delegated requests. See `docs/GETTING_STARTED.md`.
|
|
229
|
+
|
|
230
|
+
## Kernel invariants
|
|
231
|
+
|
|
232
|
+
The kernel enforces a small set of invariants, specified in full in
|
|
233
|
+
[`docs/KERNEL_SYSCALL_SPEC.md`](docs/KERNEL_SYSCALL_SPEC.md).
|
|
234
|
+
|
|
235
|
+
| Invariant | Definition |
|
|
236
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
237
|
+
| Identity | Every governed action is attributed to a kernel-registered cryptographic identity. |
|
|
238
|
+
| Authority | Authorization is evaluated against the caller's applicable scope and delegation state. |
|
|
239
|
+
| Delegation | Delegations are signed protocol objects and are independently verified. |
|
|
240
|
+
| Revocation | Revocation state is durable and evaluated during authorization. |
|
|
241
|
+
| Events | Governed transitions produce append-only, hash-chained events. |
|
|
242
|
+
| Time | Temporal constraints and event ordering are evaluated using kernel-defined time semantics. |
|
|
243
|
+
| Concurrency | State transitions are serialized into a single linear order. |
|
|
244
|
+
| Recovery | Kernel state is reconstructed from persistent state and the event history is verified before normal operation resumes. |
|
|
245
|
+
|
|
246
|
+
## Status
|
|
247
|
+
|
|
248
|
+
Reference implementation of the Shakun kernel and daemon.
|
|
249
|
+
|
|
250
|
+
The current release covers:
|
|
251
|
+
|
|
252
|
+
- cryptographic identity
|
|
253
|
+
- scoped delegation
|
|
254
|
+
- durable revocation
|
|
255
|
+
- tamper-evident event logging
|
|
256
|
+
- authenticated and replay-protected HTTP transport
|
|
257
|
+
- delegated authority over HTTP
|
|
258
|
+
|
|
259
|
+
The implementation is covered by 299 passing tests. Tests provide evidence of implementation correctness; they do not constitute deployment maturity, interoperability certification, or security certification.
|
|
260
|
+
|
|
261
|
+
### Scope
|
|
262
|
+
|
|
263
|
+
The current implementation is a single-kernel reference implementation. Distributed operation, multi-node execution, and additional client implementations are outside the scope of the current release.
|
|
264
|
+
|
|
265
|
+
## License
|
|
266
|
+
|
|
267
|
+
Apache 2.0 — see `LICENSE`.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "shakun-kernel"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Trust infrastructure for intelligent systems"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "Apache-2.0"
|
|
12
|
+
dependencies = [
|
|
13
|
+
"cryptography",
|
|
14
|
+
"fastapi",
|
|
15
|
+
"uvicorn",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.optional-dependencies]
|
|
19
|
+
# Test/dev tooling — install with: pip install -e ".[dev]"
|
|
20
|
+
dev = [
|
|
21
|
+
"pytest",
|
|
22
|
+
"httpx",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://github.com/shakun-labs/shakun-kernel"
|
|
27
|
+
Repository = "https://github.com/shakun-labs/shakun-kernel"
|
|
28
|
+
|
|
29
|
+
[tool.setuptools.packages.find]
|
|
30
|
+
where = ["."]
|
|
31
|
+
include = ["shakun_kernel*"]
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Shakun — a trust and identity kernel for AI agents.
|
|
3
|
+
|
|
4
|
+
This module is the public surface. Everything a developer needs to stand
|
|
5
|
+
up a kernel, obtain a caller, register identities, and delegate authority
|
|
6
|
+
between them is exported here. Reaching into kernel internals or test
|
|
7
|
+
helpers should never be necessary for ordinary use; if it is, that is a
|
|
8
|
+
gap in this surface, not the intended path.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from shakun_kernel.factory import create_shakun
|
|
12
|
+
from shakun_kernel.kernel.caller import CallerContext
|
|
13
|
+
from shakun_kernel.kernel.identity_keys import generate_identity_keypair
|
|
14
|
+
from shakun_kernel.kernel.delegation import create_delegation
|
|
15
|
+
from shakun_kernel.kernel.authorization import AuthorizationContext
|
|
16
|
+
from shakun_kernel.kernel.revocation_store import InMemoryRevocationStore, RevocationRecord
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"create_shakun",
|
|
20
|
+
"CallerContext",
|
|
21
|
+
"generate_identity_keypair",
|
|
22
|
+
"create_delegation",
|
|
23
|
+
"AuthorizationContext",
|
|
24
|
+
"InMemoryRevocationStore",
|
|
25
|
+
"RevocationRecord",
|
|
26
|
+
]
|