Logos LexiconSDK Developer Guide

SDK Developer Guide

The @silentauth/logos-lexicon SDK provides a zero-dependency TypeScript-first interface for integrating the Logos Lexicon semantic intent protocol into browser and Node.js environments.

Installation

npm / yarn / pnpm

npm install @silentauth/logos-lexicon

CDN (browser)

<script type="module">
  import { LogosLexicon } from 'https://cdn.silentauth.io/logos-lexicon/v1/index.esm.js';
</script>

Token Generator

Generate State-Frame tokens from Intent + Context + Parameters. Tokens are compact, versioned, and carry no executable instructions.

Token generation — basic

import { LogosLexicon } from '@silentauth/logos-lexicon';

const lexicon = new LogosLexicon({
  publicKey: 'pk_live_…',
  version:   '1.0.0',
});

const token = await lexicon.generate({
  intent:  'CSIV_EXEC_001',          // token ID from vocabulary
  context: {
    session_id: 'sess_abc123',
    agent_id:   'agent_gpt4o',
    timestamp:   Date.now(),
  },
  parameters: {
    action: 'read_customer_data',
    scope:  ['id', 'email'],
  },
});

console.log(token.id);          // 'CSIV_EXEC_001'
console.log(token.state_frame); // compact binary representation
console.log(token.version);     // '1.0.0'
console.log(token.expires_at);  // ISO timestamp

Token type definition

interface StateFrameToken {
  id:          string;           // CSIV token ID
  state_frame: Uint8Array;       // compact binary encoding
  version:     string;           // vocabulary version
  context:     Record<string, unknown>;
  parameters:  Record<string, unknown>;
  issued_at:   string;           // ISO timestamp
  expires_at:  string;           // ISO timestamp
  signature?:  string;           // RS256 signature (v1.0+)
}

Policy Evaluator

Evaluate tokens against the local logic library. Works entirely offline — no network request required.

Offline policy evaluation

import { evaluatePolicy } from '@silentauth/logos-lexicon';

// Synchronous — no network, no async
const decision = evaluatePolicy({
  token_id: 'CSIV_TXN_002',
  context:  {
    value_usd:     25000,
    dual_approved: false,
  },
});

// { allowed: false, reason: 'dual_approval_required', required_layer: 4 }

// With dual approval in context
const approved = evaluatePolicy({
  token_id: 'CSIV_TXN_002',
  context:  { value_usd: 25000, dual_approved: true },
});

// { allowed: true, action: 'authorize_high_value_txn', required_layer: 4 }

Policy decision type

interface PolicyDecision {
  allowed:        boolean;
  action?:        string;        // action label if allowed
  required_layer: number;        // 1–4
  risk_tier:      RiskTier;      // low | medium | high | critical
  reason?:        string;        // denial reason if not allowed
  execution_policy?: {
    max_uses:               number;
    rate_limit_per_hour:    number;
    approval_window_seconds?: number;
    dual_approval?:          boolean;
    quorum_required?:        number;
    value_limit_usd?:        number;
    change_window_required?: boolean;
    require_same_device?:    boolean;
  };
}

Vocabulary Client

Fetch and cache the active CSIV vocabulary from the SilentAuth API. Results are cached locally and refreshed on version change.

Vocabulary fetch and lookup

import { LogosLexicon } from '@silentauth/logos-lexicon';

const lexicon = new LogosLexicon({ publicKey: 'pk_live_…' });

// Fetch full vocabulary (cached after first call)
const vocab = await lexicon.vocabulary.fetch({ version: '1.0.0' });
console.log(vocab.count);    // 8
console.log(vocab.entries);  // VocabEntry[]

// Lookup single token
const entry = await lexicon.vocabulary.get('CSIV_EXEC_001');
console.log(entry.frequency_hz);  // 19000
console.log(entry.action.risk_tier);  // 'high'
console.log(entry.action.execution_policy);

Token Resolution (Server-Side)

Resolve a VINAC-FM certificate token to its authorized action. Called after the acoustic verification flow completes.

Resolve a certificate token

import { LogosLexicon } from '@silentauth/logos-lexicon';

const lexicon = new LogosLexicon({ publicKey: 'pk_live_…' });

const result = await lexicon.resolve({
  certificate_token: 'vinac_abc123…',
  token_id:          'CSIV_EXEC_001',
});

if (result.resolved) {
  const { action, token } = result;
  console.log(action.label);           // 'authorize_agent_action'
  console.log(action.namespace);       // 'agent.execution'
  console.log(action.execution_policy);

  // Token is now consumed — single-use
}

TypeScript Types

Full type exports

import type {
  StateFrameToken,
  PolicyDecision,
  VocabEntry,
  VocabEntryAction,
  VocabularyResponse,
  ResolveResult,
  RiskTier,           // 'low' | 'medium' | 'high' | 'critical'
  CsivTokenId,        // 'CSIV_AUTH_001' | 'CSIV_EXEC_001' | ...
  ActionNamespace,    // 'auth.identity' | 'agent.execution' | ...
  LogosLexiconConfig,
} from '@silentauth/logos-lexicon';

CSIV Vocabulary

Full reference for all v1.0 tokens

Policy Evaluation

How the policy evaluator works