HDP — Human Delegation Provenance Protocol

A cryptographic chain-of-custody protocol for agentic AI systems. Signed delegation context and agent activity, preserved for audit.

HDP delegation chain — cryptographic audit trail for AI agents

What is HDP?

HDP (Human Delegation Provenance) is an open protocol that captures, structures, cryptographically signs, and verifies records of human delegation context in agentic AI systems.

When a person delegates a task to an AI agent — and that agent delegates to another agent, and another — HDP creates a tamper-evident chain from the issuer's signed statement to the activity each hop records. The full trail is encoded in a compact, self-contained token signed with Ed25519 and canonicalized with RFC 8785. Verification is fully offline: it uses a trusted issuer public key, local session context, the current time, and verifier-local revocation state, with no central registry or network call.

Who it is for: developers building AI agents with Grok/xAI, CrewAI, MCP servers, or any OpenAI-compatible API who need accountable, auditable records of delegation context and subsequent agent activity.

Boundary: HDP is not an authorization protocol, capability, access token, or credential. A valid token proves that its signed record is authentic and intact; it does not grant access, prove that an action occurred, or show that a named delegate consented. Services must make authorization decisions using their own access-control system.

Standardization: HDP is specified in the IETF individual Internet-Draft draft-helixar-hdp-agentic-delegation (Informational). Revision -02 tightens verification, revocation, transport, and audit requirements while keeping the v0.1 token structure and signature payloads unchanged.

→ Protocol boundaries, live verification, and historical audit

Revision -02 compatibility: Use the standard HTTP field names HDP-Token and HDP-Token-Ref. Maintained middleware accepts the former X-HDP-* names as deprecated input aliases during migration. Earlier SDK releases also signed different, non-interoperable root and hop payload shapes; tokens they emitted must be reissued because corrected implementations do not silently fall back to the earlier signature scheme.

Packages

Package	Registry	Language	Framework	Description
`@helixar_ai/hdp`	npm	TypeScript	Any	Core SDK — issue, extend, verify HDP tokens
`@helixar_ai/hdp-mcp`	npm	TypeScript	MCP	MCP middleware — attaches HDP to any MCP server
`@helixar_ai/hdp-physical`	npm	TypeScript	Physical AI / Robotics	HDP-P guardrails — signs EDTs and blocks unsafe robot actions pre-execution
`hdp-physical`	PyPI	Python	Physical AI / Robotics	HDP-P guardrails — Python SDK for EDT issuance and pre-execution checks
`hdp-crewai`	PyPI	Python	CrewAI	CrewAI middleware — attaches HDP to any crew
`hdp-grok`	PyPI	Python	Grok / xAI	Grok middleware — attaches HDP to any xAI conversation
`hdp-autogen`	PyPI	Python	AutoGen	AutoGen middleware — attaches HDP to any AutoGen agent or GroupChat
`hdp-agent-framework`	PyPI	Python	Microsoft agent-framework	agent-framework middleware — attaches HDP to any Agent or workflow
`@helixar_ai/hdp-autogen`	npm	TypeScript	AutoGen	AutoGen middleware — HdpAgentWrapper + hdpMiddleware for AutoGen flows
`hdp-langchain`	PyPI	Python	LangChain / LangGraph	LangChain middleware — attaches HDP to any chain, agent, or LangGraph node
`llama-index-callbacks-hdp`	PyPI	Python	LlamaIndex	LlamaIndex integration — callback handler, instrumentation dispatcher, node postprocessor
`hdp-llamaindex`	PyPI	Python	LlamaIndex	Metapackage — `pip install hdp-llamaindex` for HDP-first users

Install

TypeScript / Node.js

npm install @helixar_ai/hdp

TypeScript / Physical AI

npm install @helixar_ai/hdp-physical

Python / CrewAI

pip install hdp-crewai

Python / Physical AI

pip install hdp-physical

Python / Grok (xAI API)

pip install hdp-grok

Python / AutoGen

pip install hdp-autogen

Python / Microsoft agent-framework

pip install hdp-agent-framework

Python / LangChain

pip install hdp-langchain

Python / LlamaIndex

pip install llama-index-callbacks-hdp
# or, from the HDP side:
pip install hdp-llamaindex

Quickstart — TypeScript

Issue a root token, extend it through a delegation chain, verify it offline. Under 2 minutes.

import {
  generateKeyPair,
  issueToken,
  extendChain,
  verifyToken,
} from "@helixar_ai/hdp";

// 1. Generate a key pair for the issuer
const { privateKey, publicKey } = await generateKeyPair();

// 2. Issue a token (the issuer's signed record of the delegation context)
let token = await issueToken({
  sessionId: "sess-20260326-abc123",
  principal: {
    id: "usr_alice_opaque",
    id_type: "opaque",
    display_name: "Alice Chen",
  },
  scope: {
    intent: "Analyze Q1 sales data and generate a summary report.",
    authorized_tools: ["database_read", "file_write"],
    authorized_resources: ["db://sales/q1-2026"],
    data_classification: "confidential",
    network_egress: false,
    persistence: true,
    max_hops: 3,        // issuer's choice of delegation budget, not a protocol limit
  },
  signingKey: privateKey,
  keyId: "alice-signing-key-v1",
});

// 3. Extend the chain as the task delegates to agents
token = await extendChain(
  token,
  {
    agent_id: "orchestrator-v2",
    agent_type: "orchestrator",
    action_summary: "Decompose analysis task and delegate to sub-agents.",
    parent_hop: 0,
  },
  privateKey,
);

token = await extendChain(
  token,
  {
    agent_id: "sql-agent-v1",
    agent_type: "sub-agent",
    action_summary: "Execute read query against sales database.",
    parent_hop: 1,
  },
  privateKey,
);

// 4. Verify at any point in the chain — fully offline, no network call
const result = await verifyToken(token, {
  publicKey,
  currentSessionId: "sess-20260326-abc123",
});

console.log(result.valid); // true
console.log(token.chain.length); // 2

Physical AI Integration

@helixar_ai/hdp-physical and hdp-physical extend HDP into robotics with Embodied Delegation Tokens (EDTs) and a pre-execution guard. Before a motion command reaches an actuator, HDP-P verifies the EDT signature, checks the irreversibility ceiling, enforces excluded zones, and blocks actions that exceed force or velocity limits.

import {
  EdtBuilder,
  IrreversibilityClass,
  PreExecutionGuard,
  signEdt,
} from "@helixar_ai/hdp-physical";
import { generateKeyPair } from "@helixar_ai/hdp";

const { privateKey, publicKey } = await generateKeyPair();

const edt = new EdtBuilder()
  .setEmbodiment({
    agent_type: "robot_arm",
    platform_id: "aloha_v2",
    workspace_scope: "zone_A",
  })
  .setActionScope({
    permitted_actions: ["pick", "place", "move"],
    excluded_zones: ["human_zone"],
    max_force_n: 45,
    max_velocity_ms: 0.5,
  })
  .setIrreversibility({
    max_class: IrreversibilityClass.REVERSIBLE_WITH_EFFORT,
    class2_requires_confirmation: true,
    class3_prohibited: true,
  })
  .setPolicyAttestation({
    policy_hash: "sha256-of-weights",
    training_run_id: "run-1",
    sim_validated: true,
  })
  .setDelegationScope({
    allow_fleet_delegation: false,
    max_delegation_depth: 1,
    sub_agent_whitelist: [],
  })
  .build();

const signedEdt = await signEdt(edt, privateKey, "robot-key-v1");
const guard = new PreExecutionGuard();

const decision = await guard.authorize(
  {
    description: "pick box from left bin",
    force_n: 5,
    velocity_ms: 0.2,
  },
  signedEdt,
  publicKey,
);

console.log(decision.approved);

For Python, install hdp-physical and use the same EDT model and guard flow, with optional lerobot and gemma extras for adapters and interception.

→ Full TypeScript physical AI docs → Full Python physical AI docs

Grok / xAI Integration

hdp-grok attaches HDP to any Grok conversation via three native tool schemas. No changes to your prompts or model configuration are required — Grok calls hdp_issue_token, hdp_extend_chain, and hdp_verify_token as regular tool calls, and HdpMiddleware handles everything statelessly behind the scenes.

import json
import os
from openai import OpenAI
from hdp_grok import HdpMiddleware, get_hdp_tools

# xAI API — OpenAI-compatible endpoint
client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

# One middleware instance per conversation
middleware = HdpMiddleware(
    signing_key=os.getenv("HDP_SIGNING_KEY"),  # base64url Ed25519 private key
    principal_id="user@example.com",
)

messages = [{"role": "user", "content": "Issue an HDP token and delegate to research-agent."}]

while True:
    response = client.chat.completions.create(
        model="grok-3",
        messages=messages,
        tools=get_hdp_tools(),  # inject the three HDP tool schemas
    )
    choice = response.choices[0]

    if choice.finish_reason == "tool_calls":
        messages.append(choice.message)
        for tc in choice.message.tool_calls:
            result = middleware.handle_tool_call(
                name=tc.function.name,
                args=json.loads(tc.function.arguments),
            )
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": json.dumps(result),
            })
    else:
        print(choice.message.content)
        break

# Full delegation chain — verifiable offline with the public key
print(middleware)  # HdpMiddleware(session_id='...', hops=2, valid=True)

Three HDP tools Grok can call

Tool	Required args	What it does
`hdp_issue_token`	—	Signs a root token for the session and principal
`hdp_extend_chain`	`delegatee_id`	Appends a signed delegation hop (e.g. to a sub-agent)
`hdp_verify_token`	`token`	Verifies the full chain using the middleware's public key

What `HdpMiddleware` manages for you

Holds the Ed25519 signing key (bytes, hex, base64url, or HDP_SIGNING_KEY env var)
Maintains the current token and hop counter for the conversation lifetime
Routes all hdp_* tool calls via handle_tool_call(name, args)
Handles both snake_case and camelCase argument names from Grok
Raises typed errors: HdpTokenMissingError, HdpTokenExpiredError, HdpSigningKeyError

→ Full Grok integration docs

CrewAI Integration

hdp-crewai attaches HDP to any CrewAI crew with a single middleware.configure(crew) call. No changes to your agents, tasks, or crew configuration are required.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from crewai import Agent, Crew, Task
from hdp_crewai import HdpMiddleware, HdpPrincipal, ScopePolicy, verify_chain

private_key = Ed25519PrivateKey.generate()

middleware = HdpMiddleware(
    signing_key=private_key.private_bytes_raw(),
    session_id="q1-review-2026",
    principal=HdpPrincipal(id="analyst@company.com", id_type="email"),
    scope=ScopePolicy(
        intent="Analyse Q1 sales data and produce a summary",
        authorized_tools=["FileReadTool", "CSVAnalysisTool"],
        max_hops=5,
    ),
)

crew = Crew(agents=[...], tasks=[...])
middleware.configure(crew)  # attach HDP — one line, zero crew changes
crew.kickoff()

# Verify the full delegation chain offline
result = verify_chain(middleware.export_token(), private_key.public_key())
print(result.valid, result.hop_count, result.violations)

#	Consideration	Behaviour
1	Scope enforcement	`step_callback` checks every tool call against `authorized_tools`. `strict=True` raises `HDPScopeViolationError`; default logs and records in the audit trail.
2	Delegation depth	`max_hops` is enforced per run; hops beyond the limit are skipped and warned.
3	Token size / perf	Ed25519 = 64 bytes/hop. All operations are non-blocking — failures log, never halt the crew.
4	Verification	`verify_chain(token, public_key)` validates root + every hop offline.
5	Memory integration	Signed token is persisted to CrewAI's storage directory for retroactive auditing.

→ Full CrewAI integration docs

AutoGen Integration

hdp-autogen attaches HDP to any AutoGen ConversableAgent or GroupChatManager with a single middleware.configure(target) call. Each speaker turn in a GroupChat is recorded as a delegation hop.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from autogen import ConversableAgent, GroupChat, GroupChatManager
from hdp_autogen import HdpMiddleware, HdpPrincipal, ScopePolicy, verify_chain

private_key = Ed25519PrivateKey.generate()

middleware = HdpMiddleware(
    signing_key=private_key.private_bytes_raw(),
    session_id="research-2026-q1",
    principal=HdpPrincipal(id="researcher@lab.edu", id_type="email"),
    scope=ScopePolicy(
        intent="Coordinate research agents to summarise recent papers",
        authorized_tools=["web_search", "file_reader"],
        max_hops=10,
    ),
)

researcher = ConversableAgent("researcher", ...)
reviewer = ConversableAgent("reviewer", ...)
groupchat = GroupChat(agents=[researcher, reviewer], messages=[])
manager = GroupChatManager(groupchat=groupchat, ...)

middleware.configure(manager)  # hooks all agents + wraps run_chat
manager.run_chat(messages=[{"role": "user", "content": "Summarise recent LLM papers"}])

# Verify the full delegation chain offline
result = verify_chain(middleware.export_token(), private_key.public_key())
print(result.valid, result.hop_count, result.violations)

#	Consideration	Behaviour
1	Scope enforcement	Incoming messages are inspected for tool calls against `authorized_tools`. `strict=True` raises `HDPScopeViolationError`; default logs and records in the audit trail.
2	Delegation depth	`max_hops` is enforced per conversation; hops beyond the limit are skipped and warned.
3	Token size / perf	Ed25519 = 64 bytes/hop. All operations are non-blocking — failures log, never halt agents.
4	Verification	`verify_chain(token, public_key)` validates root + every hop offline.
5	GroupChat integration	`configure()` detects `ConversableAgent` vs `GroupChatManager` and attaches the appropriate hooks automatically.

→ Full AutoGen integration docs

Microsoft agent-framework Integration

hdp-agent-framework attaches HDP to any Microsoft agent-framework Agent via the native ChatMiddleware and function middleware protocols. A single middleware.configure(agent) call appends both middlewares to agent.middleware — no other changes required.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
from hdp_agent_framework import HdpMiddleware, HdpPrincipal, ScopePolicy, verify_chain

private_key = Ed25519PrivateKey.generate()

middleware = HdpMiddleware(
    signing_key=private_key.private_bytes_raw(),
    session_id="analysis-2026",
    principal=HdpPrincipal(id="analyst@corp.com", id_type="email"),
    scope=ScopePolicy(
        intent="Analyse Q1 sales data and generate a summary",
        authorized_tools=["fetch_data", "write_report"],
        max_hops=5,
    ),
)

agent = Agent(client=FoundryChatClient(credential=AzureCliCredential()), name="sales_analyst", tools=[...])
middleware.configure(agent)   # attaches chat + function middleware — one line
await agent.run("Analyse Q1 EMEA sales and write a summary.")

result = verify_chain(middleware.export_token(), private_key.public_key())
print(result.valid, result.hop_count)

#	Consideration	Behaviour
1	Scope enforcement	Tool calls are inspected against `authorized_tools`. `strict=True` raises `HDPScopeViolationError`; default logs and records in the audit trail.
2	Delegation depth	`max_hops` is enforced; hops beyond the limit are skipped and logged.
3	Token size / perf	Ed25519 = 64 bytes/hop. All operations are non-blocking — failures log, never halt agents.
4	Verification	`verify_chain(token, public_key)` validates root + every hop offline.
5	Agent integration	`configure()` appends `HdpMiddleware` and `_function_middleware` to `agent.middleware` — idempotent, duck-typed, no hard dependency on agent-framework internals.

→ Full agent-framework integration docs

LlamaIndex Integration

llama-index-callbacks-hdp covers all three LlamaIndex hook points. Use whichever layer fits your pipeline — they share the same ContextVar-backed session so all three can be active simultaneously.

Option 1 — Instrumentation dispatcher (recommended, LlamaIndex ≥0.10.20)

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from llama_index.callbacks.hdp import HdpInstrumentationHandler, HdpPrincipal, ScopePolicy, verify_chain

private_key = Ed25519PrivateKey.generate()

HdpInstrumentationHandler.init(
    signing_key=private_key.private_bytes_raw(),
    principal=HdpPrincipal(id="alice@corp.com", id_type="email"),
    scope=ScopePolicy(
        intent="Research RAG pipeline",
        authorized_tools=["web_search", "retriever"],
        max_hops=10,
    ),
    on_token_ready=lambda token: print(token["header"]["token_id"]),
)
# All subsequent LlamaIndex queries are now covered — no further changes required

Option 2 — Legacy CallbackManager

from llama_index.callbacks.hdp import HdpCallbackHandler, HdpPrincipal, ScopePolicy
from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager

handler = HdpCallbackHandler(
    signing_key=private_key.private_bytes_raw(),
    principal=HdpPrincipal(id="alice@corp.com", id_type="email"),
    scope=ScopePolicy(intent="Research pipeline"),
)
Settings.callback_manager = CallbackManager([handler])

Option 3 — Node postprocessor (RAG retrieval enforcement)

from llama_index.callbacks.hdp import HdpNodePostprocessor

postprocessor = HdpNodePostprocessor(
    signing_key=private_key.private_bytes_raw(),
    strict=False,
    check_data_classification=True,
)
query_engine = index.as_query_engine(node_postprocessors=[postprocessor])

Verifying the chain

from llama_index.callbacks.hdp import verify_chain

result = verify_chain(token_dict, private_key.public_key())
print(result.valid, result.hop_count, result.violations)

#	Consideration	Behaviour
1	Hook coverage	Instrumentation dispatcher captures `QueryStartEvent`, `AgentToolCallEvent`, `LLMChatStartEvent`, `QueryEndEvent`. Callback handler covers legacy `FUNCTION_CALL` and `LLM` events.
2	Shared session	All three layers read/write the same `ContextVar` — a token issued by the instrumentation handler is visible to the node postprocessor in the same asyncio task.
3	Scope enforcement	`strict=True` raises `HDPScopeViolationError` on out-of-scope tool calls; default logs and records in the audit trail.
4	Data classification	Postprocessor checks token `data_classification` against a 4-level hierarchy: `public < internal < confidential < restricted`.
5	Observability overlap	HDP complements Arize Phoenix and Langfuse — they observe runtime activity; HDP authenticates the issuer's delegation record and signed chain entries.

→ Full LlamaIndex integration docs

Key Management

HDP ships a KeyRegistry for kid → publicKey resolution and a well-known endpoint format for automated key distribution.

import { KeyRegistry, generateKeyPair, exportPublicKey } from "@helixar_ai/hdp";

const registry = new KeyRegistry();

const { privateKey, publicKey } = await generateKeyPair();
registry.register("signing-key-v1", publicKey);

// Resolve a key before verification
const key = registry.resolve(token.signature.kid); // Uint8Array | null

// Rotate: revoke old, register new
registry.revoke("signing-key-v1");
registry.register("signing-key-v2", newPublicKey);

// Export for /.well-known/hdp-keys.json
const doc = registry.exportWellKnown();
// → { keys: [{ kid, alg: 'Ed25519', pub: '<base64url>' }] }

Environment	Recommended storage
Development	In-memory `KeyRegistry`, keys generated per-process
Staging	Environment variables via secrets manager
Production	HSM or cloud KMS (AWS KMS, GCP Cloud HSM, Azure Key Vault)
Edge / serverless	Pre-distributed public keys; private key in secure enclave

Key rotation: Issue new tokens with a new kid while keeping the old key in the verifier registry until all tokens signed with it have expired.

Offline Verification

HDP verification requires zero network calls. The complete trust state is:

The issuer's Ed25519 public key (32 bytes)
The current session_id (string)
The current time (for expiry check)
The verifier's local set of revoked token_id values

import { verifyToken } from "@helixar_ai/hdp";

// Works in air-gapped environments, edge runtimes, or any context
// where a network call before every agent action is unacceptable.
const result = await verifyToken(token, {
  publicKey, // locally held — no fetch
  currentSessionId: "sess-20260326-abc", // locally known — no registry
  revokedTokenIds: localRevokedTokenIds, // ReadonlySet<string> or local callback
  expectedPresenterAgentId: "tool-executor-v1", // when transport authenticates the caller
});

This is architecturally enforced: the verification pipeline has no required I/O operations. It is proven by the test suite (tests/security/offline-verification.test.ts), which verifies a full chain using only local inputs.

Historical audit

import { auditToken, computeTokenDigest } from "@helixar_ai/hdp";

const report = await auditToken(archivedToken, {
  publicKey: archivedIssuerKey,
  evidence: {
    authenticated: true,
    tokenDigest: computeTokenDigest(archivedToken),
    sessionId: archivedToken.header.session_id,
    verifierId: "payments-gateway-1",
    evaluatedAt: receipt.evaluatedAt,
    decision: receipt.decision,
    revoked: receipt.revoked,
    policyAccepted: receipt.policyAccepted,
  },
});

// Reported independently:
// report.recordIntegrity.status
// report.currentAcceptance.status
// report.historicalAcceptance.status

Immutable token references

import {
  InMemoryTokenStore,
  storeToken,
  storeTokenByReference,
  resolveToken,
} from "@helixar_ai/hdp";

const store = new InMemoryTokenStore();
const tokenIdRef = await storeToken(store, token); // immutable first snapshot
const digestRef = await storeTokenByReference(store, extendedToken); // sha256:...
const snapshot = await resolveToken(store, digestRef); // digest checked on resolution

UUID and digest references are write-once snapshots. Extending a token preserves its token_id, so later chain states must use a new content-addressed reference instead of overwriting the UUID mapping.

Streaming Sessions & Re-Authorization

Long-running tasks may exhaust max_hops, expand their scope, or require fresh human confirmation mid-session. Issue a re-authorization token rather than modifying the original.

import { issueReAuthToken } from "@helixar_ai/hdp";

const reAuth = await issueReAuthToken({
  original: exhaustedToken,
  scope: {
    ...exhaustedToken.scope,
    intent: "Continue analysis: generate charts from extracted data.",
    max_hops: 3,
  },
  signingKey: privateKey,
  keyId: "signing-key-v1",
});
// reAuth.header.parent_token_id === exhaustedToken.header.token_id

Session type	Recommended `expiresInMs`
Short interactive task	15–60 minutes
Background batch job	4–8 hours
SDK fallback (set explicitly in production)	24 hours
High-risk / elevated scope	5–15 minutes

Multi-Principal Delegation

For actions requiring joint authorization by multiple humans, chain tokens sequentially — each human issues a token pointing to the previous one.

import { issueToken, issueReAuthToken, verifyPrincipalChain } from '@helixar_ai/hdp'

const t1 = await issueToken({ /* Alice authorizes */ signingKey: alicePrivateKey, keyId: 'alice-key', ... })
const t2 = await issueReAuthToken({ original: t1, /* Bob co-authorizes */ signingKey: bobPrivateKey, keyId: 'bob-key', ... })

const result = await verifyPrincipalChain(
  [{ token: t1, publicKey: alicePublicKey }, { token: t2, publicKey: bobPublicKey }],
  {
    currentSessionId: 'sess-joint-approval',
    relationshipContext: { type: 'joint_authorization', authenticated: true },
  }
)
// result.valid === true, result.relationship === 'joint_authorization'

HDP v0.2 preview — CoAuthorizationRequest: Simultaneous multi-signature using a threshold scheme (FROST / Schnorr multisig) is planned for v0.2.

Privacy Utilities

import { stripPrincipal, redactPii, buildAuditSafe } from "@helixar_ai/hdp";

const safeForTransmission = stripPrincipal(token); // remove all principal PII
const anonymized = redactPii(token); // principal.id → '[REDACTED]'
const auditEntry = buildAuditSafe(token); // token_id + intent + chain summary

Verification Pipeline

verifyToken() runs the live-acceptance pipeline defined by HDP:

Input and version checks, including header.version === hdp
Lifecycle: issued_at <= now < expires_at and local revocation by token_id
Root signature (Ed25519 over the canonical unsigned token as it existed at issuance, with an empty chain)
Hop structure and signatures, including sequence, parent links, and nondecreasing timestamps
max_hops constraint — the issuer chooses this value; HDP defines no fixed or maximum number of hops, and omitting it leaves chain length unbounded
Session ID binding (cross-session replay defense)
Optional application checks, such as Proof of Humanity and presenter identity

Live acceptance is separate from historical audit. An expired or revoked token may still have valid record integrity, while evidence of historical acceptance can remain indeterminate. See audit semantics.

Why Not IPP?

The Intent Provenance Protocol (draft-haberkamp-ipp-01) solves the same problem with different trade-offs. The critical difference: IPP requires agents to poll a central revocation registry every 5 seconds. If the registry is unreachable, agents cannot safely act. Every IPP token is also cryptographically anchored to ipp.khsovereign.com/keys/founding_public.pem — making fully self-sovereign deployment impossible.

HDP verification is fully offline. It requires a trusted issuer public key, session context, current time, and verifier-local revocation state. No central registry, central endpoint, or third-party trust anchor is required at verification time.

→ Full technical comparison: COMPARISON.md

Scope Boundary

HDP stops at provenance. It does not enforce.

HDP records an issuer's statement about human delegation context and the activity the issuer subsequently recorded. It does not:

Prevent an agent from exceeding its declared scope at runtime
Enforce authorized_tools or data_classification constraints at the model layer
Decide who may revoke or distribute revocation instructions
Provide a central authority
Prove that an action occurred or that a named delegate consented
Prove that the supplied chain is the only or final branch

Applications that need runtime enforcement should treat HDP tokens as audit input and implement enforcement at the application layer.

Security

HDP v0.1 has been audited against spec §12's 10 threat scenarios. See docs/security/audit-report-v0.1.md.

Test coverage includes: token forgery, chain tampering, prompt injection, seq gap / chain poisoning, replay attack (session + expiry), and offline verification guarantee.

Releasing

This monorepo uses five independent tag prefixes to release packages separately.

TypeScript core packages → npm

Publishes @helixar_ai/hdp, @helixar_ai/hdp-mcp, and hdp-validate CLI:

git tag v0.1.2 && git push origin v0.1.2

Pipeline: test-node → vet-node (ReleaseGuard) → publish-hdp + publish-hdp-mcp + publish-hdp-cli + publish-hdp-autogen-ts

@helixar_ai/hdp-autogen → npm

Publishes only @helixar_ai/hdp-autogen (TypeScript AutoGen middleware):

git tag node/hdp-autogen/v0.1.2 && git push origin node/hdp-autogen/v0.1.2

Pipeline: test-hdp-autogen-ts → vet-hdp-autogen-ts (ReleaseGuard) → publish-hdp-autogen-ts-standalone

hdp-crewai → PyPI

git tag python/v0.1.1 && git push origin python/v0.1.1

Pipeline: test-python → vet-hdp-crewai (ReleaseGuard) → publish-hdp-crewai

hdp-grok → PyPI

git tag python/hdp-grok/v0.1.1 && git push origin python/hdp-grok/v0.1.1

Pipeline: test-hdp-grok → vet-hdp-grok (ReleaseGuard) → publish-hdp-grok

hdp-autogen → PyPI

git tag python/hdp-autogen/v0.1.2 && git push origin python/hdp-autogen/v0.1.2

Pipeline: test-hdp-autogen → vet-hdp-autogen (ReleaseGuard) → publish-hdp-autogen

hdp-agent-framework → PyPI

git tag python/hdp-agent-framework/v0.1.0 && git push origin python/hdp-agent-framework/v0.1.0

Pipeline: test-hdp-agent-framework → vet-hdp-agent-framework (ReleaseGuard) → publish-hdp-agent-framework

hdp-langchain → PyPI

git tag python/hdp-langchain/v0.1.1 && git push origin python/hdp-langchain/v0.1.1

Pipeline: test-hdp-langchain → vet-hdp-langchain (ReleaseGuard) → publish-hdp-langchain

llama-index-callbacks-hdp → PyPI

git tag python/llama-index-callbacks-hdp/v0.1.1 && git push origin python/llama-index-callbacks-hdp/v0.1.1

Pipeline: test-llama-index-callbacks-hdp → vet-llama-index-callbacks-hdp (ReleaseGuard) → publish-llama-index-callbacks-hdp

hdp-llamaindex → PyPI

git tag python/hdp-llamaindex/v0.1.1 && git push origin python/hdp-llamaindex/v0.1.1

Pipeline: test-hdp-llamaindex → vet-hdp-llamaindex (ReleaseGuard) → publish-hdp-llamaindex

Artifact vetting — ReleaseGuard

Every artifact is scanned by ReleaseGuard before it reaches PyPI or npm — checking for secrets, unexpected files, license compliance, and generating a CycloneDX SBOM. The exact vetted artifact is what gets published. If ReleaseGuard fails, the publish job never runs.

# Vet locally before tagging
cd packages/hdp-grok && python -m build && releaseguard check ./dist
cd packages/hdp-crewai && python -m build && releaseguard check ./dist
cd packages/hdp-autogen && python -m build && releaseguard check ./dist
cd packages/hdp-agent-framework && python -m build && releaseguard check ./dist
cd packages/hdp-langchain && python -m build && releaseguard check ./dist
cd packages/llama-index-callbacks-hdp && python -m build && releaseguard check ./dist
cd packages/hdp-autogen-ts && npm run build && releaseguard check ./dist

Spec

Full protocol specification: https://helixar.ai/about/labs/hdp/

Citation

If you use HDP in your research, please cite:

@misc{dalugoda2026hdp,
  title        = {{HDP}: A Lightweight Cryptographic Protocol for Human Delegation
                  Provenance in Agentic {AI} Systems},
  author       = {Dalugoda, Asiri},
  year         = {2026},
  month        = apr,
  eprint       = {2604.04522},
  archivePrefix = {arXiv},
  primaryClass = {cs.CR},
  url          = {https://arxiv.org/abs/2604.04522},
}

License

Apache License 2.0 — Helixar Limited

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apps/hdp-physical-hf		apps/hdp-physical-hf
docs		docs
packages		packages
src		src
tests		tests
.gitignore		.gitignore
.releaseguard.yml		.releaseguard.yml
COMPARISON.md		COMPARISON.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

HDP — Human Delegation Provenance Protocol

What is HDP?

Packages

Install

Quickstart — TypeScript

Physical AI Integration

Grok / xAI Integration

Three HDP tools Grok can call

What HdpMiddleware manages for you

CrewAI Integration

AutoGen Integration

Microsoft agent-framework Integration

LlamaIndex Integration

Option 1 — Instrumentation dispatcher (recommended, LlamaIndex ≥0.10.20)

Option 2 — Legacy CallbackManager

Option 3 — Node postprocessor (RAG retrieval enforcement)

Verifying the chain

Key Management

Offline Verification

Historical audit

Immutable token references

Streaming Sessions & Re-Authorization

Multi-Principal Delegation

Privacy Utilities

Verification Pipeline

Why Not IPP?

Scope Boundary

Security

Releasing

TypeScript core packages → npm

@helixar_ai/hdp-autogen → npm

hdp-crewai → PyPI

hdp-grok → PyPI

hdp-autogen → PyPI

hdp-agent-framework → PyPI

hdp-langchain → PyPI

llama-index-callbacks-hdp → PyPI

hdp-llamaindex → PyPI

Artifact vetting — ReleaseGuard

Spec

Citation

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

What `HdpMiddleware` manages for you