@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/trace-spans.d.ts

@@ -0,0 +1,360 @@
+/**
+ * @module trace-spans
+ * Distributed tracing spans with parent-child relationships
+ *
+ * Provides span tracking for distributed tracing with automatic timing,
+ * attribute collection, and integration with W3C Trace Context.
+ *
+ * Performance target: <1ms overhead per operation
+ *
+ * Usage:
+ * ```typescript
+ * import { TraceSpan, SpanRecorder } from '@private.me/xbind';
+ *
+ * // Create a span recorder
+ * const recorder = new SpanRecorder();
+ *
+ * // Start a span
+ * const span = recorder.startSpan('operation-name', { attr: 'value' });
+ *
+ * // Do work...
+ *
+ * // End the span
+ * span.end();
+ *
+ * // Get completed spans
+ * const spans = recorder.getCompletedSpans();
+ * ```
+ */
+import { TraceContext } from './trace-context.js';
+/**
+ * Span status codes (aligned with OpenTelemetry)
+ */
+export declare enum SpanStatusCode {
+    /** Operation completed successfully */
+    OK = 0,
+    /** Operation encountered an error */
+    ERROR = 1,
+    /** Status is unset (default) */
+    UNSET = 2
+}
+/**
+ * Span status
+ */
+export interface SpanStatus {
+    code: SpanStatusCode;
+    message?: string;
+}
+/**
+ * Span attributes (key-value pairs)
+ */
+export interface SpanAttributes {
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Span event (timestamped log entry within a span)
+ */
+export interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** Event timestamp (milliseconds since epoch) */
+    timestamp: number;
+    /** Event attributes */
+    attributes?: SpanAttributes;
+}
+/**
+ * Span kind (aligned with OpenTelemetry)
+ */
+export declare enum SpanKind {
+    /** Internal span (default) */
+    INTERNAL = 0,
+    /** Server span (handling incoming request) */
+    SERVER = 1,
+    /** Client span (outgoing request) */
+    CLIENT = 2,
+    /** Producer span (message queue producer) */
+    PRODUCER = 3,
+    /** Consumer span (message queue consumer) */
+    CONSUMER = 4
+}
+/**
+ * Completed span data
+ */
+export interface SpanData {
+    /** Span ID (16 hex characters) */
+    spanId: string;
+    /** Trace ID (32 hex characters) */
+    traceId: string;
+    /** Parent span ID (16 hex characters, if any) */
+    parentSpanId?: string;
+    /** Span name */
+    name: string;
+    /** Span kind */
+    kind: SpanKind;
+    /** Start timestamp (milliseconds since epoch) */
+    startTime: number;
+    /** End timestamp (milliseconds since epoch) */
+    endTime: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Span status */
+    status: SpanStatus;
+    /** Span attributes */
+    attributes: SpanAttributes;
+    /** Span events */
+    events: SpanEvent[];
+}
+/**
+ * Trace span for distributed tracing
+ *
+ * Represents a single unit of work in a distributed trace with automatic timing.
+ */
+export declare class TraceSpan {
+    /** Span ID (unique within trace) */
+    readonly spanId: string;
+    /** Trace context */
+    readonly traceContext: TraceContext;
+    /** Span name */
+    readonly name: string;
+    /** Span kind */
+    readonly kind: SpanKind;
+    /** Parent span ID */
+    readonly parentSpanId?: string;
+    /** Start timestamp (milliseconds since epoch) */
+    readonly startTime: number;
+    /** End timestamp (milliseconds since epoch, undefined if not ended) */
+    private endTime?;
+    /** Span status */
+    private status;
+    /** Span attributes */
+    private attributes;
+    /** Span events */
+    private events;
+    /** Whether span has ended */
+    private ended;
+    /**
+     * Create a trace span
+     *
+     * @param name - Span name
+     * @param traceContext - Trace context
+     * @param options - Span options
+     */
+    constructor(name: string, traceContext: TraceContext, options?: {
+        kind?: SpanKind;
+        parentSpanId?: string;
+        attributes?: SpanAttributes;
+    });
+    /**
+     * Set span attribute
+     *
+     * @param key - Attribute key
+     * @param value - Attribute value
+     * @returns This span (for chaining)
+     */
+    setAttribute(key: string, value: string | number | boolean): this;
+    /**
+     * Set multiple span attributes
+     *
+     * @param attributes - Attributes to set
+     * @returns This span (for chaining)
+     */
+    setAttributes(attributes: SpanAttributes): this;
+    /**
+     * Add an event to the span
+     *
+     * Events are timestamped log entries within a span.
+     *
+     * @param name - Event name
+     * @param attributes - Optional event attributes
+     * @returns This span (for chaining)
+     */
+    addEvent(name: string, attributes?: SpanAttributes): this;
+    /**
+     * Set span status
+     *
+     * @param code - Status code
+     * @param message - Optional status message
+     * @returns This span (for chaining)
+     */
+    setStatus(code: SpanStatusCode, message?: string): this;
+    /**
+     * Record an exception in the span
+     *
+     * Automatically sets status to ERROR and adds exception event.
+     *
+     * @param error - Error to record
+     * @returns This span (for chaining)
+     */
+    recordException(error: Error | unknown): this;
+    /**
+     * End the span
+     *
+     * Records the end timestamp and marks the span as complete.
+     * If status is UNSET, automatically sets to OK.
+     *
+     * @param endTime - Optional end timestamp (defaults to now)
+     */
+    end(endTime?: number): void;
+    /**
+     * Check if span has ended
+     *
+     * @returns True if ended
+     */
+    isEnded(): boolean;
+    /**
+     * Get span duration in milliseconds
+     *
+     * @returns Duration or null if not ended
+     */
+    getDuration(): number | null;
+    /**
+     * Export span data
+     *
+     * @returns Span data (throws if span not ended)
+     */
+    toData(): SpanData;
+    /**
+     * Create a child span
+     *
+     * The child span will have the same trace ID but a new span ID.
+     *
+     * @param name - Child span name
+     * @param options - Span options
+     * @returns New child span
+     */
+    createChild(name: string, options?: {
+        kind?: SpanKind;
+        attributes?: SpanAttributes;
+    }): TraceSpan;
+}
+/**
+ * Span recorder for collecting completed spans
+ *
+ * Manages span lifecycle and provides access to completed span data.
+ */
+export declare class SpanRecorder {
+    /** Active spans (not yet ended) */
+    private activeSpans;
+    /** Completed spans */
+    private completedSpans;
+    /** Maximum number of completed spans to keep (prevent memory leak) */
+    private maxSpans;
+    /** Trace context for root spans */
+    private rootContext?;
+    /**
+     * Create a span recorder
+     *
+     * @param options - Recorder options
+     */
+    constructor(options?: {
+        maxSpans?: number;
+        traceContext?: TraceContext;
+    });
+    /**
+     * Start a new span
+     *
+     * @param name - Span name
+     * @param options - Span options
+     * @returns New span
+     */
+    startSpan(name: string, options?: {
+        kind?: SpanKind;
+        attributes?: SpanAttributes;
+        traceContext?: TraceContext;
+        parentSpan?: TraceSpan;
+    }): TraceSpan;
+    /**
+     * End a span and record its data
+     *
+     * @param span - Span to end
+     */
+    private endSpan;
+    /**
+     * Get all completed spans
+     *
+     * @returns Array of completed span data
+     */
+    getCompletedSpans(): readonly SpanData[];
+    /**
+     * Get active spans
+     *
+     * @returns Array of active spans
+     */
+    getActiveSpans(): readonly TraceSpan[];
+    /**
+     * Clear all completed spans
+     */
+    clearCompletedSpans(): void;
+    /**
+     * Get span count
+     *
+     * @returns Object with active and completed span counts
+     */
+    getSpanCount(): {
+        active: number;
+        completed: number;
+    };
+    /**
+     * Find completed spans by trace ID
+     *
+     * @param traceId - Trace ID to search for
+     * @returns Array of matching spans
+     */
+    findSpansByTraceId(traceId: string): SpanData[];
+    /**
+     * Build trace tree from completed spans
+     *
+     * Groups spans by trace ID and builds parent-child relationships.
+     *
+     * @param traceId - Trace ID to build tree for
+     * @returns Tree structure
+     */
+    buildTraceTree(traceId: string): SpanTree | null;
+}
+/**
+ * Span tree node (for visualization)
+ */
+export interface SpanTree {
+    span: SpanData;
+    children: SpanTree[];
+}
+/**
+ * Helper function to measure async operation with automatic span tracking
+ *
+ * @param recorder - Span recorder
+ * @param name - Span name
+ * @param fn - Async function to measure
+ * @param options - Span options
+ * @returns Result of async function
+ *
+ * @example
+ * ```typescript
+ * const result = await measureAsync(recorder, 'database-query', async () => {
+ *   return await db.query('SELECT * FROM users');
+ * });
+ * ```
+ */
+export declare function measureAsync<T>(recorder: SpanRecorder, name: string, fn: () => Promise<T>, options?: {
+    kind?: SpanKind;
+    attributes?: SpanAttributes;
+}): Promise<T>;
+/**
+ * Helper function to measure sync operation with automatic span tracking
+ *
+ * @param recorder - Span recorder
+ * @param name - Span name
+ * @param fn - Sync function to measure
+ * @param options - Span options
+ * @returns Result of sync function
+ *
+ * @example
+ * ```typescript
+ * const result = measureSync(recorder, 'encryption', () => {
+ *   return encrypt(data, key);
+ * });
+ * ```
+ */
+export declare function measureSync<T>(recorder: SpanRecorder, name: string, fn: () => T, options?: {
+    kind?: SpanKind;
+    attributes?: SpanAttributes;
+}): T;

package/dist-standalone/trace-spans.js

@@ -0,0 +1 @@
+import{TraceContext,generateSpanId}from"./trace-context.js";export var SpanStatusCode;!function(t){t[t.OK=0]="OK",t[t.ERROR=1]="ERROR",t[t.UNSET=2]="UNSET"}(SpanStatusCode||(SpanStatusCode={}));export var SpanKind;!function(t){t[t.INTERNAL=0]="INTERNAL",t[t.SERVER=1]="SERVER",t[t.CLIENT=2]="CLIENT",t[t.PRODUCER=3]="PRODUCER",t[t.CONSUMER=4]="CONSUMER"}(SpanKind||(SpanKind={}));export class TraceSpan{spanId;traceContext;name;kind;parentSpanId;startTime;endTime;status;attributes;events;ended;constructor(t,e,n={}){this.spanId=generateSpanId(),this.traceContext=e,this.name=t,this.kind=n.kind??SpanKind.INTERNAL,this.parentSpanId=n.parentSpanId,this.startTime=Date.now(),this.status={code:SpanStatusCode.UNSET},this.attributes=n.attributes??{},this.events=[],this.ended=!1}setAttribute(t,e){if(this.ended)throw new Error("Cannot set attribute on ended span");return this.attributes[t]=e,this}setAttributes(t){if(this.ended)throw new Error("Cannot set attributes on ended span");return Object.assign(this.attributes,t),this}addEvent(t,e){if(this.ended)throw new Error("Cannot add event to ended span");return this.events.push({name:t,timestamp:Date.now(),attributes:e}),this}setStatus(t,e){if(this.ended)throw new Error("Cannot set status on ended span");return this.status={code:t,message:e},this}recordException(t){if(this.ended)throw new Error("Cannot record exception on ended span");this.setStatus(SpanStatusCode.ERROR);const e={};return t instanceof Error?(e["exception.type"]=t.name,e["exception.message"]=t.message,t.stack&&(e["exception.stacktrace"]=t.stack)):e["exception.message"]=String(t),this.addEvent("exception",e),this}end(t){this.ended||(this.endTime=t??Date.now(),this.ended=!0,this.status.code===SpanStatusCode.UNSET&&(this.status={code:SpanStatusCode.OK}))}isEnded(){return this.ended}getDuration(){return this.ended&&this.endTime?this.endTime-this.startTime:null}toData(){if(!this.ended||!this.endTime)throw new Error("Cannot export data from active span. Call end() first.");return{spanId:this.spanId,traceId:this.traceContext.traceId,parentSpanId:this.parentSpanId,name:this.name,kind:this.kind,startTime:this.startTime,endTime:this.endTime,duration:this.endTime-this.startTime,status:{...this.status},attributes:{...this.attributes},events:this.events.map(t=>({name:t.name,timestamp:t.timestamp,attributes:t.attributes?{...t.attributes}:void 0}))}}createChild(t,e={}){return new TraceSpan(t,this.traceContext,{...e,parentSpanId:this.spanId})}}export class SpanRecorder{activeSpans;completedSpans;maxSpans;rootContext;constructor(t={}){this.activeSpans=new Map,this.completedSpans=[],this.maxSpans=t.maxSpans??1e3,this.rootContext=t.traceContext}startSpan(t,e={}){const n=e.traceContext??e.parentSpan?.traceContext??this.rootContext??TraceContext.create(),a=new TraceSpan(t,n,{kind:e.kind,attributes:e.attributes,parentSpanId:e.parentSpan?.spanId});this.activeSpans.set(a.spanId,a);const s=setTimeout(()=>{a.isEnded()||(a.setStatus(SpanStatusCode.ERROR,"Span not ended (auto-ended by recorder)"),this.endSpan(a))},6e4),r=a.end.bind(a);return a.end=t=>{clearTimeout(s),r(t),this.endSpan(a)},a}endSpan(t){t.isEnded()||t.end(),this.activeSpans.delete(t.spanId);const e=t.toData();this.completedSpans.push(e),this.completedSpans.length>this.maxSpans&&this.completedSpans.shift()}getCompletedSpans(){return[...this.completedSpans]}getActiveSpans(){return Array.from(this.activeSpans.values())}clearCompletedSpans(){this.completedSpans=[]}getSpanCount(){return{active:this.activeSpans.size,completed:this.completedSpans.length}}findSpansByTraceId(t){return this.completedSpans.filter(e=>e.traceId===t)}buildTraceTree(t){const e=this.findSpansByTraceId(t);if(0===e.length)return null;const n=e.find(t=>!t.parentSpanId);return n?buildSpanTreeNode(n,e):null}}function buildSpanTreeNode(t,e){const n=e.filter(e=>e.parentSpanId===t.spanId).map(t=>buildSpanTreeNode(t,e));return{span:t,children:n}}export async function measureAsync(t,e,n,a){const s=t.startSpan(e,a);try{const t=await n();return s.setStatus(SpanStatusCode.OK),t}catch(t){throw s.recordException(t),t}finally{s.end()}}export function measureSync(t,e,n,a){const s=t.startSpan(e,a);try{const t=n();return s.setStatus(SpanStatusCode.OK),t}catch(t){throw s.recordException(t),t}finally{s.end()}}

package/dist-standalone/transport.js

@@ -1,59 +1 @@
-import { ok, err } from"./_deps/shared/index.js";
-/**
- * HTTPS transport adapter — sends envelopes as JSON POST requests.
- *
- * Recipient URL resolved as: baseUrl/deliver/{recipientDid}
- * This is the SDK's default transport for server-to-server delivery.
- */
-export class HttpsTransportAdapter {
-    baseUrl;
-    timeoutMs;
-    fetchFn;
-    handlers = [];
-    constructor(opts) {
-        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
-        this.timeoutMs = opts.timeoutMs ?? 10_000;
-        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    }
-    async send(envelope, recipientDid) {
-        const url = `${this.baseUrl}/deliver/${encodeURIComponent(recipientDid)}`;
-        try {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-            const response = await this.fetchFn(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(envelope),
-                signal: controller.signal,
-            });
-            clearTimeout(timer);
-            if (!response.ok) {
-                return err(response.status === 404
-                    ? 'RECIPIENT_UNREACHABLE'
-                    : 'SEND_FAILED');
-            }
-            return ok(undefined);
-        }
-        catch (e) {
-            if (e instanceof DOMException && e.name === 'AbortError') {
-                return err('TIMEOUT');
-            }
-            return err('NETWORK_ERROR');
-        }
-    }
-    onReceive(handler) {
-        this.handlers.push(handler);
-    }
-    /**
-     * Dispatch a received envelope to all handlers.
-     * Called by the server when an incoming POST is received.
-     */
-    dispatch(envelope) {
-        for (const handler of this.handlers) {
-            handler(envelope);
-        }
-    }
-    dispose() {
-        this.handlers = [];
-    }
-}
+import{ok,err}from"./_deps/shared/index.js";export class HttpsTransportAdapter{baseUrl;timeoutMs;fetchFn;handlers=[];constructor(t){this.baseUrl=t.baseUrl.replace(/\/$/,""),this.timeoutMs=t.timeoutMs??1e4,this.fetchFn=t.fetch??globalThis.fetch.bind(globalThis)}async send(t,e){const s=`${this.baseUrl}/deliver/${encodeURIComponent(e)}`;try{const e=new AbortController,r=setTimeout(()=>e.abort(),this.timeoutMs),o=await this.fetchFn(s,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(t),signal:e.signal});return clearTimeout(r),o.ok?ok(void 0):err(404===o.status?"RECIPIENT_UNREACHABLE":"SEND_FAILED")}catch(t){return t instanceof DOMException&&"AbortError"===t.name?err("TIMEOUT"):err("NETWORK_ERROR")}}onReceive(t){this.handlers.push(t)}dispatch(t){for(const e of this.handlers)e(t)}dispose(){this.handlers=[]}}

package/dist-standalone/trust-registry.d.ts

@@ -1,7 +1,81 @@
 import type { Result } from '@private.me/shared';
 import type { DIDStateCheckpoint } from './checkpoint.js';
+/**
+ * Rate limiter for DID registration endpoints.
+ *
+ * Implements sliding window algorithm with:
+ * - Per-IP limit: 10 registrations/hour
+ * - Global limit: 1000 registrations/hour
+ *
+ * Prevents DID registration spam attacks (SCALE-1).
+ */
+export declare class RegistrationRateLimiter {
+    private readonly perIPTimestamps;
+    private readonly globalTimestamps;
+    private readonly perIPLimit;
+    private readonly globalLimit;
+    private readonly windowMs;
+    private cleanupInterval;
+    /**
+     * Create a new registration rate limiter.
+     *
+     * @param perIPLimit - Maximum registrations per IP in time window (default: 10)
+     * @param globalLimit - Maximum global registrations in time window (default: 1000)
+     * @param windowMs - Time window in milliseconds (default: 3600000 = 1 hour)
+     */
+    constructor(perIPLimit?: number, globalLimit?: number, windowMs?: number);
+    /**
+     * Check if registration is allowed for the given IP.
+     *
+     * @param ip - Client IP address
+     * @returns True if allowed, false if rate limited
+     */
+    checkLimit(ip: string): boolean;
+    /**
+     * Record a registration attempt.
+     *
+     * Call this AFTER successful registration to avoid counting failures.
+     *
+     * @param ip - Client IP address
+     */
+    recordRegistration(ip: string): void;
+    /**
+     * Get remaining registrations for an IP.
+     *
+     * @param ip - Client IP address
+     * @returns Remaining registrations allowed
+     */
+    getRemainingForIP(ip: string): number;
+    /**
+     * Get remaining global registrations.
+     *
+     * @returns Remaining global registrations allowed
+     */
+    getRemainingGlobal(): number;
+    /**
+     * Get reset time for an IP's rate limit.
+     *
+     * @param ip - Client IP address
+     * @returns Unix timestamp (ms) when limit resets, or null if not rate limited
+     */
+    getResetTimeForIP(ip: string): number | null;
+    /**
+     * Cleanup old timestamps to prevent memory leaks.
+     *
+     * Removes entries with no requests in the last window period.
+     */
+    cleanup(): void;
+    /**
+     * Stop cleanup interval (for testing or shutdown).
+     */
+    destroy(): void;
+    /**
+     * Reset all rate limits (for testing).
+     */
+    reset(): void;
+}
 /** Trust registry error codes. */
-export type RegistryError = 'NOT_FOUND' | 'ALREADY_REGISTERED' | 'REVOKED' | 'NETWORK_ERROR';
+export type RegistryError = 'NOT_FOUND' | 'ALREADY_REGISTERED' | 'REVOKED' | 'EXPIRED' | 'NETWORK_ERROR' | 'RATE_LIMIT_EXCEEDED';
 /** Metadata stored for a registered DID. */
 export interface RegistryEntry {
     readonly did: string;
@@ -21,6 +95,14 @@ export interface RegistryEntry {
     readonly xchange?: boolean;
     /** Current rotation sequence for this DID (prevents rollback attacks). */
     readonly rotation_sequence: number;
+    /** SDK version (semver format, e.g., "1.2.3"). Optional for backward compatibility. */
+    readonly sdkVersion?: string;
+    /** Minimum supported envelope version. Optional for backward compatibility. */
+    readonly minEnvelopeVersion?: number;
+    /** Maximum supported envelope version. Optional for backward compatibility. */
+    readonly maxEnvelopeVersion?: number;
+    /** Unix timestamp (milliseconds) when this entry expires. Undefined = never expires. */
+    readonly expiresAt?: number;
 }
 /** Trust event types for real-time registry updates. */
 export interface TrustEvent {
@@ -40,7 +122,7 @@ export interface TrustEvent {
  */
 export interface TrustRegistry {
     /** Register a DID with its public key, name, and scopes. */
-    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[]): Promise<Result<void, RegistryError>>;
+    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[], sdkVersion?: string, minEnvelopeVersion?: number, maxEnvelopeVersion?: number, ttlMs?: number, clientIP?: string): Promise<Result<void, RegistryError>>;
     /** Resolve a DID to its raw public key bytes. */
     resolve(did: string): Promise<Result<Uint8Array, RegistryError>>;
     /** Check if a DID has a specific scope permission. */
@@ -76,19 +158,33 @@ export interface TrustRegistry {
      * @param scopes - New scopes (replaces existing)
      */
     updateScopes?(did: string, scopes: string[]): Promise<Result<void, RegistryError>>;
+    /**
+     * Remove all expired entries from the registry.
+     * Optional method - not all implementations support cleanup.
+     *
+     * @returns Number of entries removed.
+     */
+    cleanup?(): Promise<number>;
 }
 /**
  * In-memory trust registry for development and testing.
  */
 export declare class MemoryTrustRegistry implements TrustRegistry {
     private readonly entries;
-    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[]): Promise<Result<void, RegistryError>>;
+    private readonly rateLimiter?;
+    constructor(opts?: {
+        enableRateLimiting?: boolean;
+        rateLimiter?: RegistrationRateLimiter;
+    });
+    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[], sdkVersion?: string, minEnvelopeVersion?: number, maxEnvelopeVersion?: number, ttlMs?: number, clientIP?: string): Promise<Result<void, RegistryError>>;
     resolve(did: string): Promise<Result<Uint8Array, RegistryError>>;
     hasScope(did: string, scope: string): Promise<boolean>;
     hasReceiveScope(did: string, scope: string): Promise<boolean>;
     revoke(did: string): Promise<Result<void, RegistryError>>;
     getEntry(did: string): Promise<Result<RegistryEntry, RegistryError>>;
     updateScopes(did: string, scopes: string[]): Promise<Result<void, RegistryError>>;
+    /** Remove all expired entries from the registry. */
+    cleanup(): Promise<number>;
     /** Number of entries (for testing). */
     get size(): number;
 }
@@ -126,7 +222,7 @@ export declare class HttpTrustRegistry implements TrustRegistry {
     constructor(opts: HttpTrustRegistryOptions);
     /** Clear all cached entries. Call after registration or revocation. */
     clearCache(): void;
-    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[]): Promise<Result<void, RegistryError>>;
+    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[], sdkVersion?: string, minEnvelopeVersion?: number, maxEnvelopeVersion?: number, ttlMs?: number, clientIP?: string): Promise<Result<void, RegistryError>>;
     resolve(did: string): Promise<Result<Uint8Array, RegistryError>>;
     hasScope(did: string, scope: string): Promise<boolean>;
     hasReceiveScope(did: string, scope: string): Promise<boolean>;
@@ -226,13 +322,15 @@ export declare class FileTrustRegistry implements TrustRegistry {
     private init;
     /** Append record to JSONL file. */
     private append;
-    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[]): Promise<Result<void, RegistryError>>;
+    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[], sdkVersion?: string, minEnvelopeVersion?: number, maxEnvelopeVersion?: number, ttlMs?: number, clientIP?: string): Promise<Result<void, RegistryError>>;
     resolve(did: string): Promise<Result<Uint8Array, RegistryError>>;
     hasScope(did: string, scope: string): Promise<boolean>;
     hasReceiveScope(did: string, scope: string): Promise<boolean>;
     revoke(did: string): Promise<Result<void, RegistryError>>;
     getEntry(did: string): Promise<Result<RegistryEntry, RegistryError>>;
     updateScopes(did: string, scopes: string[]): Promise<Result<void, RegistryError>>;
+    /** Remove all expired entries from the registry. */
+    cleanup(): Promise<number>;
     /**
      * Rotate a DID to a new public key with rollback protection.
      *
@@ -282,5 +380,8 @@ export declare function createEnterpriseTrustRegistry(opts: {
         mlKemPublicKey?: Uint8Array;
         mlDsaPublicKey?: Uint8Array;
         xchange?: boolean;
+        sdkVersion?: string;
+        minEnvelopeVersion?: number;
+        maxEnvelopeVersion?: number;
     }>;
 }): Promise<TrustRegistry>;