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.
Files changed (58) hide show
  1. shakun_kernel-0.1.0/LICENSE +19 -0
  2. shakun_kernel-0.1.0/PKG-INFO +285 -0
  3. shakun_kernel-0.1.0/README.md +267 -0
  4. shakun_kernel-0.1.0/pyproject.toml +31 -0
  5. shakun_kernel-0.1.0/setup.cfg +4 -0
  6. shakun_kernel-0.1.0/shakun_kernel/__init__.py +26 -0
  7. shakun_kernel-0.1.0/shakun_kernel/daemon/__init__.py +3 -0
  8. shakun_kernel-0.1.0/shakun_kernel/daemon/__main__.py +42 -0
  9. shakun_kernel-0.1.0/shakun_kernel/daemon/caller_resolver.py +67 -0
  10. shakun_kernel-0.1.0/shakun_kernel/daemon/delegation_wire.py +61 -0
  11. shakun_kernel-0.1.0/shakun_kernel/daemon/dispatcher.py +213 -0
  12. shakun_kernel-0.1.0/shakun_kernel/daemon/nonce_store.py +133 -0
  13. shakun_kernel-0.1.0/shakun_kernel/daemon/server.py +136 -0
  14. shakun_kernel-0.1.0/shakun_kernel/daemon/signature_resolver.py +173 -0
  15. shakun_kernel-0.1.0/shakun_kernel/daemon/signed_invocation.py +66 -0
  16. shakun_kernel-0.1.0/shakun_kernel/factory.py +236 -0
  17. shakun_kernel-0.1.0/shakun_kernel/kernel/__init__.py +0 -0
  18. shakun_kernel-0.1.0/shakun_kernel/kernel/attestation.py +275 -0
  19. shakun_kernel-0.1.0/shakun_kernel/kernel/authorization.py +156 -0
  20. shakun_kernel-0.1.0/shakun_kernel/kernel/caller.py +42 -0
  21. shakun_kernel-0.1.0/shakun_kernel/kernel/clock.py +75 -0
  22. shakun_kernel-0.1.0/shakun_kernel/kernel/delegation.py +215 -0
  23. shakun_kernel-0.1.0/shakun_kernel/kernel/event_chain.py +47 -0
  24. shakun_kernel-0.1.0/shakun_kernel/kernel/identity.py +17 -0
  25. shakun_kernel-0.1.0/shakun_kernel/kernel/identity_keys.py +140 -0
  26. shakun_kernel-0.1.0/shakun_kernel/kernel/kernel.py +2570 -0
  27. shakun_kernel-0.1.0/shakun_kernel/kernel/revocation_store.py +96 -0
  28. shakun_kernel-0.1.0/shakun_kernel/kernel/rotation.py +132 -0
  29. shakun_kernel-0.1.0/shakun_kernel/kernel/schemas.py +263 -0
  30. shakun_kernel-0.1.0/shakun_kernel/kernel/validation.py +14 -0
  31. shakun_kernel-0.1.0/shakun_kernel/kernel/verification.py +89 -0
  32. shakun_kernel-0.1.0/shakun_kernel/storage/__init__.py +0 -0
  33. shakun_kernel-0.1.0/shakun_kernel/storage/sqlite_store.py +311 -0
  34. shakun_kernel-0.1.0/shakun_kernel/transport/__init__.py +0 -0
  35. shakun_kernel-0.1.0/shakun_kernel/transport/http.py +163 -0
  36. shakun_kernel-0.1.0/shakun_kernel.egg-info/PKG-INFO +285 -0
  37. shakun_kernel-0.1.0/shakun_kernel.egg-info/SOURCES.txt +56 -0
  38. shakun_kernel-0.1.0/shakun_kernel.egg-info/dependency_links.txt +1 -0
  39. shakun_kernel-0.1.0/shakun_kernel.egg-info/requires.txt +7 -0
  40. shakun_kernel-0.1.0/shakun_kernel.egg-info/top_level.txt +1 -0
  41. shakun_kernel-0.1.0/tests/test_attestation.py +897 -0
  42. shakun_kernel-0.1.0/tests/test_bootstrap.py +165 -0
  43. shakun_kernel-0.1.0/tests/test_caller.py +31 -0
  44. shakun_kernel-0.1.0/tests/test_caller_resolver.py +56 -0
  45. shakun_kernel-0.1.0/tests/test_concurrency.py +69 -0
  46. shakun_kernel-0.1.0/tests/test_daemon_startup.py +98 -0
  47. shakun_kernel-0.1.0/tests/test_delegation.py +546 -0
  48. shakun_kernel-0.1.0/tests/test_delegation_over_http.py +269 -0
  49. shakun_kernel-0.1.0/tests/test_delegation_wire.py +85 -0
  50. shakun_kernel-0.1.0/tests/test_dispatcher.py +92 -0
  51. shakun_kernel-0.1.0/tests/test_event_chain.py +88 -0
  52. shakun_kernel-0.1.0/tests/test_factory.py +357 -0
  53. shakun_kernel-0.1.0/tests/test_http_transport.py +184 -0
  54. shakun_kernel-0.1.0/tests/test_kernel.py +1723 -0
  55. shakun_kernel-0.1.0/tests/test_signature_resolver.py +150 -0
  56. shakun_kernel-0.1.0/tests/test_signed_invocation.py +121 -0
  57. shakun_kernel-0.1.0/tests/test_sqlite_nonce_store.py +115 -0
  58. 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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ ]
@@ -0,0 +1,3 @@
1
+ # Shakun daemon package. Intentionally empty: importing the package must
2
+ # not eagerly import submodules, or any submodule that imports back into
3
+ # the package creates a circular import. The CLI lives in __main__.py.