@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/docs/en/security.md

@@ -0,0 +1,115 @@
+# Security
+
+PlayerVox OverCrow treats every widget as untrusted code, built-ins
+included: the same package checks, the same sandbox, the same permissions
+and the same consent apply to a PlayerVox widget and to yours. This page
+describes what that means for a widget author.
+
+## The sandbox
+
+Each widget runs behind two barriers.
+
+1. **The VM.** Your `logic.js` runs in its own QuickJS virtual machine with
+   a heap ceiling, a time budget per turn, a bounded stack and bounded
+   queues. There is no `eval`, no `Function` constructor, no module loader,
+   no `WebAssembly` and no shared memory; the only global besides
+   ECMAScript is the frozen SDK. Local time is UTC: the SDK applies the
+   user's offset for you.
+2. **The process.** Each VM runs in its own operating-system process that
+   needs no display, GPU, network or files, so its sandbox takes all of them
+   away. On Linux, Bubblewrap namespaces, a seccomp allowlist that kills the
+   process on any attempt to open a file, a socket or another process, and
+   a cgroup per widget. On Windows, a Less Privileged AppContainer without
+   capabilities, a Job Object per widget, and process mitigations that
+   forbid dynamic code and the window system.
+
+OverCrow draws everything itself: the VM sends a description of the view,
+never pixels, and never runs code in OverCrow's process. Hover, focus,
+pressed states and transitions are resolved by OverCrow, so a widget does
+not observe pointer motion it has not asked for through an event.
+
+Going over a budget ends only that widget. OverCrow shows a fixed error in
+its frame and restarts it after 1, 5 and 15 seconds, at most three times;
+a package or protocol error waits for the user to enable it again. The
+numbers are in [limits](limits.md#logic).
+
+## Permissions and consent
+
+A widget gets nothing it has not declared in `manifest.json`, and a
+declaration grants nothing by itself. When the widget is installed, the
+Control Center proposes each permission checked, and the user may uncheck
+any. Later, the user allows or takes back each permission in the Control
+Center; taking one back restarts the widget without it.
+OverCrow checks the permission again at every call of a service.
+
+Four permissions open general services: `network` (exact HTTPS routes,
+through OverCrow's broker), `storage` (a key-value store for this widget
+only), `clipboardWrite` (writing text, during a user action) and
+`gameEvents` (named game events).
+
+Capabilities give access to data and actions of OverCrow and of the user's
+accounts. A **sensitive** capability reveals personal data or the game
+being played: a widget that declares one cannot also declare `network` or
+`clipboardWrite`, and its storage lasts only as long as its process, so the
+data cannot leave the machine through the widget.
+
+Account connections (PlayerVox, Twitch) belong to OverCrow: sign-in, codes
+and tokens are drawn and kept by OverCrow, and a widget receives only the
+data its capability describes.
+
+Each permission, each capability and the services it opens are described
+in [services and permissions](services.md). Declare the least you need:
+reviewers read every permission and route, and users see them before they
+consent. Widgets tagged `built-in` in the signed catalog (PlayerVox widgets
+only) start with their declared permissions granted; an update that asks
+for more needs the user's consent, built-ins included.
+
+## User actions
+
+Services that change something for the user can be called only while the
+logic handles a real action of the user in the widget: a click, a key, an
+edit, a submitted form. A call from a timer, from a service answer or from
+a row of the options menu is refused with `gesture_required`. Widgets
+receive input only in OverCrow's Interactive mode; in Passive mode they are
+click-through. Deleting a note or a journal session also asks the user to
+confirm in a dialog drawn by OverCrow. See
+[calls that need a user action](services.md#calls-that-need-a-user-action).
+
+What the user writes to notes, ratings and chat never passes through your
+logic: a `form` with an `intent` sends the values of its own text fields and
+sliders, which OverCrow fills, edits and submits itself. Your logic can read
+them, not set them. See
+[forms that write user data](forms.md#forms-that-write-user-data).
+
+## What a widget cannot do
+
+- Read or write files, open sockets, reach the local network or any address
+  its manifest does not declare.
+- Start processes, load native code, compile code at runtime or fetch code:
+  the only code is the reviewed `logic.js` of the package.
+- See other widgets, their state, storage or permissions, or the game's
+  memory, window or input. OverCrow never injects into the game.
+- Draw outside its frame, cover or imitate OverCrow's frame, menus or
+  confirmations.
+- Read account tokens, cookies or credentials.
+- Read the clipboard.
+- Write to logs in production: `log.*` output appears only in a local
+  development session.
+- Grant itself a permission, or use a menu row as a user action.
+
+## What OverCrow verifies
+
+Every package is checked when it is admitted to the catalog and again each
+time OverCrow starts it: the signed catalog, the ledger of its files and
+the compiled view must match, or the widget does not start. See
+[the package](package.md#how-overcrow-checks-a-package) and
+[publishing and review](publishing.md).
+
+A version of the catalog can be suspended or revoked after its
+publication: OverCrow then stops the installed copy. See
+[version statuses](publishing.md#version-statuses).
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately, as described in the repository's
+[security policy](../../../SECURITY.md).

package/dist/content/docs/en/service-reference.md

@@ -0,0 +1,344 @@
+# Service reference
+
+Every service that the logic of a PlayerVox OverCrow widget can call, with
+what it requires, when it can be called, its parameters and its result.
+[Services and permissions](services.md) explains how calls, subscriptions,
+errors and user actions work; this page is the list.
+
+<!-- source: widgets/stopwatch/logic.ts -->
+```ts
+      if (canRead) {
+        state.stopwatch = next;
+      }
+    },
+    () => {},
+  );
+}
+```
+
+In the SDK, a service `stopwatch.subscribe` is the function
+`stopwatch.subscribe` of the `stopwatch` namespace. A call returns a
+promise of its result; a subscription takes a listener that receives each
+update.
+
+## How to read a service
+
+- **Kind**: a *call* is answered once; a *subscription* delivers a value at
+  once, then each new value.
+- **Requires**: the permission or the capability to declare in
+  [the manifest](manifest.md#permissions), which the user must grant.
+- **When it can be called**: at any time, or only during a
+  [user action](services.md#calls-that-need-a-user-action).
+- **Parameters**: the members of the object to pass; a `?` marks an
+  optional one. A type such as "text ≤ 128 bytes" gives a
+  [limit](limits.md).
+- **Result**, or **Each update** for a subscription: what the service
+  answers, and the error codes that are specific to it. Every service can
+  also fail with the general [error codes](services.md#errors).
+- **Shape**: the type of the result, described in
+  [result shapes](result-shapes.md).
+
+## Services
+
+<!-- generated:services -->
+### `storage.get`
+
+- **Kind**: call, answered once
+- **Requires**: permission `storage`
+- **When it can be called**: At any time
+- **Parameters**: `key`: text ≤ 128 bytes
+- **Result**: stored JSON value or `null`
+- **Shape**: JSON
+
+### `storage.set`
+
+- **Kind**: call, answered once
+- **Requires**: permission `storage`
+- **When it can be called**: At any time
+- **Parameters**: `key`: text ≤ 128 bytes; `value`: JSON
+- **Result**: `null`; `quota_exceeded` beyond 256 KiB
+- **Shape**: `null`
+
+### `storage.remove`
+
+- **Kind**: call, answered once
+- **Requires**: permission `storage`
+- **When it can be called**: At any time
+- **Parameters**: `key`: text ≤ 128 bytes
+- **Result**: `null`
+
+### `storage.keys`
+
+- **Kind**: call, answered once
+- **Requires**: permission `storage`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Result**: list of keys
+- **Shape**: list of text
+
+### `http.fetch`
+
+- **Kind**: call, answered once
+- **Requires**: permission `network`
+- **When it can be called**: At any time
+- **Parameters**: `url`: text ≤ 2 KiB; `method`: `GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE`; `contentType?`: `application/json` \| `text/plain`; `as`: `json` \| `text` \| `bytes` \| `image`
+- **Result**: `{ status, contentType }` with the body, ≤ the rule's `maxResponseBytes` (1 MiB when absent), or `{ status, asset }` from a body ≤ 1 MiB
+- **Shape**: [`HttpResponse`](result-shapes.md#httpresponse)
+
+### `clipboard.writeText`
+
+- **Kind**: call, answered once
+- **Requires**: permission `clipboardWrite`
+- **When it can be called**: Only during a user action
+- **Parameters**: `text`: text ≤ 16 KiB
+- **Result**: `null`
+
+### `gameEvents.subscribe`
+
+- **Kind**: subscription
+- **Requires**: permission `gameEvents`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ event, at }` for each declared event
+- **Shape**: [`GameEvent`](result-shapes.md#gameevent)
+
+### `session.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `session.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ elapsedMs, at }` counted from the start of the game process, or `null` without an active game
+- **Shape**: [`Session`](result-shapes.md#session) or `null`
+
+### `telemetry.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `telemetry.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ cpu, ram, cpuTemperature, gpuTemperature, sources }`, or `null` without an active game: `cpu` is the game's share of the whole machine in % (0–100), `ram` its resident bytes, temperatures are °C or `null`, `sources` `{ cpuTemperature, gpuTemperature }` says whether the host has each sensor
+- **Shape**: [`Telemetry`](result-shapes.md#telemetry) or `null`
+
+### `fps.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `fps.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ fps, stale, status }`: `fps` a number or `null`; the host sets `stale` 3 s after the last sample; `status` is `ready`, `waiting`, `unsupported`, `permission_denied`, `ambiguous`, `events_lost` or `unavailable`
+- **Shape**: [`Fps`](result-shapes.md#fps)
+
+### `media.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `media.read`
+- **When it can be called**: At any time
+- **Parameters**: `cover?`: boolean
+- **Each update**: `null` without a player, or `{ player, title, artists, playing, canPrevious, canPlayPause, canNext, cover }`: `player` an opaque ID, `artists` a list, `cover` an `asset:` handle of at most 512 px or `null`
+- **Shape**: [`Media`](result-shapes.md#media) or `null`
+
+### `media.previous`
+
+- **Kind**: call, answered once
+- **Requires**: capability `media.control`
+- **When it can be called**: Only during a user action
+- **Parameters**: `player?`: text ≤ 128 bytes
+- **Result**: `null`; `stale_context` when `player` is no longer current
+- **Shape**: `null`
+
+### `media.playPause`
+
+- **Kind**: call, answered once
+- **Requires**: capability `media.control`
+- **When it can be called**: Only during a user action
+- **Parameters**: `player?`: text ≤ 128 bytes
+- **Result**: `null`; `stale_context` when `player` is no longer current
+- **Shape**: `null`
+
+### `media.next`
+
+- **Kind**: call, answered once
+- **Requires**: capability `media.control`
+- **When it can be called**: Only during a user action
+- **Parameters**: `player?`: text ≤ 128 bytes
+- **Result**: `null`; `stale_context` when `player` is no longer current
+- **Shape**: `null`
+
+### `stopwatch.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `stopwatch.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ running, elapsedMs, at, shortcuts }`, or `null` without an active game; `shortcuts` `{ toggle, reset, bound }` holds host-formatted key chords
+- **Shape**: [`Stopwatch`](result-shapes.md#stopwatch) or `null`
+
+### `stopwatch.toggle`
+
+- **Kind**: call, answered once
+- **Requires**: capability `stopwatch.control`
+- **When it can be called**: Only during a user action
+- **Parameters**: none
+- **Result**: the new state, as in `stopwatch.subscribe`; `unavailable` when the host cannot act
+- **Shape**: [`Stopwatch`](result-shapes.md#stopwatch) or `null`
+
+### `stopwatch.reset`
+
+- **Kind**: call, answered once
+- **Requires**: capability `stopwatch.control`
+- **When it can be called**: Only during a user action
+- **Parameters**: none
+- **Result**: the new state, as in `stopwatch.subscribe`; `unavailable` when the host cannot act
+- **Shape**: [`Stopwatch`](result-shapes.md#stopwatch) or `null`
+
+### `notes.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `notes.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ active, notes }` of the user's single notes document; each note `{ id, title, body, items }`, each item `{ id, text, checked }`
+- **Shape**: [`Notes`](result-shapes.md#notes)
+
+### `notes.create`
+
+- **Kind**: call, answered once
+- **Requires**: capability `notes.write`
+- **When it can be called**: Only during a user action
+- **Parameters**: none
+- **Result**: `{ note }`, a new empty active note titled `Note {n}` in the user's language; `quota_exceeded` beyond 8
+- **Shape**: [`CreatedNote`](result-shapes.md#creatednote)
+
+### `notes.select`
+
+- **Kind**: call, answered once
+- **Requires**: capability `notes.write`
+- **When it can be called**: Only during a user action
+- **Parameters**: `note`: text ≤ 128 bytes
+- **Result**: `null`; the host stores the active note
+- **Shape**: `null`
+
+### `notes.setItem`
+
+- **Kind**: call, answered once
+- **Requires**: capability `notes.write`
+- **When it can be called**: Only during a user action
+- **Parameters**: `note`: text ≤ 128 bytes; `item`: text ≤ 128 bytes; `checked`: boolean
+- **Result**: `null`
+
+### `notes.delete`
+
+- **Kind**: call, answered once; the user confirms it first, in a dialog drawn by OverCrow
+- **Requires**: capability `notes.write`
+- **When it can be called**: Only during a user action
+- **Parameters**: `note`: text ≤ 128 bytes
+- **Result**: `null`, or `cancelled` when the user declines
+- **Shape**: `null`
+
+### `playervox.score.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `playervox.score.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ state, name, score, grade, ratingsCount, criteria }`: `state` is `idle`, `unsupported`, `loading`, `ready`, `no_ratings`, `not_found` or `unavailable`; `criteria` `{ gameplay, art, tech }`, each from 0 to 100 or `null`
+- **Shape**: [`Score`](result-shapes.md#score)
+
+### `playervox.rating.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `playervox.rating.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ state, name, offline, rating }`: `state` is `idle`, `unsupported`, `loading`, `ready` or `unavailable`; `rating` is `null` before the user's first rating, or `{ gameplay, art, tech, review, publishedAt, offsetMinutes }`. Nothing is sent while the PlayerVox account is signed out, pending or expired. A published rating is sent again by the subscription. The host fills the `playervox.rating.publish` controls from it
+- **Shape**: [`RatingState`](result-shapes.md#ratingstate)
+
+### `playervox.reviews.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `playervox.reviews.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ state, revision, offline }`: `state` is `idle`, `unsupported` or `ready`; `revision` changes whenever the reviews to read change (another game, another PlayerVox account, reviews changed on PlayerVox), so the widget reads its page again; `offline` while PlayerVox is unreachable. Nothing is sent while the PlayerVox account is signed out, pending or expired. Holding this subscription is what keeps the host's reviews source running
+- **Shape**: [`ReviewsState`](result-shapes.md#reviewsstate)
+
+### `playervox.reviews.page`
+
+- **Kind**: call, answered once
+- **Requires**: capability `playervox.reviews.read`
+- **When it can be called**: At any time
+- **Parameters**: `page?`: integer 1 to 100000; `followedOnly?`: boolean
+- **Result**: `{ gameName, items, page, totalPages, count }`: three reviews of the active game per page, in the language of the host's interface; a page past the end answers the last page; each item `{ id, author, grade, score, text, original, hidden, publishedAt, offsetMinutes }`, `text` translated when a translation exists, `original` the untranslated text of a translated review or `null`, both cut by the host to 16 KiB. Each call reads its own page: the host keeps no page position or filter shared between widgets
+- **Shape**: [`ReviewsPage`](result-shapes.md#reviewspage)
+
+### `journal.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `journal.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `null` without an active game, or `{ revision, notice }`: `revision` changes whenever the merged journal of the active game changes (a session recorded or deleted, cloud sessions merged, the PlayerVox account or sync changed), so the widget reads its page again; `notice` is `null`, `offline`, `storage_unavailable`, `full`, `expired`, `busy` or `unavailable`. Holding this subscription is what keeps the host's journal source running
+- **Shape**: [`JournalState`](result-shapes.md#journalstate) or `null`
+
+### `journal.page`
+
+- **Kind**: call, answered once
+- **Requires**: capability `journal.read`
+- **When it can be called**: At any time
+- **Parameters**: `cursor?`: text ≤ 128 bytes
+- **Result**: `{ gameName, items, page, next, previous }`: five local and cloud sessions of the active game, merged and deduplicated, newest first; without `cursor`, the first page; each item `{ id, startedAt, offsetMinutes, durationMs, source }`; cursors are host handles that stay valid for the widget whatever other widgets read, and a cursor past the end answers the last page
+- **Shape**: [`JournalPage`](result-shapes.md#journalpage)
+
+### `journal.delete`
+
+- **Kind**: call, answered once; the user confirms it first, in a dialog drawn by OverCrow
+- **Requires**: capability `journal.delete`
+- **When it can be called**: Only during a user action
+- **Parameters**: `session`: text ≤ 128 bytes
+- **Result**: `null`, or `cancelled` when the user declines; `not_connected` for a cloud session while PlayerVox is disconnected
+- **Shape**: `null`
+
+### `twitch.chat.subscribe`
+
+- **Kind**: subscription
+- **Requires**: capability `twitch.chat.read`
+- **When it can be called**: At any time
+- **Parameters**: none
+- **Each update**: `{ account, channel, joinState, failure, favorites, canSend, generation, reset, messages, removed, skipped }`: `account` is `signed_out`, `pending`, `connected` or `expired` (sign-in is drawn by the host); `failure` is the fixed category of a `failed` join; messages arrive as deltas, at most one update per 100 ms, with `reset` after subscribing, a generation change or a show, and nothing while the widget is hidden; a faster chat is sampled, `skipped` counting the new messages left out; each message `{ id, author, color, badges, fragments, reply, deleted, receivedAt }` with at most 16 fragments, emotes and badges as `asset:` handles for the current theme and scale
+- **Shape**: [`TwitchChat`](result-shapes.md#twitchchat)
+
+### `twitch.chat.join`
+
+- **Kind**: call, answered once
+- **Requires**: capability `twitch.chat.read`
+- **When it can be called**: Only during a user action
+- **Parameters**: `channel`: text ≤ 25 bytes
+- **Result**: `null`; the host remembers the channel and rejoins it when the widget starts
+- **Shape**: `null`
+
+### `twitch.chat.leave`
+
+- **Kind**: call, answered once
+- **Requires**: capability `twitch.chat.read`
+- **When it can be called**: Only during a user action
+- **Parameters**: none
+- **Result**: `null`; the host forgets the channel
+- **Shape**: `null`
+
+### `twitch.chat.favorite`
+
+- **Kind**: call, answered once
+- **Requires**: capability `twitch.chat.read`
+- **When it can be called**: Only during a user action
+- **Parameters**: `channel`: text ≤ 25 bytes; `favorite`: boolean
+- **Result**: `null`; `quota_exceeded` beyond 20
+- **Shape**: `null`
+<!-- /generated:services -->
+
+## Writes that go through a form
+
+Saving a note, publishing a rating and sending a chat message are not in
+this list: they are write intents, sent by a `form` from the values that
+the user typed. See
+[forms that write user data](forms.md#forms-that-write-user-data).