silentmode/theseus-site
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

theseus.x: the extensions page describes the sandbox community extensions run in

Browse source 
The trust note said a community extension runs with the same access as any
add-on. It now runs in its own process with read access to its own folder
only; the note says what that does and does not cover, and the build steps
list what an author has to change (promises, bundled dependencies, no
request filters). To be deployed with the Theseus release that ships the
sandbox, not before.
This commit is contained in:
Local Dev 2026-10-05 23:40:48 +02:00
parent a4cd819265
commit 21d3fd8663
1 changed files with 14 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
extensions/index.html
View file

@ -283,9 +283,12 @@
cannot substitute code under a trusted name.</p>
<div id="communityList"><div class="ext" style="color:var(--dim)">Loading the catalog…</div></div>
<div class="nomatch note" id="nomatchCommunity">No community extension matches that search.</div>
<div class="note"><b>Trust, stated plainly.</b> A community extension runs with the same access as any add-on —
treat one like an unsigned executable from that publisher. The signature proves <i>who</i> published it,
not that it is safe.</div>
<div class="note"><b>Trust, stated plainly.</b> The signature proves <i>who</i> published an extension, not that it
is safe. A community extension runs in its own sandboxed process: it can read only its own folder, cannot start
other programs, and cannot see your vault, your wallet or the browser's memory. It reaches Theseus only through
the capabilities its manifest declares, and it <i>can</i> use the network. Its panel and anything it injects
into pages still do what those capabilities allow, so read the capability list before installing. Older Theseus
builds ran extensions inside the browser itself — keep Theseus up to date.</div>
</section>
<section id="build">
@ -306,6 +309,14 @@
The bundled <a href="https://code.silentmode.st/silentmode/theseus/src/branch/master/TheseusNavigator/bundled-addons/notepad">Notepad</a>
is the smallest complete example; <a href="https://code.silentmode.st/silentmode/theseus/src/branch/master/TheseusNavigator/addons-host.js">addons-host.js</a>
is the full API. <code>id</code> is <code>[a-z0-9._-]</code>, 2–64 chars, and belongs to the first name that publishes it.</li>
<li><b>Mind the sandbox.</b> Your main script runs in its own process, not inside the browser:
<ul>
<li>It can read its own folder and write to <code>api.dataDir</code>, nothing else on disk. No child processes, workers or native modules.</li>
<li>Calls into Theseus return promises, <code>api.tabs.active()</code> included. <code>api.storage.get</code> stays synchronous.</li>
<li><code>api.require</code> and <code>api.import</code> are not available: bundle the modules you need in the package.</li>
<li>Request filters and site routes are for built-in add-ons. The vault is reachable only as <code>api.vault.derive</code> under your own id and <code>api.vault.requestUnlock</code>, where Theseus draws the prompt.</li>
<li><code>api.features.sandboxed</code> is <code>true</code> when this applies.</li>
</ul></li>
<li><b>Test it locally.</b> Settings › Extensions › <i>Open extensions folder</i>, drop the folder in, <i>Reload</i>.</li>
<li><b>Package it.</b> <code>tar -czf my-ext-1.0.0.tar.gz -C my-ext .</code> (max 8 MB; <code>addon.json</code> at the root or in a single top folder).</li>
<li><b>Publish it.</b> Open <a class="btn" href="./publish/" style="display:inline-block;padding:.35rem .8rem;border-radius:8px;background:var(--acid);color:#0b0e14;font-weight:650;text-decoration:none">Publish an extension →</a>