@sidurijs/ear 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { EarOrgan, HardenedEarPerception, EarLimitsConfig, EarIngestOptions } from '@sidurijs/core';
+export interface EarOrganConfig extends EarLimitsConfig {
+    defaultSource?: string;
+    transcriber?: (audio: Uint8Array, signal?: AbortSignal) => Promise<string>;
+}
+export declare function detectAudioSignature(bytes: Uint8Array): string | undefined;
+export declare class DefaultEarOrgan implements EarOrgan {
+    private readonly defaultSource;
+    private readonly transcriber?;
+    private readonly maxTextLength;
+    private readonly maxAudioBytes;
+    private readonly allowedAudioMimeTypes;
+    private readonly maxDurationSeconds;
+    private readonly transcriptionTimeoutMs;
+    constructor(config?: EarOrganConfig);
+    listen(source: string | undefined, payload: unknown, options?: EarIngestOptions): Promise<HardenedEarPerception>;
+    transcribeAudio(audio: Uint8Array): Promise<string>;
+}

package/dist/index.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultEarOrgan = void 0;
+exports.detectAudioSignature = detectAudioSignature;
+function detectAudioSignature(bytes) {
+    if (!bytes || bytes.length < 4)
+        return undefined;
+    // RIFF (WAV) - starts with 'RIFF' and at offset 8 has 'WAVE'
+    if (bytes[0] === 0x52 &&
+        bytes[1] === 0x49 &&
+        bytes[2] === 0x46 &&
+        bytes[3] === 0x46) {
+        if (bytes.length >= 12 && bytes[8] === 0x57 && bytes[9] === 0x41 && bytes[10] === 0x56 && bytes[11] === 0x45) {
+            return 'audio/wav';
+        }
+        return 'audio/wav';
+    }
+    // ID3 (MP3 with ID3 header) - starts with 'ID3'
+    if (bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33) {
+        return 'audio/mpeg';
+    }
+    // MP3 Sync word (0xFF, 0xFB/0xF3/0xF2)
+    if (bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0) {
+        return 'audio/mpeg';
+    }
+    // OGG (OggS)
+    if (bytes[0] === 0x4f && bytes[1] === 0x67 && bytes[2] === 0x67 && bytes[3] === 0x53) {
+        return 'audio/ogg';
+    }
+    // FLAC (fLaC)
+    if (bytes[0] === 0x66 && bytes[1] === 0x4c && bytes[2] === 0x61 && bytes[3] === 0x43) {
+        return 'audio/flac';
+    }
+    // WebM / EBML (0x1A, 0x45, 0xDF, 0xA3)
+    if (bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3) {
+        return 'audio/webm';
+    }
+    return undefined;
+}
+class DefaultEarOrgan {
+    defaultSource;
+    transcriber;
+    maxTextLength;
+    maxAudioBytes;
+    allowedAudioMimeTypes;
+    maxDurationSeconds;
+    transcriptionTimeoutMs;
+    constructor(config = {}) {
+        this.defaultSource = config.defaultSource || 'text_chat';
+        this.transcriber = config.transcriber;
+        this.maxTextLength = config.maxTextLength ?? 4000;
+        this.maxAudioBytes = config.maxAudioBytes ?? 10 * 1024 * 1024; // 10MB default
+        this.allowedAudioMimeTypes = config.allowedAudioMimeTypes ?? [
+            'audio/wav',
+            'audio/wave',
+            'audio/x-wav',
+            'audio/mpeg',
+            'audio/mp3',
+            'audio/ogg',
+            'audio/webm',
+            'audio/flac',
+        ];
+        this.maxDurationSeconds = config.maxDurationSeconds ?? 300; // 5 mins
+        this.transcriptionTimeoutMs = config.transcriptionTimeoutMs ?? 15_000;
+    }
+    async listen(source = this.defaultSource, payload, options) {
+        const id = `ear-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const timestamp = new Date().toISOString();
+        const context = options?.context;
+        // 1. Text payload validation & normalization
+        if (typeof payload === 'string') {
+            if (payload.length > this.maxTextLength) {
+                throw new Error(`Ear text input exceeds maximum allowed length of ${this.maxTextLength} characters (received ${payload.length})`);
+            }
+            return {
+                id,
+                source: source || this.defaultSource,
+                text: payload,
+                timestamp,
+                modality: 'text',
+                rawConfidence: 1.0,
+                metadata: {
+                    source: source || this.defaultSource,
+                    channel: context?.conversation?.channel,
+                    actorId: context?.actor?.actorId,
+                    sessionId: context?.actor?.sessionId,
+                    correlationId: context?.conversation?.correlationId,
+                    provenance: 'direct_input',
+                    byteSize: Buffer.byteLength(payload, 'utf8'),
+                },
+            };
+        }
+        // 2. Binary audio buffer validation & magic-byte signature inspection
+        if (payload instanceof Uint8Array) {
+            if (payload.byteLength > this.maxAudioBytes) {
+                throw new Error(`Ear audio input exceeds maximum allowed size of ${this.maxAudioBytes} bytes (received ${payload.byteLength})`);
+            }
+            // Independently inspect audio signature
+            const detectedMime = detectAudioSignature(payload);
+            if (options?.mimeType) {
+                const declaredMime = options.mimeType.toLowerCase();
+                if (!this.allowedAudioMimeTypes.includes(declaredMime)) {
+                    throw new Error(`Ear audio input MIME type "${options.mimeType}" is not supported. Allowed: [${this.allowedAudioMimeTypes.join(', ')}]`);
+                }
+                if (detectedMime && !declaredMime.includes(detectedMime.replace('audio/', '')) && !detectedMime.includes(declaredMime.replace('audio/', ''))) {
+                    throw new Error(`Audio signature mismatch: declared MIME "${options.mimeType}" does not match detected format "${detectedMime}"`);
+                }
+            }
+            if (options?.durationSeconds && options.durationSeconds > this.maxDurationSeconds) {
+                throw new Error(`Ear audio duration ${options.durationSeconds}s exceeds limit of ${this.maxDurationSeconds}s`);
+            }
+            let transcribedText;
+            let rawConfidence = 0.8;
+            if (this.transcriber) {
+                try {
+                    const controller = new AbortController();
+                    const timeoutId = setTimeout(() => controller.abort(), this.transcriptionTimeoutMs);
+                    transcribedText = await this.transcriber(payload, controller.signal);
+                    clearTimeout(timeoutId);
+                    rawConfidence = 0.95;
+                }
+                catch (err) {
+                    transcribedText = undefined;
+                    rawConfidence = 0.0;
+                }
+            }
+            return {
+                id,
+                source: source || 'microphone',
+                audioBuffer: payload,
+                text: transcribedText,
+                timestamp,
+                modality: 'audio',
+                rawConfidence,
+                metadata: {
+                    source: source || 'microphone',
+                    channel: context?.conversation?.channel,
+                    actorId: context?.actor?.actorId,
+                    sessionId: context?.actor?.sessionId,
+                    correlationId: context?.conversation?.correlationId,
+                    provenance: 'transcribed_audio',
+                    byteSize: payload.byteLength,
+                    declaredMimeType: options?.mimeType,
+                    verifiedMimeType: detectedMime,
+                    untrustedDurationSeconds: options?.durationSeconds,
+                },
+            };
+        }
+        // 3. Structured object payload validation
+        if (payload && typeof payload === 'object') {
+            const obj = payload;
+            const textVal = typeof obj.text === 'string' ? obj.text : undefined;
+            if (textVal && textVal.length > this.maxTextLength) {
+                throw new Error(`Ear text within payload exceeds limit of ${this.maxTextLength} characters (received ${textVal.length})`);
+            }
+            // Filter out reserved system keys from incoming payload to prevent metadata pollution/spoofing
+            const reservedKeys = new Set(['source', 'channel', 'actorId', 'sessionId', 'correlationId', 'provenance', 'byteSize']);
+            const sanitizedPayload = {};
+            for (const [key, val] of Object.entries(obj)) {
+                if (!reservedKeys.has(key)) {
+                    sanitizedPayload[key] = val;
+                }
+            }
+            return {
+                id,
+                source,
+                text: textVal,
+                timestamp,
+                modality: 'object',
+                rawConfidence: 1.0,
+                metadata: {
+                    ...sanitizedPayload,
+                    source,
+                    channel: context?.conversation?.channel,
+                    actorId: context?.actor?.actorId,
+                    sessionId: context?.actor?.sessionId,
+                    correlationId: context?.conversation?.correlationId,
+                    provenance: 'structured_payload',
+                },
+            };
+        }
+        // 4. Fallback/Null payload
+        return {
+            id,
+            source,
+            timestamp,
+            modality: 'system',
+            metadata: {
+                source,
+                channel: context?.conversation?.channel,
+                actorId: context?.actor?.actorId,
+                sessionId: context?.actor?.sessionId,
+                correlationId: context?.conversation?.correlationId,
+            },
+        };
+    }
+    async transcribeAudio(audio) {
+        if (!this.transcriber) {
+            throw new Error('No audio transcriber configured in Ear organ');
+        }
+        if (audio.byteLength > this.maxAudioBytes) {
+            throw new Error(`Audio buffer size (${audio.byteLength} bytes) exceeds limit of ${this.maxAudioBytes}`);
+        }
+        return this.transcriber(audio);
+    }
+}
+exports.DefaultEarOrgan = DefaultEarOrgan;

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+describe('DefaultEarOrgan Adversarial Remediation Suite', () => {
+    it('ingests plain text message and populates metadata', async () => {
+        const ear = new index_1.DefaultEarOrgan();
+        const perception = await ear.listen('user_chat', 'Hello Siduri');
+        expect(perception.source).toBe('user_chat');
+        expect(perception.text).toBe('Hello Siduri');
+        expect(perception.modality).toBe('text');
+        expect(perception.metadata?.byteSize).toBeGreaterThan(0);
+        expect(perception.id).toMatch(/^ear-/);
+    });
+    it('rejects oversized text input according to configured limit', async () => {
+        const ear = new index_1.DefaultEarOrgan({ maxTextLength: 100 });
+        const longText = 'A'.repeat(150);
+        await expect(ear.listen('user_chat', longText)).rejects.toThrow(/Ear text input exceeds maximum allowed length/);
+    });
+    it('rejects oversized audio input according to configured byte limit', async () => {
+        const ear = new index_1.DefaultEarOrgan({ maxAudioBytes: 1024 }); // 1KB limit
+        const bigAudio = new Uint8Array(2048);
+        await expect(ear.listen('microphone', bigAudio)).rejects.toThrow(/Ear audio input exceeds maximum allowed size/);
+    });
+    it('rejects unsupported audio MIME type', async () => {
+        const ear = new index_1.DefaultEarOrgan();
+        const audio = new Uint8Array([1, 2, 3]);
+        await expect(ear.listen('microphone', audio, { mimeType: 'video/mp4' })).rejects.toThrow(/MIME type "video\/mp4" is not supported/);
+    });
+    it('detects valid WAV signature (RIFF/WAVE) and rejects mismatched declared MIME type', async () => {
+        const ear = new index_1.DefaultEarOrgan();
+        // Construct valid RIFF WAV header
+        const wavBytes = new Uint8Array([
+            0x52, 0x49, 0x46, 0x46, // "RIFF"
+            0x24, 0x00, 0x00, 0x00, // length
+            0x57, 0x41, 0x56, 0x45, // "WAVE"
+            0x66, 0x6d, 0x74, 0x20, // "fmt "
+        ]);
+        expect((0, index_1.detectAudioSignature)(wavBytes)).toBe('audio/wav');
+        // Mismatched declared MIME: declares MP3 but signature is WAV
+        await expect(ear.listen('microphone', wavBytes, { mimeType: 'audio/mp3' })).rejects.toThrow(/Audio signature mismatch: declared MIME "audio\/mp3" does not match detected format "audio\/wav"/);
+        // Matching declared MIME: declares WAV and signature is WAV
+        const legitPerception = await ear.listen('microphone', wavBytes, { mimeType: 'audio/wav', durationSeconds: 2 });
+        expect(legitPerception.modality).toBe('audio');
+        expect(legitPerception.metadata?.verifiedMimeType).toBe('audio/wav');
+        expect(legitPerception.metadata?.untrustedDurationSeconds).toBe(2);
+    });
+    it('ingests structured object with metadata and limits check', async () => {
+        const ear = new index_1.DefaultEarOrgan();
+        const perception = await ear.listen('webhook', { text: 'Notification alert', sender: 'system' });
+        expect(perception.text).toBe('Notification alert');
+        expect(perception.modality).toBe('object');
+        expect(perception.metadata?.sender).toBe('system');
+    });
+    it('prevents structured object payload from overwriting reserved provenance and context metadata', async () => {
+        const ear = new index_1.DefaultEarOrgan();
+        const mockContext = {
+            companionId: 'comp-1',
+            actor: { actorId: 'legit-user', sessionId: 'sess-1', authorizationRole: 'operator', capabilities: [], authenticated: true },
+            conversation: { channel: 'direct', correlationId: 'corr-1' },
+        };
+        const spoofedPayload = {
+            text: 'Exploit attempt',
+            actorId: 'spoofed-admin',
+            provenance: 'spoofed_system',
+            channel: 'spoofed_channel',
+            customField: 'valid_data',
+        };
+        const perception = await ear.listen('webhook', spoofedPayload, { context: mockContext });
+        expect(perception.metadata?.actorId).toBe('legit-user');
+        expect(perception.metadata?.provenance).toBe('structured_payload');
+        expect(perception.metadata?.channel).toBe('direct');
+        expect(perception.metadata?.customField).toBe('valid_data');
+    });
+    it('transcribes audio if transcriber is provided', async () => {
+        const ear = new index_1.DefaultEarOrgan({
+            transcriber: async () => 'transcribed voice text',
+        });
+        const perception = await ear.listen('microphone', new Uint8Array([1, 2, 3]));
+        expect(perception.text).toBe('transcribed voice text');
+        expect(perception.modality).toBe('audio');
+        expect(perception.audioBuffer).toBeDefined();
+        expect(perception.rawConfidence).toBeGreaterThan(0.9);
+    });
+});

package/organ-manifest.json

@@ -0,0 +1,31 @@
+{
+  "name": "@sidurijs/ear",
+  "organType": "ear",
+  "version": "1.0.0",
+  "displayName": "Ear (Perception Ingress)",
+  "description": "Multi-modal sensory input ingestion, transcription bounds, and mime validation",
+  "entrypoint": "./dist/index.js",
+  "factory": "DefaultEarOrgan",
+  "configKey": "ear",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "defaultSource": {
+        "type": "string",
+        "default": "text_chat"
+      },
+      "maxTextLength": {
+        "type": "number",
+        "default": 4000
+      },
+      "maxAudioBytes": {
+        "type": "number",
+        "default": 10485760
+      }
+    }
+  },
+  "environment": [],
+  "services": [],
+  "database": null,
+  "healthCheck": null
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sidurijs/ear",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "jest --config jest.config.json"
+  },
+  "dependencies": {
+    "@sidurijs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.5.1",
+    "jest": "^30.5.1",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.9.3"
+  },
+  "description": "Ear organ for audio transcription, text perception, and sensory stream ingestion",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vxnus-studio/siduri-x",
+    "directory": "packages/organs/ear"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "files": [
+    "dist",
+    "organ-manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./organ-manifest.json": "./organ-manifest.json"
+  }
+}