@ekka-ai/sdk

TypeScript SDK for the EKKA governance platform. Provides cryptographic consent, policy enforcement, and secure action execution for applications operating under EKKA's security model.

This SDK implements a dual-layer architecture: a sandboxed public API for application code, and a privileged host API for trusted runtime environments.

Security Model

EKKA SDK enforces strict separation between App Mode (sandboxed) and Host Mode (privileged).

App Mode — Public API

import { authorize, execute, EkkaError } from '@ekka-ai/sdk';

The public API is designed for application code running in constrained environments (web apps, sandboxed processes, third-party integrations). All operations are:

• Capability-gated by the host runtime
• Audited with correlation IDs
• Expressed as user intent, not infrastructure mechanics

App Mode applications interact with EKKA through intent-based abstractions (authorize, execute) that enforce policy at the transport layer.

Host Mode — Privileged API

Note: Host mode requires a trusted runtime environment. Importing @ekka-ai/sdk/host from a browser or sandboxed process will fail at module resolution.

import { createHostAdapter, HostAdapter } from '@ekka-ai/sdk/host';

The host API is exclusively for EKKA-owned runtimes (Tauri desktop app, Node.js backend services, CLI tools). Host Mode provides:

• Capability management and enforcement
• Audit logging
• Transport-level security controls

Host applications mediate all App Mode requests through the HostAdapter.

Usage

Authorization Flow (App Mode)

import { authorize, sign, execute, ed25519 } from '@ekka-ai/sdk';

// Generate ephemeral keypair
const keypair = await ed25519.generateKeypair();

// Step 1: Request authorization
const auth = await authorize(jwt, {
  tenant_id: 'tenant-001',
  key_id: 'my-key',
  action_id: 'transfer',
  resources: [{ type: 'account', id: 'acc-123' }],
  issued_at_iso_utc: new Date().toISOString(),
});

// Step 2: Sign the authorization payload
const signature = await sign(auth.payload, keypair.private_key_b64);

// Step 3: Execute the authorized action
const result = await execute({
  authorization_id: auth.authorization_id,
  signature_b64: signature,
  public_key_b64: keypair.public_key_b64,
  key_id: 'my-key',
});

Combined Flow

import { authorizeAndExecute, ed25519 } from '@ekka-ai/sdk';

const keypair = await ed25519.generateKeypair();

const result = await authorizeAndExecute({
  jwt,
  tenant_id: 'tenant-001',
  key_id: 'my-key',
  action_id: 'approve',
  resources: [],
  issued_at_iso_utc: new Date().toISOString(),
  public_key_b64: keypair.public_key_b64,
}, keypair.private_key_b64);

console.log(result.execution.execution_id);

Host Mode

import { createHostAdapter } from '@ekka-ai/sdk/host';

const adapter = createHostAdapter({
  appId: 'my-app',
  hostType: 'node',
  capabilities: {
    authorization: { grant: true, revoke: true },
    execution: { run: true, status: true },
    network: { allowedHosts: ['api.ekka.ai'] },
  },
});

// Host adapter mediates all privileged operations

Why EKKA Is Secure by Design

EKKA's security model is built on four foundational principles:

1. Intent-Based Authorization

Every action in EKKA begins with an explicit authorization request. Applications declare what they want to do and which resources they need access to. There is no implicit permission inheritance, no "god mode" tokens, and no hidden scopes.

User Intent → Authorization Request → Explicit Grant → Signed Execution

This ensures that every action is auditable, traceable, and revocable.

2. Cryptographic Signatures Per Action

Each authorized action requires a fresh cryptographic signature from the requesting party. This signature:

• Binds the action to a specific moment in time
• Cannot be reused for different actions
• Cannot be forged without the private key
• Is verified before any operation proceeds

Signatures are not stored credentials—they are single-use proofs of intent.

3. No Ambient Trust

EKKA does not rely on ambient authority. Being "logged in" does not grant implicit permission to perform sensitive operations. Every action must be:

• Explicitly requested
• Explicitly authorized
• Explicitly signed
• Explicitly executed

This eliminates entire classes of privilege escalation attacks.

4. Hard Security Boundaries

The Host Adapter acts as an uncircumventable security checkpoint. All App Mode requests must pass through this boundary, where:

• Capabilities are verified
• Audit logs are generated
• Policy is enforced
• Blast radius is contained

There is no way for application code to bypass the Host Adapter.

App Mode vs Host Mode (At a Glance)

| Aspect | App Mode | Host Mode | |--------|----------|-----------| | Trust Level | Untrusted | Trusted | | Environment | Web apps, sandboxed processes, third-party code | EKKA desktop app, backend services, CLI | | API Access | @ekka-ai/sdk (public) | @ekka-ai/sdk/host (privileged) | | Can authorize actions | ✓ Yes | ✓ Yes | | Can sign payloads | ✓ Yes | ✓ Yes | | Can execute actions | ✓ Yes (through Host) | ✓ Yes (directly) | | Can access infrastructure | ✗ No | ✓ Yes | | Can bypass capability checks | ✗ No | ✗ No | | Audit logging | Automatic | Automatic | | Blast radius if compromised | Limited to granted capabilities | Full host access |

Key insight: App Mode applications can only do what they've been explicitly authorized to do. Even if an app is fully compromised, the attacker cannot exceed the app's granted capabilities.

How It Works

App Mode Flow

┌─────────────────────────────────────────────────────────────────────┐
│                         APP MODE FLOW                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────┐    ┌───────────┐    ┌──────────┐    ┌─────────────┐  │
│   │   App   │───▶│ authorize │───▶│  User    │───▶│   execute   │  │
│   │         │    │   ( )     │    │  Signs   │    │     ( )     │  │
│   └─────────┘    └───────────┘    └──────────┘    └──────┬──────┘  │
│                                                          │         │
│                                                          ▼         │
│                     ┌────────────────────────────────────────┐     │
│                     │           HOST ADAPTER                 │     │
│                     │  ┌──────────────────────────────────┐  │     │
│                     │  │  • Verify capabilities           │  │     │
│                     │  │  • Enforce policy                │  │     │
│                     │  │  • Generate audit log            │  │     │
│                     │  │  • Route to EKKA                 │  │     │
│                     │  └──────────────────────────────────┘  │     │
│                     └────────────────────────────────────────┘     │
│                                       │                            │
│                                       ▼                            │
│                              ┌─────────────┐                       │
│                              │    EKKA     │                       │
│                              │  Platform   │                       │
│                              └─────────────┘                       │
│                                                                     │
│   ▸ App NEVER touches infrastructure directly                      │
│   ▸ User signature is REQUIRED for every action                    │
│   ▸ Host Adapter is the ONLY path to EKKA                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Host Mode Flow

┌─────────────────────────────────────────────────────────────────────┐
│                        HOST MODE FLOW                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────────┐                                                   │
│   │  Trusted    │                                                   │
│   │  Host App   │                                                   │
│   │  (Desktop,  │                                                   │
│   │   CLI,      │                                                   │
│   │   Service)  │                                                   │
│   └──────┬──────┘                                                   │
│          │                                                          │
│          ▼                                                          │
│   ┌────────────────────────────────────────────────────────────┐   │
│   │                    HOST ADAPTER                             │   │
│   │  ┌────────────────────────────────────────────────────┐    │   │
│   │  │  Capabilities Configuration:                        │    │   │
│   │  │  ┌────────────────┐  ┌────────────────────────┐    │    │   │
│   │  │  │ authorization: │  │ network:               │    │    │   │
│   │  │  │   grant: ✓     │  │   allowedHosts: [...]  │    │    │   │
│   │  │  │   revoke: ✓    │  │                        │    │    │   │
│   │  │  └────────────────┘  └────────────────────────┘    │    │   │
│   │  └────────────────────────────────────────────────────┘    │   │
│   └──────────────────────────┬─────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│                     ┌─────────────┐                                 │
│                     │    EKKA     │                                 │
│                     │  Platform   │                                 │
│                     └─────────────┘                                 │
│                                                                     │
│   ▸ Host has direct infrastructure access                          │
│   ▸ Capabilities STILL gate all operations                         │
│   ▸ Audit logging is STILL mandatory                               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Threat Model (Simplified)

What happens if an App Mode application is compromised?

| Threat | Mitigation | |--------|------------| | Attacker tries to execute unauthorized actions | Blocked. Every action requires explicit authorization. | | Attacker tries to reuse a previous signature | Blocked. Signatures are bound to specific actions and timestamps. | | Attacker tries to forge a signature | Blocked. Requires the private key, which is never transmitted. | | Attacker tries to escalate privileges | Blocked. Host Adapter enforces capability boundaries. | | Attacker tries to access infrastructure directly | Blocked. Infrastructure APIs are not exposed to App Mode. | | Attacker tries to impersonate another user | Blocked. Signatures are tied to cryptographic identity. |

Blast radius: A compromised App Mode application can only perform actions that:

1. It was already authorized to perform
2. The user explicitly signs
3. Fall within its granted capabilities

Why signatures prevent replay attacks

Each authorization is bound to:

• A specific action type
• Specific resources
• A specific timestamp
• A specific key identity

Replaying a signature for a different action, different resources, or at a later time will fail verification.

Why the Host Adapter prevents privilege escalation

The Host Adapter is not a passthrough—it is an enforcement point. Every request is:

1. Validated against the app's declared capabilities
2. Logged for audit purposes
3. Rejected if it exceeds granted permissions

There is no configuration option to disable these checks. The security boundary is architectural, not policy-based.

API Surface

Public Exports (@ekka-ai/sdk)

| Export | Purpose | |--------|---------| | authorize | Request authorization for an action | | sign | Sign an authorization payload | | execute | Execute an authorized action | | authorizeAndExecute | Combined authorize → sign → execute | | EkkaError | Typed error for EKKA operations | | createEkkaClient | Initialize SDK client | | AppModeTransport | Sandboxed transport for app code | | auth | Authentication utilities | | ed25519 | Cryptographic signing | | canonicalize | Deterministic JSON serialization |

Host Exports (@ekka-ai/sdk/host)

| Export | Purpose | |--------|---------| | createHostAdapter | Create capability-gated adapter | | HostAdapter | Capability enforcement boundary | | TauriTransport | Tauri IPC transport |

Node Utilities (@ekka-ai/sdk/node)

| Export | Purpose | |--------|---------| | loadScenarioPack | Load scenario definitions from filesystem |

Security Guarantees

• Export boundaries enforced: Only documented entry points are importable
• Capability gating: All operations validate against declared capabilities
• Trusted runtime required: @ekka-ai/sdk/host requires Node.js or Tauri
• No ambient authority: Every action requires explicit authorization and signature

Version

0.9.7

License

MIT