@7h3/protocol 0.5.0 → 0.5.1

package/agentAdapter.d.ts

@@ -0,0 +1,26 @@
+import { type AgentReceiveResult, type AgentSessionConfig } from './protocolAgent';
+import { type IntentKind, type ProtocolEnvelope } from './protocol';
+import { type WireEnvelope, type WireFormat } from './protocolTransport';
+export interface AipAdapterConfig extends AgentSessionConfig {
+    wireFormat?: WireFormat;
+}
+export declare class AipAgentAdapter {
+    private readonly session;
+    private readonly wireFormat;
+    constructor(config: AipAdapterConfig);
+    toRaw(envelope: ProtocolEnvelope): WireEnvelope;
+    createRawIntent(input: {
+        recipient?: string;
+        intent: IntentKind;
+        content: string;
+        capability?: string;
+        correlationId?: string;
+        ttlMs?: number;
+        messageId?: string;
+        nonce?: string;
+        nowMs?: number;
+    }): Promise<WireEnvelope>;
+    receiveRaw(raw: WireEnvelope, nowMs?: number): Promise<AgentReceiveResult>;
+    handleRaw(raw: WireEnvelope, emitResponseRaw: (rawResponse: WireEnvelope, responseEnvelope: ProtocolEnvelope) => void | Promise<void>, nowMs?: number): Promise<AgentReceiveResult>;
+}
+export declare function createAipAgentAdapter(config: AipAdapterConfig): AipAgentAdapter;

package/auditLog.d.ts

@@ -0,0 +1,54 @@
+export type AuditEventType = 'verify-ok' | 'verify-fail' | 'rate-limited' | 'sender-denied' | 'response-signed';
+export interface AuditEntry {
+    id: string;
+    timestampMs: number;
+    type: AuditEventType;
+    sender?: string;
+    path?: string;
+    method?: string;
+    envelopeId?: string;
+    failReason?: string;
+    upstream?: string;
+    responseStatus?: number;
+    entrySignature: string;
+}
+export interface AuditLogger {
+    log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>;
+    query(opts?: {
+        type?: AuditEventType;
+        sender?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    verify(entry: AuditEntry, publicKey: string): Promise<boolean>;
+}
+declare class InMemoryAuditLog implements AuditLogger {
+    private entries;
+    private privateKey;
+    private maxEntries;
+    constructor(privateKey: string, maxEntries?: number);
+    log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>;
+    query(opts?: {
+        type?: AuditEventType;
+        sender?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    verify(entry: AuditEntry, publicKey: string): Promise<boolean>;
+    size(): number;
+}
+declare class NoopAuditLog implements AuditLogger {
+    log(_event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>;
+    query(_opts?: {
+        type?: AuditEventType;
+        sender?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    verify(_entry: AuditEntry, _publicKey: string): Promise<boolean>;
+    size(): number;
+}
+export declare function createAuditLog(privateKey: string, opts?: {
+    maxEntries?: number;
+}): InMemoryAuditLog;
+export { InMemoryAuditLog, NoopAuditLog };

package/capability.d.ts

@@ -0,0 +1,67 @@
+import { generateEd25519KeypairBase64Url } from './protocol';
+export { generateEd25519KeypairBase64Url };
+export interface CapabilityScope {
+    pathGlob: string;
+    methods?: string[];
+    maxDelegations?: number;
+}
+export interface CapabilityToken {
+    id: string;
+    version: '7h3-cap/1';
+    issuer: string;
+    subject: string;
+    scopes: CapabilityScope[];
+    issuedAt: number;
+    expiresAt: number;
+    delegationDepth: number;
+    parentTokenId?: string;
+    /** How many more times this token can be re-delegated. undefined = unlimited, 0 = no further delegation. */
+    maxDelegations: number | undefined;
+    signature: string;
+    keyId: string;
+}
+export type CapabilityVerifyResult = {
+    ok: true;
+    token: CapabilityToken;
+    chain: CapabilityToken[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const CAP_HEADER = "x-7h3-capability";
+/**
+ * Deterministic canonical form for signing: alphabetically sorted top-level fields,
+ * each scope also sorted. The `signature` field is excluded.
+ */
+export declare function canonicalizeCapabilityToken(token: Omit<CapabilityToken, 'signature'>): string;
+export declare function issueCapabilityToken(opts: {
+    issuerPrivateKey: string;
+    issuerId: string;
+    subject: string;
+    scopes: CapabilityScope[];
+    ttlMs: number;
+    maxDelegations?: number;
+    keyId?: string;
+}): Promise<CapabilityToken>;
+export declare function delegateCapabilityToken(opts: {
+    parentToken: CapabilityToken;
+    delegatorPrivateKey: string;
+    delegatorId: string;
+    newSubject: string;
+    scopes?: CapabilityScope[];
+    ttlMs: number;
+    keyId?: string;
+}): Promise<CapabilityToken>;
+export declare function verifyCapabilityToken(token: CapabilityToken, publicKey: string, opts?: {
+    now?: number;
+}): Promise<boolean>;
+export declare function verifyCapabilityChain(chain: CapabilityToken[], keyRegistry: {
+    getPublicKey(id: string): Promise<string | null>;
+}, opts?: {
+    requiredPathGlob?: string;
+    requiredMethod?: string;
+    now?: number;
+}): Promise<CapabilityVerifyResult>;
+export declare function tokenMatchesScope(token: CapabilityToken, pathGlob: string, method?: string): boolean;
+export declare function serializeCapabilityChain(chain: CapabilityToken[]): string;
+export declare function parseCapabilityChain(serialized: string): CapabilityToken[];

package/cborCodec.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal deterministic CBOR encoder/decoder — zero external dependencies.
+ * Follows RFC 8949 §4.2 deterministic encoding:
+ *   - Shortest-length integers
+ *   - Map keys sorted by lexicographic byte order of encoded key
+ */
+export declare class CborEncoder {
+    private chunks;
+    encode(value: unknown): Uint8Array;
+    private _encode;
+    private _encodeNumber;
+    private _float64Header;
+    private _encodeString;
+    private _encodeByteString;
+    private _encodeArray;
+    private _encodeMapFromAnyEntries;
+    private _encodeMapFromEntries;
+    private _compareBytes;
+    private _concatPair;
+    private _encodeHead;
+    private _encodeHeadBytes;
+    private _concat;
+}
+export declare class CborDecoder {
+    private data;
+    private offset;
+    decode(data: Uint8Array): unknown;
+    private _decode;
+    private _decodeUint;
+    private _readByte;
+    private _readBytes;
+}
+export declare function encodeCbor(value: unknown): Uint8Array;
+export declare function decodeCbor(data: Uint8Array): unknown;

package/conformanceVectors.d.ts

@@ -0,0 +1,20 @@
+import type { ProtocolEnvelope } from './protocol';
+export interface ConformanceVector {
+    id: string;
+    secret: string;
+    keyId: string;
+    envelope: Omit<ProtocolEnvelope, 'signature'>;
+    canonical: string;
+    signature: string;
+}
+export interface Ed25519ConformanceVector {
+    id: string;
+    keyId: string;
+    publicKey: string;
+    privateKey: string;
+    envelope: Omit<ProtocolEnvelope, 'signature'>;
+    canonical: string;
+    signature: string;
+}
+export declare const AIP_V01_CONFORMANCE_VECTORS: ConformanceVector[];
+export declare const AIP_V01_ED25519_CONFORMANCE_VECTORS: Ed25519ConformanceVector[];

package/encryption.d.ts

@@ -0,0 +1,85 @@
+/**
+ * E2E Encryption for 7h3 Protocol
+ *
+ * Uses X25519 Diffie-Hellman key exchange + ChaCha20-Poly1305 AEAD.
+ * All operations via Node.js built-in `node:crypto` — zero new dependencies.
+ *
+ * Architecture:
+ *   EncryptedEnvelope = SignedEnvelope where body.content is a base64url-encoded
+ *   EncryptedPayload, body.intent = 'ENCRYPTED', body.capability = 'x25519-chacha20poly1305'
+ */
+import { type ProtocolBody, type ProtocolEnvelope } from './protocol.js';
+export interface X25519KeyPair {
+    /** Raw 32-byte X25519 public key, base64url-encoded (no padding) */
+    publicKey: string;
+    /** Raw 32-byte X25519 private key, base64url-encoded (no padding) */
+    privateKey: string;
+}
+export interface EncryptedPayload {
+    /** Ephemeral X25519 public key (base64url, raw 32 bytes) */
+    ephemeralPublic: string;
+    /** ChaCha20 nonce / HKDF salt (base64url, 12 bytes) */
+    nonce: string;
+    /** Ciphertext without auth tag (base64url) */
+    ciphertext: string;
+    /** 16-byte Poly1305 auth tag (base64url) */
+    tag: string;
+}
+/**
+ * Generate a fresh X25519 keypair.
+ * Both keys are raw 32-byte values encoded as base64url (no padding).
+ */
+export declare function generateX25519KeyPair(): X25519KeyPair;
+/**
+ * Perform X25519 DH + HKDF-SHA256 to derive a 32-byte ChaCha20-Poly1305 key.
+ *
+ * @param privateKeyBase64Url  - raw 32-byte X25519 private key (base64url)
+ * @param peerPublicKeyBase64Url - raw 32-byte X25519 public key (base64url)
+ * @param nonce - raw 12-byte nonce (base64url); used as HKDF salt
+ * @returns 32-byte Buffer ready for use with createCipheriv/createDecipheriv
+ */
+export declare function deriveEncryptionKey(privateKeyBase64Url: string, peerPublicKeyBase64Url: string, nonce: string): Buffer;
+/**
+ * Encrypt a ProtocolBody with the recipient's X25519 public key.
+ *
+ * @returns encryptedContent (base64url-encoded EncryptedPayload JSON) and ephemeralPublic
+ */
+export declare function encryptBody(body: ProtocolBody, recipientX25519PublicKey: string): {
+    encryptedContent: string;
+    ephemeralPublic: string;
+};
+/**
+ * Decrypt an encrypted ProtocolBody.
+ *
+ * @param encryptedContent - base64url-encoded EncryptedPayload
+ * @param recipientX25519PrivateKey - raw 32-byte X25519 private key (base64url)
+ * @returns decrypted ProtocolBody
+ * @throws if AEAD tag verification fails
+ */
+export declare function decryptBody(encryptedContent: string, recipientX25519PrivateKey: string): ProtocolBody;
+/**
+ * Encrypt and sign an envelope (full pipeline).
+ *
+ * The original body is encrypted; the envelope body is replaced with:
+ *   { intent: 'ENCRYPTED', content: <encrypted-payload>, capability: 'x25519-chacha20poly1305' }
+ * The modified envelope is then signed with Ed25519.
+ */
+export declare function sealEnvelope(envelope: Omit<ProtocolEnvelope, 'signature'>, opts: {
+    recipientX25519PublicKey: string;
+    senderEd25519PrivateKey: string;
+}): Promise<ProtocolEnvelope>;
+/**
+ * Verify signature and decrypt an envelope (full pipeline).
+ *
+ * Signature is verified FIRST; decryption only proceeds if valid.
+ *
+ * @returns The signed envelope (with encrypted body) and the decrypted original body
+ * @throws if Ed25519 signature invalid or AEAD tag fails
+ */
+export declare function openEnvelope(envelope: ProtocolEnvelope, opts: {
+    recipientX25519PrivateKey: string;
+    senderEd25519PublicKey: string;
+}): Promise<{
+    envelope: ProtocolEnvelope;
+    body: ProtocolBody;
+}>;

package/envelopeCbor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Higher-level CBOR codec for ProtocolEnvelope.
+ * Uses numeric field keys for maximum compactness.
+ *
+ * Envelope map structure:
+ *   1 → header map
+ *   2 → body map
+ *   3 → signature map (omitted if no signature)
+ *
+ * Header map:
+ *   1 → version (string)
+ *   2 → messageId (string)
+ *   3 → timestampMs (int)
+ *   4 → ttlMs (int)
+ *   5 → sender (string)
+ *   6 → recipient (string, omit if absent)
+ *   7 → nonce (string)
+ *
+ * Body map:
+ *   1 → intent (string)
+ *   2 → content (string)
+ *   3 → capability (string, omit if absent)
+ *   4 → correlationId (string, omit if absent)
+ *
+ * Signature map:
+ *   1 → alg (string)
+ *   2 → keyId (string)
+ *   3 → value (string — base64url signature)
+ */
+import type { ProtocolEnvelope } from './protocol';
+export declare const CBOR_CONTENT_TYPE = "application/7h3-cbor";
+export declare function encodeEnvelopeCbor(env: ProtocolEnvelope): Uint8Array;
+export declare function decodeEnvelopeCbor(data: Uint8Array): ProtocolEnvelope;

package/frameworkAdapters.d.ts

@@ -0,0 +1,72 @@
+import { type AipAgentAdapter } from './agentAdapter';
+import { type ProtocolEnvelope } from './protocol';
+import { type WireEnvelope } from './protocolTransport';
+export interface LangChainMessageLike {
+    content: string;
+    name?: string;
+    additionalKwargs?: Record<string, unknown>;
+}
+export interface LlamaIndexMessageLike {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    additionalKwargs?: Record<string, unknown>;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcRequestLike {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponseLike {
+    jsonrpc: '2.0';
+    id: string | number;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+export interface JsonRpcBridgeOptions {
+    recipient?: string;
+    allowedMethods?: readonly string[];
+    methodToCapability?: (method: string) => string;
+    authorizeMethod?: (request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => boolean | Promise<boolean>;
+    rateLimitKey?: (request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => string;
+    rateLimiter?: {
+        consume: (key: string, request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => boolean | Promise<boolean>;
+    };
+    onPolicyEvent?: (event: JsonRpcPolicyEvent) => void | Promise<void>;
+}
+export interface JsonRpcPolicyContext {
+    intent: 'TASK';
+    recipient?: string;
+    capability: string;
+    correlationId: string;
+    createdAtMs: number;
+}
+export interface JsonRpcPolicyEvent {
+    stage: 'allowlist' | 'authorize' | 'rateLimit';
+    decision: 'allow' | 'deny';
+    method: string;
+    context: JsonRpcPolicyContext;
+    reason?: string;
+}
+export interface JsonRpcResponseOptions {
+    defaultErrorCode?: number;
+}
+export declare function createRawTaskFromLangChain(adapter: AipAgentAdapter, message: LangChainMessageLike, options?: {
+    recipient?: string;
+    capability?: string;
+    correlationId?: string;
+}): Promise<WireEnvelope>;
+export declare function toLangChainMessage(envelope: ProtocolEnvelope): LangChainMessageLike;
+export declare function createRawTaskFromLlamaIndex(adapter: AipAgentAdapter, message: LlamaIndexMessageLike, options?: {
+    recipient?: string;
+    capability?: string;
+    correlationId?: string;
+}): Promise<WireEnvelope>;
+export declare function toLlamaIndexMessage(envelope: ProtocolEnvelope): LlamaIndexMessageLike;
+export declare function createRawTaskFromJsonRpc(adapter: AipAgentAdapter, request: JsonRpcRequestLike, options?: JsonRpcBridgeOptions): Promise<WireEnvelope>;
+export declare function toJsonRpcResponse(envelope: ProtocolEnvelope, id: string | number, options?: JsonRpcResponseOptions): JsonRpcResponseLike;

package/gateway.d.ts

@@ -0,0 +1,53 @@
+import { type KeyRegistry } from './keyRegistry';
+import { type RoutePolicy } from './routePolicy';
+import { SlidingWindowRateLimiter } from './rateLimiter';
+import type { ReplayStore } from './replayStores';
+export type { KeyRegistry, RoutePolicy };
+export interface GatewayConfig {
+    upstream: string;
+    keyRegistry: KeyRegistry;
+    policies?: RoutePolicy[];
+    privateKey?: string;
+    sender?: string;
+    signResponses?: boolean;
+    defaultPolicy?: 'allow' | 'deny';
+    headerName?: string;
+    metricsPath?: string;
+    /** Optional distributed replay store — prevents nonce reuse across gateway instances. */
+    replayStore?: ReplayStore;
+    /** Optional capability token registry for capability-based auth. */
+    capabilityRegistry?: {
+        getPublicKey(id: string): Promise<string | null>;
+    };
+}
+export interface GatewayRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[]>;
+    body?: string;
+    url?: string;
+}
+export interface GatewayResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export type GatewayVerifyOutcome = {
+    ok: true;
+    sender: string;
+    envelopeId?: string;
+} | {
+    ok: false;
+    status: 401 | 403 | 429;
+    reason: string;
+};
+declare class Protocol7h3Gateway {
+    private config;
+    private rateLimiter;
+    constructor(config: GatewayConfig);
+    verify(req: GatewayRequest): Promise<GatewayVerifyOutcome>;
+    handle(req: GatewayRequest): Promise<GatewayResponse>;
+    getRateLimiter(): SlidingWindowRateLimiter;
+}
+export declare function createGateway(config: GatewayConfig): Protocol7h3Gateway;
+export { Protocol7h3Gateway };

package/grpcBinding.d.ts

@@ -0,0 +1,29 @@
+import { type ProtocolEnvelope } from './protocol';
+import type { KeyRegistry } from './keyRegistry';
+export { type KeyRegistry };
+export declare const GRPC_METADATA_KEY = "7h3-envelope-bin";
+export interface GrpcSignOptions {
+    privateKey: string;
+    sender: string;
+    recipient?: string;
+    ttlMs?: number;
+    metadataKey?: string;
+}
+export interface GrpcVerifyOptions {
+    keyRegistry: KeyRegistry;
+    metadataKey?: string;
+    strictTtl?: boolean;
+}
+export type GrpcVerifyResult = {
+    ok: true;
+    envelope: ProtocolEnvelope;
+} | {
+    ok: false;
+    code: number;
+    message: string;
+};
+export declare function signGrpcCall(opts: GrpcSignOptions): Promise<Record<string, string>>;
+export declare function verifyGrpcCall(metadata: Record<string, string | Buffer | string[]>, opts: GrpcVerifyOptions): Promise<GrpcVerifyResult>;
+export declare function withGrpcVerification<TCall extends {
+    metadata: Record<string, string | Buffer | string[]>;
+}, TResp>(handler: (call: TCall) => Promise<TResp>, opts: GrpcVerifyOptions): (call: TCall) => Promise<TResp>;

package/httpBinding.d.ts

@@ -0,0 +1,50 @@
+import { type ProtocolEnvelope } from './protocol';
+import type { KeyRegistry } from './keyRegistry';
+import { CBOR_CONTENT_TYPE as _CBOR_CONTENT_TYPE } from './envelopeCbor';
+export { _CBOR_CONTENT_TYPE as CBOR_CONTENT_TYPE };
+export { type KeyRegistry };
+export declare const DEFAULT_HEADER = "x-7h3-envelope";
+export type VerifyFailReason = 'missing-header' | 'malformed-envelope' | 'unknown-sender' | 'invalid-signature' | 'ttl-expired' | 'validation-error';
+export type VerifyHttpResult = {
+    ok: true;
+    envelope: ProtocolEnvelope;
+} | {
+    ok: false;
+    reason: VerifyFailReason;
+    detail?: string;
+};
+export interface HttpBindingOptions {
+    keyRegistry: KeyRegistry;
+    headerName?: string;
+    strictTtl?: boolean;
+}
+export declare function verifyHttpEnvelope(headers: Record<string, string | string[] | undefined>, opts: HttpBindingOptions, body?: Uint8Array): Promise<VerifyHttpResult>;
+export declare function signHttpRequest(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKey: string, opts?: {
+    headerName?: string;
+    format?: 'cbor' | 'json';
+}): Promise<{
+    headers: Record<string, string>;
+    body?: Uint8Array;
+}>;
+export declare function signHttpRequestHmac(envelope: Omit<ProtocolEnvelope, 'signature'>, secret: string, keyId: string, opts?: {
+    headerName?: string;
+}): Promise<{
+    headers: Record<string, string>;
+}>;
+export declare function createHttpMiddleware(opts: HttpBindingOptions): (req: {
+    headers: Record<string, string | string[] | undefined>;
+}, res: {
+    status: (n: number) => {
+        json: (b: unknown) => void;
+    };
+}, next: (err?: unknown) => void) => Promise<void>;
+export declare function signFetchRequest(request: Request, envelope: Omit<ProtocolEnvelope, 'signature'>, privateKey: string, opts?: {
+    headerName?: string;
+}): Promise<Request>;
+export declare function createSignedFetchRequest(request: Request, opts: {
+    privateKey: string;
+    sender: string;
+    recipient?: string;
+    ttlMs?: number;
+    headerName?: string;
+}): Promise<Request>;

package/index.d.ts

@@ -0,0 +1,39 @@
+export * from './protocol';
+export * from './protocolTransport';
+export * from './protocolBinary';
+export * from './protocolCapabilities';
+export * from './protocolReplay';
+export * from './keyRotation';
+export * from './protocolAgent';
+export * from './agentAdapter';
+export * from './frameworkAdapters';
+export * from './mcpGateway';
+export * from './runtimePolicy';
+export * from './policyEnforcer';
+export * from './runtimePolicyManager';
+export * from './runtimePolicyPresets';
+export * from './policyTelemetryFeedback';
+export * from './redisClient';
+export * from './replayStores';
+export * from './revocation';
+export * from './mcpWrapper';
+export * from './mcpTransports';
+export * from './keyRegistry';
+export * from './httpBinding';
+export * from './webhookBinding';
+export * from './queueBinding';
+export * from './wsBinding';
+export * from './grpcBinding';
+export * from './keyInfra';
+export * from './rateLimiter';
+export * from './routePolicy';
+export * from './gateway';
+export * from './signedResponse';
+export * from './auditLog';
+export * from './telemetry';
+export * from './otel';
+export * from './cborCodec';
+export * from './envelopeCbor';
+export * from './encryption';
+export * from './capability';
+export * from './stream';