OrgKernel

<p align="center"> <strong>The Open-Source Trust Layer for AI Agents</strong><br/> Cryptographic agent identity, scoped execution, and tamper-evident audit trails —<br/> transparent by design, not by promise. </p> <p align="center"> <a href="https://github.com/MetapriseAI/OrgKernel/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a> <a href="https://github.com/MetapriseAI/OrgKernel/stargazers"><img src="https://img.shields.io/github/stars/MetapriseAI/OrgKernel?style=flat&color=yellow" alt="GitHub Stars" /></a> <a href="https://github.com/MetapriseAI/OrgKernel/issues"><img src="https://img.shields.io/github/issues/MetapriseAI/OrgKernel" alt="GitHub Issues" /></a> <a href="https://github.com/MetapriseAI/OrgKernel/pulls"><img src="https://img.shields.io/github/issues-pr/MetapriseAI/OrgKernel" alt="Pull Requests" /></a> <img src="https://img.shields.io/badge/Python-3.10+-3776AB?logo=python" alt="Python 3.10+" /> <img src="https://img.shields.io/badge/FastAPI-supported-009688?logo=fastapi" alt="FastAPI" /> <img src="https://img.shields.io/badge/PostgreSQL-supported-336791?logo=postgresql" alt="PostgreSQL" /> </p> <p align="center"> <b>3</b> Core Modules &nbsp;·&nbsp; <b>27</b> REST Endpoints &nbsp;·&nbsp; PostgreSQL / MySQL / SQLite Persistence &nbsp;·&nbsp; Works with LangGraph, CrewAI &amp; AutoGen </p>

---

The four questions

Every organization that deploys AI agents eventually asks the same four questions:

1. Who is this agent? → AgentIdentity — a cryptographic credential (Ed25519 keypair) signed by your Org CA
2. What can it do? → ExecutionToken — scoped, time-bounded permissions with tool allowlists and parameter bounds
3. What did it do? → AuditChain — an append-only, SHA-256 hash-chained execution log
4. Who authorized it? → the organizational authority chain — a verifiable lineage of who granted what

Agent frameworks help you build and orchestrate agents. None of them answer these questions. OrgKernel does — and because it sits in the execution path, it can't be bypassed. Governance is built into the engine, not left to the application developer.

Authorization is not a boolean — it's a graph

In a real organization, permission is never a single yes/no flag. A mission's execution permission is determined jointly by four layers — organization, department, role, and instance. Any layer's denial blocks execution.

Consider an agent that attempts to spend $10,000 to complete a task. The request is blocked — purchasing authority at that amount belongs to the department lead. With OrgKernel, the block is enforced at the token scope check, and the full context (which agent, which mission, what it requested, why it was denied) is already in the audit chain when the department lead asks what happened.

📖 Read the launch announcement: Introducing OrgKernel

---

Part of Metaprise AURA

OrgKernel is the open-source trust foundation of AURA, the execution governance engine of the Metaprise Enterprise Agent Operating System. Every agent running on Metaprise — across banking, healthcare, insurance, and capital-markets deployments — authenticates, executes, and is audited through OrgKernel primitives.

You don't need Metaprise to use OrgKernel. It's a standalone Apache 2.0 Python library that runs entirely on your own infrastructure — no API key, no phone-home, no vendor lock-in. Inspect every line, audit the cryptography, fork it for your own stack.

---

What's in the box

| Capability | Status | Description | | -------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | Cryptographic Identity (PKI) | ✅ Available | Ed25519 keypairs, Org CA signing, CSR flow, challenge-response verification, full suspend/revoke/reactivate lifecycle | | Scoped Execution Tokens | ✅ Available | Mission-scoped permission tokens with tool allowlists, immutable & bounded parameters, and Ed25519 signatures to prevent token grafting | | Hash-Chained Audit Trail | ✅ Available | Three-layer audit (IDENTITY / EXECUTION / COMPLIANCE) persisted to PostgreSQL/MySQL/SQLite with SHA-256 hash chaining and integrity verification |

Identity plus execution token together form the DualToken model: at execution time an agent presents both its organizational identity credential and an instance-scoped execution token. Both must validate before a tool call proceeds.

Upcoming capabilities (mission lifecycle, tool gateway, policy engine, authority graph, data classifier, SSO/SAML, SCIM) are tracked in the Roadmap.

---

Why OrgKernel

| If you use… | You get… | What's missing | | ---------------------------------- | ------------------------------------------ | -------------------------------------------------------- | | LangGraph / CrewAI / AutoGen alone | Agent orchestration | No verifiable identity, no scoped authority, no tamper-evident audit | | API keys per agent | Coarse access control | Keys are permanent, unscoped, unauditable, and shareable | | Application-level logging | A log you hope is complete | Logs can be edited or deleted; nothing proves integrity | | OrgKernel | Identity + scoped authority + audit, enforced in the execution path | — |

Key properties:

• Enforced, not advisory. Scope checks run before every tool call. There is no code path around them.
• Tamper-evident, not tamper-"proof by promise". Any deletion, modification, or reordering of audit entries breaks the SHA-256 chain and is detected by the integrity API.
• Least privilege by construction. Tokens carry only the tools and parameter bounds a single mission needs, and they expire.
• Compliance-grade evidence. The audit chain supports full replay of any agent's history and independent third-party verification — designed for the evidentiary requirements of financial, healthcare, and legal deployments.

---

System Architecture

Agent Platform
    |
    |-- CSR submitted --> AgentIdentityService.submit_csr()
    |                      |-- validates duplicate
    |                      v
    |-- CSR issued -----> AgentIdentityService.issue_from_csr()
    |                      |-- generates Ed25519 keypair (server-side)
    |                      |-- signs certificate with Org CA
    |                      |-- returns certificate + private_key_pem ONCE
    |                      |-- persists identity record (NO private key)
    |                      v
    |                  AgentCertificate + AgentIdentity
    |
    |-- token mint ----> ExecutionTokenService.mint()
    |                      |-- Ed25519-signed by Org CA (prevents Token Grafting)
    |                      |-- tool allowlist + numeric bounds
    |                      v
    |                  ExecutionToken
    |
    |-- scope check ---> ExecutionTokenService.check_scope()
    |                      |-- tool in scope?
    |                      |-- bounded params within limits?
    |                      v
    |                  ScopeCheckResponse (ALLOWED or BLOCKED)
    |
    |-- audit init ----> AuditChainService.initialize()
    |                      |-- writes genesis IDENTITY entry (SHA-256)
    |                      v
    |-- audit append ---> AuditChainService.append()
    |                      |-- SHA-256 prev_hash chain
    |                      v
    |-- audit verify ---> AuditChainService.verify_integrity()
                           |-- recomputes all hashes
                           |-- detects deletion / tampering / reorder

Challenge-Response Authentication

| Step | Party | Action | | ---- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Verifier | Calls AgentIdentityService.request_challenge(agent_id, issued_by) — generates random nonce + challenge_id, stored in memory with 5-minute TTL | | 2 | Verifier → Agent | Sends nonce to the target Agent | | 3 | Agent | Signs the nonce with its Ed25519 private key, constructs ChallengeResponse(challenge_id, nonce, public_key, signature) | | 4 | Verifier | Calls AgentIdentityService.verify_challenge(response) — validates: nonce one-time use (anti-replay), Ed25519 signature correct, certificate ACTIVE and not expired |

Attack vectors prevented: Replay attack (nonce consumed after one use), private key theft (signature must match nonce), Token Grafting (token.agent_id == caller.agent_id verified at every scope check).

Three-Layer Audit Semantics

| Audit Layer | Triggered By | Semantics | | ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------- | |