Shakun

Trust infrastructure for intelligent systems.

The current implementation provides a kernel for cryptographic identity, scoped delegation, authorization, revocation, and tamper-evident event history.

Shakun provides kernel-level primitives for cryptographic identity, scoped delegation, authorization, revocation, and tamper-evident event history for AI agents.

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.

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.

Design model

Shakun treats trust state as governed kernel state rather than as an application-level concern.

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.

The resulting model is:

identity → authority → authorization → state transition → evidence

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.

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.

Terminology

Term	Meaning
Identity	A kernel-registered principal associated with a public-key history.
Caller	The identity authenticated for a particular invocation.
Scope	A kernel-governed authority boundary.
Delegation	A signed grant allowing one identity to exercise authority associated with another identity subject to specified constraints.
Authorization	The kernel decision determining whether an authenticated caller may perform an operation under the applicable authority.
Revocation	Persistent state invalidating previously granted authority.
Mission	A governed unit of execution to which authority and evidence may be bound.
Event	A kernel-produced record of a governed state transition.
SignedInvocation	The authenticated request envelope used by the HTTP transport binding.

Kernel model

Identity

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.

Authority

Authority is represented through scopes and signed delegation records. A delegation identifies the delegator, delegate, scope, validity interval, and optional mission binding.

A delegated caller does not acquire unrestricted authority. The kernel evaluates the delegation against the requested operation, scope, mission, expiry, and current revocation state.

Revocation

Revocation is persistent kernel state. Authorization checks current revocation state rather than treating delegation validity as a property of the delegation object alone.

The current implementation provides a durable SQLite-backed revocation store.

Evidence

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.

The kernel reconstructs and verifies the chain when rebuilding state. A broken chain causes reconstruction to fail rather than silently accepting modified history.

Concurrency

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.

Transport

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.

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.

Shakun does not require the agent runtime itself to implement these trust-state semantics.

Architecture

┌─────────────────────────────────────────────┐
│              Agent framework                 │
│        (custom loop, LangGraph, etc.)        │
└──────────────────────┬──────────────────────┘
                       │ signed requests
┌──────────────────────▼──────────────────────┐
│                  Daemon                      │
│  request authentication · delegation         │
│  ·verification · replay protection · HTTP    │
└──────────────────────┬──────────────────────┘
                       │
┌──────────────────────▼──────────────────────┐
│                  Kernel                      │
│  identity · scope · delegation · revocation  │
│  missions · tamper-evident event log         │
└──────────────────────┬──────────────────────┘
                       │
┌──────────────────────▼──────────────────────┐
│               Persistence                    │
│         SQLite (WAL) · in-memory             │
└─────────────────────────────────────────────┘

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.

The separation is:

• agent runtime — reasoning and execution
• daemon — transport authentication and protocol adaptation
• kernel — identity, authority, authorization, revocation, state transitions, and evidence
• persistence — durable representation of kernel state

Transport-specific representations are adapted before reaching kernel authorization logic. Kernel authorization therefore does not depend on HTTP-specific request objects.

Request processing

A request is processed in the following order:

1. The transport reads the request bytes without interpreting the body.
2. The transport constructs the transport-independent authentication adapter.
3. The resolver validates the signed invocation metadata.
4. The resolver validates timestamp constraints and resolves the caller's key using key history.
5. The resolver verifies the body digest and request signature.
6. The resolver checks replay state.
7. Only after authentication succeeds is the request body parsed.
8. The dispatcher resolves the signed operation.
9. For delegated operations, the delegation is reconstructed and supplied through an AuthorizationContext.
10. The kernel verifies the delegation, evaluates revocation and authorization state, and performs the governed transition.
11. The resulting event is appended to the kernel event history.

Authentication failure is returned through a uniform transport-level error. Internal exception details are not exposed through the transport.

Delegation

Delegation is represented as a signed DelegationRecord.

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.

A delegation contains:

• protocol version
• delegation identifier
• delegator identity
• delegate identity
• issuer identity
• scope
• optional mission binding
• issuance time
• expiry time
• optional revocation reference
• delegation signature

The delegation signature is verified independently of the request signature.

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.

The two signatures establish separate facts:

• the delegation signature establishes that the authority grant was issued by the appropriate authority;
• the invocation signature establishes that the authenticated caller presented that delegation for the particular request.

Interoperability

Shakun defines interoperability at multiple boundaries.

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.

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.

The current implementation therefore supports interoperability between independent implementations at the protocol level, subject to implementation of the defined protocol semantics.

Running it

Install the reference implementation:

git clone https://github.com/shakun-labs/shakun-kernel.git
cd shakun
pip install -r requirements.txt

Delegation Runs an end-to-end delegation flow: identity setup, scoped delegation, governed execution, revocation, and subsequent authorization failure.

python3 -m examples.delegation_demo

Evidence Demonstrates kernel-produced evidence and evidence validation.

python3 -m examples.governance_execution_demo

Restart and recovery Runs the kernel across process restarts and verifies reconstruction of governed state and event-chain integrity.

python3 -m examples.restart_consistency_demo

Minimal example (in-process)

from shakun import create_shakun, CallerContext

kernel = create_shakun(storage="sqlite", sqlite_path="./example.db")

A fresh kernel is bootstrapped with a root identity.

caller = CallerContext(kernel.genesis_identity())

Authorization is evaluated by the kernel for each governed operation.

kernel.syscall_create_scope("example_scope", caller=caller)

mission = kernel.syscall_create_mission( "record governed execution state", scope_id="example_scope", caller=caller, ) kernel.syscall_start_mission(mission["mission_id"], caller=caller)

Delegating scoped authority to another identity — the full flow is in examples/delegation_demo.py, and docs/GETTING_STARTED.md walks through it step by step.

The daemon adds authenticated, signature-verified access to the same syscalls over HTTP, including delegated requests. See docs/GETTING_STARTED.md.

Kernel invariants

The kernel enforces a small set of invariants, specified in full in docs/KERNEL_SYSCALL_SPEC.md.

Invariant	Definition
Identity	Every governed action is attributed to a kernel-registered cryptographic identity.
Authority	Authorization is evaluated against the caller's applicable scope and delegation state.
Delegation	Delegations are signed protocol objects and are independently verified.
Revocation	Revocation state is durable and evaluated during authorization.
Events	Governed transitions produce append-only, hash-chained events.
Time	Temporal constraints and event ordering are evaluated using kernel-defined time semantics.
Concurrency	State transitions are serialized into a single linear order.
Recovery	Kernel state is reconstructed from persistent state and the event history is verified before normal operation resumes.

Status

Reference implementation of the Shakun kernel and daemon.

The current release covers:

• cryptographic identity
• scoped delegation
• durable revocation
• tamper-evident event logging
• authenticated and replay-protected HTTP transport
• delegated authority over HTTP

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.

Scope

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.

License

Apache 2.0 — see LICENSE.