The local @silentauth/logos-lexicon package is a beta SDK for deterministic intent tokens. It compiles readable .logos vocabulary files, creates compact tokens, signs and verifies token envelopes, maps tool calls, and resolves only when context and required proof match.

Beta boundary

Use the SDK for local demos, signed-token experiments, and early developer feedback. Freeze vocabulary versions before production, keep signing secrets server-side, and use signed envelopes whenever tokens cross trust boundaries.

Installation

npm betabash

npm install @silentauth/logos-lexicon@beta

The local package is currently versioned as 0.9.0-beta.0. Keep the public npm release on the beta tag until the vocabulary and signing model are frozen.

Compile a Vocabulary

A .logos file defines the closed vocabulary: intent id, local name, risk level, allowed context, required params, required proofs, and the local handler to dispatch after verification.

compile and registertypescript

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

const { vocabulary } = compileLogos(`
  vocabulary silentauth.agent.v1

  intent CSIV_EXEC_001 agent.execute {
    risk: 4
    context: ai_agent_runtime
    params: agentId, toolName, actionHash
    proofs: human_approval, vinac_fm_level_3
    handler: agents.execute
  }
`);

const lexicon = new LogosLexicon();
lexicon.registerVocabulary(vocabulary);

Create and Sign a Token

Tokens carry no executable command. They bind vocabulary version, intent, context, params, and nonce. Signed envelopes add tamper evidence and expiry for trust-boundary crossing.

create and signtypescript

const token = lexicon.createToken({
  vocabularyVersion: 'silentauth.agent.v1',
  intent: 'agent.execute',
  context: 'ai_agent_runtime',
  params: {
    agentId: 'agent_local',
    toolName: 'deploy_service',
    actionHash: 'sha256:...'
  },
  nonce: 'fresh-nonce'
});

const signed = await lexicon.sign(token, {
  keyId: 'server-key-1',
  secret: process.env.LOGOS_HS256_SECRET!,
  expiresAt: new Date(Date.now() + 300_000).toISOString()
});

Verify and Resolve

Prefer verifyAndResolve() at execution boundaries. It verifies the signature, checks expiry, validates context and params, confirms required proof, then returns the local handler.

fail-closed execution boundarytypescript

const result = await lexicon.verifyAndResolve(signed, {
  secret: process.env.LOGOS_HS256_SECRET!,
  resolution: {
    context: 'ai_agent_runtime',
    satisfiedProofs: ['human_approval', 'vinac_fm_level_3']
  }
});

if (!result.ok) {
  throw new Error(`Logos denied: ${result.reason}`);
}

await handlers[result.resolved.handler](result.token.params);

Tool-Call Adapter

Map MCP, LangChain, or agent runtime tool names to Logos tokens before a tool executes. This keeps the agent from passing free-form instructions into privileged handlers.

map a tool calltypescript

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

const mapped = createToolCallToken(
  lexicon,
  { name: 'deploy_service', input: { service: 'api', environment: 'prod' } },
  [{
    toolName: 'deploy_service',
    vocabularyVersion: 'silentauth.infra.v1',
    intent: 'infra.deploy',
    context: 'ci_cd',
    paramMap: { service: 'service', environment: 'environment' }
  }],
  { context: 'ci_cd', satisfiedProofs: ['maintainer_approval'] },
  'fresh-nonce'
);

Runtime Schemas

The SDK exports lightweight validators for vocabularies, unsigned tokens, and signed envelopes. Use them before accepting external input.

shape validationtypescript

import {
  validateLogosTokenShape,
  validateSignedTokenShape,
  validateVocabularyShape
} from '@silentauth/logos-lexicon';

const vocabularyCheck = validateVocabularyShape(vocabularyJson);
const tokenCheck = validateLogosTokenShape(tokenJson);
const signedCheck = validateSignedTokenShape(signedEnvelopeJson);

CSIV Vocabulary

Reference for seed intent IDs, risk, and namespaces

Logic Library

How local handlers and constraints are registered