@7h3/protocol 0.4.0 → 0.5.1

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';