open-index/open-npm huggingface dataset:
npm package: @kraki/crypto
Description: E2E encryption library for Kraki — hybrid RSA-OAEP + AES-256-GCM
Latest version: 0.2.0

<p align="center">
  <a href="https://github.com/corelli18512/kraki">
    <img src="https://raw.githubusercontent.com/corelli18512/kraki/main/logo.png" alt="Kraki" width="140">
  </a>
</p>

<p align="center">
  <a href="https://github.com/corelli18512/kraki">GitHub repository</a>
</p>

# @kraki/crypto

End-to-end encryption helpers for Kraki.

> Preview: `@kraki/crypto` is still evolving with the rest of the protocol and device model.

This package provides the Node.js crypto primitives used by Kraki for multi-recipient message encryption, blob encoding, and challenge-response signing.

## Install

```bash
npm i @kraki/crypto
```

## What it includes

- RSA-OAEP 4096-bit key generation
- AES-256-GCM payload encryption
- per-recipient wrapped keys for multi-device delivery
- blob encoding: `base64(iv ‖ ciphertext ‖ tag)`
- blob-level encrypt/decrypt helpers
- compact public-key export/import helpers
- challenge signing and verification helpers

## Blob API

### `encryptToBlob(plaintext, recipients)` → `{ blob, keys }`

Encrypts a plaintext string for one or more recipients. Returns a single base64 blob (`iv ‖ ciphertext ‖ tag`) and a map of wrapped AES keys, one per recipient device.

### `decryptFromBlob({ blob, keys }, deviceId, privateKey)` → `plaintext`

Decrypts a blob using the calling device's private key. Looks up the wrapped key by `deviceId`, unwraps it with RSA-OAEP, and decrypts the blob.

### `payloadToBlob(payload)` → `blobPayload`

Converts a legacy separated payload (iv, ciphertext, tag, keys) into the consolidated blob format.

### `blobToPayload(blobPayload)` → `payload`

Converts a blob payload back into separated fields. Useful for interop or debugging.

## Blob format

The blob is a single base64 string encoding the concatenation of:

1. **IV** — 12 bytes (AES-256-GCM initialization vector)
2. **Ciphertext** — variable length
3. **Tag** — 16 bytes (GCM authentication tag)

This keeps the wire format compact — one string instead of three separate fields.

## Example

```ts
import { generateKeyPair, encryptToBlob, decryptFromBlob } from '@kraki/crypto';

const alice = generateKeyPair();

const { blob, keys } = encryptToBlob('hello from kraki', [
  { deviceId: 'alice', publicKey: alice.publicKey },
]);

const plaintext = decryptFromBlob({ blob, keys }, 'alice', alice.privateKey);
```

This package currently targets Node.js via the built-in `crypto` module.

## Links

- Main docs: `https://github.com/corelli18512/kraki/blob/main/README.md`
- Security model: `https://github.com/corelli18512/kraki/blob/main/SECURITY.md`
npm package: @kraki/head
Description: Kraki relay server — the brain that routes messages between tentacles and apps
Latest version: 0.9.1

<p align="center">
  <a href="https://github.com/corelli18512/kraki">
    <img src="https://raw.githubusercontent.com/corelli18512/kraki/main/logo.png" alt="Kraki" width="140">
  </a>
</p>

<p align="center">
  <a href="https://github.com/corelli18512/kraki">GitHub repository</a>
</p>

# @kraki/head

Thin encrypted relay that forwards messages between tentacles and apps.

> Preview: `@kraki/head` is still early-stage. Expect breaking changes while the hosted and self-hosted flows stabilize.

Use `@kraki/head` when you want to self-host the Kraki relay instead of using the hosted default.

## Install

Run it once with `npx`:

```bash
npx @kraki/head
```

Or install it globally:

```bash
npm i -g @kraki/head
kraki-relay
```

## Quick start

Start a local relay:

```bash
npx @kraki/head
```

By default the relay listens on `ws://localhost:4000` and stores user/device data in `kraki-head.db`.

Enable GitHub login for the web app:

```bash
GITHUB_CLIENT_ID=your_client_id \
GITHUB_CLIENT_SECRET=your_client_secret \
npx @kraki/head --auth github
```

## What the relay does

The relay has three jobs:

1. **Authenticate** — verify device identity on connect
2. **Forward blobs** — route unicast and broadcast envelopes to the right WebSocket connections
3. **Track identity** — maintain users and devices tables

It stores no messages, no sessions, and no content. All message bodies are encrypted blobs that the relay cannot read.

## Useful options

```bash
kraki-relay --port 8080
kraki-relay --db /path/to/kraki-head.db
kraki-relay --auth open
kraki-relay --auth github
kraki-relay --log debug
```

## Auth methods

The relay supports multiple authentication methods as a discriminated union: `github_token`, `github_oauth`, `pairing`, `challenge`, `apikey`, and `open`.

## Package naming

- `@kraki/head` installs the `kraki-relay` CLI
- `@kraki/tentacle` installs the `kraki` CLI

## Links

- Main docs: `https://github.com/corelli18512/kraki/blob/main/README.md`
- Security model: `https://github.com/corelli18512/kraki/blob/main/SECURITY.md`
npm package: @kraki/protocol
Description: Shared TypeScript types and message definitions for the Kraki protocol
Latest version: 0.9.1

<p align="center">
  <a href="https://github.com/corelli18512/kraki">
    <img src="https://raw.githubusercontent.com/corelli18512/kraki/main/logo.png" alt="Kraki" width="140">
  </a>
</p>

<p align="center">
  <a href="https://github.com/corelli18512/kraki">GitHub repository</a>
</p>

# @kraki/protocol

Shared TypeScript types and protocol contracts for Kraki.

> Preview: `@kraki/protocol` may still evolve as Kraki's message model and clients expand.

This package contains the shared envelope, message, device, and auth types used across the relay, tentacle, and receiver apps.

## Install

```bash
npm i @kraki/protocol
```

## What it includes

### Envelope types

- **UnicastEnvelope** — sent from an app to a specific tentacle. Contains a `to` field identifying the target device and a `blob` with the encrypted payload.
- **BroadcastEnvelope** — sent from a tentacle to all of a user's connected devices. Contains a `blob` and an optional `notify` hint.

### Inner message types (inside encrypted blob)

- **ProducerMessage** — messages from tentacle: session events, agent output, tool calls, permission requests.
- **ConsumerMessage** — messages from arm: approvals, answers, follow-up input.

These types are only visible after decryption. The relay never sees them.

### Control messages (unencrypted, relay-level)

- **auth** — device authentication (discriminated union: `github_token`, `github_oauth`, `pairing`, `challenge`, `apikey`, `open`)
- **device_joined** / **device_left** — presence notifications from the relay
- **ping** / **pong** — heartbeat

### Device and user models

- device registration, identity, and public key types
- user identity types

## Example

```ts
import type {
  UnicastEnvelope,
  BroadcastEnvelope,
  DeviceInfo,
  AuthMethod,
} from '@kraki/protocol';
```

This package is the schema layer only. It does not include a runtime client or server.

## Links

- Main docs: `https://github.com/corelli18512/kraki/blob/main/README.md`
- Architecture: `https://github.com/corelli18512/kraki/blob/main/ARCHITECTURE.md`
npm package: @kraki/tentacle
Description: Kraki agent bridge — the arm that connects your coding agent to the head
Latest version: 0.9.1

<p align="center">
  <a href="https://github.com/corelli18512/kraki">
    <img src="https://raw.githubusercontent.com/corelli18512/kraki/main/logo.png" alt="Kraki" width="140">
  </a>
</p>

<p align="center">
  <a href="https://github.com/corelli18512/kraki">GitHub repository</a>
</p>

# @kraki/tentacle

CLI bridge that connects your coding machine to Kraki.

> Preview: `@kraki/tentacle` is still early-stage. Expect breaking changes while the core flows stabilize.

`@kraki/tentacle` runs next to your coding agent, connects to a Kraki relay, and lets you watch and steer sessions from another browser or device.

Right now the main supported agent flow is GitHub Copilot CLI.

## Install

Run it once with `npx`:

```bash
npx @kraki/tentacle
```

Or install it globally:

```bash
npm i -g @kraki/tentacle
kraki
```

## Requirements

- GitHub Copilot CLI installed on the coding machine
- `gh auth login` completed
- A browser or phone to connect to the Kraki web app

## Quick start

1. Run `npx @kraki/tentacle` or `kraki`
2. Follow the setup prompts in the terminal
3. By default it connects to the hosted relay
4. Scan the QR code or open the web app to connect your browser or phone

The hosted web app lives at:

- `https://kraki.corelli.cloud`

## What tentacle handles

Beyond bridging agent events, tentacle is responsible for several things that used to live on the relay:

- **Sequence numbers and timestamps** — assigned locally by tentacle, not by the relay
- **Message buffering** — tentacle buffers messages and handles replay when devices reconnect
- **Session lifecycle** — session create, update, and close are managed here
- **Auto-approval** — tools on a local allowed list are approved automatically without user interaction
- **Encryption** — all outgoing messages are encrypted before leaving the machine

The relay is a thin forwarder. Tentacle and the frontend own the application logic.

## Useful commands

```bash
kraki          # start the tentacle / setup flow
kraki status   # show daemon + relay status
kraki connect  # generate a fresh QR code / pairing link
kraki stop     # stop the local daemon
```

## Use your own relay

Start a relay with `@kraki/head`:

```bash
npx @kraki/head

# or
npm i -g @kraki/head
kraki-relay
```

Then point tentacle setup at your own relay URL instead of the hosted default.

## Package naming

- `@kraki/tentacle` installs the `kraki` CLI
- `@kraki/head` installs the `kraki-relay` CLI

## Links

- Main docs: `https://github.com/corelli18512/kraki/blob/main/README.md`
- Security model: `https://github.com/corelli18512/kraki/blob/main/SECURITY.md`