From e52e8d4b3852270286bba8b8d2d2dd9ed26a541b Mon Sep 17 00:00:00 2001 From: tsukino <87639218+0xtsukino@users.noreply.github.com> Date: Fri, 12 Jun 2026 14:41:26 +0200 Subject: [PATCH 1/4] blog: mobile-launch post + two new interactive components MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Announces the TLSNotary mobile app for iOS / Android and walks developers through the four-layer host-adapter stack the app sits on (plugin-sdk → host-contracts → host-react-native → consumer app). Two new MDX components: - renders the four user-facing app screens (browse plugins / approve plugin / approve reveal / verified result) as styled HTML phone-frame mockups — no screenshot assets, no light-vs-dark variants to chase, colors mirror the real app. - is an interactive layered architecture explorer in the same style as . Tap a layer to see what lives in it. Takes a `platform` prop so the same component can drive future posts about the extension or CLI variants. The post itself is ~1300 words: walkthrough, architecture, three build-your-own paths (plugin / extension / mobile) routing through the new tlsnotary Claude Code skill. --- blog/2026-06-12-mobile-launch/index.md | 72 +++ src/components/MobileAppShowcase/index.tsx | 267 +++++++++ .../MobileAppShowcase/styles.module.css | 563 ++++++++++++++++++ src/components/MobileFlowDiagram/index.tsx | 242 ++++++++ .../MobileFlowDiagram/styles.module.css | 210 +++++++ 5 files changed, 1354 insertions(+) create mode 100644 blog/2026-06-12-mobile-launch/index.md create mode 100644 src/components/MobileAppShowcase/index.tsx create mode 100644 src/components/MobileAppShowcase/styles.module.css create mode 100644 src/components/MobileFlowDiagram/index.tsx create mode 100644 src/components/MobileFlowDiagram/styles.module.css diff --git a/blog/2026-06-12-mobile-launch/index.md b/blog/2026-06-12-mobile-launch/index.md new file mode 100644 index 0000000..8981666 --- /dev/null +++ b/blog/2026-06-12-mobile-launch/index.md @@ -0,0 +1,72 @@ +--- +title: "TLSNotary on Mobile: A New App and a Path for Building Your Own" +authors: [tsukino] +description: "We just shipped TLSNotary for iOS and Android — both as a demo of selective-disclosure proofs on a phone, and as a reference implementation for developers who want to build their own TLSN-powered mobile app on top of the new @tlsn/host-react-native adapter." +--- + +import MobileAppShowcase from '@site/src/components/MobileAppShowcase'; +import MobileFlowDiagram from '@site/src/components/MobileFlowDiagram'; + +A few months ago, TLSNotary was a browser extension and a protocol. Today it's also a mobile app — iOS and Android, with the same plugin gallery you know from the extension, the same selective-disclosure guarantees, and a brand-new development story for anyone who wants to ship their own TLSN-powered app. + +The app itself is a **demo**: install it, browse the gallery, and produce a real proof against the public verifier. But it's also a **reference implementation**. Everything the app does on top of the TLSNotary protocol — the WebView that intercepts headers, the bottom sheet that asks for your approval, the native module that runs the Rust prover — is packaged so you can build the same stack into your own app without reading 2,000 lines of source. + + + +--- + +## A walk through the app + +The mobile app's flow mirrors the extension's, but reorganized for a phone-sized screen. Four states matter: + + + +**Browse plugins.** Each plugin is a small piece of TypeScript that knows how to prove something specific — your Spotify top artist, your bank balance above a threshold, your Twitter handle. The gallery is curated, but a developer can swap in their own registry. + +**Approve the plugin.** Before any code runs, the app shows you exactly which hosts the plugin will hit, what data it will request, and asks you to choose how strictly you want to gate it: approve every reveal one-by-one, or approve everything for the session. Rejecting at this point means the plugin never executes. + +**Approve the reveal.** After the prover has built the protocol up to the moment of disclosure, the app stops and shows you the actual bytes that will leave your device — every range, with REVEAL or HASH badges so you can tell what's plaintext and what's a commitment. This is the same gate the extension's strict-mode flow uses, ported to a mobile-native bottom sheet. + +**See the verified result.** The proof completes against the verifier, and the app shows you the value you proved (your top artist, your follower count) along with which host signed it. The full proof transcript is collapsible — most users don't need it, but it's there if you want to inspect or share it. + +The whole flow runs locally except for the TLS prover's outbound connection (to the target server) and its multi-party computation handshake (with the verifier). Your session cookie never leaves the device. + +--- + +## How the app is built + +The mobile app is one consumer of a four-layer stack we shipped alongside it. Tap a layer to see what lives in it: + + + +The protocol core (`@tlsn/plugin-sdk`) is the same code the browser extension runs. It owns the `HostCore` engine that evaluates a plugin's JavaScript inside a sandbox, drives the reactive `main()` loop, manages plugin state, and exposes the capabilities a plugin uses (`prove()`, `openWindow()`, `useHeaders()`, …). Nothing in there knows whether it's running in a service worker, a phone, or a Node CLI. + +Below it sits `@tlsn/host-contracts` — five interfaces every platform adapter implements. There's a `ProverClient` (how do I run a TLS prover on this platform?), a `WindowManager` (how do I open a tab/window/WebView and track it?), a `RequestInterceptor` (how do I capture the headers that fire inside it?), a `PluginRenderer` (how do I turn `DomJson` into UI?), and an `ApprovalUi` (how do I ask the user before doing something?). The contract is the bridge — it's why the same plugin runs on three radically different platforms unchanged. + +`@tlsn/host-react-native` is the mobile-specific glue that implements those five contracts. The window manager wraps `react-native-webview`. The request interceptor uses injected JavaScript inside the WebView to wrap `fetch` and `XMLHttpRequest`. The prover client is a thin shim over `tlsn-native`, an Expo native module that hosts a Rust port of the TLSNotary prover (Hermes can't run the WASM build, so we built the prover natively for iOS and Android). The renderer maps the plugin's `DomJson` tree onto React Native primitives — ``, ``, `` — with style adapters that translate browser CSS to React Native's `StyleSheet`. The approval UI is your app's responsibility: the adapter exposes hooks; you bring the bottom sheet. + +The top layer is **your app**. The mobile app at `app/mobile/` in the monorepo is one example — Expo Router screens, a plugin registry, the approval sheets you saw above, a theme. You can fork it or you can start from scratch, depending on how much UX you want to own. + +--- + +## Build your own + +There are three paths a developer can take into TLSNotary, and we ship a Claude Code skill for each of them. + +**Build a plugin.** If you want to prove data from a specific API — your bank, a SaaS dashboard, anything you can hit with `fetch` — write a plugin. Plugins are platform-agnostic: the same `swissbank.plugin.ts` runs on the mobile app, the browser extension, and the CLI. The `create-plugin` skill walks you through it. + +**Build your own extension.** If you want a Chrome / Firefox / Safari extension with your own branding and plugin curation, scaffold a new project on top of `@tlsn/host-extension`. You own the manifest, the popup, the gallery — the adapter brings the WindowManager, the offscreen WASM prover, the request interception, and the content-script renderer. The upstream TLSNotary extension is the canonical reference. + +**Build your own mobile app.** If you want TLSN on iOS or Android, scaffold on top of `@tlsn/host-react-native`. You own the screens, the gallery, and the theming; the adapter brings the WebView, the native prover, and the renderer. The TLSN mobile app at `app/mobile/` is the canonical reference. + +For all three paths, the canonical entry point is the **`tlsnotary` Claude Code skill** that lives in the monorepo at `.claude/skills/tlsnotary/SKILL.md`. Clone it into your own project under `.claude/skills/` and ask Claude something like *"add TLSNotary to my Expo app"* — Claude reads the skill, picks the right path, and walks you through scaffolding the consumer files. The skill is the canonical, auto-discoverable entry point so you don't have to remember any slash commands. + +The packages and the skill are all in the monorepo at [tlsnotary/tlsn-extension](https://github.com/tlsnotary/tlsn-extension). The mobile app lives under `app/mobile/`, the adapters under `packages/host-*`, and the skills under `.claude/skills/`. + +--- + +## What's next + +The mobile app is the first ship of the new host-adapter platform — there will be a CLI cut, an Electron adapter, and more reference plugins to follow. If you're building something with TLSNotary and the tooling has a sharp edge, please file an issue on GitHub or join us on Discord. We want to hear it. + +Install the app, run a proof, and let us know what you build. diff --git a/src/components/MobileAppShowcase/index.tsx b/src/components/MobileAppShowcase/index.tsx new file mode 100644 index 0000000..39cbd1e --- /dev/null +++ b/src/components/MobileAppShowcase/index.tsx @@ -0,0 +1,267 @@ +import React from 'react'; +import styles from './styles.module.css'; + +/** + * Four mockup screens of the TLSN mobile app, rendered as styled HTML — + * no screenshot assets, no light/dark variants to maintain, no app/store + * frames to chase. Colors and copy mirror the real React Native screens at: + * + * app/mobile/app/(tabs)/index.tsx → + * app/mobile/components/tlsn/PluginApprovalSheet.tsx → + * app/mobile/components/tlsn/RevealApprovalSheet.tsx → + * app/mobile/app/plugin/[id].tsx (success branch) → + */ + +export default function MobileAppShowcase() { + return ( +
+ + + + + + + + + + + + +
+ ); +} + +interface PhoneProps { + caption: string; + children: React.ReactNode; +} + +function Phone({ caption, children }: PhoneProps) { + return ( +
+
+ +
{caption}
+
+ ); +} + +/* -------------------------------------------------------------------------- */ +/* Screen 1 — plugin gallery */ +/* -------------------------------------------------------------------------- */ + +const GALLERY_PLUGINS: Array<{ logo: string; name: string; description: string; wip?: boolean }> = [ + { logo: '🐦', name: 'Twitter', description: 'Prove your handle and follower count.' }, + { logo: '🎵', name: 'Spotify', description: 'Prove your top artist of the year.' }, + { logo: '🦉', name: 'Duolingo', description: 'Prove your current streak.' }, + { logo: '🏦', name: 'Swiss Bank', description: 'Prove your balance is above a threshold.' }, + { logo: '🚗', name: 'Uber', description: 'Prove your lifetime trip count.', wip: true }, +]; + +function GalleryMockup() { + return ( +
+
+ Plugins +
+
+ {GALLERY_PLUGINS.map((p) => ( +
+ {p.logo} +
+
+ {p.name} + {p.wip && WIP} +
+ {p.description} +
+
+ ))} +
+ +
+ ); +} + +/* -------------------------------------------------------------------------- */ +/* Screen 2 — pre-execution plugin approval */ +/* -------------------------------------------------------------------------- */ + +function PluginApprovalMockup() { + return ( +
+
+
+
+
Spotify
+
by TLSNotary · v1.0.0
+
+ Prove your top Spotify artist of the year without revealing your account. +
+
WILL REQUEST DATA FROM
+
+ GET + + api.spotify.com/v1/me/top/artists + +
+
+ GET + + api.spotify.com/v1/me + +
+
View source on GitHub →
+
+ + + +
+
+
+ ); +} + +/* -------------------------------------------------------------------------- */ +/* Screen 3 — reveal approval */ +/* -------------------------------------------------------------------------- */ + +function RevealApprovalMockup() { + return ( +
+
+
+
+
Approve reveal to verifier
+
+ Review the bytes that will be sent to the verifier. +
+
+ + GET /v1/me/top/artists?limit=1&time_range=long_term HTTP/1.1 + + + Bearer •••••••••••••••••••••••••• + + + "items":[{'{'}"name":"Charli xcx" + +
+
+ + +
+
+
+ ); +} + +interface RevealRowProps { + label: string; + badge: string; + badgeKind: 'reveal' | 'hash'; + hashed?: boolean; + children: React.ReactNode; +} + +function RevealRow({ label, badge, badgeKind, hashed, children }: RevealRowProps) { + return ( +
+
+ {label} + + {badge} + +
+
+ {children} +
+
+ ); +} + +/* -------------------------------------------------------------------------- */ +/* Screen 4 — success */ +/* -------------------------------------------------------------------------- */ + +function SuccessMockup() { + return ( +
+
+ 🎵 + Spotify + VERIFIED +
+
+
Top Artist
+
Charli xcx
+
+
+
+ Verified on + api.spotify.com +
+
+ Time + just now +
+
+
+ + +
+ +
+ ); +} + +/* -------------------------------------------------------------------------- */ +/* Shared — tab bar */ +/* -------------------------------------------------------------------------- */ + +function TabBar({ active }: { active: 'plugins' | 'settings' | 'about' }) { + return ( +
+ + + +
+ ); +} + +function TabBarItem({ icon, label, isActive }: { icon: string; label: string; isActive: boolean }) { + return ( +
+ {icon} + {label} +
+ ); +} diff --git a/src/components/MobileAppShowcase/styles.module.css b/src/components/MobileAppShowcase/styles.module.css new file mode 100644 index 0000000..81f0232 --- /dev/null +++ b/src/components/MobileAppShowcase/styles.module.css @@ -0,0 +1,563 @@ +.showcase { + --mas-bg-light: #f0f2f5; + --mas-card-light: #ffffff; + --mas-text: #111827; + --mas-muted: #6b7280; + --mas-subtle: #374151; + --mas-tlsn: #243f5f; + --mas-divider: #e5e7eb; + --mas-frame: #1a1a1a; + --mas-frame-shine: rgba(255, 255, 255, 0.06); + --mas-mono: ui-monospace, 'SF Mono', Menlo, Consolas, monospace; + + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 28px 18px; + margin: 2rem auto; + padding: 0; + max-width: 760px; +} + +@media (max-width: 540px) { + .showcase { + grid-template-columns: 1fr; + gap: 24px; + } +} + +/* ============================================================ */ +/* Phone frame */ +/* ============================================================ */ + +.phoneWrap { + margin: 0; + display: flex; + flex-direction: column; + align-items: center; +} + +.phone { + position: relative; + width: 240px; + height: 460px; + background: var(--mas-frame); + border-radius: 32px; + padding: 4px; + box-shadow: + 0 0 0 1.5px rgba(0, 0, 0, 0.5), + 0 12px 28px rgba(0, 0, 0, 0.18), + inset 0 0 0 1px var(--mas-frame-shine); + box-sizing: border-box; + overflow: hidden; +} + +.notch { + position: absolute; + top: 8px; + left: 50%; + transform: translateX(-50%); + width: 72px; + height: 18px; + background: var(--mas-frame); + border-radius: 12px; + z-index: 2; +} + +.statusBar { + position: absolute; + top: 6px; + left: 12px; + right: 12px; + height: 22px; + display: flex; + justify-content: space-between; + align-items: center; + font-size: 9px; + font-weight: 600; + color: #fff; + z-index: 3; + pointer-events: none; + padding: 0 18px; +} + +.statusBar > span:first-child { + margin-left: -10px; +} + +.statusIcons { + display: flex; + gap: 4px; + align-items: center; + font-size: 9px; + margin-right: -10px; +} + +.screen { + position: relative; + top: 28px; + height: calc(100% - 32px); + background: var(--mas-bg-light); + border-radius: 26px; + overflow: hidden; + color: var(--mas-text); +} + +.caption { + margin-top: 14px; + font-size: 13px; + color: var(--ifm-font-color-base); + font-weight: 500; + text-align: center; +} + +:global([data-theme='dark']) .caption { + color: var(--ifm-font-color-base); +} + +/* ============================================================ */ +/* Gallery screen */ +/* ============================================================ */ + +.gallery { + position: absolute; + inset: 0; + display: flex; + flex-direction: column; +} + +.galleryHeader { + padding: 14px 16px 8px; + font-size: 22px; + font-weight: 700; + color: var(--mas-text); +} + +.galleryList { + flex: 1; + overflow: hidden; + padding: 4px 12px 12px; + display: flex; + flex-direction: column; + gap: 8px; +} + +.galleryCard { + display: flex; + align-items: center; + background: var(--mas-card-light); + border-radius: 10px; + padding: 10px 12px; + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05); +} + +.galleryLogo { + font-size: 24px; + width: 36px; + text-align: center; +} + +.galleryBody { + flex: 1; + margin-left: 10px; + min-width: 0; +} + +.galleryNameRow { + display: flex; + align-items: center; + gap: 6px; + margin-bottom: 2px; +} + +.galleryName { + font-size: 13px; + font-weight: 700; + color: var(--mas-tlsn); +} + +.galleryDescription { + display: block; + font-size: 10.5px; + color: var(--mas-muted); + line-height: 1.35; + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.wipBadge { + background: #fef3c7; + color: #92400e; + font-size: 8px; + font-weight: 700; + padding: 1px 4px; + border-radius: 3px; +} + +/* Tab bar */ +.tabBar { + display: flex; + border-top: 1px solid var(--mas-divider); + background: var(--mas-card-light); + padding: 6px 0 8px; +} + +.tabBarItem { + flex: 1; + display: flex; + flex-direction: column; + align-items: center; + gap: 2px; + font-size: 12px; + color: var(--mas-muted); +} + +.tabBarItemActive { + color: var(--mas-tlsn); +} + +.tabBarLabel { + font-size: 9px; + font-weight: 500; +} + +/* ============================================================ */ +/* Sheet screens (plugin approval + reveal approval) */ +/* ============================================================ */ + +.sheetScreen { + position: absolute; + inset: 0; + background: rgba(0, 0, 0, 0.05); + overflow: hidden; +} + +.sheetBackdrop { + position: absolute; + inset: 0; + background: rgba(0, 0, 0, 0.45); +} + +.sheetCard { + position: absolute; + left: 0; + right: 0; + bottom: 0; + background: var(--mas-card-light); + border-radius: 18px 18px 0 0; + padding: 8px 14px 12px; + max-height: 88%; + overflow: hidden; +} + +.sheetHandle { + width: 32px; + height: 4px; + background: #d1d5db; + border-radius: 2px; + margin: 4px auto 8px; +} + +.sheetTitle { + font-size: 16px; + font-weight: 700; + color: var(--mas-text); +} + +.sheetByline { + font-size: 10px; + color: var(--mas-muted); + margin-top: 1px; + margin-bottom: 8px; +} + +.sheetSubtitle { + font-size: 11px; + color: var(--mas-muted); + margin-top: 1px; + margin-bottom: 10px; +} + +.sheetBody { + font-size: 11px; + color: var(--mas-subtle); + line-height: 1.5; + margin-bottom: 10px; +} + +.sectionLabel { + font-size: 9px; + font-weight: 600; + color: var(--mas-muted); + letter-spacing: 0.05em; + margin-bottom: 6px; +} + +.requestRow { + display: flex; + align-items: center; + gap: 6px; + padding: 5px 0; + border-top: 1px solid var(--mas-divider); +} + +.requestRow:first-of-type { + border-top: none; +} + +.methodBadge { + background: #dbeafe; + color: #1e40af; + font-family: var(--mas-mono); + font-size: 8.5px; + font-weight: 700; + padding: 1px 5px; + border-radius: 3px; +} + +.requestHost { + font-family: var(--mas-mono); + font-size: 9.5px; + color: var(--mas-text); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + flex: 1; +} + +.requestPath { + color: var(--mas-muted); +} + +.sourceLink { + font-size: 10px; + color: #2563eb; + font-weight: 500; + margin-top: 8px; + margin-bottom: 4px; +} + +.sheetActions { + display: flex; + flex-direction: column; + gap: 6px; + padding-top: 8px; +} + +.sheetButton { + border: none; + border-radius: 8px; + padding: 8px 10px; + font-size: 11px; + font-weight: 600; + cursor: pointer; + font-family: inherit; +} + +.btnReject { + background: #fee2e2; + color: #991b1b; +} + +.btnManual { + background: #dbeafe; + color: #1e40af; +} + +.btnAllSession { + background: #d1fae5; + color: #065f46; +} + +/* ============================================================ */ +/* Reveal list */ +/* ============================================================ */ + +.revealList { + max-height: 230px; + overflow: hidden; + display: flex; + flex-direction: column; + gap: 6px; + margin-bottom: 10px; +} + +.revealRow { + background: #f9fafb; + border-radius: 6px; + padding: 6px 8px; +} + +.revealRowHeader { + display: flex; + justify-content: space-between; + align-items: center; + gap: 6px; + margin-bottom: 3px; +} + +.revealRowLabel { + font-size: 10px; + font-weight: 600; + color: var(--mas-subtle); +} + +.revealBadge { + font-size: 8px; + font-weight: 700; + padding: 1px 4px; + border-radius: 3px; + letter-spacing: 0.02em; +} + +.badgeReveal { + background: #d1fae5; + color: #065f46; +} + +.badgeHash { + background: #fef3c7; + color: #92400e; +} + +.revealPreview { + font-family: var(--mas-mono); + font-size: 9px; + color: #1f2937; + line-height: 1.5; + word-break: break-all; +} + +.revealHashed { + color: #9ca3af; + font-style: italic; +} + +/* ============================================================ */ +/* Success screen */ +/* ============================================================ */ + +.successScreen { + position: absolute; + inset: 0; + background: var(--mas-bg-light); + padding: 14px; + display: flex; + flex-direction: column; + gap: 10px; +} + +.successBanner { + background: linear-gradient(135deg, #1db954 0%, #1ed760 100%); + border-radius: 12px; + padding: 14px; + display: flex; + flex-direction: column; + align-items: center; + gap: 4px; + color: #fff; + position: relative; +} + +.successLogo { + font-size: 28px; +} + +.successPluginName { + font-size: 15px; + font-weight: 700; +} + +.successVerifiedBadge { + background: rgba(255, 255, 255, 0.25); + color: #fff; + font-size: 8.5px; + font-weight: 700; + letter-spacing: 0.05em; + padding: 2px 6px; + border-radius: 3px; + margin-top: 2px; +} + +.successResultCard { + background: var(--mas-card-light); + border-radius: 10px; + padding: 12px; + text-align: center; +} + +.successResultLabel { + font-size: 9.5px; + font-weight: 600; + color: #1db954; + text-transform: uppercase; + letter-spacing: 0.05em; + margin-bottom: 4px; +} + +.successResultValue { + font-size: 18px; + font-weight: 700; + color: var(--mas-text); +} + +.successDetailCard { + background: var(--mas-card-light); + border-radius: 10px; + padding: 10px 12px; +} + +.successDetailRow { + display: flex; + justify-content: space-between; + align-items: center; + padding: 3px 0; +} + +.successDetailRow + .successDetailRow { + border-top: 1px solid var(--mas-divider); + margin-top: 1px; +} + +.successDetailKey { + font-size: 10px; + color: var(--mas-muted); +} + +.successDetailVal { + font-family: var(--mas-mono); + font-size: 9.5px; + color: var(--mas-text); +} + +.successToggles { + display: flex; + flex-direction: column; + gap: 4px; +} + +.successToggle { + background: var(--mas-card-light); + border: 1px solid var(--mas-divider); + border-radius: 8px; + padding: 7px; + font-size: 10px; + color: var(--mas-subtle); + font-weight: 500; + cursor: pointer; + text-align: left; + font-family: inherit; +} + +.successBackBtn { + margin-top: auto; + background: var(--mas-tlsn); + color: #fff; + border: none; + border-radius: 8px; + padding: 10px; + font-size: 12px; + font-weight: 600; + cursor: pointer; + font-family: inherit; +} diff --git a/src/components/MobileFlowDiagram/index.tsx b/src/components/MobileFlowDiagram/index.tsx new file mode 100644 index 0000000..22f7c6d --- /dev/null +++ b/src/components/MobileFlowDiagram/index.tsx @@ -0,0 +1,242 @@ +import React, { useState } from 'react'; +import styles from './styles.module.css'; + +type LayerId = 'consumer' | 'adapter' | 'contracts' | 'sdk'; + +interface Layer { + id: LayerId; + title: string; + subtitle: string; + rows: string[]; + detail: React.ReactNode; +} + +interface MobileFlowDiagramProps { + /** + * Which platform's adapter to highlight. Default `mobile` flips the second + * layer to @tlsn/host-react-native. `extension` swaps it for + * @tlsn/host-extension. Lets the same component drive future posts. + */ + platform?: 'mobile' | 'extension' | 'cli'; +} + +const SDK_ROW: Layer = { + id: 'sdk', + title: '@tlsn/plugin-sdk', + subtitle: 'protocol core — platform-agnostic', + rows: ['HostCore', 'Handler · DomJson · PluginConfig', 'NativeFunctionEvaluator / QuickJS sandbox'], + detail: ( + <> + The protocol core. HostCore drives the plugin lifecycle: it + evaluates the plugin's JavaScript inside a sandbox, manages the + reactive main() loop, holds plugin state, and exposes the + capabilities the plugin uses (prove(), openWindow(), + useHeaders(), …). It owns every type the plugin and the host + pass each other — Handler, DomJson, + PluginConfig, WindowMessage. Nothing in here knows + whether it's running on a phone, in a browser, or in a Node CLI. + + ), +}; + +const CONTRACTS_ROW: Layer = { + id: 'contracts', + title: '@tlsn/host-contracts', + subtitle: 'adapter spec — what every platform must implement', + rows: ['ProverClient · WindowManager · RequestInterceptor', 'PluginRenderer · ApprovalUi', 'translateHandler (native-bridge helper)'], + detail: ( + <> + Five interfaces that describe what a platform adapter must do — make a + window, intercept its headers, render the plugin's UI, ask the user + for approval, run a prover. HostCore doesn't care how + these work; it just calls them. That's why the same plugin runs + unchanged on three radically different platforms: the contract is the + bridge. + + ), +}; + +function adapterRow(platform: 'mobile' | 'extension' | 'cli'): Layer { + if (platform === 'extension') { + return { + id: 'adapter', + title: '@tlsn/host-extension', + subtitle: 'platform glue — Manifest V3', + rows: [ + 'WindowManager (chrome.windows + webRequest)', + 'SessionManager + ProveManager (offscreen WASM prover)', + 'PluginRenderer (content-script DOM)', + ], + detail: ( + <> + Implements every contract using browser-extension primitives: + chrome.windows for managed windows, + webRequest.onBeforeRequest for header interception, an + offscreen document hosting the tlsn-wasm prover, content-script DOM + for rendering the plugin's UI. The upstream TLSN extension + consumes this exact package. + + ), + }; + } + if (platform === 'cli') { + return { + id: 'adapter', + title: '@tlsn/host-cli', + subtitle: 'platform glue — Node + Playwright', + rows: [ + 'PlaywrightWindowManager (BrowserContext)', + 'RustProverClient (spawns tlsn-prover binary)', + 'PlaywrightDomRenderer · ClackApprovalUi', + ], + detail: ( + <> + Implements the contracts with Playwright (windows + headers via{' '} + page.route()), a Rust prover binary built from the + native crate, and @clack/prompts for terminal-friendly + approval. Doubles as the cross-platform protocol test harness. + + ), + }; + } + return { + id: 'adapter', + title: '@tlsn/host-react-native', + subtitle: 'platform glue — Expo / React Native', + rows: [ + 'PluginWebView (header interception via injected JS)', + 'NativeProver (tlsn-native Expo module wrapping Rust)', + 'PluginRenderer (DomJson → RN primitives)', + ], + detail: ( + <> + Implements every contract using React Native and Expo. A + WebView with injected JavaScript wraps{' '} + fetch/XHR to intercept headers, an Expo + native module hosts the Rust prover (no WASM — Hermes can't run + it), and React Native primitives (View,{' '} + Text, TouchableOpacity) render the + plugin's DomJson tree. The TLSN mobile app consumes + this exact package. + + ), + }; +} + +function consumerRow(platform: 'mobile' | 'extension' | 'cli'): Layer { + if (platform === 'extension') { + return { + id: 'consumer', + title: 'Your browser extension', + subtitle: 'user-owned UI · manifest · plugin gallery', + rows: ['Popup, background service worker, content scripts', 'Plugin registry', 'Your branding + UX'], + detail: ( + <> + The extension you ship. You own the manifest, the popup UI, the + gallery of plugins you curate, and the styling. Everything below this + line is the @tlsn/* stack the skill scaffolds for you. + + ), + }; + } + if (platform === 'cli') { + return { + id: 'consumer', + title: 'Your CLI tool / script', + subtitle: 'user-owned · CI / batch / local', + rows: ['Plugin runner script', 'Storage-state / cookie cache', 'Your prompts + logging'], + detail: ( + <> + The CLI you ship. A short script that wires createCliAdapter() + to your plugin list and lets users run proofs from a terminal — + interactively the first time, headlessly thereafter from a saved + Playwright storage state. + + ), + }; + } + return { + id: 'consumer', + title: 'Your Expo / React Native app', + subtitle: 'user-owned UI · screens · plugin gallery', + rows: ['PluginGalleryScreen, PluginRunnerScreen, SettingsScreen', 'Plugin registry + theming', 'PluginApprovalSheet · RevealApprovalSheet'], + detail: ( + <> + The mobile app you ship. You own the screens, the gallery of plugins + you curate, the approval sheets your users see, and the theming. + Everything below this line is the @tlsn/* stack the skill scaffolds + for you. + + ), + }; +} + +export default function MobileFlowDiagram({ platform = 'mobile' }: MobileFlowDiagramProps) { + const layers: Layer[] = [ + consumerRow(platform), + adapterRow(platform), + CONTRACTS_ROW, + SDK_ROW, + ]; + + const [activeId, setActiveId] = useState('adapter'); + const active = layers.find((l) => l.id === activeId) ?? layers[1]; + + return ( +
+
+

How the {platformLabel(platform)} integration stacks up

+

Tap a layer to see what lives in it.

+
+ +
+ {layers.map((layer, idx) => ( + + + {idx < layers.length - 1 && ( + + )} + + ))} +
+ +
+
{active.title}
+
{active.detail}
+
+
+ ); +} + +function platformLabel(platform: 'mobile' | 'extension' | 'cli'): string { + if (platform === 'extension') return 'extension'; + if (platform === 'cli') return 'CLI'; + return 'mobile'; +} + +function connectorLabel(idx: number): string { + // Between consumer (0) and adapter (1) → imports. + // Between adapter (1) and contracts (2) → implements. + // Between contracts (2) and sdk (3) → built on. + if (idx === 0) return 'imports'; + if (idx === 1) return 'implements'; + return 'built on'; +} diff --git a/src/components/MobileFlowDiagram/styles.module.css b/src/components/MobileFlowDiagram/styles.module.css new file mode 100644 index 0000000..62d33a9 --- /dev/null +++ b/src/components/MobileFlowDiagram/styles.module.css @@ -0,0 +1,210 @@ +.widget { + --mfd-card: var(--ifm-background-color); + --mfd-panel: var(--ifm-color-emphasis-100); + --mfd-text: var(--ifm-font-color-base); + --mfd-muted: var(--ifm-color-emphasis-700); + --mfd-line: var(--ifm-color-emphasis-200); + --mfd-line-strong: var(--ifm-color-emphasis-300); + --mfd-accent: #0969da; + --mfd-accent-soft: #ddf4ff; + --mfd-accent-border: #b6e3ff; + --mfd-tlsn: #243f5f; + --mfd-mono: ui-monospace, 'SF Mono', Menlo, Consolas, monospace; + + margin: 2rem auto; + padding: 24px 26px 20px; + max-width: 720px; + border-radius: 14px; + background: var(--mfd-panel); + border: 1px solid var(--mfd-line); + box-sizing: border-box; + color: var(--mfd-text); + font-size: 14px; + line-height: 1.5; +} + +:global([data-theme='dark']) .widget { + --mfd-accent: #58a6ff; + --mfd-accent-soft: #0a2540; + --mfd-accent-border: #1f6feb; + --mfd-tlsn: #6088b8; +} + +.header { + text-align: center; + margin-bottom: 18px; +} + +.title { + font-size: 18px; + font-weight: 600; + margin: 0 0 4px; + letter-spacing: -0.01em; + color: var(--mfd-text); +} + +.subtitle { + font-size: 13px; + margin: 0; + color: var(--mfd-muted); +} + +/* ------------------------------------------------------------ */ +/* Layer stack */ +/* ------------------------------------------------------------ */ +.stack { + display: flex; + flex-direction: column; + align-items: stretch; +} + +.layer { + position: relative; + display: block; + width: 100%; + text-align: left; + background: var(--mfd-card); + border: 1px solid var(--mfd-line-strong); + border-radius: 10px; + padding: 12px 16px; + font: inherit; + color: inherit; + cursor: pointer; + transition: + border-color 120ms ease, + box-shadow 120ms ease, + transform 120ms ease; +} + +.layer:hover { + border-color: var(--mfd-accent-border); + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06); +} + +.layer:focus-visible { + outline: 2px solid var(--mfd-accent); + outline-offset: 2px; +} + +.layer.active { + border-color: var(--mfd-accent); + box-shadow: 0 0 0 3px var(--mfd-accent-soft); +} + +.layer.consumer { + border-style: dashed; + border-color: var(--mfd-tlsn); +} + +.layer.consumer.active { + border-style: solid; + border-color: var(--mfd-tlsn); + box-shadow: 0 0 0 3px var(--mfd-accent-soft); +} + +.layerHeader { + display: flex; + justify-content: space-between; + align-items: baseline; + gap: 12px; + margin-bottom: 4px; + flex-wrap: wrap; +} + +.layerTitle { + font-family: var(--mfd-mono); + font-size: 14px; + font-weight: 600; + color: var(--mfd-text); +} + +.layerSubtitle { + font-size: 12px; + color: var(--mfd-muted); + font-style: italic; +} + +.layerRows { + list-style: none; + padding: 0; + margin: 6px 0 0; +} + +.layerRows li { + font-family: var(--mfd-mono); + font-size: 12px; + color: var(--mfd-muted); + line-height: 1.65; +} + +/* ------------------------------------------------------------ */ +/* Connectors between layers */ +/* ------------------------------------------------------------ */ +.connector { + display: flex; + align-items: center; + justify-content: center; + gap: 8px; + padding: 6px 0; +} + +.connectorLine { + width: 1px; + height: 14px; + background: var(--mfd-line-strong); +} + +.connectorLabel { + font-size: 11px; + color: var(--mfd-muted); + letter-spacing: 0.04em; + text-transform: uppercase; +} + +/* ------------------------------------------------------------ */ +/* Detail panel */ +/* ------------------------------------------------------------ */ +.detailPanel { + margin-top: 16px; + padding: 14px 16px; + background: var(--mfd-card); + border: 1px solid var(--mfd-line); + border-radius: 10px; +} + +.detailHeader { + font-family: var(--mfd-mono); + font-size: 13px; + font-weight: 600; + color: var(--mfd-accent); + margin-bottom: 6px; +} + +.detailBody { + font-size: 13.5px; + line-height: 1.6; + color: var(--mfd-text); +} + +.detailBody code { + font-family: var(--mfd-mono); + font-size: 12.5px; + background: var(--mfd-panel); + padding: 1px 5px; + border-radius: 4px; + border: 1px solid var(--mfd-line); +} + +/* ------------------------------------------------------------ */ +/* Narrow viewport */ +/* ------------------------------------------------------------ */ +@media (max-width: 540px) { + .widget { + padding: 18px 14px 14px; + } + + .layerHeader { + flex-direction: column; + gap: 2px; + } +} From 30a7f19268473e81b6e49f857a7cb201e03f4a88 Mon Sep 17 00:00:00 2001 From: tsukino <87639218+0xtsukino@users.noreply.github.com> Date: Fri, 12 Jun 2026 14:41:26 +0200 Subject: [PATCH 2/4] blog: more accurate mobile mockups + real code samples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mobile app rendering: - Bigger phone frames (280px vs 240px) so the content is readable - Real iOS-style status bar (time + signal bars + battery — no fake emoji icons) - Real navbar on each screen with the app's #243f5f background and white bold title (matches Expo Stack header) - Plugin gallery cards now match the real app's spacing, font sizes, and #243f5f plugin-name color - Success screen now uses the real horizontal banner layout (logo left, name + verified badge stacked right) with the key-result card overlapping the banner by 14px the way the real app does - All padding / typography / button styles aligned to the React Native source (PluginApprovalSheet.tsx, RevealApprovalSheet.tsx, plugin/[id].tsx) How-the-app-is-built section: - Replaced 4 paragraphs of architecture prose with 5 real code snippets pulled straight from app/mobile/components/tlsn/PluginScreen.tsx: MobilePluginHost setup, , , , and the executePlugin() call that ties it together. - Kept the for the structural overview, but the meat of the section is now "here's what the integration looks like in code", not a wall of text. Also: skills moved from .claude/skills/ to ./skills/ in the tlsn-extension repo; updated the link in this post accordingly. --- blog/2026-06-12-mobile-launch/index.md | 81 ++- src/components/MobileAppShowcase/index.tsx | 183 ++++--- .../MobileAppShowcase/styles.module.css | 517 ++++++++++-------- 3 files changed, 461 insertions(+), 320 deletions(-) diff --git a/blog/2026-06-12-mobile-launch/index.md b/blog/2026-06-12-mobile-launch/index.md index 8981666..5afaa93 100644 --- a/blog/2026-06-12-mobile-launch/index.md +++ b/blog/2026-06-12-mobile-launch/index.md @@ -33,19 +33,78 @@ The whole flow runs locally except for the TLS prover's outbound connection (to --- -## How the app is built +## How the app uses the libraries -The mobile app is one consumer of a four-layer stack we shipped alongside it. Tap a layer to see what lives in it: +The mobile app is one consumer of a four-layer stack: your app on top, `@tlsn/host-react-native` underneath it, `@tlsn/host-contracts` describing what every adapter implements, and `@tlsn/plugin-sdk` at the bottom — the same protocol core the browser extension runs. -The protocol core (`@tlsn/plugin-sdk`) is the same code the browser extension runs. It owns the `HostCore` engine that evaluates a plugin's JavaScript inside a sandbox, drives the reactive `main()` loop, manages plugin state, and exposes the capabilities a plugin uses (`prove()`, `openWindow()`, `useHeaders()`, …). Nothing in there knows whether it's running in a service worker, a phone, or a Node CLI. - -Below it sits `@tlsn/host-contracts` — five interfaces every platform adapter implements. There's a `ProverClient` (how do I run a TLS prover on this platform?), a `WindowManager` (how do I open a tab/window/WebView and track it?), a `RequestInterceptor` (how do I capture the headers that fire inside it?), a `PluginRenderer` (how do I turn `DomJson` into UI?), and an `ApprovalUi` (how do I ask the user before doing something?). The contract is the bridge — it's why the same plugin runs on three radically different platforms unchanged. - -`@tlsn/host-react-native` is the mobile-specific glue that implements those five contracts. The window manager wraps `react-native-webview`. The request interceptor uses injected JavaScript inside the WebView to wrap `fetch` and `XMLHttpRequest`. The prover client is a thin shim over `tlsn-native`, an Expo native module that hosts a Rust port of the TLSNotary prover (Hermes can't run the WASM build, so we built the prover natively for iOS and Android). The renderer maps the plugin's `DomJson` tree onto React Native primitives — ``, ``, `` — with style adapters that translate browser CSS to React Native's `StyleSheet`. The approval UI is your app's responsibility: the adapter exposes hooks; you bring the bottom sheet. - -The top layer is **your app**. The mobile app at `app/mobile/` in the monorepo is one example — Expo Router screens, a plugin registry, the approval sheets you saw above, a theme. You can fork it or you can start from scratch, depending on how much UX you want to own. +What that looks like in code is short. Every screen the user sees is a thin wrapper over four primitives the adapter ships. Here's how `PluginScreen.tsx` — the file that orchestrates a whole prove session — wires them together. + +**1. Set up the host.** `MobilePluginHost` wraps the SDK's `HostCore` and asks you for a handful of callbacks: how to run the native prover, how to render UI, how to open a WebView. The user-approval bottom sheets are *your* component; the host calls into them when it needs a decision. + +```tsx +const host = new MobilePluginHost({ + onProveUntilReveal: async (request, options) => { + // Run the protocol up to compute_reveal, before the user has approved + // anything — the result includes the byte ranges that *would* be revealed. + return await proverRef.current.prepareReveal({ ...request, proverOptions: options }); + }, + onProveFinalize: async (sessionId, approved) => { + // After the user approves the reveal bottom sheet, finalize the proof. + return await proverRef.current.finalizeReveal(sessionId, approved); + }, + onRevealApproval: ({ descriptors, approve, reject }) => { + setRevealApproval({ descriptors, approve, reject }); // shows + }, + onRenderPluginUi: (windowId, domJson) => setDomJson(domJson), + onOpenWindow: async (url) => { + setWebViewUrl(url); // mounts + return { windowId, uuid: `mobile-${windowId}`, tabId: 0 }; + }, + onCloseWindow: () => { setWebViewUrl(null); setDomJson(null); }, +}); +``` + +**2. Mount the native prover.** `` is a headless component that wraps the `tlsn-native` Expo module — a Rust port of the TLSNotary prover packaged as an iOS / Android native library (Hermes can't run the WASM build the extension uses, so we shipped one natively). The `ref` is what `MobilePluginHost` calls `prepareReveal()` and `finalizeReveal()` against. + +```tsx + setProverReady(true)} + onError={(err) => setError(err.message)} + onProgress={handleProveProgress} +/> +``` + +**3. Intercept headers in a WebView.** When the plugin calls `openWindow()`, your app mounts ``, which loads the URL and runs injected JavaScript to wrap `fetch` and `XMLHttpRequest`. Every request fires `onHeaderIntercepted`, and your app routes that into the running plugin via `host.emitHeaderIntercepted()`. + +```tsx + { + host.emitHeaderIntercepted(eventEmitter, windowId, header); + }} +/> +``` + +**4. Render the plugin's UI.** Plugins describe their UI as `DomJson` — a JSON tree of `div` / `button` / `text` nodes. `` walks that tree and renders it as React Native primitives (``, ``, ``), translating any CSS the plugin emits to RN's `StyleSheet`. Click handlers route back to the host so the plugin can react. + +```tsx + host.emitPluginAction(eventEmitter, windowId, handlerName)} +/> +``` + +**5. Run the plugin.** Everything above is plumbing. The actual entry point is one line: + +```tsx +await host.executePlugin(pluginCode, { eventEmitter }); +``` + +That's the whole integration. The approval sheets, the plugin gallery, the theming, the settings — those are yours to design. The TLSN-specific machinery is the snippets above plus the components that render them. The reference implementation at [`app/mobile/`](https://github.com/tlsnotary/tlsn-extension/tree/main/app/mobile) is around 600 lines on top of the adapter; you can fork it or start from scratch depending on how much UX you want to own. --- @@ -59,9 +118,9 @@ There are three paths a developer can take into TLSNotary, and we ship a Claude **Build your own mobile app.** If you want TLSN on iOS or Android, scaffold on top of `@tlsn/host-react-native`. You own the screens, the gallery, and the theming; the adapter brings the WebView, the native prover, and the renderer. The TLSN mobile app at `app/mobile/` is the canonical reference. -For all three paths, the canonical entry point is the **`tlsnotary` Claude Code skill** that lives in the monorepo at `.claude/skills/tlsnotary/SKILL.md`. Clone it into your own project under `.claude/skills/` and ask Claude something like *"add TLSNotary to my Expo app"* — Claude reads the skill, picks the right path, and walks you through scaffolding the consumer files. The skill is the canonical, auto-discoverable entry point so you don't have to remember any slash commands. +For all three paths, the canonical entry point is the **`tlsnotary` Claude Code skill** that lives in the monorepo at [`skills/tlsnotary/SKILL.md`](https://github.com/tlsnotary/tlsn-extension/blob/main/skills/tlsnotary/SKILL.md). Copy the `skills/` directory into your own project, point Claude Code at it, and ask something like *"add TLSNotary to my Expo app"* — Claude reads the skill, picks the right path, and walks you through scaffolding the consumer files. The skill is the canonical, auto-discoverable entry point so you don't have to remember any slash commands. -The packages and the skill are all in the monorepo at [tlsnotary/tlsn-extension](https://github.com/tlsnotary/tlsn-extension). The mobile app lives under `app/mobile/`, the adapters under `packages/host-*`, and the skills under `.claude/skills/`. +The packages and the skill are all in the monorepo at [tlsnotary/tlsn-extension](https://github.com/tlsnotary/tlsn-extension). The mobile app lives under `app/mobile/`, the adapters under `packages/host-*`, and the skills under `skills/`. --- diff --git a/src/components/MobileAppShowcase/index.tsx b/src/components/MobileAppShowcase/index.tsx index 39cbd1e..879a689 100644 --- a/src/components/MobileAppShowcase/index.tsx +++ b/src/components/MobileAppShowcase/index.tsx @@ -3,13 +3,13 @@ import styles from './styles.module.css'; /** * Four mockup screens of the TLSN mobile app, rendered as styled HTML — - * no screenshot assets, no light/dark variants to maintain, no app/store - * frames to chase. Colors and copy mirror the real React Native screens at: + * no screenshot assets, no light/dark variants to maintain. Colors and copy + * mirror the real React Native screens at: * - * app/mobile/app/(tabs)/index.tsx → + * app/mobile/app/(tabs)/index.tsx → * app/mobile/components/tlsn/PluginApprovalSheet.tsx → * app/mobile/components/tlsn/RevealApprovalSheet.tsx → - * app/mobile/app/plugin/[id].tsx (success branch) → + * app/mobile/app/plugin/[id].tsx (success branch) → */ export default function MobileAppShowcase() { @@ -42,11 +42,12 @@ function Phone({ caption, children }: PhoneProps) {