docs: the Store in the framework (shared catalog format, keys, tooling, trust model, adding it)

- docs/STORE.md: one signed catalog for every app (format 2, `apps` per item, field rules), Ed25519
  signing and key rotation, `waybetter store build|sign|verify` with an app config, install links,
  the trust model, and how an app adds the Store (StoreConfig, command wrappers, InstallHost,
  StoreView, tokens, strings).
- README: `store` in the layout and in what the host gives an app; the shell's Store modules.
- npm README: the Store components, models, schema and command.
This commit is contained in:
CRTkafa 2026-09-29 11:21:17 +07:00
parent f116f1b10b
commit 3e6cbe0773
3 changed files with 176 additions and 1 deletions

View file

@ -70,6 +70,8 @@ crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfi
src/update.rs silent-update scheduling and crash handshake src/update.rs silent-update scheduling and crash handshake
src/tabs.rs TabLayout/TabState/OpenRequest, link modes, shortcut and drag validation, src/tabs.rs TabLayout/TabState/OpenRequest, link modes, shortcut and drag validation,
deck ColumnConfig bounds and unread caps deck ColumnConfig bounds and unread caps
src/store/ install links, download allow-list, signed multi-app store catalog, staging
and installs; downloads with feature "net" (docs/STORE.md)
src/host.rs (feature "tauri") webview helpers, shell events, system menu src/host.rs (feature "tauri") webview helpers, shell events, system menu
packages/runtime/src/ page runtime core (TypeScript, no dependencies) packages/runtime/src/ page runtime core (TypeScript, no dependencies)
site.ts SiteAdapter (the page half of the adapter) + configureRuntime site.ts SiteAdapter (the page half of the adapter) + configureRuntime
@ -92,7 +94,12 @@ packages/shell/src/ shell core (TypeScript, no dependencies)
updateModel.ts titlebar update chip updateModel.ts titlebar update chip
windowControls.ts caption buttons, resize grips, system menu (Tauri API injected) windowControls.ts caption buttons, resize grips, system menu (Tauri API injected)
chrome.ts titlebar/toolbar/resize-border sizes (match policy.rs) chrome.ts titlebar/toolbar/resize-border sizes (match policy.rs)
packages/waybetter/ the published npm package (runtime + shell as ESM + .d.ts, theme.schema.json) storeModel.ts storeMessages.ts Store wire types, item states, permission words; wb.store/install/permission.*
installController.ts the install screen's state machine (links, drops, store items, confirm)
InstallDialog.tsx StoreView.tsx store.css the install screen and the Store view (React peer, --wb-* tokens)
packages/waybetter/ the published npm package (runtime + shell as ESM + .d.ts, theme.schema.json,
store-catalog.schema.json, the `waybetter store build|sign|verify` command)
docs/STORE.md the Store: shared catalog format, signing and keys, tooling, trust model, how to add it
packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies) packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies)
``` ```
@ -198,6 +205,13 @@ site, and a shell save can never change it (`ProfileSettings::keep_accounts_from
- `hotfix`: minisign-verified, schema-checked, monotonic, expiring data; delivered frozen as data. - `hotfix`: minisign-verified, schema-checked, monotonic, expiring data; delivered frozen as data.
- `update`: check schedule with jitter, crash handshake (automatic apply off after two failed boots). - `update`: check schedule with jitter, crash handshake (automatic apply off after two failed boots).
- `tabs`: shell payloads and validation; `deliver_script` hands JSON to a runtime member or parks it. - `tabs`: shell payloads and validation; `deliver_script` hands JSON to a runtime member or parks it.
- `store`: the wayBetter Store for any app from a `StoreConfig` (app id, link scheme, store URL,
public keys with rotation, download hosts): `waybetter://install` link parsing, the allow-list,
size caps, catalog verification (Ed25519, strict schema, each app sees only its items), `Store`
(pending links, staged installs, commit of exactly the staged bytes, records, offline catalog),
and with feature `net` no-redirect/no-cookie downloads. The shell half is `waybetter/shell`'s
`InstallHost`, `StoreView` and install controller; the tooling is `waybetter store`
(docs/STORE.md).
- `host` (feature `tauri`): `shell_only`, `tab_only`, `site_tab_only`, `emit_shell`, `tab_webview`, - `host` (feature `tauri`): `shell_only`, `tab_only`, `site_tab_only`, `emit_shell`, `tab_webview`,
`eval_in_site_tabs`, `navigate_tab`, `tab_action`, `forward_shortcut`, `forward_link_drag`, `eval_in_site_tabs`, `navigate_tab`, `tab_action`, `forward_shortcut`, `forward_link_drag`,
`read_json`/`write_json`, `remove_profile_dirs`, `prune_profile_dirs`, `migrate_identifier`, `read_json`/`write_json`, `remove_profile_dirs`, `prune_profile_dirs`, `migrate_identifier`,

149
docs/STORE.md Normal file
View file

@ -0,0 +1,149 @@
# The wayBetter Store, install links and the install screen
Every wayBetter app can install themes and plugins from a dropped file, a `waybetter://install`
link or the signed wayBetter Store, always through its install screen. The framework has all of it:
the rules and the state (waybetter-host `store`), the UI (`waybetter/shell/InstallDialog`,
`waybetter/shell/StoreView`), the strings in every language (`wb.store.*`, `wb.install.*`,
`wb.permission.*` in the framework catalogs) and the tooling (`waybetter store build|sign|verify`).
An app adds its settings, its Tauri command wrappers, its theme format and its look.
## One catalog, many apps
The store is one folder, `https://waybetter.fyi/store/`, with one signed catalog shared by every
app (`catalog.json` + `catalog.json.sig`). Each item names the apps it is for; an app verifies the
whole file, then keeps only its own items: it never shows, stages or installs another app's item,
even one listed in the same signed file.
```json
{ "format": 2, "name": "wayBetter Store", "generatedAt": "2026-09-29T04:18:08Z", "items": [
{ "apps": ["x"], "kind": "plugin", "id": "thread-reader", "name": "Thread Reader", "author": "wayBetter",
"version": "1.1.2", "description": "…", "category": "reading", "tags": ["threads"],
"url": "https://waybetter.fyi/store/plugins/bt-thread-reader.plugin.js", "file": "bt-thread-reader.plugin.js",
"sha256": "<64 lowercase hex>", "size": 12345, "preview": "https://waybetter.fyi/store/previews/plugin-thread-reader.svg",
"permissions": ["ui", "clipboard", "commands", "network:none"] },
{ "apps": ["x"], "kind": "theme", "id": "nord", "name": "Nord", "author": "", "version": "1.0.0",
"description": "…", "category": "dark", "tags": ["dark"], "url": "https://waybetter.fyi/store/themes/nord.json",
"sha256": "…", "size": 1700, "preview": "…", "colors": { "bg": "#232831", "surface": "#2e3440", "text": "#eceff4", "accent": "#88c0d0" } }
] }
```
JSON Schema: `waybetter/store-catalog.schema.json` (npm package). The rules apps enforce
(waybetter-host `store::catalog`, mirrored by the CLI):
| Field | Rule |
| --- | --- |
| `format` | `2`. An app that reads another format says "update the app". Format 1 (before `apps`) is gone. |
| `apps` | 1–16 distinct app ids (`[a-z0-9-]{1,32}`), e.g. `"x"`; an item for several apps lists each. |
| `kind`, `id` | `theme` or `plugin`; `[a-z0-9-]{1,40}`, unique per app and kind. |
| `name`, `author`, `version`, `description`, `category`, `tags` | plain text (no control characters), ≤ 60 / 60 / 32 / 600 / 32 characters, ≤ 12 tags of ≤ 32. Known categories show in the reader's language (`wb.store.category.*`). |
| `url`, `preview` | https; for the reading app's own items, on its download hosts (below). |
| `file` | plugins only: `name.plugin.js` (letters, digits, `-_. `), unique per app ignoring case. |
| `sha256`, `size` | of the exact file; size 1 byte … 2 MiB. |
| `permissions` | plugins only: the header's `@permissions` (`null` = no line, legacy). |
| `colors` | themes only: `#rrggbb` swatches for the card. |
Also refused: unknown fields anywhere, more than 500 items, a catalog over 1 MiB, a signature file
over 512 bytes. A malformed item for another app refuses the whole catalog (one file, one set of
rules); another app's download hosts are not held to this app's list.
## Signing and keys
The signature is Ed25519 over the exact catalog bytes (`verify_strict`), base64 of 64 bytes in
`catalog.json.sig`. Apps compile in the public keys (base64 of the raw 32 bytes) and accept a
catalog signed by any of them, so a key rotates in three steps: ship an app version that lists the
new key next to the old one, re-sign the catalog with the new key, drop the old key in a later
version. The private key is a PKCS#8 PEM that never leaves the machine it was made on; the CLI never
prints, copies or moves it.
## Tooling: `waybetter store`
```sh
waybetter store build --config store.config.mjs [--out public/store] [--base https://waybetter.fyi/store/]
waybetter store sign --init --key ~/.keys/store.key --pub keys/store.pub # once; never overwrites
waybetter store sign public/store/catalog.json --key ~/.keys/store.key --pub keys/store.pub
waybetter store verify public/store/catalog.json --pub keys/store.pub [--pub next.pub] [--app x]
```
`build` takes an app's config module:
```js
export default {
app: 'x',
async items() {
return [{ kind: 'plugin', id: 'focus', name: 'Focus', version: '1.0.0', category: 'focus', tags: [],
file: 'focus.plugin.js', permissions: ['ui', 'network:none'], path: 'plugins/focus.plugin.js', bytes: source,
preview: { path: 'previews/plugin-focus.svg', bytes: svg } }];
},
};
```
It replaces only that app's items (other apps' items and files stay), writes the files, fills
`apps`, `url`, `sha256` and `size`, removes files only the app's previous items used, and checks the
whole catalog with the apps' rules before writing anything. `pluginHeader(source)` (from
`waybetter/cli/store`) reads a plugin header for the config. `--key` defaults to
`$WAYBETTER_STORE_KEY`. Then deploy the folder as it is.
## Install links
`waybetter://install?kind=theme|plugin&url=<percent-encoded https URL>` (the scheme is the app's
`StoreConfig::scheme`): https only, a host on the app's list (`DEFAULT_HOSTS`: `waybetter.fyi`,
`cdn1.crt.fyi`, and `git.crt.fyi` only for raw files `/<owner>/<repo>/raw/…`), default port, no
credentials or fragment, at most 2048 characters, no other or repeated parameters. A plugin URL must
end in `name.plugin.js`, the name it is saved under. A link only proposes an install: it is queued
for the shell (`install-link` event, `install_pending` for links that arrived before the shell
listened) and nothing is downloaded until the shell asks.
## Trust model
- Only the app's local shell webview may call the install commands; site tabs and web pages never
can. The framework has no commands of its own: the app's wrappers call `shell_only` first.
- Native code downloads (no redirects, no cookies, size caps), hashes and validates, and stages
the exact bytes under a random token; the screen shows those bytes; `Store::commit` writes exactly
them after validating them again, and refuses a commit less than 0.6 s after staging. The screen
keeps Install disabled for 1 s; Enter never confirms.
- Store items: catalog signature first, then the download's size and sha256. A link to a store file
that matches the catalog still shows as a link.
- Plugins: `plugins::validate_plugin` (file name, ≤ 2 MiB, UTF-8 text without binary bytes, header
with `@name` + `@version`, valid `@permissions`, `network:none` refused when the code calls
network APIs), then `PluginStore::install` (atomic rename, never enabled on its own; an update keeps
the enabled state). Themes: a JSON object with a `name` (≤ 2 MiB), then the app's own theme
sanitizer, as for any import.
- Permissions are a declaration and a guard rail, not a sandbox.
## Adding the Store to an app
Native (`waybetter-host` with the `net` feature):
```rust
pub static STORE: StoreConfig = StoreConfig {
app_id: "kick", product: "wayBetter for Kick", user_agent: concat!("wayBetter-for-Kick/", env!("CARGO_PKG_VERSION")),
scheme: "waybetter", store_base: DEFAULT_STORE_BASE, public_keys: &[include_str!("../keys/store.pub")],
allowed_hosts: DEFAULT_HOSTS,
};
// setup: app.manage(Store::new(&STORE, &plugins::HOST, app_data_dir));
// deep links: emit_shell(app, EVENT_LINK, store.receive_link(url)).
```
Commands, each starting with `shell_only(&webview)?` and listed only in the shell's capability:
`install_pending` → `take_pending`, `install_stage_link {kind,url}` → `stage_link`,
`install_stage_file {name,text}` → `stage_file`, `install_cancel {token}` → `cancel`,
`install_commit {token,enable,themeId}` → `commit(…, run)` where `run` evaluates a plugin
start/stop script in the site's tabs, `plugin_remove {file}` → `remove_plugin`, `install_records`
→ `records`, `install_forget {kind,name}` → `forget`, `store_catalog {refresh}` → `catalog`,
`store_stage {item:{kind,id}}` → `stage_item`.
Shell (React):
```tsx
const controller = createInstallController({ backend: { invoke, listen }, t, site: 'Kick', theme: themeAdapter });
<InstallHost controller={controller} t={t} site="Kick" setOverlay={setOverlay} openSection={openSettings}
renderThemePreview={theme => <Preview theme={theme}/>}/>
<StoreView t={t} site="Kick" controller={controller} load={refresh => invoke('store_catalog', { refresh })}
builtinThemes={…} userThemes={…} onRemove={…} onUse={…} notify={…} relativeTime={…}/>
```
`t` is the app's translator with the framework catalogs merged in (their English is
`STORE_MESSAGES`); `{site}` fills in the site's name. Import `waybetter/shell/store.css` and map the
`--wb-*` tokens listed at its top to the app's theme on `.wbs, .wbi-backdrop, .wbi-drop`. Pass your
own `controls` (Button, SearchField, Segmented, EmptyState, Badge) and `classNames` to match the
app's settings UI; the defaults work on their own.

View file

@ -12,6 +12,10 @@ heavy Electron client alike: every wayBetter app is the same shell, runtime and
- **`waybetter/shell/*`**: pure models for the app chrome around the pages: address bar chips, - **`waybetter/shell/*`**: pure models for the app chrome around the pages: address bar chips,
dock/split-pane rules, dragged links, account profiles, the update chip, command palette dock/split-pane rules, dragged links, account profiles, the update chip, command palette
ranking and window controls. The Tauri window API is passed in by the caller, never imported. ranking and window controls. The Tauri window API is passed in by the caller, never imported.
And the wayBetter Store: the install screen and the Store view as React components (React is an
optional peer; everything else has no dependencies), their controller and models.
- **`waybetter store build|sign|verify`** and **`waybetter/store-catalog.schema.json`**: the tooling
and JSON Schema of the shared, signed wayBetter Store catalog.
Plain ESM with `.d.ts` types. Zero dependencies. Plain ESM with `.d.ts` types. Zero dependencies.
@ -63,6 +67,14 @@ pieces. The source comments document each module's contract.
- `profileModel`: the account profile model. - `profileModel`: the account profile model.
- `updateModel`: the titlebar update chip model. - `updateModel`: the titlebar update chip model.
- `windowControls`: native window calls for the titlebar, resize grips and caption buttons. - `windowControls`: native window calls for the titlebar, resize grips and caption buttons.
- `storeModel`, `storeMessages`: Store wire types, item states (install, update, changed locally, built in), permission badges, search; the English of every `wb.store.*`, `wb.install.*`, `wb.permission.*` message (translations in `waybetter/locales/*.json`).
- `installController`: the install screen's state (install links, dropped files, store items, confirm), given the app's native bridge and theme adapter.
- `InstallDialog` (`InstallHost`), `StoreView`, `store.css`: the install screen, the window drop target and the Store view, themed with `--wb-*` tokens. See docs/STORE.md in the repository.
**Command line**
- `waybetter store build --config store.config.mjs`: builds an app's part of the shared store folder (its items only, validated with the apps' own rules).
- `waybetter store sign [--init] --key <private key>` / `waybetter store verify --pub <key file>`: Ed25519 signature over the exact catalog bytes; any listed public key verifies (rotation). The private key is never printed or copied.
## Plugin UI kit (`runtime/ui`) ## Plugin UI kit (`runtime/ui`)