iCanText App Bridge

How it works

The iCanText App Bridge allows third-party web applications (running in a separate tab or window) to securely leverage the iCanText P2P network. It acts as a Decentralized OS where iCanText provides the identity, discovery, and encrypted transport layer.

• Discovery: Your app can request the list of peers in the active workspace.
• Identity: Use iCanText PeerIDs to identify users without a login system.
• Transport: Send and receive JSON data packets across the P2P mesh.
• Isolation: Each app is sandboxed to its domain and workspace.

The Security Handshake

To prevent unauthorized access, a strict handshake protocol is enforced:

1. Launch: A user types /app https://your-app.com in iCanText.
2. Hello: Your app opens and sends an ICT_HELLO via postMessage.
3. Init: iCanText verifies the origin and returns an instanceId, the localPeerId and the localPseudonym.
4. Ready: The bridge is established. All future communications are locked to this instance.

ICTBridgeSDK.js

We provide a lightweight, promise-based SDK to handle the complexity of postMessage communication and handshaking.

Include it in your HTML:

<script src="https://icantext.com/ICTBridgeSDK.js"></script>

API Reference

const connection = await sdk.init();
if (connection.status === 'READY') {
    console.log("Connected as:", connection.localPseudonym);
}

const peers = await sdk.getPeers();
// peer: {id, pseudonym, verified, isActiveOnApp}
const activePeers = peers.filter(p => p.isActiveOnApp);

const targets = ['peer_xyz...'];
const data = { action: 'move', x: 10, y: 20 };
sdk.sendData(targets, data);

sdk.onData((fromPeerId, payload) => {
    console.log(`Message from ${fromPeerId}:`, payload);
});

sdk.onProfileUpdate((newPseudonym) => {
    document.getElementById('display-name').textContent = newPseudonym;
});

const timeStr = await sdk.getServerTime(); 
// Returns string format: YYYYMMDDHHMMSS (e.g. "20260202101030")

// Close the app when the user clicks a "Quit" button
document.getElementById('quit-btn').onclick = () => sdk.closeApp();

// Post Text
const id = await sdk.postMessage({ text: "Hello!" });

// Post Image/File
sdk.postMessage({ 
    file: { 
        name: "image.png", 
        type: "image/png", 
        data: "data:image/png;base64,..." 
    } 
});

await sdk.editMessage("msg_123...", "Updated text content");

// From a configuration popup:
sdk.postAppContent("https://vote.app/", { 
    question: "Pizza or Tacos?", 
    votes: {} 
});

// On app startup inside the chat:
const state = await sdk.getAppContext();
console.log("Question:", state.question);

// When a user interacts (e.g. votes):
state.votes[myId] = "Pizza";
sdk.updateAppContext(state); 
// Result: All channel members see the update instantly.

const mode = sdk.getDisplayMode();

if (mode === 'MESSAGE') {
    renderCompactView(); // Simplified UI for the chat timeline
} else {
    renderFullEditor();  // Full UI for configuration or popups
}

sdk.onContextUpdate((updatedContext) => {
    console.log("New votes received!");
    refreshUI(updatedContext.votes);
});

const mid = sdk.getMessageId();
console.log("This app instance belongs to message:", mid);

SDK Source Code (Open Source)

The ICTBridgeSDK is a zero-dependency JavaScript class. It is designed to be robust against standalone execution and handles the multiplexing of messages between iCanText and your application logic.

/* SDK code loading... */

Usage Example: Shared Sticky Notes

Below is a minimal example of a collaborative app where users send notes to each other.

const sdk = new ICTBridgeSDK('my_collab_app');

async function startApp() {
    const connection = await sdk.init();
    
    if (connection.status === 'READY') {
        console.log(`Connected as: ${connection.localPseudonym}`);

        // Listen for incoming notes
        sdk.onData((from, payload) => {
            alert(`Note from ${from}: ${payload.text}`);
        });

        // Send a note to all known peers
        const peers = await sdk.getPeers();
        const peerIds = peers.map(p => p.id);
        sdk.sendData(peerIds, { text: 'Hello decentralized world!' });
    }
}

startApp();

Complete Usage Example

This example shows a simple "Status Update" app. When launched through iCanText, it fetches your contacts and allows you to broadcast your current activity to them.

// 1. Initialize the SDK with a unique Application ID
		const sdk = new ICTBridgeSDK('p2p_status_tracker');

		async function setup() {
		    // 2. Start the handshake with the parent iCanText window
		    const connection = await sdk.init();

		    if (connection.status === 'STANDALONE') {
			showUIError('Please launch this app from within iCanText using /app');
			return;
		    }

		    // 3. Handle incoming data from other peers
		    sdk.onData((senderId, payload) => {
			console.log(`Peer ${senderId} is now: ${payload.status}`);
			updateStatusBoard(senderId, payload.status);
		    });

		    // 4. Discovery: Fetch the list of peers in the current Workspace
		    const peers = await sdk.getPeers();
		    renderContactList(peers);
		}

		// 5. Sending Data: Encrypted P2P transmission
		function broadcastMyStatus(newStatus) {
		    sdk.getPeers().then(peers => {
			const targetIds = peers.map(p => p.id);
			
			// This JSON object will be E2EE encrypted and routed via Sealed Forward
			const packet = { 
			    type: 'STATUS_UPDATE', 
			    status: newStatus,
			    timestamp: Date.now() 
			};

			sdk.sendData(targetIds, packet);
		    });
		}

		setup();

async function sayHello() {
    // 1. Create the message
    const msgId = await sdk.postMessage({ 
        text: "I am computing the results..." 
    });
    
    // 2. Simulate work and update the same message
    setTimeout(async () => {
        await sdk.editMessage(msgId, "Computation complete: 42 ✅");
    }, 3000);
}

Best Practices

• Handle Disconnections: Always check window.opener before sending data; if the user closes iCanText, the bridge will break.
• Payload Size: While the P2P layer handles fragmentation, keep payloads under 1MB for optimal performance across the mesh.
• Origin Security: The SDK automatically ensures messages are only exchanged with the domain that launched the app.
• Validation: Always validate the structure of the payload received in onData as it comes from a remote peer's application instance.
• Frame Permissions: Your server must allow your app to be embedded in an iframe. Ensure your Content-Security-Policy does not have a restrictive frame-ancestors directive, and avoid the X-Frame-Options: DENY header.