JavaScript / TypeScript Implementation

The JS/TS implementation lives in the js-aihint/ directory. It provides a core protocol library, a CLI, and a trust scoring engine.

Requirements: Node.js 18+ (Node 20+ recommended)

Setup

From the cloned repository root, install the project's local dependencies and compile the TypeScript:

cd /path/to/aihint-standard

# Install local dependencies (ajv, commander, node-fetch, typescript)
npm install

# Compile TypeScript source to JavaScript
npm run build

This compiles js-aihint/src/ into js-aihint/dist/. Everything runs locally from the cloned repo — nothing is fetched from a remote package registry for AiHint itself.

CLI Usage

Protocol CLI

After building, run the protocol CLI with Node:

node js-aihint/dist/cli.js <command> [options]

Generate RSA keys

node js-aihint/dist/cli.js generate-keys \
  --out-private private_key.pem \
  --out-public public_key.pem

Sign a hint

node js-aihint/dist/cli.js sign \
  --input aihint.json \
  --private-key private_key.pem \
  --output aihint-signed.json

Verify a signature

node js-aihint/dist/cli.js verify \
  --input aihint.json \
  --public-key public_key.pem

The --public-key option accepts either a local file path or an HTTP(S) URL.

Validate against schema

node js-aihint/dist/cli.js validate \
  --input aihint.json
  --detailed

Scoring CLI

The scoring CLI is available as:

# Via npm script
npm run scoring -- score https://example.com

# Or directly
node js-aihint/dist/scoring/cli.js score https://example.com

After setup, the aihint-scoring binary is also available via npx locally:

npx aihint-scoring score https://example.com

Score a website

node js-aihint/dist/scoring/cli.js score https://example.com --verbose

Batch scoring

node js-aihint/dist/scoring/cli.js batch \
  --urls "https://example.com,https://another.com"

Or from a file (one URL per line):

node js-aihint/dist/scoring/cli.js batch --file urls.txt

Generate scoring config

node js-aihint/dist/scoring/cli.js config --output scoring-config.json

TypeScript API

Core functions

import { signHint, verifyHint, validateHint, generateKeys, canonicalize } from '../js-aihint/src/aihint';
import type { AiHint } from '../js-aihint/src/aihint';

// Create a hint object
const hint: AiHint = {
  version: '0.1',
  type: 'global',
  target: 'https://example.com',
  issuer: 'https://trust.example.org',
  score: 0.85,
  method: 'aihint-core-v1',
  issued_at: '2025-06-15T12:00:00Z',
  expires_at: '2026-06-15T12:00:00Z',
  public_key_url: 'https://example.com/.well-known/aihint-pubkey.pem',
};

// Generate RSA keys
generateKeys('private_key.pem', 'public_key.pem');

// Sign the hint (synchronous, returns a new object with signature field)
const signed = signHint(hint, 'private_key.pem');

// Validate against JSON Schema
const isValid = validateHint(signed);

// Verify signature (async — fetches public key if given a URL)
const isVerified = await verifyHint(signed, 'public_key.pem');
// or: await verifyHint(signed, 'https://example.com/.well-known/aihint-pubkey.pem');

Trust scoring

import { TrustScoringEngine } from '../js-aihint/src/scoring';
import type { ScoringConfig } from '../js-aihint/src/scoring';

const config: Partial<ScoringConfig> = {
  weights: {
    security: 0.4,
    reputation: 0.35,
    compliance: 0.25,
  },
};

const engine = new TrustScoringEngine(config);
const result = await engine.scoreWebsite('https://example.com');

console.log(`Score: ${result.finalScore}`);
console.log(`Trust level: ${result.trustLevel}`);
console.log(`Security: ${result.securityScore}`);
console.log(`Reputation: ${result.reputationScore}`);
console.log(`Compliance: ${result.complianceScore}`);

Exported API

Core (js-aihint/src/aihint.ts)

Export	Type	Description
AiHint	interface	The AiHint document shape
signHint(hint, privateKeyPath)	function	Sign a hint with RSA-SHA256
verifyHint(hint, publicKeyPathOrUrl)	async function	Verify a signature (file path or URL)
validateHint(hint, detailed?)	function	Validate against JSON Schema
generateKeys(outPrivate, outPublic)	function	Generate RSA 2048-bit key pair
canonicalize(obj)	function	Canonical JSON (sorted keys)

Scoring (js-aihint/src/scoring/)

Export	Type	Description
TrustScoringEngine	class	Main scoring engine
ScoringConfig	interface	Configuration (timeouts, API keys, weights)
ScoringResult	class	Scoring result with toJSON()
TrustLevel	enum	VERY_LOW, LOW, MODERATE, GOOD, HIGH
MetricResult	class	Individual metric result
MetricStatus	enum	INFO, SUCCESS, WARNING, ERROR

Scorer classes

All scorers implement async score(url: string): Promise<ScorerResult>:

Scorer	Real network checks	Status
SSLTLSValidator	TLS cert, expiry, version, HSTS	Functional
SecurityHeadersAnalyzer	CSP, X-Frame-Options, etc.	Functional
MalwareChecker	Heuristic domain/TLD checks	Heuristic only
DomainReputationChecker	—	Placeholder
DomainAgeAnalyzer	—	Placeholder
IncidentTracker	—	Placeholder
PrivacyPolicyAnalyzer	—	Placeholder
ContactValidator	—	Placeholder
ComplianceChecker	—	Placeholder

Required Node Packages

These third-party packages are declared in the root package.json and installed locally during setup:

Package	Purpose
ajv	JSON Schema validation
commander	CLI framework
node-fetch	HTTP fetching (public key URLs)
typescript	TypeScript compiler (dev)

The scoring engine uses the built-in Node.js fetch API (available in Node 18+) for HTTP checks.