@noxy-network/browser-sdk

Browser SDK for Noxy.

What is Noxy?

Noxy adds human-in-the-loop guardrails: encrypted prompts reach your product, the user acts on them, and your app sends decision outcomes back to the relay—plaintext prompts stay off the relay.

This package connects to the relay over WebSockets (wss://).

At a glance:

1. Identity + registration — Configure network.appSigningSecret from the dashboard (APP_SIGNING_SECRET). the SDK registers the device with an HMAC for your relay identity (see Relay identity types).
2. Prompts — Receive end-to-end encrypted payloads; decrypt locally and drive your UI.
3. Outcomes — Send DecisionOutcome to the relay as JSON on the WebSocket.

Before you integrate

Create your app at noxy.network. On the dashboard, copy APP_ID into network.appId and APP_SIGNING_SECRET into network.appSigningSecret (device registration HMAC). Agent backends use a separate app token, not these values.

Table of Contents

• What is Noxy?
• Before you integrate
• Features
• Relay identity types
• Installation
• Quick start
• Configuration
• API reference
• Usage guide
• Error handling
• Pre-validation
• Exports
• Security
• License

Features

• Human-in-the-loop — on() delivers decrypted prompts to your UI; when the user has decided, send an outcome with submitDecisionOutcome (see NoxyDecisionOutcomeValues).
• Relay identities — Supports wallet, email, phone, and user_id (details in Relay identity types).
• End-to-end encryption — Kyber (post-quantum) + AES-GCM for payloads.
• Relay — Single WebSocket URL; encrypted delivery to the browser.
• Encrypted local storage — IndexedDB + AES-GCM; SDK can generate and persist the storage key.

Relay identity types

The relay identity_type values are wallet, email, phone, and user_id (wire strings). In TypeScript you typically use NOXY_IDENTITY_TYPE.WALLET through NOXY_IDENTITY_TYPE.USER_ID; for non-wallet kinds identityId is the logical id string.

Initializing identities in TypeScript

Wallet (EOA or SCW) — use type: "eoa" or "scw" plus address and signer. Optional identityType: NOXY_IDENTITY_TYPE.WALLET is accepted. Device registration uses network.appSigningSecret (HMAC); wallet signer remains part of the identity shape.

identity: {
  type: "eoa",
  address: "0x…",
  signer: async (data) => wallet.signMessage({ message: { raw: data } }),
}

Email / phone / user_id — set identityType to NOXY_IDENTITY_TYPE.EMAIL, PHONE, or USER_ID (relay string user_id) and identityId to the stable logical id string your app uses. Registration uses network.appSigningSecret for these kinds as well.

import { NOXY_IDENTITY_TYPE } from "@noxy-network/browser-sdk";

// Email (identityType "email" on the relay)
identity: {
  identityType: NOXY_IDENTITY_TYPE.EMAIL,
  identityId: "[email protected]",
},

// Phone (identityType "phone")
identity: {
  identityType: NOXY_IDENTITY_TYPE.PHONE,
  identityId: "+15551234567",
},

// Opaque user id (identityType "user_id")
identity: {
  identityType: NOXY_IDENTITY_TYPE.USER_ID,
  identityId: "internal-user-abc123",
},

Always pass network.appSigningSecret (APP_SIGNING_SECRET) alongside network.appId (APP_ID) (see Quick start).

Installation

npm install @noxy-network/browser-sdk

Requirements

• IndexedDB, WebSocket, and Web Crypto API
• ES modules (or a bundler)
• TypeScript types: dist/bundle.d.ts

Quick start

import {
  createNoxyClient,
  NoxyDecisionOutcomeValues,
  NOXY_IDENTITY_TYPE,
} from "@noxy-network/browser-sdk";

const noxy = await createNoxyClient({
  identity: {
    type: "scw",
    address: "0xabc…",
    signer: async (data) => wallet.signMessage({ message: { raw: data } }),
  },
  network: {
    relayNodesUrl: "wss://relay.noxy.network",
    appId: "your-app-id",
    appSigningSecret: "paste-app-signing-secret-here",
  },
});

await noxy.on(async (decisionId, decision) => {
  // Show UI; map the user’s decision to NoxyDecisionOutcomeValues when calling submitDecisionOutcome
  const outcome = await showConfirmDialog(decision);
  await noxy.submitDecisionOutcome({
    decisionId,
    outcome: outcome ? NoxyDecisionOutcomeValues.APPROVE : NoxyDecisionOutcomeValues.REJECT,
    receivedAt: Date.now(),
  });
});

Configuration

createNoxyClient({
  identity: {
    type: "eoa", // or "scw"; or use identityType email / phone / user_id as above
    address: "0x…",
    signer: async (data) => …,
    chainId: "…",
    publicKey: "…",
    publicKeyType: "secp256k1",
  },
  network: {
    relayNodesUrl: "wss://relay.noxy.network",
    appId: "your-app-id",
    appSigningSecret: "paste-app-signing-secret-here",
    maxRetries: 3,
    retryTimeoutMs: 5000,
  },
  storage: {
    encryptionKey: new Uint8Array(32),
    indexedDb: { dbName: "noxy-db", dbVersion: 1 },
  },
});

API reference

createNoxyClient(options)

Initializes identity → device → relay connection. Throws NoxyInitializationError on invalid options or failure.

Client

| Member | Description | |--------|-------------| | options | Configuration used to create the client | | address | Wallet address when identity is wallet-only | | logicalIdentityId | Stable logical id for every identity kind | | isDeviceActive | false if device revoked | | isRelayConnected | WebSocket open | | isNetworkReady | Authenticated and ready | | on(handler) | Decrypt prompt → invoke handler (show UI); does not send an outcome by itself | | submitDecisionOutcome(payload) | Send a DecisionOutcome for the user’s choice | | revokeDevice() | Revoke device (identity-bound signature) | | rotateKeys() | Rotate device keys on relay | | close() | Disconnect |

Usage guide

Default storage — Omit storage to use IndexedDB noxy-client-db, version 1, and an SDK-generated encryption key persisted in IndexedDB.

Custom encryption key — Pass encryptionKey (16/24/32 bytes) when you derive material from user input.

SCW — Use identity.type: "scw" and your SCW signing logic.

Error handling

Initialization errors include message, code, optional stage (init_identity | load_device | connect_network), and optional cause. Network and device methods may throw; wrap in try/catch as needed.

Pre-validation

import { createNoxyClient, NoxyClientOptionsSchema } from "@noxy-network/browser-sdk";

const result = NoxyClientOptionsSchema.safeParse(userInput);
if (!result.success) return;
await createNoxyClient(result.data);

Exports

| Export | Description | |--------|-------------| | createNoxyClient | Create client | | NOXY_IDENTITY_TYPE | Relay strings: wallet, email, phone, user_id | | logicalIdentityIdOf, relayIdentityTypeOf | Identity helpers | | NoxyClientOptions, identity types | Types | | NoxyIdentityTypeEnum | "eoa" / "scw" (wallet flavour only) | | NoxyDecisionOutcome, NoxyDecisionOutcomeValue | Decision outcome types | | NoxyDecisionOutcomeValues | APPROVE / REJECT constants | | NoxyClientOptionsSchema, etc. | Zod schemas |

Security

• Device registration — One-time HMAC (network.appSigningSecret) binds the device to the relay identity (RegisterDevice.signature).
• Payload encryption — Kyber KEM, HKDF, AES-GCM; relay sees ciphertext only.
• Identity keys — Not used to encrypt prompt payloads; device and post-quantum keys are.

License

MIT © Noxy Network