akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/packages/core/src/testing.ts

@@ -0,0 +1,176 @@
+
+
+import { aclCheck, type CallScope, listenItem, type ResolvedAcl } from "./acl.ts";
+import type { Platform, PluginDecl } from "./boot.ts";
+import { akanNativeGlobal } from "./boot.ts";
+import { AkanNativeError } from "./errors.ts";
+import {
+  BRIDGE_PLUGIN,
+  type BridgeRequest,
+  type BridgeResponse,
+  CANCEL,
+  errorResponse,
+  LISTEN,
+  type ListenArgs,
+  okResponse,
+  RELEASE,
+  UNLISTEN,
+  validateRequest,
+} from "./protocol.ts";
+import { resetRuntime, runtime } from "./runtime.ts";
+import { refreshBoot } from "./state.ts";
+
+/**
+ * `scope`: what the app's capabilities allow this call (PL-11), as a real host passes it. `signal`
+ * fires when the page cancels the call ($bridge.cancel), like a desktop plugin's ctx.signal.
+ */
+export type MockMethod = (args: any, host: MockHost, scope?: CallScope, signal?: AbortSignal) => unknown;
+
+export interface MockPlugin {
+  methods?: Record<string, MockMethod>;
+  events?: string[];
+  /** The other methods and events use the web implementation (a native subset with `web: true`). */
+  web?: true;
+}
+
+export interface MockHostOptions {
+  platform?: Platform;
+  env?: Record<string, string>;
+  dev?: boolean;
+  /** "web" makes the page use the plugin's web implementation, as a desktop host may declare. */
+  plugins?: Record<string, MockPlugin | "web">;
+  /** Capabilities (PL-11): the mock host enforces them like a real host, and the page sees them in boot. */
+  acl?: ResolvedAcl;
+  /** The page's window id (desktop multi-window). Default 1. */
+  windowId?: number;
+}
+
+export interface MockHost {
+  readonly requests: BridgeRequest[];
+  /** $bridge.cancel requests the page sent: the call id and the reason. */
+  readonly cancels: { id: number; reason: string; cancelled: boolean }[];
+  /** $bridge.release requests: the FileRef URLs (answered released: true). */
+  readonly releases: string[];
+  /** Pushes an event the way a native host would. Delivered only while subscribed. */
+  emit(plugin: string, event: string, data?: unknown): boolean;
+  subscriptions(plugin: string, event: string): number;
+  uninstall(): void;
+}
+
+export function installMockHost(options: MockHostOptions = {}): MockHost {
+  const platform = options.platform ?? "ios";
+  const plugins = options.plugins ?? {};
+  const decls: Record<string, PluginDecl> = {};
+  for (const [id, plugin] of Object.entries(plugins)) {
+    decls[id] =
+      plugin === "web"
+        ? "web"
+        : {
+            methods: Object.keys(plugin.methods ?? {}),
+            events: plugin.events ?? [],
+            ...(plugin.web ? { web: true as const } : {}),
+          };
+  }
+
+  resetRuntime();
+  const g = akanNativeGlobal();
+  for (const key of Object.keys(g)) delete (g as Record<string, unknown>)[key];
+  Object.assign(g, {
+    v: 1,
+    platform,
+    runtimeVersion: "0.0.0-mock",
+    dev: options.dev ?? false,
+    env: options.env ?? {},
+    plugins: decls,
+    ...(options.acl ? { acl: options.acl } : {}),
+    ...(options.windowId ? { windowId: options.windowId } : {}),
+  });
+
+  const subs = new Map<string, number>();
+  const requests: BridgeRequest[] = [];
+  const cancels: MockHost["cancels"] = [];
+  const releases: string[] = [];
+  const running = new Map<number, AbortController>();
+
+  const host: MockHost = {
+    requests,
+    cancels,
+    releases,
+    emit(plugin, event, data) {
+      if ((subs.get(`${plugin}.${event}`) ?? 0) === 0) return false;
+      g.receive?.(JSON.stringify({ v: 1, plugin, event, data }));
+      return true;
+    },
+    subscriptions: (plugin, event) => subs.get(`${plugin}.${event}`) ?? 0,
+    uninstall() {
+      resetRuntime();
+      for (const key of Object.keys(g)) delete (g as Record<string, unknown>)[key];
+      refreshBoot();
+    },
+  };
+
+  const handle = async (req: BridgeRequest): Promise<BridgeResponse> => {
+    const invalid = validateRequest(req);
+    if (invalid) return errorResponse(req.id, "INVALID_ARGS", invalid);
+    if (req.plugin === BRIDGE_PLUGIN && req.method === CANCEL) {
+      const { id, reason = "abort" } = req.args as { id: number; reason?: string };
+      const call = running.get(id);
+      call?.abort(
+        new AkanNativeError(reason === "timeout" ? "TIMEOUT" : "CANCELLED", `cancelled by the page (${reason})`),
+      );
+      cancels.push({ id, reason, cancelled: call !== undefined });
+      return okResponse(req.id, { cancelled: call !== undefined });
+    }
+    if (req.plugin === BRIDGE_PLUGIN && req.method === RELEASE) {
+      releases.push((req.args as { url: string }).url);
+      return okResponse(req.id, { released: true });
+    }
+    const plugin = plugins[req.plugin];
+    if (!plugin || plugin === "web") return errorResponse(req.id, "NOT_FOUND", `unknown plugin ${req.plugin}`);
+    let scope: CallScope | undefined;
+    if (req.method !== UNLISTEN) {
+      const item = req.method === LISTEN ? listenItem(String((req.args as ListenArgs | undefined)?.event)) : req.method;
+      const access = aclCheck(options.acl, req.plugin, item, options.windowId ?? 1);
+      if (!access.allowed)
+        return errorResponse(
+          req.id,
+          "NOT_ALLOWED",
+          `${req.plugin}.${req.method} is not allowed by the app's capabilities`,
+        );
+      scope = access.scope;
+    }
+    if (req.method === LISTEN || req.method === UNLISTEN) {
+      const { event } = req.args as ListenArgs;
+      if (!plugin.events?.includes(event)) return errorResponse(req.id, "NOT_FOUND", `unknown event ${event}`);
+      const key = `${req.plugin}.${event}`;
+      const count = (subs.get(key) ?? 0) + (req.method === LISTEN ? 1 : -1);
+      subs.set(key, Math.max(0, count));
+      return okResponse(req.id);
+    }
+    const method = plugin.methods?.[req.method];
+    if (!method) return errorResponse(req.id, "NOT_FOUND", `unknown method ${req.plugin}.${req.method}`);
+    const controller = new AbortController();
+    running.set(req.id, controller);
+    try {
+      return okResponse(req.id, await method(req.args, host, scope, controller.signal));
+    } catch (error) {
+      const e = AkanNativeError.from(error);
+      return errorResponse(req.id, e.code, e.message, e);
+    } finally {
+      running.delete(req.id);
+    }
+  };
+
+  const rt = runtime();
+  rt.transport = {
+    async send(req) {
+      
+      const wire = JSON.parse(JSON.stringify(req)) as BridgeRequest;
+      requests.push(wire);
+      await Promise.resolve();
+      return JSON.parse(JSON.stringify(await handle(wire))) as BridgeResponse;
+    },
+  };
+  refreshBoot();
+  return host;
+}

package/vendor/@akanjs/native/packages/core/src/version.ts

@@ -0,0 +1,2 @@
+/** The runtime version (UP-3): builtin plugins share it, and OTA updates compare its line. */
+export const VERSION = "0.1.0";

package/vendor/@akanjs/native/packages/core/src/veto.ts

@@ -0,0 +1,55 @@
+
+
+export interface VetoEvent {
+  /** Keeps the window open / the app running. Call it before the handler returns (await first if needed). */
+  preventDefault(): void;
+  readonly defaultPrevented: boolean;
+}
+
+export type VetoHandler<E> = (event: E & VetoEvent) => void | Promise<void>;
+
+/**
+ * Builds an `onX(handler)` registration for a cancelable event.
+ * `listen` subscribes to the plugin event; `answer` is the plugin method the host waits for.
+ * Registering is a no-op where the event is not supported (it simply never fires).
+ */
+export function vetoable<E extends object>(
+  listen: (listener: (data: E & { id: number }) => void) => () => void,
+  answer: (args: { id: number; allow?: boolean }) => Promise<unknown>,
+): (handler: VetoHandler<E>) => () => void {
+  const handlers = new Set<VetoHandler<E>>();
+  let stop: (() => void) | null = null;
+
+  const onEvent = async ({ id, ...data }: E & { id: number }) => {
+    const send = (allow?: boolean) => answer(allow === undefined ? { id } : { id, allow }).catch(() => {});
+    void send();
+    let prevented = false;
+    const event = {
+      ...(data as unknown as E),
+      preventDefault: () => {
+        prevented = true;
+      },
+      get defaultPrevented() {
+        return prevented;
+      },
+    };
+    for (const handler of [...handlers]) {
+      try {
+        await handler(event);
+      } catch (error) {
+        console.error("[akan-native] cancelable event handler failed", error);
+      }
+    }
+    void send(!prevented);
+  };
+
+  return (handler) => {
+    handlers.add(handler);
+    stop ??= listen(onEvent);
+    return () => {
+      if (!handlers.delete(handler) || handlers.size > 0) return;
+      stop?.();
+      stop = null;
+    };
+  };
+}

package/vendor/@akanjs/native/packages/core/vectors/acl.json

@@ -0,0 +1,57 @@
+{
+  "about": "The capabilities a host enforces (PL-11) as boot.json carries them. cases: { acl (absent: boot.json has none, and everything is allowed), problem (the ACL is not one hosts can enforce: then every call is denied, fail-closed), checks: [plugin, item, window, allowed, scope or null ({ allow: entries or null, deny: entries })] }.",
+  "cases": [
+    {
+      "problem": false,
+      "checks": [["fs", "readFile", 1, true, null], ["anything", "at-all", 7, true, null]]
+    },
+    {
+      "acl": {
+        "grants": [
+          { "plugin": "fs", "windows": "*", "items": ["readFile", "stat"] },
+          { "plugin": "fs", "windows": [1], "items": ["writeFile"], "allow": [{ "base": "data", "path": "notes/**" }], "deny": [{ "path": "notes/secret/**" }] },
+          { "plugin": "fs", "windows": [2], "items": ["writeFile"], "allow": [{ "base": "cache", "path": "**" }] },
+          { "plugin": "fs", "windows": "*", "items": ["remove"], "deny": [{ "path": "keep/**" }] },
+          { "plugin": "win", "windows": "*", "items": "*" }
+        ],
+        "denied": { "win": ["close"], "fs": ["listen:change"] }
+      },
+      "problem": false,
+      "checks": [
+        ["fs", "readFile", 1, true, null],
+        ["fs", "readFile", 3, true, null],
+        ["fs", "writeFile", 1, true, { "allow": [{ "base": "data", "path": "notes/**" }], "deny": [{ "path": "notes/secret/**" }] }],
+        ["fs", "writeFile", 2, true, { "allow": [{ "base": "cache", "path": "**" }], "deny": [] }],
+        ["fs", "writeFile", 3, false, null],
+        ["fs", "remove", 1, true, { "allow": null, "deny": [{ "path": "keep/**" }] }],
+        ["fs", "listen:change", 1, false, null],
+        ["fs", "mkdir", 1, false, null],
+        ["win", "setTitle", 5, true, null],
+        ["win", "close", 1, false, null],
+        ["other", "x", 1, false, null]
+      ]
+    },
+    { "acl": { "grants": [] }, "problem": false, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"] }], "denied": {} }, "problem": false, "checks": [["fs", "readFile", 1, true, null]] },
+    { "acl": null, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": "all", "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": {}, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": "all" }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"] }, 3] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "windows": "*", "items": ["readFile"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "", "windows": "*", "items": ["readFile"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "items": ["readFile"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*" }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": "readFile" }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile", 1] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": [0], "items": ["readFile"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": [1.5], "items": ["readFile"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "main", "items": ["readFile"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"], "allow": { "path": "x" } }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"], "allow": [{ "path": 1 }] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"], "deny": ["x"] }] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"] }], "denied": [] }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"] }], "denied": { "fs": "remove" } }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] },
+    { "acl": { "grants": [{ "plugin": "fs", "windows": "*", "items": ["readFile"] }], "denied": { "fs": [1] } }, "problem": true, "checks": [["fs", "readFile", 1, false, null]] }
+  ]
+}

package/vendor/@akanjs/native/packages/core/vectors/bridge.json

@@ -0,0 +1,76 @@
+{
+  "about": "Bridge v1.1 request checks every host makes before anything runs (architecture.md §4). requests: [the parsed request, the error message or null]. documents: [the current document (null: none; \"\": one without an id), ended document ids, the request's doc (null: none), what the host does: current|new|ended|no-doc]. declarations: [the plugin's entry in boot.json plugins (\"web\": no native part; absent: null), method, event of a $listen/$unlisten or null, whether the host lets the call through to the plugin].",
+  "requests": [
+    [{"v": 1, "id": 1, "plugin": "p", "method": "m"}, null],
+    [{"v": 1, "id": 0, "plugin": "p", "method": "m", "args": {"a": 1}}, null],
+    [{"v": 1, "id": -5, "plugin": "p", "method": "m"}, null],
+    [{"v": 1, "id": 9007199254740991, "plugin": "$host", "method": "echo"}, null],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "m", "doc": "0123456789abcdef0123456789abcdef"}, null],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "$listen", "args": {"event": "tick"}}, null],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "$unlisten", "args": {"event": "tick"}}, null],
+    ["text", "request must be an object"],
+    [[1], "request must be an object"],
+    [null, "request must be an object"],
+    [{"v": 2, "id": 1, "plugin": "p", "method": "m"}, "unsupported protocol version: 2"],
+    [{"v": true, "id": 1, "plugin": "p", "method": "m"}, "unsupported protocol version: true"],
+    [{"v": "1", "id": 1, "plugin": "p", "method": "m"}, "unsupported protocol version: 1"],
+    [{"v": 1.5, "id": 1, "plugin": "p", "method": "m"}, "unsupported protocol version: 1.5"],
+    [{"id": 1, "plugin": "p", "method": "m"}, "unsupported protocol version: undefined"],
+    [{"v": 1, "id": 1.5, "plugin": "p", "method": "m"}, "id must be an integer"],
+    [{"v": 1, "id": "1", "plugin": "p", "method": "m"}, "id must be an integer"],
+    [{"v": 1, "id": true, "plugin": "p", "method": "m"}, "id must be an integer"],
+    [{"v": 1, "id": 9007199254740992, "plugin": "p", "method": "m"}, "id must be an integer"],
+    [{"v": 1, "plugin": "p", "method": "m"}, "id must be an integer"],
+    [{"v": 1, "id": 1, "plugin": "", "method": "m"}, "invalid plugin name"],
+    [{"v": 1, "id": 1, "plugin": 3, "method": "m"}, "invalid plugin name"],
+    [{"v": 1, "id": 1, "plugin": "a b", "method": "m"}, "invalid plugin name"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": ""}, "invalid method name"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "__proto__x!"}, "invalid method name"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "m", "doc": "short"}, "invalid document id"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "m", "doc": 12345678}, "invalid document id"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "$listen"}, "$listen requires args.event"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "$listen", "args": {"event": 1}}, "$listen requires args.event"],
+    [{"v": 1, "id": 1, "plugin": "p", "method": "$unlisten", "args": []}, "$unlisten requires args.event"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": 1, "reason": "abort"}}, null],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": 1, "reason": "timeout"}}, null],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": -7}}, null],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel"}, "$bridge.cancel requires args.id"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": "1"}}, "$bridge.cancel requires args.id"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": 1.5}}, "$bridge.cancel requires args.id"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": true}}, "$bridge.cancel requires args.id"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": 1, "reason": "later"}}, "$bridge.cancel: reason must be abort or timeout"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "cancel", "args": {"id": 1, "reason": null}}, "$bridge.cancel: reason must be abort or timeout"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "release", "args": {"url": "/__akan_native/file/abc"}}, null],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "release", "args": {}}, "$bridge.release requires args.url"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "release", "args": {"url": 5}}, "$bridge.release requires args.url"],
+    [{"v": 1, "id": 2, "plugin": "$bridge", "method": "drop"}, "unknown bridge operation $bridge.drop"]
+  ],
+  "documents": [
+    [null, [], "aaaaaaaa", "new"],
+    [null, [], null, "new"],
+    ["aaaaaaaa", [], "aaaaaaaa", "current"],
+    ["aaaaaaaa", [], "bbbbbbbb", "new"],
+    ["aaaaaaaa", ["bbbbbbbb"], "bbbbbbbb", "ended"],
+    [null, ["bbbbbbbb"], "bbbbbbbb", "ended"],
+    ["aaaaaaaa", [], null, "no-doc"],
+    ["", [], null, "current"],
+    ["", [], "aaaaaaaa", "new"],
+    ["", ["aaaaaaaa"], "aaaaaaaa", "ended"]
+  ],
+  "declarations": [
+    [{"methods": ["get", "set"], "events": ["change"]}, "get", null, true],
+    [{"methods": ["get", "set"], "events": ["change"]}, "remove", null, false],
+    [{"methods": ["get", "set"], "events": ["change"]}, "$listen", "change", true],
+    [{"methods": ["get", "set"], "events": ["change"]}, "$listen", "other", false],
+    [{"methods": ["get", "set"], "events": ["change"]}, "$unlisten", "change", true],
+    [{"methods": ["get", "set"], "events": ["change"]}, "$unlisten", "other", false],
+    [{"methods": ["get", "set"], "events": ["change"]}, "constructor", null, false],
+    [{"methods": ["get"], "events": [], "web": ["set"]}, "set", null, false],
+    ["web", "get", null, false],
+    [null, "get", null, false],
+    [{"methods": "get", "events": []}, "get", null, false],
+    [{"events": ["change"]}, "$listen", "change", true],
+    [{"methods": ["get"]}, "get", null, true],
+    [{"methods": ["get"]}, "$listen", "change", false]
+  ]
+}