🚀 Signal Bridge

Lightweight communication bridge berbasis window.postMessage untuk komunikasi Host ↔ Iframe (Remote App) dengan fitur:

• 🔐 Optional encryption (AES)
• 🛡️ Origin validation (security)
• 🔁 Listener & emitter sederhana
• ♻️ Singleton instance (init hanya sekali)
• 🌐 Support UMD (browser global) + npm package

📦 Installation

npm install signal-bridge

atau via CDN (UMD):

<script src="signal-bridge.umd.js"></script>

⚙️ Konsep Dasar

Bridge ini digunakan untuk komunikasi antara:

• Host App (parent window)
• Remote App (iframe)

⚠️ Library ini hanya berjalan di dalam iframe (remote).

🧠 API Overview

1. Create Bridge (Singleton)

import { createBridge } from "signal-bridge";

const bridge = createBridge("my-app-id", {
  allowedHostOrigins: ["https://host.com"],
  cryptoKey: "SECRET_KEY", // optional
  debug: true
});

Hanya akan dibuat 1x (singleton). Jika dipanggil ulang, akan reuse instance lama.

2. Init Bridge

bridge.init();

Mengirim sinyal "ready" ke host.

3. Emit Event ke Host

bridge.emit("login", {
  userId: 123,
  token: "abc"
});

4. Listen Event dari Host

bridge.listen((message) => {
  console.log("Received:", message);

  if (message.type === "logout") {
    // handle logout
  }
});

5. Akses Global Instance

Jika ingin akses dari mana saja:

import { signalBridge } from "signal-bridge";

signalBridge().emit("ping", {});

⚠️ Pastikan sudah createBridge().init() sebelumnya.

6. Reset Bridge

import { resetBridge } from "signal-bridge";

resetBridge();

🔐 Security Features

✅ Origin Validation

allowedHostOrigins: ["https://host.com"]

Hanya origin ini yang bisa kirim message ke iframe.

✅ Encryption (Optional)

cryptoKey: "SECRET_KEY"

Payload akan otomatis:

• Encrypt saat emit
• Decrypt saat receive

📡 Message Format

type BridgeMessage = {
  type: string;
  payload: any;
  txn: string;
  __source: "host" | "remote";
  __origin?: string;
};

🌍 Browser (UMD) Usage

<script>
  const bridge = window.SignalBridge.createBridge("app-id", {
    allowedHostOrigins: ["https://host.com"]
  });

  bridge.init();

  bridge.listen((msg) => {
    console.log(msg);
  });

  bridge.emit("hello", { foo: "bar" });
</script>

🧪 Example Flow

Remote (Iframe)

const bridge = createBridge("child-app", {
  allowedHostOrigins: ["https://parent.com"]
});

bridge.init();

bridge.listen((msg) => {
  if (msg.type === "user-data") {
    console.log("User:", msg.payload);
  }
});

bridge.emit("ready", { status: "ok" });

⚠️ Important Notes

• ❗ Harus dijalankan di dalam iframe
• ❗ init() hanya akan trigger sekali (anti duplicate)
• ❗ Pastikan origin host sesuai (tidak akan menerima jika tidak match)
• ❗ Encryption hanya aktif jika cryptoKey di-set

🛠️ Available Exports

createBridge
signalBridge
resetBridge
encrypt
decrypt
generateKey

🧩 Internal Behavior

• Singleton global instance (globalBridge)
• Anti loop message (__source check)
• Auto ignore invalid message
• Optional debug logger

📄 Source

Implementasi utama bisa dilihat di file:

🧑‍💻 Author Notes

Dirancang untuk kebutuhan komunikasi microfrontend / iframe integration dengan fokus:

• Simple API
• Secure by default
• Minimal dependency

📜 License

MIT License © 2026 - EkaHersada