KiLu Integration Docs

kilu-sdk is the public TypeScript integration layer for submitting intents to KiLu, receiving authorization decisions, and verifying execution receipts.

KiLu is an authority layer — it sits between what an agent proposes and what a system is allowed to execute. The SDK is the bridge between those two worlds.

Installation

npm install @kilu/sdk
# or
bun add @kilu/sdk

Requires Node.js 18+ or Bun 1+. The package ships ESM and CJS builds.

Quick Start

The minimal integration: create a client, set your identity token, submit an intent, inspect the decision.

import { KiluClient, verifyReceipt } from "@kilu/sdk";

// v0.1 identity model: opaque bearer token
// See: https://kilu.network for current access model
const client = new KiluClient({
  apiUrl: "https://authority.kilu.network"
});

client.setMoltIdentity(process.env.KILU_IDENTITY_TOKEN);

const result = await client.submitIntent({
  action: "fetch",
  target: "https://example.com",
});

switch (result.decision) {
  case "ALLOW":
    // Authority approved — verify receipt before proceeding
    await verifyReceipt(result.receipt, authorityPublicKey);
    break;
  case "DENY":
    // Policy blocked — do not proceed
    break;
  case "HUMAN_APPROVAL_REQUIRED":
    // Pause and wait for explicit human approval
    break;
}

Decision Model

KiLu separates intent from authority. An agent may propose an action, but KiLu returns one of three explicit decision classes:

This model ensures that cognition and execution authority remain separate concerns. The SDK does not execute actions — it submits requests and surfaces decisions.

Receipt Verification

On ALLOW, KiLu returns a cryptographically signed execution receipt. Verifying receipts is how you confirm that an action was actually authorized — not just approved in memory.

Receipt structure (illustrative)

{
  "decision": "ALLOW",
  "receipt": {
    "intent_hash": "sha256:a1b2c3d4...",
    "signature":   "ed25519:390a...82f1",
    "runtime_id":  "rt_b3d6...",
    "version":     "0.1.0",
    "timestamp":   1774280000,
    "tamper_evident": true
  }
}

Verify signature only

import { verifyReceipt } from "@kilu/sdk";

// Returns true if signature is valid
const valid = await verifyReceipt(result.receipt, authorityPublicKey);

Verify signature + intent hash match

import { verifyReceiptForIntent } from "@kilu/sdk";

// Verifies signature AND confirms receipt hash matches the original intent
// Stronger guarantee — use this when you can provide the original intent payload
const result = await verifyReceiptForIntent(intent, receipt, authorityPublicKey);

Scope & Limits

Using @kilu/sdk does not by itself constrain an agent that still has unrestricted access to shell, browser, network, or file system.

The SDK is effective when the execution path is actually routed through KiLu-controlled authority and runtime boundaries. An agent that calls submitIntent() but then executes independently of the decision is not meaningfully constrained.

• Current runtime wedge: Android Hub — validated, not positioned as final production runtime
• Production direction: Linux/gateway runtimes — broader execution environments
• Authority device: Android Approver (Ed25519, biometric, non-exportable keys)

API — KiluClient

const client = new KiluClient({
  apiUrl:    string,    // KiLu authority endpoint
  timeoutMs: number?   // default: 10000ms
});

API — submitIntent()

const result = await client.submitIntent(payload: Record<string, unknown>)

// Returns:
{
  decision: "ALLOW" | "DENY" | "HUMAN_APPROVAL_REQUIRED",
  receipt?: KiluReceipt  // present on ALLOW
}

The payload can be any JSON-serializable object describing the intended action. KiLu evaluates it against policy and returns a decision.

API — verifyReceipt() / verifyReceiptForIntent()

// Verify Ed25519 signature on receipt
verifyReceipt(
  receipt: KiluReceipt,
  publicKey: Uint8Array | string
): Promise<boolean>

// Verify signature + confirm receipt matches original intent
verifyReceiptForIntent(
  intent: Record<string, unknown>,
  receipt: KiluReceipt,
  publicKey: Uint8Array | string
): Promise<VerificationResult>

Ecosystem Map

KiLu is not a single repository — it is a split-trust architecture across multiple public components.

← kilu.network  ·  SDK on GitHub →