@ai-pip/core

Core implementation of the AI-PIP protocol. Layered, zero-trust context processing and transversal integrity for AI systems.

Why AI-PIP?

AI-powered browsers and chat interfaces (e.g. GPT Atlas, embedded AI in web apps) create new attack surfaces: prompt injection, hidden text, jailbreaking, and role hijacking. The AI-PIP (AI Prompt Integrity Protocol) was designed to improve the security of these environments by providing rules and tools to detect, score, and respond to such threats before content reaches the model. This package is the semantic core of that protocol—pure functions, immutable value objects, and clear contracts between layers—so that SDKs and applications can build secure, auditable pipelines.

Description

AI-PIP is a multi-layer security protocol that protects AI systems from prompt injection and malicious context manipulation. This package contains the core implementation: it does not execute network calls or side effects; it provides the logic for segmentation, sanitization, risk scoring, policy decisions, and remediation plans. The official AI-PIP SDK (in development) will use this core to deliver production-ready features, including browser extensions and integrations for AI-powered applications.

Architecture (summary)

| Layer | Role | |-------|------| | CSL (Context Segmentation Layer) | Segments and classifies content by origin (UI, DOM, API, SYSTEM). | | ISL (Instruction Sanitization Layer) | Detects threats (~287 patterns), scores risk, sanitizes content, and emits a signal (risk score, detections) for other layers. From v0.5.0: produces ThreatTag metadata and exposes the canonical tag serializer for semantic isolation (encapsulation with <aipip:threat-type>...</aipip> is applied by the SDK at fragment level). | | AAL (Agent Action Lock) | Consumes the ISL signal and applies policy: ALLOW, WARN, or BLOCK. Produces a remediation plan (what to clean—target segments, goals, constraints); the SDK or an AI agent performs the actual cleanup. | | CPE (Cryptographic Prompt Envelope) | Transversal: ensures the integrity of each layer. Wraps pipeline output with a signed envelope (nonce, metadata, HMAC-SHA256) so that results can be verified. Implemented in shared/envelope; exported as @ai-pip/core/cpe. |

The processing pipeline is CSL → ISL (optionally AAL consumes the signal). CPE is not a step in that sequence—it is a transversal capability that can wrap the result at any point to guarantee integrity. Layers communicate via signals, not internal results, so that each layer stays independent and testable.

Trust and security (contract):

• source (UI, DOM, API, SYSTEM) determines trust level and sanitization. It must be set only by trusted code (backend/SDK), never derived from user input. Otherwise an attacker could send source: 'SYSTEM' and reduce sanitization.
• CPE secret key: The key passed to envelope(..., secretKey) must not be logged or serialized. Key rotation and storage are the SDK’s responsibility (e.g. use a key id in metadata and multiple keys in the verifier).

Semantic isolation and canonical tags (v0.5.0): The core does not modify segment text. It produces ThreatTag metadata (segmentId, offsets, type, confidence) and defines the canonical AI-PIP tag format via the serializer (openTag, closeTag, wrapWithTag). Encapsulation with tags like <aipip:prompt-injection>...</aipip> is applied by the SDK at fragment level. Benefits: no semantic corruption, auditable and reversible, deterministic; the SDK is responsible for applying offsets, insertions, and ordering (e.g. by descending offset when resolving multiple tags).

Installation

pnpm add @ai-pip/core
# or
npm install @ai-pip/core
# or
yarn add @ai-pip/core

Usage example

Segment user input, sanitize it, optionally get a risk decision and remediation plan, and wrap the result in a cryptographic envelope:

import { segment, sanitize, emitSignal, resolveAgentAction, buildRemediationPlan, envelope } from '@ai-pip/core'
import type { AgentPolicy } from '@ai-pip/core'

const cslResult = segment({ content: userInput, source: 'UI', metadata: {} })
const islResult = sanitize(cslResult)
const signal = emitSignal(islResult)
const policy: AgentPolicy = {
  thresholds: { warn: 0.3, block: 0.7 },
  remediation: { enabled: true }
}
const action = resolveAgentAction(signal, policy)  // 'ALLOW' | 'WARN' | 'BLOCK'
const remediationPlan = buildRemediationPlan(islResult, policy)
const cpeResult = envelope(islResult, secretKey)   // integrity for the pipeline result

if (action === 'BLOCK') {
  // SDK: block the request, log, and optionally run cleanup using remediationPlan
}
if (remediationPlan.needsRemediation) {
  // SDK or AI agent: clean targetSegments using goals and constraints
}

Documentation

• Full README (examples, use cases, audit, all layers): docs/readme.md
• Protocol docs (whitepaper, architecture, layers): AI-PIP documentation repository
• Package changelog: CHANGELOG.md — Latest: 0.5.0 (unreleased)
• Features by version: FEATURE.md
• Roadmap (path to 1.0.0): roadmap.md

Requirements

• Node.js ≥ 18
• TypeScript: For correct imports and types, your tsconfig.json must use:
  • "module": "NodeNext"
  • "moduleResolution": "nodenext"
  • "target": "ES2022" (or compatible)

Without this, you may see resolution errors for subpaths (@ai-pip/core/csl, etc.). See docs/readme.md for a full configuration example.

License

Apache-2.0. See LICENSE.

Repository: github.com/AI-PIP/ai-pip-core · npm: @ai-pip/core