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:
parent
f116f1b10b
commit
3e6cbe0773
3 changed files with 176 additions and 1 deletions
16
README.md
16
README.md
|
|
@ -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
149
docs/STORE.md
Normal 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.
|
||||||
|
|
@ -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`)
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue