@exellix/narrix-cni

Single source of truth for CNI v1.1 TypeScript types and JSON Schemas.

This package is intentionally boring: types + schemas only. No runtime logic, no nondeterminism.

Purpose

Provides the canonical definitions for:

• CNI v1.1 TypeScript types - Complete type definitions for CNI (Claim Normalization Interface) v1.1
• JSON Schema files - Validation schemas for use by adapters, scoper, detector, and engine packages

Installation

npm install @exellix/narrix-cni

Usage

TypeScript Types

import {
  CniV11,
  CniSubjectV11,
  CniContentItemV11,
  CniReferenceV11,
  EvidencePointerV11,
  CniMetaV11,
  CniSourceMetaV11,
  CniEntityV11,
  CniFactV11,
  CniSignalV11,
  CNI_SCHEMA_VERSION,
  EVIDENCE_POINTER_VERSION,
  CNI_SCHEMA_FILE_V11,
  EVIDENCE_POINTER_SCHEMA_FILE_V11,
} from "@exellix/narrix-cni";

Schema IDs (Single Source of Truth)

import {
  CNI_SCHEMA_ID_V11,
  EVIDENCE_POINTER_SCHEMA_ID_V11,
  CNI_META_SCHEMA_ID_V11,
  CNI_FACT_SCHEMA_ID_V11,
  CNI_SIGNAL_SCHEMA_ID_V11,
} from "@exellix/narrix-cni";

JSON Schemas

The package ships JSON Schema files under schema/:

• schema/cni.v1.1.schema.json - Main CNI v1.1 schema
• schema/evidence.pointer.v1.1.schema.json - Evidence pointer schema

These can be used with validators like AJV in other packages (adapters/scoper/engine).

Public API

Types

• CniV11 - The canonical CNI v1.1 object
• CniSubjectV11 - What this CNI is about
• CniContentItemV11 - Raw/normalized content attached to the subject
• CniReferenceV11 - Extracted atomic references (IPs, CVEs, etc.)
• EvidencePointerV11 - References to where claims came from
• CniMetaV11 - Metadata about origin, determinism settings, traceability
• CniSourceMetaV11 - Source metadata
• CniEntityV11 - Normalized entity objects (optional)
• CniFactV11 - Auditable, low-level statements
• CniSignalV11 - Alert-like outputs

Constants

• CNI_SCHEMA_VERSION - Schema version string ("cni.v1.1")
• EVIDENCE_POINTER_VERSION - Evidence pointer version string ("evidence.pointer.v1.1")
• CNI_SCHEMA_FILE_V11 - Schema file path ("schema/cni.v1.1.schema.json")
• EVIDENCE_POINTER_SCHEMA_FILE_V11 - Evidence pointer schema file path ("schema/evidence.pointer.v1.1.schema.json")

Schema IDs

• CNI_SCHEMA_ID_V11 - "cni.v1.1"
• EVIDENCE_POINTER_SCHEMA_ID_V11 - "evidence.pointer.v1.1"
• CNI_META_SCHEMA_ID_V11 - "cni.meta.v1.1"
• CNI_FACT_SCHEMA_ID_V11 - "cni.fact.v1.1"
• CNI_SIGNAL_SCHEMA_ID_V11 - "cni.signal.v1.1"

Design Principles

Strong Invariants

• No nondeterministic logic - No Date.now(), no environment reads
• No runtime dependencies - Zero runtime deps (no zod, no ajv, no crypto)
• No validation code - Validation belongs in adapters/scoper packages
• No hashing/normalization/chunking - These operations belong elsewhere
• Types + schemas only - Pure type definitions and JSON schemas

Single Source of Truth

All schema IDs are centralized in src/schema-ids.ts to ensure consistency across:

• TypeScript type definitions
• JSON Schema $id fields
• JSON Schema const values

Project Structure

narrix-cni/
  package.json
  tsconfig.json
  src/
    types.ts          # TypeScript type definitions
    schema-ids.ts    # Centralized schema ID constants
    index.ts         # Public API exports
  schema/
    cni.v1.1.schema.json
    evidence.pointer.v1.1.schema.json

Development

# Build TypeScript
npm run build

Publishing

This package is published to GitHub Packages as a private scoped package.

Setup

1. Create a .npmrc file in the project root (copy from .npmrc.example):

   @exellix:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN_HERE

2. Generate a GitHub Personal Access Token with read:packages and write:packages permissions.

3. Replace YOUR_GITHUB_TOKEN_HERE with your token.

Publishing

# Build the package
npm run build

# Publish to GitHub Packages
npm publish

Installing

To install this package in other projects, add to your .npmrc:

@exellix:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN_HERE

Then install:

npm install @exellix/narrix-cni

Dependencies

• Runtime: None (zero runtime dependencies)
• Dev: TypeScript (workspace)

Related Packages

This package is used by:

• Adapters - Produce CniV11 and EvidencePointerV11 correctly, optionally validate with schemas
• Scoper/Detector - Read CNI, emit facts/signals/stories
• Engine - Process CNI documents through the pipeline

License

[Add your license here]