@ekrooh/bare 0.5.0 → 0.6.0

package/README.md

@@ -3,11 +3,14 @@
 **One soul, many platforms.** One codebase and identity across Android, iOS,
 web, and desktop.
 
+**Docs: <https://anderscan.github.io/ekrooh>**
+
 [![CI](https://github.com/AndersCan/ekrooh/actions/workflows/test.yml/badge.svg)](https://github.com/AndersCan/ekrooh/actions/workflows/test.yml)
+[![Release](https://img.shields.io/github/v/release/AndersCan/ekrooh)](https://github.com/AndersCan/ekrooh/releases/latest)
 
 The boring bootstrap for cross-platform apps on the Bare runtime (holepunch): a
 binary wire protocol, plugin kernel, RPC messenger, transports, and native host
-bridges, plus a reference app. Public docs: <https://anderscan.github.io/ekrooh>.
+bridges, plus a reference app.
 
 - [`vision.md`](vision.md): what this project is and is not.
 - [`AGENTS.md`](AGENTS.md): how to develop it and the canonical commands.
@@ -99,16 +102,23 @@ ephemeral port. Every request is gated by a per-session token:
 
 1. The shell injects `window.__ekrooh = { bootstrap }`, a single-use nonce (never the raw token).
 2. The page calls `POST /login` with the nonce and receives a
-   `bare_session` cookie (`HttpOnly; SameSite=Lax; Path=/`).
+   `bare_session_<port>` cookie (`HttpOnly; SameSite=Strict; Path=/`). The port
+   in the name keeps two loopback servers in one cookie store apart. The raw
+   token is never a login credential.
 3. The cookie authorizes `<img>`, `<video>`, `fetch`, and the WS upgrade.
    Non-browser clients send `X-Bare-Token`. There is no `?token=` fallback
    (see `docs/adr/0003-loopback-auth-surface.md`).
 
 Only the bootstrap mount at `/` is public pre-auth. The worklet writes
-`{ origin, port, token, bootstrap }` to `handoff.json` in the host's sandbox dir;
-the host keeps `token` and loads `http://127.0.0.1:<port>/index.html`.
+`{ origin, port, bootstrap }` to `handoff.json` in the host's sandbox dir (never
+the session token); the host loads `http://127.0.0.1:<port>/index.html` and
+deletes the file.
+
+Every request must also target the bound loopback server (`Host`), and a page
+`Origin` must be that server or an explicitly allowed one, in every mode.
 
-The dev backend runs the same bundle with auth off on `ws://localhost:8080`.
+The dev backend (`mode=dev`) runs the same bundle with auth off on
+`ws://localhost:8080`, allowing the Vite dev origin (`origin=` tokens).
 
 ## Testing
 

package/dist/index.mjs

@@ -1 +1 @@
-export { h as CoreError, g as ErrorCode, _ as MAX_FRAME_BYTES, v as MAX_HEADER_BYTES, o as MessageProtocol, y as MessageType, b as VERSION, f as coerceErrorCode, n as createBareRuntimeContext, l as createPluginBus, u as createPluginRegistry, d as createPluginRouter, s as createProtocolMessenger, r as definePlugin, i as dispatchEvent, p as err, t as installWebConsoleCapture, a as invokeEvent, m as ok } from "./messages-BbpF3wNH.mjs";
+export { h as CoreError, g as ErrorCode, _ as MAX_FRAME_BYTES, v as MAX_HEADER_BYTES, o as MessageProtocol, y as MessageType, b as VERSION, f as coerceErrorCode, n as createBareRuntimeContext, l as createPluginBus, u as createPluginRegistry, d as createPluginRouter, s as createProtocolMessenger, r as definePlugin, i as dispatchEvent, p as err, t as installWebConsoleCapture, a as invokeEvent, m as ok } from "./messages-CevD8qkV.mjs";

package/dist/{messages-BbpF3wNH.mjs → messages-CevD8qkV.mjs}

@@ -296,9 +296,9 @@ function isPluginInvokeResponseHeader(header) {
 /**
 * CSPRNG-backed correlation id for RPC requests.
 *
-* Shared by the production messenger (`rpc-messenger.ts`) and the mantaq
-* prototype (`rpc-messenger.mantaq.ts`) so the unguessable,
-* collision-resistant guarantee can never regress in a single copy. Request
+* Shared by the RPC messenger (`rpc-messenger.ts`) and the host IPC bridge
+* (`host-ipc.ts`) so the unguessable, collision-resistant guarantee can never
+* regress in a single copy. Request
 * IDs must never be derived from `Math.random()` — a guessable id lets a peer
 * spoof or collide with an in-flight request and corrupt correlation. See
 * ekrooh#141.
@@ -747,9 +747,11 @@ function dispatchEvent(spec, args, payload) {
 // core/messages/create-bare-runtime-context.ts
 function createBareRuntimeContext(plugins = [], routerOptions) {
 	const runtime = "bare";
+	const textEncoder = new TextEncoder$1();
+	const textDecoder = new TextDecoder$1();
 	const protocol = new MessageProtocol({
-		encode: (str) => new TextEncoder$1().encode(str),
-		decode: (bytes) => new TextDecoder$1().decode(bytes)
+		encode: (str) => textEncoder.encode(str),
+		decode: (bytes) => textDecoder.decode(bytes)
 	});
 	const pluginRegistry = createPluginRegistry();
 	for (const plugin of plugins) pluginRegistry.register(plugin);

package/dist/{plugins-DZu_NWVp.mjs → plugins-Ddp2AgOe.mjs}

@@ -1,4 +1,4 @@
-import { g as ErrorCode, m as ok, p as err, r as definePlugin } from "./messages-BbpF3wNH.mjs";
+import { g as ErrorCode, m as ok, p as err, r as definePlugin } from "./messages-CevD8qkV.mjs";
 import { discoverySpecs } from "./plugins-discovery-events.mjs";
 import { healthSpecs } from "./plugins-health-events.mjs";
 import { logsSpecs } from "./plugins-logs-events.mjs";
@@ -84,6 +84,7 @@ function createLogsPlugin(deps) {
 * mounted at once and evict the least-recently-used so picked/captured files
 * do not accumulate on the loopback server for the whole session. */
 const MEDIA_MOUNT_CAP = 4;
+const MEDIA_KINDS = ["image", "video"];
 function newRequestId() {
 	const rand = crypto.randomBytes(16).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 	return `${Date.now().toString(36)}-${rand}`;
@@ -108,18 +109,20 @@ function createMediaPlugin(deps) {
 		}
 	};
 	const serve = async (event, args) => {
+		const kind = args?.kind;
+		if (kind !== void 0 && !MEDIA_KINDS.includes(kind)) return err(ErrorCode.PLUGIN_ERROR, `Unknown media kind for ${event}`);
 		const host = await deps.invokeOnHost({
 			type: "INVOKE_REQUEST",
 			pluginId: "vendor.media",
 			event,
 			requestId: newRequestId(),
-			args
+			args: kind === void 0 ? {} : { kind }
 		}, /* @__PURE__ */ new Uint8Array(0));
 		if (!host) return err(ErrorCode.HOST_ERROR, `Host did not answer ${event}`);
 		if (host.error) return err(host.error.code || ErrorCode.HOST_ERROR, host.error.message ?? `Host failed ${event}`);
 		const path = host.result?.path;
 		if (!path) return err(ErrorCode.HOST_ERROR, `Host returned no path for ${event}`);
-		const id = `${args?.kind ?? "media"}-${newRequestId()}`;
+		const id = `${kind ?? "media"}-${newRequestId()}`;
 		mountMedia(id, path);
 		const url = await deps.staticServer.url(`/media/${id}`);
 		return ok({ url });

package/dist/plugins-discovery-events.mjs

@@ -1,4 +1,4 @@
-import { a as invokeEvent } from "./messages-BbpF3wNH.mjs";
+import { a as invokeEvent } from "./messages-CevD8qkV.mjs";
 // plugins/discovery/events.ts
 const discoverySpecs = { list: {
 	pluginId: "core.discovery",

package/dist/plugins-health-events.mjs

@@ -1,4 +1,4 @@
-import { a as invokeEvent } from "./messages-BbpF3wNH.mjs";
+import { a as invokeEvent } from "./messages-CevD8qkV.mjs";
 // plugins/health/events.ts
 const healthSpecs = {
 	ping: {

package/dist/plugins-logs-events.mjs

@@ -1,4 +1,4 @@
-import { a as invokeEvent } from "./messages-BbpF3wNH.mjs";
+import { a as invokeEvent } from "./messages-CevD8qkV.mjs";
 // plugins/logs/events.ts
 const logsSpecs = {
 	view: {

package/dist/plugins-media-events.mjs

@@ -1,4 +1,4 @@
-import { a as invokeEvent } from "./messages-BbpF3wNH.mjs";
+import { a as invokeEvent } from "./messages-CevD8qkV.mjs";
 // plugins/media/events.ts
 const MEDIA_INVOKE_TIMEOUT_MS = 3e5;
 const mediaSpecs = {

package/dist/plugins-permissions-events.mjs

@@ -1,4 +1,4 @@
-import { a as invokeEvent } from "./messages-BbpF3wNH.mjs";
+import { a as invokeEvent } from "./messages-CevD8qkV.mjs";
 // plugins/permissions/events.ts
 const permissionSpecs = {
 	request: {

package/dist/plugins.d.mts

@@ -1,5 +1,5 @@
 import { F as CapabilityDescriptor, Q as PluginManifest, X as PluginInvokeRequestHeader, Z as PluginInvokeResponseHeader, a as LogStore, et as RuntimeTarget } from "./index-BkwUzwVt.mjs";
-import { n as LoopbackServer } from "./static-file-server-C8pIX1JD.mjs";
+import { n as LoopbackServer } from "./static-file-server-COxd-PFR.mjs";
 type DiscoveryPluginDeps = {
   listBareCapabilities: () => Array<{
     pluginId: string;

package/dist/plugins.mjs

@@ -1 +1 @@
-export { t as createDefaultPlugins } from "./plugins-DZu_NWVp.mjs";
+export { t as createDefaultPlugins } from "./plugins-Ddp2AgOe.mjs";

package/dist/runtime.d.mts

@@ -1,17 +1,19 @@
 import { C as createPluginRegistry, F as CapabilityDescriptor, K as MessageHeader, Q as PluginManifest, X as PluginInvokeRequestHeader, Z as PluginInvokeResponseHeader, g as MessageProtocol, o as BareRuntimeContext, tt as WireMessage, w as createPluginRouter } from "./index-BkwUzwVt.mjs";
-import { i as createLoopbackServer, n as LoopbackServer, r as collectRequestBody, t as LoopbackRouteHandler } from "./static-file-server-C8pIX1JD.mjs";
+import { i as createLoopbackServer, n as LoopbackServer, r as collectRequestBody, t as LoopbackRouteHandler } from "./static-file-server-COxd-PFR.mjs";
 type BareIpcLike = {
-  write(data: Uint8Array | Buffer | string): boolean;
+  write(data: Uint8Array | string): boolean;
 };
 declare function createHostIpcBridge(config: {
   ipc: BareIpcLike;
   protocol: MessageProtocol;
 }): {
   tryConsumeDownstream: (parsed: WireMessage) => boolean;
-  tryConsumeDownstreamFromHost(raw: Uint8Array | ArrayBuffer | Buffer): boolean;
+  tryConsumeDownstreamFromHost(raw: Uint8Array | ArrayBuffer): boolean;
   queryCapabilities(timeoutMs?: number): Promise<CapabilityDescriptor[]>;
   invokeOnHost(header: PluginInvokeRequestHeader, payload: Uint8Array, timeoutMs?: number): Promise<PluginInvokeResponseHeader | null>;
 };
+/** Envelope encoder bound to a loopback server's connected protocol socket —
+ * the server-initiated (backend → web) push seam. */
 type LoopbackPush = (header: MessageHeader, payload?: Uint8Array | ArrayBuffer | null) => boolean;
 /** Builds the push seam for the server's connected protocol socket: encodes a
  * `DISPATCH`-style envelope and writes it, mirroring how `attachWebSocketProtocol`
@@ -20,8 +22,9 @@ export declare function createLoopbackPush(server: LoopbackServer, protocol: Mes
 /**
  * Attaches the framed-protocol socket to the unified loopback server. The
  * server owns the WebSocket upgrade (origin check, cookie/token auth, single
- * client, idle timeout); this layer only routes decoded envelopes through the
- * plugin router and writes responses back as raw frames.
+ * client, idle timeout); this layer runs one frame channel per socket. A peer
+ * that sends a malformed frame is not recoverable on that socket, so it is
+ * torn down and the client reconnects.
  */
 export declare function attachWebSocketProtocol(server: LoopbackServer, context: BareRuntimeContext): void;
 /**
@@ -29,36 +32,36 @@ export declare function attachWebSocketProtocol(server: LoopbackServer, context:
  */
 interface BareIPC extends NodeJS.EventEmitter {
   read(n?: number): Buffer | null;
-  write(data: Buffer | string): boolean;
+  write(data: Uint8Array | string): boolean;
   resume?(): void;
   pause?(): void;
 }
 /**
- * Returns the active IPC channel.
- * In BareKit (Android), it uses BareKit.IPC.
+ * Returns the active IPC channel, or null when there is no host.
+ * In BareKit (Android, iOS), it uses BareKit.IPC.
  * In Bare (Sidecar), it uses Bare.IPC.
  */
-export declare function getIPC(): BareIPC;
+export declare function getIPC(): BareIPC | null;
 /** Resolves the host-provided worklet configuration from `start(...)`
  * arguments. On-device hosts pass `["<webAssets>", "<storage>", "<cache>"]`
- * (three existing directories, in that order), landing at `Bare.argv[0..2]`;
- * the Bare CLI (dev) passes the binary and the script path instead, so a
- * missing/absent config means dev mode (auth off, fixed port, no handoff
- * file). Falls back to the labeled CLI token syntax (see `resolveCliConfig`)
- * when the positional shape doesn't match, so the same entry works for both
- * device and dev runs. */
+ * (three existing directories, in that order), landing at `Bare.argv[0..2]`.
+ * Falls back to the labeled CLI token syntax (see `resolveCliConfig`) when the
+ * positional shape doesn't match, so the same entry works for device and dev
+ * runs. Nothing here turns auth off: the dev backend is selected only by an
+ * explicit `mode=dev` token. */
 export declare function resolveWorkletConfig(): WorkletRuntimeOptions;
 /**
- * Parses the dev/CLI labeled-token configuration from bare CLI arguments:
- * `webassets=<dir>`, `storage=<dir>`, `cache=<dir>`, `host=<addr>`,
- * `port=<n>`, `auth=<on|off|true|false|1|0>` — a single `key=value` separator.
- * Unknown labels (e.g. `bootstrap=127.0.0.1:49737`) are ignored and stay
- * consumer-owned.
+ * Parses labeled-token configuration from bare CLI arguments, one `key=value`
+ * per token: `webassets=<dir>`, `storage=<dir>`, `cache=<dir>`,
+ * `host=<addr>`, `port=<n>`, `auth=<on|off|true|false|1|0>`,
+ * `mode=<device|dev>` and `origin=<scheme://host[:port]>` (repeatable; an
+ * extra allowed page origin, e.g. the Vite dev server). Unknown labels (e.g.
+ * `bootstrap=127.0.0.1:49737`) are ignored and stay consumer-owned.
  *
- * Returns the equivalent `WorkletRuntimeOptions` in **dev mode**: `deviceMode:
- * false` (so a `storage=` token does not flip auth on or make the port
- * ephemeral), `auth: false`, `port: 8080`, each overridable by a token. When
- * no labeled tokens are present it returns `{}` (plain dev defaults).
+ * Without `mode=dev` the result keeps the secure device defaults (auth on, an
+ * ephemeral port), and `auth=off` is ignored with a warning. `mode=dev` selects the dev backend: `deviceMode: false`,
+ * `auth: false`, `port: 8080`, each overridable by a token. Returns `{}` when
+ * no labeled tokens are present.
  */
 export declare function resolveCliConfig(argv?: readonly string[]): WorkletRuntimeOptions;
 export type WorkletRuntimeOptions = {
@@ -73,16 +76,21 @@ export type WorkletRuntimeOptions = {
   /** Port to bind; `0` picks an ephemeral port (on-device). Defaults to an
    * ephemeral port in device mode, 8080 in dev mode. */
   port?: number;
-  /** Require the per-session token/cookie. Defaults to on in device mode. */
+  /** Require the per-session token/cookie. Defaults to on in device mode and
+   * off in dev mode. The origin check applies either way. */
   auth?: boolean;
-  /** Write the credentials to `<storage>/handoff.json` for the host to read
-   * (auth on only). Defaults to true; a host that receives them over its own
-   * channel (the desktop host reads them from a pipe) sets false so the
-   * session token never touches disk. */
+  /** Extra page origins allowed to call the loopback server, e.g. the Vite dev
+   * server (`http://localhost:5173`). The bound origin and its loopback
+   * aliases are always allowed. */
+  allowedOrigins?: readonly string[];
+  /** Write `{ origin, port, bootstrap }` to `<storage>/handoff.json` for the
+   * host to read (auth on only; the session token is never written). Defaults
+   * to true; a host that receives them over its own channel (the desktop host
+   * reads them from a pipe) sets false so nothing touches disk. */
   handoffFile?: boolean;
-  /** Explicit device-mode override. Defaults to on whenever `storage` is set
-   * (the on-device 3-arg contract); `resolveCliConfig` resolves it to false so
-   * a dev backend keeps auth off + fixed port even with a storage dir. */
+  /** Device mode (the default): auth on, an ephemeral port, and the handoff
+   * file when `storage` is set. Pass `false` (or the `mode=dev` CLI token) for
+   * the dev backend: auth off and port 8080 unless set explicitly. */
   deviceMode?: boolean;
   /** Additional plugin manifests to register after the canonical defaults
    * (consumer product plugins, e.g. `app.photos`). */
@@ -93,7 +101,8 @@ export type WorkletRuntimeOptions = {
    * is destroyed, freeing the slot. Defaults to 10s. */
   wsDeadPeerTimeoutMs?: number;
   /** Minimum gap (ms) before an accepted protocol socket may be replaced by a
-   * new authenticated one. Defaults to 1s. */
+   * new authenticated one; an upgrade that arrives sooner is held until then.
+   * Defaults to 1s. */
   wsReplaceMinIntervalMs?: number;
   /** Bytes queued behind a protocol socket whose reader stopped reading before
    * server pushes are dropped (newest first). Defaults to 2 MiB. */