aether-wv 0.0.0-stage → 1.0.0

package/dist/packages/core/src/security/capability.js

@@ -0,0 +1,56 @@
+import { createHmac } from 'node:crypto';
+export class CapabilityGatekeeper {
+    secretKey;
+    constructor(secretKey = 'aether-internal-secret') {
+        this.secretKey = secretKey;
+    }
+    /**
+     * Generates a signed capability token for a trusted mini-app origin
+     */
+    generateToken(manifest) {
+        const payload = JSON.stringify(manifest);
+        const signature = createHmac('sha256', this.secretKey).update(payload).digest('hex');
+        const b64Payload = Buffer.from(payload).toString('base64url');
+        return `${b64Payload}.${signature}`;
+    }
+    /**
+     * Verifies a capability token and checks if the service/method is authorized
+     */
+    authorize(token, currentOrigin, serviceName, methodName) {
+        if (!token)
+            return false;
+        const parts = token.split('.');
+        if (parts.length !== 2)
+            return false;
+        const [b64Payload, signature] = parts;
+        const payload = Buffer.from(b64Payload, 'base64url').toString('utf8');
+        const expectedSig = createHmac('sha256', this.secretKey).update(payload).digest('hex');
+        if (signature !== expectedSig) {
+            return false;
+        }
+        try {
+            const manifest = JSON.parse(payload);
+            if (manifest.expiresAt < Date.now()) {
+                return false;
+            }
+            if (manifest.origin !== '*' && currentOrigin !== '*' && manifest.origin !== currentOrigin) {
+                return false;
+            }
+            // Check wildcards and exact service matches
+            const target = `${serviceName}.${methodName}`;
+            return manifest.allowedServices.some((pattern) => {
+                if (pattern === '*')
+                    return true;
+                if (pattern === serviceName || pattern === `${serviceName}.*`)
+                    return true;
+                if (pattern === target)
+                    return true;
+                return false;
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=capability.js.map

package/dist/packages/core/src/security/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../../../packages/core/src/security/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQzC,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,YAAoB,wBAAwB;QAA5C,cAAS,GAAT,SAAS,CAAmC;IAAG,CAAC;IAE7E;;OAEG;IACH,aAAa,CAAC,QAA4B;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC9D,OAAO,GAAG,UAAU,IAAI,SAAS,EAAE,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAa,EAAE,aAAqB,EAAE,WAAmB,EAAE,UAAkB;QACrF,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAErC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtE,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEvF,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAuB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACzD,IAAI,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBACpC,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,aAAa,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;gBAC1F,OAAO,KAAK,CAAC;YACf,CAAC;YAED,4CAA4C;YAC5C,MAAM,MAAM,GAAG,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC;YAC9C,OAAO,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;gBAC/C,IAAI,OAAO,KAAK,GAAG;oBAAE,OAAO,IAAI,CAAC;gBACjC,IAAI,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,GAAG,WAAW,IAAI;oBAAE,OAAO,IAAI,CAAC;gBAC3E,IAAI,OAAO,KAAK,MAAM;oBAAE,OAAO,IAAI,CAAC;gBACpC,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/packages/core/src/session/session.d.ts

@@ -0,0 +1,29 @@
+import { AetherFrame } from '../protocol/frames.js';
+/**
+ * Ring buffer of recent frames for session resumption following WebContent process OOM reload.
+ */
+export declare class SessionRingBuffer {
+    private readonly capacity;
+    private buffer;
+    constructor(capacity?: number);
+    add(frame: AetherFrame): void;
+    /**
+     * Retrieves all frames with sequenceId > lastAckSeq
+     */
+    getFramesAfter(lastAckSeq: number): AetherFrame[];
+    clear(): void;
+}
+export interface SessionState {
+    sessionId: string;
+    createdAt: number;
+    lastActive: number;
+    lastSequenceId: number;
+    ringBuffer: SessionRingBuffer;
+}
+export declare class SessionRegistry {
+    private sessions;
+    getOrCreateSession(sessionId: string): SessionState;
+    getSession(sessionId: string): SessionState | undefined;
+    deleteSession(sessionId: string): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/packages/core/src/session/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../../packages/core/src/session/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;GAEG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,MAAM,CAAqB;gBAEN,QAAQ,GAAE,MAAY;IAEnD,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAO7B;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE;IAIjD,KAAK,IAAI,IAAI;CAGd;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAmC;IAEnD,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAiBnD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIvD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAGvC"}

package/dist/packages/core/src/session/session.js

@@ -0,0 +1,52 @@
+/**
+ * Ring buffer of recent frames for session resumption following WebContent process OOM reload.
+ */
+export class SessionRingBuffer {
+    capacity;
+    buffer = [];
+    constructor(capacity = 256) {
+        this.capacity = capacity;
+    }
+    add(frame) {
+        if (this.buffer.length >= this.capacity) {
+            this.buffer.shift();
+        }
+        this.buffer.push(frame);
+    }
+    /**
+     * Retrieves all frames with sequenceId > lastAckSeq
+     */
+    getFramesAfter(lastAckSeq) {
+        return this.buffer.filter((f) => f.sequenceId > lastAckSeq);
+    }
+    clear() {
+        this.buffer = [];
+    }
+}
+export class SessionRegistry {
+    sessions = new Map();
+    getOrCreateSession(sessionId) {
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            session = {
+                sessionId,
+                createdAt: Date.now(),
+                lastActive: Date.now(),
+                lastSequenceId: 0,
+                ringBuffer: new SessionRingBuffer(256),
+            };
+            this.sessions.set(sessionId, session);
+        }
+        else {
+            session.lastActive = Date.now();
+        }
+        return session;
+    }
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    deleteSession(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/packages/core/src/session/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../../../packages/core/src/session/session.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAGC;IAFrB,MAAM,GAAkB,EAAE,CAAC;IAEnC,YAA6B,WAAmB,GAAG;QAAtB,aAAQ,GAAR,QAAQ,CAAc;IAAG,CAAC;IAEvD,GAAG,CAAC,KAAkB;QACpB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,UAAkB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,UAAU,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,CAAC;CACF;AAUD,MAAM,OAAO,eAAe;IAClB,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEnD,kBAAkB,CAAC,SAAiB;QAClC,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG;gBACR,SAAS;gBACT,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;gBACtB,cAAc,EAAE,CAAC;gBACjB,UAAU,EAAE,IAAI,iBAAiB,CAAC,GAAG,CAAC;aACvC,CAAC;YACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,aAAa,CAAC,SAAiB;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/packages/native-host/src/host.d.ts

@@ -0,0 +1,30 @@
+import { Transport, CapabilityGatekeeper, SessionRegistry } from '../../core/src/index.js';
+export interface StreamEmitter {
+    send(payload: Uint8Array): Promise<void>;
+    close(): void;
+    error(err: Error): void;
+    onCancel(cb: () => void): void;
+}
+export type RpcHandler = (payload: Uint8Array) => Promise<Uint8Array>;
+export type StreamHandler = (payload: Uint8Array, emitter: StreamEmitter) => void;
+export declare class AetherNativeHost {
+    private transport;
+    private rpcHandlers;
+    private streamHandlers;
+    private activeEmitters;
+    private streamControllers;
+    private sequenceId;
+    gatekeeper: CapabilityGatekeeper;
+    sessionRegistry: SessionRegistry;
+    constructor(transport: Transport, secretKey?: string);
+    registerRpc(service: string, method: string, handler: RpcHandler): void;
+    registerStream(service: string, method: string, handler: StreamHandler): void;
+    private handleRawBytes;
+    private sendFrame;
+    private sendError;
+    private handleFrame;
+    private handleRpcRequest;
+    private handleStreamInit;
+    private handleHandshake;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/packages/native-host/src/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../../../packages/native-host/src/host.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAST,oBAAoB,EACpB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;AAElF,qBAAa,gBAAgB;IAWzB,OAAO,CAAC,SAAS;IAVnB,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,iBAAiB,CAA6C;IACtE,OAAO,CAAC,UAAU,CAAK;IAEhB,UAAU,EAAE,oBAAoB,CAAC;IACjC,eAAe,EAAE,eAAe,CAAC;gBAG9B,SAAS,EAAE,SAAS,EAC5B,SAAS,CAAC,EAAE,MAAM;IAQpB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAIvE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI;IAI7E,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,WAAW;IA4CnB,OAAO,CAAC,gBAAgB;IAwCxB,OAAO,CAAC,gBAAgB;IA8ExB,OAAO,CAAC,eAAe;CAyCxB"}

package/dist/packages/native-host/src/host.js

@@ -0,0 +1,232 @@
+import { FrameType, FrameFlags, encodeFrame, decodeFrame, BinaryReader, BinaryWriter, StreamCreditController, CapabilityGatekeeper, SessionRegistry, } from '../../core/src/index.js';
+export class AetherNativeHost {
+    transport;
+    rpcHandlers = new Map();
+    streamHandlers = new Map();
+    activeEmitters = new Map();
+    streamControllers = new Map();
+    sequenceId = 1;
+    gatekeeper;
+    sessionRegistry;
+    constructor(transport, secretKey) {
+        this.transport = transport;
+        this.gatekeeper = new CapabilityGatekeeper(secretKey);
+        this.sessionRegistry = new SessionRegistry();
+        this.transport.onReceive((data) => this.handleRawBytes(data));
+    }
+    registerRpc(service, method, handler) {
+        this.rpcHandlers.set(`${service}.${method}`, handler);
+    }
+    registerStream(service, method, handler) {
+        this.streamHandlers.set(`${service}.${method}`, handler);
+    }
+    handleRawBytes(bytes) {
+        const frame = decodeFrame(bytes);
+        this.handleFrame(frame);
+    }
+    sendFrame(frame, sessionId) {
+        if (sessionId) {
+            const session = this.sessionRegistry.getOrCreateSession(sessionId);
+            session.ringBuffer.add(frame);
+        }
+        const bytes = encodeFrame(frame);
+        this.transport.send(bytes);
+    }
+    sendError(streamId, message, sessionId) {
+        const errorFrame = {
+            type: FrameType.ERROR,
+            flags: FrameFlags.NONE,
+            streamId,
+            sequenceId: this.sequenceId++,
+            payload: new TextEncoder().encode(message),
+        };
+        this.sendFrame(errorFrame, sessionId);
+    }
+    handleFrame(frame) {
+        switch (frame.type) {
+            case FrameType.RPC_REQ: {
+                this.handleRpcRequest(frame);
+                break;
+            }
+            case FrameType.STREAM_DATA: {
+                this.handleStreamInit(frame);
+                break;
+            }
+            case FrameType.FLOW_ACK: {
+                const credits = new DataView(frame.payload.buffer, frame.payload.byteOffset).getUint32(0, false);
+                const controller = this.streamControllers.get(frame.streamId);
+                if (controller) {
+                    controller.grantCredits(credits);
+                }
+                break;
+            }
+            case FrameType.STREAM_CANCEL: {
+                const emitter = this.activeEmitters.get(frame.streamId);
+                if (emitter) {
+                    // Trigger the handler's onCancel callback so it can stop producing data
+                    emitter.__cancelCallback?.();
+                    this.activeEmitters.delete(frame.streamId);
+                }
+                const controller = this.streamControllers.get(frame.streamId);
+                if (controller) {
+                    controller.cancel();
+                    this.streamControllers.delete(frame.streamId);
+                }
+                break;
+            }
+            case FrameType.HANDSHAKE: {
+                this.handleHandshake(frame);
+                break;
+            }
+        }
+    }
+    handleRpcRequest(frame) {
+        try {
+            const reader = new BinaryReader(frame.payload);
+            const sessionId = reader.readString();
+            const service = reader.readString();
+            const method = reader.readString();
+            const token = reader.readString();
+            const reqPayload = reader.readBytes();
+            // Check ACL permissions if token is provided or expected
+            if (token && !this.gatekeeper.authorize(token, '*', service, method)) {
+                this.sendError(frame.streamId, `[Security] Access denied for ${service}.${method}`, sessionId);
+                return;
+            }
+            const handler = this.rpcHandlers.get(`${service}.${method}`);
+            if (!handler) {
+                this.sendError(frame.streamId, `[RpcError] Method not found: ${service}.${method}`, sessionId);
+                return;
+            }
+            handler(reqPayload)
+                .then((resPayload) => {
+                const respFrame = {
+                    type: FrameType.RPC_RESP,
+                    flags: FrameFlags.NONE,
+                    streamId: frame.streamId,
+                    sequenceId: this.sequenceId++,
+                    payload: resPayload,
+                };
+                this.sendFrame(respFrame, sessionId);
+            })
+                .catch((err) => {
+                this.sendError(frame.streamId, err.message || String(err), sessionId);
+            });
+        }
+        catch (err) {
+            this.sendError(frame.streamId, `[MalformedRequest] ${err.message}`);
+        }
+    }
+    handleStreamInit(frame) {
+        try {
+            const reader = new BinaryReader(frame.payload);
+            const sessionId = reader.readString();
+            const service = reader.readString();
+            const method = reader.readString();
+            const token = reader.readString();
+            const reqPayload = reader.readBytes();
+            if (token && !this.gatekeeper.authorize(token, '*', service, method)) {
+                this.sendError(frame.streamId, `[Security] Access denied for ${service}.${method}`, sessionId);
+                return;
+            }
+            const handler = this.streamHandlers.get(`${service}.${method}`);
+            if (!handler) {
+                this.sendError(frame.streamId, `[StreamError] Stream method not found: ${service}.${method}`, sessionId);
+                return;
+            }
+            const controller = new StreamCreditController({ initialCredits: 8, ackBatchSize: 4 });
+            this.streamControllers.set(frame.streamId, controller);
+            let cancelCallback = null;
+            let closed = false;
+            const emitter = {
+                send: async (data) => {
+                    if (closed)
+                        return;
+                    // Wait for available credit from client
+                    await controller.acquireCredit();
+                    if (closed)
+                        return;
+                    const dataFrame = {
+                        type: FrameType.STREAM_DATA,
+                        flags: FrameFlags.NONE,
+                        streamId: frame.streamId,
+                        sequenceId: this.sequenceId++,
+                        payload: data,
+                    };
+                    this.sendFrame(dataFrame, sessionId);
+                },
+                close: () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    this.activeEmitters.delete(frame.streamId);
+                    this.streamControllers.delete(frame.streamId);
+                    const closeFrame = {
+                        type: FrameType.STREAM_CLOSE,
+                        flags: FrameFlags.END_STREAM,
+                        streamId: frame.streamId,
+                        sequenceId: this.sequenceId++,
+                        payload: new Uint8Array(0),
+                    };
+                    this.sendFrame(closeFrame, sessionId);
+                },
+                error: (err) => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    this.activeEmitters.delete(frame.streamId);
+                    this.streamControllers.delete(frame.streamId);
+                    this.sendError(frame.streamId, err.message, sessionId);
+                },
+                onCancel: (cb) => {
+                    cancelCallback = cb;
+                    emitter.__cancelCallback = cb;
+                },
+            };
+            this.activeEmitters.set(frame.streamId, emitter);
+            handler(reqPayload, emitter);
+        }
+        catch (err) {
+            this.sendError(frame.streamId, `[MalformedStreamInit] ${err.message}`);
+        }
+    }
+    handleHandshake(frame) {
+        try {
+            const reader = new BinaryReader(frame.payload);
+            const sessionId = reader.readString();
+            const lastAckSeq = reader.readUint32();
+            const session = this.sessionRegistry.getSession(sessionId);
+            if (!session) {
+                return;
+            }
+            // Replay lost frames from ring buffer
+            const replayFrames = session.ringBuffer.getFramesAfter(lastAckSeq);
+            for (const replay of replayFrames) {
+                const replayCopy = {
+                    ...replay,
+                    flags: replay.flags | FrameFlags.RESUMED,
+                };
+                const bytes = encodeFrame(replayCopy);
+                this.transport.send(bytes);
+            }
+            // Send Handshake ACK
+            const ackPayload = new BinaryWriter()
+                .writeString(sessionId)
+                .writeUint32(replayFrames.length)
+                .finish();
+            const ackFrame = {
+                type: FrameType.HANDSHAKE_ACK,
+                flags: FrameFlags.NONE,
+                streamId: 0,
+                sequenceId: this.sequenceId++,
+                payload: ackPayload,
+            };
+            const bytes = encodeFrame(ackFrame);
+            this.transport.send(bytes);
+        }
+        catch {
+            // Ignored
+        }
+    }
+}
+//# sourceMappingURL=host.js.map

package/dist/packages/native-host/src/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../../../packages/native-host/src/host.ts"],"names":[],"mappings":"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"}

package/dist/packages/native-host/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './host.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/packages/native-host/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/native-host/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/packages/native-host/src/index.js

@@ -0,0 +1,2 @@
+export * from './host.js';
+//# sourceMappingURL=index.js.map

package/dist/packages/native-host/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/native-host/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "aether-wv",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Aether-WV: The Heterogeneous Local IPC Fabric for Modern WebViews",
+  "main": "dist/index.js",
+  "files": [
+    "dist/index.*",
+    "dist/packages",
+    "bin",
+    "packages/platform-templates"
+  ],
+  "type": "module",
+  "bin": {
+    "aetherc": "./bin/aetherc.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/tests/*.test.js",
+    "test:src": "tsc && node --test dist/tests/*.test.js",
+    "demo": "tsc && node dist/examples/run-demo.js",
+    "benchmark": "tsc && node dist/tests/benchmark.test.js"
+  },
+  "keywords": [
+    "webview",
+    "ipc",
+    "bridge",
+    "binary-protocol",
+    "reactive-streams",
+    "backpressure",
+    "wkwebview",
+    "android-webview"
+  ],
+  "author": "Aether Architecture Team",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/packages/platform-templates/android/AetherNativeDriver.kt

@@ -0,0 +1,57 @@
+//
+//  AetherNativeDriver.kt
+//  Aether-WV Android Chromium Driver
+//
+//  Production WebViewCompat integration with binary WebMessagePort and origin validation
+//
+
+package io.aether.webview
+
+import android.net.Uri
+import android.webkit.WebView
+import androidx.webkit.WebMessageCompat
+import androidx.webkit.WebMessagePortCompat
+import androidx.webkit.WebViewCompat
+import androidx.webkit.WebViewFeature
+import java.util.concurrent.Executors
+
+class AetherAndroidDriver(
+    private val webView: WebView,
+    private val allowedOrigins: Set<String>,
+    private val onFrameReceived: (ByteArray) -> Unit
+) {
+    private val backgroundExecutor = Executors.newSingleThreadExecutor()
+    private var nativePort: WebMessagePortCompat? = null
+
+    init {
+        setupDriver()
+    }
+
+    private fun setupDriver() {
+        if (!WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) {
+            throw UnsupportedOperationException("WEB_MESSAGE_LISTENER is required for Aether-WV")
+        }
+
+        // Establish channel messaging on document load
+        WebViewCompat.addWebMessageListener(
+            webView,
+            "aetherNativeChannel",
+            allowedOrigins
+        ) { _, message, sourceOrigin, isMainFrame, _ ->
+            // Extract raw bytes or channel port
+            val bytes = message.data?.toByteArray(Charsets.ISO_8859_1)
+            if (bytes != null) {
+                backgroundExecutor.execute {
+                    onFrameReceived(bytes)
+                }
+            }
+        }
+    }
+
+    fun sendFrameToWeb(data: ByteArray) {
+        val message = WebMessageCompat(data.toString(Charsets.ISO_8859_1))
+        webView.post {
+            nativePort?.postMessage(message)
+        }
+    }
+}

package/packages/platform-templates/ios/AetherNativeDriver.swift

@@ -0,0 +1,78 @@
+//
+//  AetherNativeDriver.swift
+//  Aether-WV iOS WebKit Driver
+//
+//  Production WebKit multi-process integration using WKContentWorld and WKScriptMessageHandlerWithReply
+//
+
+import Foundation
+import WebKit
+
+public final class AetherIosDriver: NSObject, WKScriptMessageHandlerWithReply {
+    private weak var webView: WKWebView?
+    private let contentWorldName = "AetherIsolatedWorld"
+    private let handlerName = "aether"
+    private var onFrameReceived: ((Data) -> Void)?
+
+    public init(webView: WKWebView, onFrameReceived: @escaping (Data) -> Void) {
+        self.webView = webView
+        self.onFrameReceived = onFrameReceived
+        super.init()
+        self.setupDriver()
+    }
+
+    private func setupDriver() {
+        guard let webView = self.webView else { return }
+        
+        let world = WKContentWorld.world(name: contentWorldName)
+        let ucc = webView.configuration.userContentController
+        
+        // Register script message handler in isolated content world to prevent page XSS access
+        ucc.addScriptMessageHandler(self, contentWorld: world, name: handlerName)
+        
+        // Inject bootstrap hook to bridge message to page context
+        let bootstrapScript = """
+        (function() {
+            if (window.__aether_initialized) return;
+            window.__aether_initialized = true;
+            console.log('[Aether-WV] Isolated bridge attached');
+        })();
+        """
+        let userScript = WKUserScript(source: bootstrapScript, injectionTime: .atDocumentStart, forMainFrameOnly: false, in: world)
+        ucc.addUserScript(userScript)
+    }
+
+    // MARK: - WKScriptMessageHandlerWithReply
+    public func userContentController(
+        _ userContentController: WKUserContentController,
+        didReceive message: WKScriptMessage,
+        replyHandler: @escaping (Any?, String?) -> Void
+    ) {
+        guard let dict = message.body as? [String: Any],
+              let b64 = dict["payload"] as? String,
+              let data = Data(base64Encoded: b64) else {
+            replyHandler(nil, "[AetherIosDriver] Malformed binary payload")
+            return
+        }
+
+        // Process incoming frame on background queue
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            self?.onFrameReceived?(data)
+            replyHandler(["status": "ack"], nil)
+        }
+    }
+
+    // MARK: - Dispatch frame back to WebView
+    public func sendFrameToWeb(data: Data) {
+        let b64 = data.base64EncodedString()
+        let js = "window.__aether_native_dispatch && window.__aether_native_dispatch('\(b64)');"
+        
+        DispatchQueue.main.async { [weak self] in
+            self?.webView?.evaluateJavaScript(js, in: nil, in: .page) { _, error in
+                if let error = error {
+                    print("[AetherIosDriver] evaluateJavaScript error: \(error.localizedDescription)")
+                }
+            }
+        }
+    }
+}