@pyric/cli 0.1.0-alpha.9

package/dist/assurance/validation.js

@@ -0,0 +1,269 @@
+import { ASSURANCE_TARGET_SCHEMA, AssuranceInputError, } from "./types.js";
+const services = new Set(["firestore", "rtdb", "storage"]);
+const dimensions = new Set([
+    "path",
+    "query",
+    "payload",
+    "operation",
+]);
+const firestoreMethods = new Set([
+    "get",
+    "list",
+    "create",
+    "set",
+    "merge",
+    "update",
+    "delete",
+]);
+const rtdbMethods = new Set(["get", "set", "update", "remove"]);
+const storageMethods = new Set([
+    "get",
+    "list",
+    "upload",
+    "updateMetadata",
+    "delete",
+]);
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function requiredString(value, message) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new AssuranceInputError(message);
+    }
+}
+function enumValue(value, allowed, message) {
+    if (typeof value !== "string" || !allowed.has(value)) {
+        throw new AssuranceInputError(message);
+    }
+}
+export function assertTarget(target) {
+    if (!isRecord(target)) {
+        throw new AssuranceInputError("target must be an object.");
+    }
+    if (target.schema !== ASSURANCE_TARGET_SCHEMA) {
+        throw new AssuranceInputError(`target schema must be '${ASSURANCE_TARGET_SCHEMA}'.`);
+    }
+    if (target.network !== "forbid") {
+        throw new AssuranceInputError("assurance v1 requires target.network to be 'forbid'.");
+    }
+    if (!isRecord(target.rules)) {
+        throw new AssuranceInputError("target.rules must be an object.");
+    }
+    if (!isRecord(target.state)) {
+        throw new AssuranceInputError("target.state must be an object.");
+    }
+    if (target.rules.firestore !== undefined &&
+        typeof target.rules.firestore !== "string") {
+        throw new AssuranceInputError("target.rules.firestore must be a string.");
+    }
+    if (target.rules.storage !== undefined &&
+        typeof target.rules.storage !== "string") {
+        throw new AssuranceInputError("target.rules.storage must be a string.");
+    }
+    if (target.rules.rtdb !== undefined) {
+        if (!isRecord(target.rules.rtdb) || !isRecord(target.rules.rtdb.rules)) {
+            throw new AssuranceInputError("target.rules.rtdb must contain a rules object.");
+        }
+    }
+    if (target.state.firestore !== undefined &&
+        !isRecord(target.state.firestore)) {
+        throw new AssuranceInputError("target.state.firestore must be an object.");
+    }
+    if (target.state.storage !== undefined) {
+        if (!Array.isArray(target.state.storage)) {
+            throw new AssuranceInputError("target.state.storage must be an array.");
+        }
+        for (const [index, object] of target.state.storage.entries()) {
+            if (!isRecord(object)) {
+                throw new AssuranceInputError(`target.state.storage[${index}] must be an object.`);
+            }
+            requiredString(object.path, `target.state.storage[${index}] path is required.`);
+            if (typeof object.dataBase64 !== "string") {
+                throw new AssuranceInputError(`target.state.storage[${index}] dataBase64 must be a string.`);
+            }
+        }
+    }
+    if (target.state.auth !== undefined) {
+        if (!isRecord(target.state.auth) ||
+            !Array.isArray(target.state.auth.users)) {
+            throw new AssuranceInputError("target.state.auth must contain a users array.");
+        }
+        for (const [index, user] of target.state.auth.users.entries()) {
+            if (!isRecord(user)) {
+                throw new AssuranceInputError(`target.state.auth.users[${index}] must be an object.`);
+            }
+            requiredString(user.uid, `target.state.auth.users[${index}] uid is required.`);
+            if (user.password !== undefined && typeof user.password !== "string") {
+                throw new AssuranceInputError(`target.state.auth.users[${index}] password must be a string.`);
+            }
+            if (user.customClaims !== undefined && !isRecord(user.customClaims)) {
+                throw new AssuranceInputError(`target.state.auth.users[${index}] customClaims must be an object.`);
+            }
+        }
+    }
+}
+export function assertActor(actor) {
+    if (!isRecord(actor)) {
+        throw new AssuranceInputError("actor must be an object.");
+    }
+    requiredString(actor.id, "actor id is required.");
+    if (!isRecord(actor.acquisition)) {
+        throw new AssuranceInputError(`actor '${actor.id}' must declare acquisition evidence.`);
+    }
+    const kind = actor.acquisition.kind;
+    enumValue(kind, new Set([
+        "anonymous-request",
+        "anonymous-account",
+        "password",
+        "fixture-user",
+        "synthetic",
+    ]), `actor '${actor.id}' has invalid acquisition kind '${String(kind)}'.`);
+    if (kind === "password") {
+        requiredString(actor.acquisition.email, `actor '${actor.id}' password acquisition requires an email.`);
+        requiredString(actor.acquisition.password, `actor '${actor.id}' password acquisition requires a password.`);
+    }
+    if (kind === "fixture-user" || kind === "synthetic") {
+        requiredString(actor.acquisition.uid, `actor '${actor.id}' ${kind} acquisition requires a uid.`);
+    }
+    if (kind === "synthetic" &&
+        actor.acquisition.token !== undefined &&
+        !isRecord(actor.acquisition.token)) {
+        throw new AssuranceInputError(`actor '${actor.id}' synthetic token must be an object.`);
+    }
+}
+export function assertInvariant(invariant) {
+    if (!isRecord(invariant)) {
+        throw new AssuranceInputError("invariant must be an object.");
+    }
+    requiredString(invariant.id, "invariant id is required.");
+    requiredString(invariant.statement, `invariant '${invariant.id}' statement is required.`);
+    enumValue(invariant.service, new Set([...services, "cross-service"]), `invariant '${invariant.id}' has invalid service '${String(invariant.service)}'.`);
+    enumValue(invariant.expected, new Set(["ALLOW", "DENY"]), `invariant '${invariant.id}' has invalid expected decision '${String(invariant.expected)}'.`);
+    enumValue(invariant.source, new Set(["declared", "authored-test", "captured", "derived", "agent"]), `invariant '${invariant.id}' has invalid source '${String(invariant.source)}'.`);
+    enumValue(invariant.confidence, new Set(["authoritative", "strong", "tentative"]), `invariant '${invariant.id}' has invalid confidence '${String(invariant.confidence)}'.`);
+}
+export function assertObservation(observation) {
+    if (!isRecord(observation)) {
+        throw new AssuranceInputError("observation must be an object.");
+    }
+    requiredString(observation.id, "observation id is required.");
+    requiredString(observation.actorId, `observation '${observation.id}' actorId is required.`);
+    if (observation.result !== "ALLOW") {
+        throw new AssuranceInputError(`observation '${observation.id}' result must be 'ALLOW'.`);
+    }
+    enumValue(observation.source, new Set(["captured", "authored", "discovered"]), `observation '${observation.id}' has invalid source '${String(observation.source)}'.`);
+    assertOperation(observation.operation, `observation '${observation.id}'`);
+}
+export function assertProbe(probe) {
+    if (!isRecord(probe)) {
+        throw new AssuranceInputError("probe must be an object.");
+    }
+    requiredString(probe.id, "probe id is required.");
+    requiredString(probe.actorId, `probe '${probe.id}' actorId is required.`);
+    requiredString(probe.invariantId, `probe '${probe.id}' invariantId is required.`);
+    assertOperation(probe.control, `probe '${probe.id}' control`);
+    if (!isRecord(probe.mutation)) {
+        throw new AssuranceInputError(`probe '${probe.id}' mutation is required.`);
+    }
+    enumValue(probe.mutation.dimension, dimensions, `probe '${probe.id}' has invalid or unsupported mutation dimension '${String(probe.mutation.dimension)}'.`);
+    requiredString(probe.mutation.description, `probe '${probe.id}' mutation description is required.`);
+    assertOperation(probe.mutation.operation, `probe '${probe.id}' mutation operation`);
+    if (probe.requires !== undefined &&
+        (!Array.isArray(probe.requires) ||
+            !probe.requires.every((item) => item !== null &&
+                typeof item === "object" &&
+                (item.kind === "construct" || item.kind === "registry-row") &&
+                typeof item.id === "string" &&
+                item.id.length > 0))) {
+        throw new AssuranceInputError(`probe '${probe.id}' requires must be an array of { kind: 'construct' | 'registry-row', id } nodes.`);
+    }
+    if (probe.control.service !== probe.mutation.operation.service) {
+        throw new AssuranceInputError(`probe '${probe.id}' control and mutation must use the same service.`);
+    }
+    const changed = changedDimensions(probe.control, probe.mutation.operation);
+    if (changed.length !== 1 || changed[0] !== probe.mutation.dimension) {
+        const changeDescription = changed.length === 0 ? "no dimensions" : changed.join(", ");
+        throw new AssuranceInputError(`probe '${probe.id}' declares a '${probe.mutation.dimension}' mutation but changes ${changeDescription}.`);
+    }
+}
+function assertOperation(operation, label) {
+    if (!isRecord(operation)) {
+        throw new AssuranceInputError(`${label} must be an object.`);
+    }
+    enumValue(operation.service, services, `${label} has invalid service '${String(operation.service)}'.`);
+    requiredString(operation.path, `${label} path is required.`);
+    const allowedMethods = operation.service === "firestore"
+        ? firestoreMethods
+        : operation.service === "rtdb"
+            ? rtdbMethods
+            : storageMethods;
+    enumValue(operation.method, allowedMethods, `${label} has invalid ${operation.service} method '${String(operation.method)}'.`);
+    if (operation.service === "firestore" &&
+        operation.data !== undefined &&
+        !isRecord(operation.data)) {
+        throw new AssuranceInputError(`${label} data must be an object.`);
+    }
+    if (operation.service !== "storage" &&
+        operation.query !== undefined &&
+        !isRecord(operation.query)) {
+        throw new AssuranceInputError(`${label} query must be an object.`);
+    }
+    if (operation.service === "storage" &&
+        operation.dataBase64 !== undefined &&
+        typeof operation.dataBase64 !== "string") {
+        throw new AssuranceInputError(`${label} dataBase64 must be a string.`);
+    }
+    if (operation.service === "storage") {
+        if (operation.contentType !== undefined &&
+            typeof operation.contentType !== "string") {
+            throw new AssuranceInputError(`${label} contentType must be a string.`);
+        }
+        if (operation.customMetadata !== undefined) {
+            if (!isRecord(operation.customMetadata) ||
+                !Object.values(operation.customMetadata).every((value) => typeof value === "string")) {
+                throw new AssuranceInputError(`${label} customMetadata must contain only string values.`);
+            }
+        }
+    }
+}
+function stableValue(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableValue).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableValue(record[key])}`)
+        .join(",")}}`;
+}
+function payload(operation) {
+    if (operation.service === "storage") {
+        return {
+            dataBase64: operation.dataBase64,
+            contentType: operation.contentType,
+            customMetadata: operation.customMetadata,
+        };
+    }
+    return operation.data;
+}
+function queryShape(operation) {
+    return operation.service === "storage" ? undefined : operation.query;
+}
+export function changedDimensions(control, mutation) {
+    const changed = [];
+    if (control.method !== mutation.method)
+        changed.push("operation");
+    if (control.path !== mutation.path)
+        changed.push("path");
+    if (stableValue(queryShape(control)) !== stableValue(queryShape(mutation))) {
+        changed.push("query");
+    }
+    if (stableValue(payload(control)) !== stableValue(payload(mutation))) {
+        changed.push("payload");
+    }
+    return changed;
+}
+//# sourceMappingURL=validation.js.map

package/dist/assurance/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/assurance/validation.ts"],"names":[],"mappings":"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"}

package/dist/bridge/client/bridge.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Browser-side bridge client. Connects an in-page `Sandbox` to a
+ * running pyric bridge process over WebSocket. Once connected,
+ * MCP tool calls reaching the bridge are forwarded here and
+ * dispatched against the in-page `Sandbox`; results flow back
+ * over the same WS.
+ *
+ * Discovery order for the bridge URL:
+ *   1. Explicit `opts.url`.
+ *   2. `window.__PYRIC_BRIDGE_URL__` (set by the Vite plugin).
+ *   3. `ws://${location.hostname}:5174/sandbox` (sidecar default).
+ *
+ * Reconnect strategy: simple exponential backoff up to 30s. The
+ * connection is best-effort — if the bridge is down the host app
+ * keeps working; tool calls just won't reach an external agent.
+ *
+ * Standby: when the bridge closes this connection with the REPLACED code
+ * (another tab registered and won the last-connection-wins slot), the client
+ * does NOT re-hello — that would kick the winner right back out and the two
+ * tabs would fight forever. It health-polls the serve origin at a gentle
+ * jittered cadence and reconnects only once `sandboxConnected` is false
+ * (the winning tab closed or refreshed). Every other close keeps the
+ * immediate reconnect loop — that path is what makes tab-refresh takeover
+ * work.
+ */
+import type { LocalSandbox } from 'pyric/sandbox';
+import type { WorkerOpPayload, WorkerSubPayload } from '../protocol.js';
+export interface ConnectBridgeOptions {
+    /**
+     * Bridge WebSocket URL. Overrides the discovery chain.
+     * Example: `ws://localhost:5174/sandbox`.
+     */
+    url?: string;
+    /**
+     * Stable identifier for this sandbox session — surfaces in the
+     * bridge's audit log entries. Default: a random UUID per page load.
+     */
+    sandboxId?: string;
+    /**
+     * Custom tool dispatcher. Defaults to the built-in sandbox tool
+     * dispatcher (see `./dispatch.ts`). Hosts can replace this to
+     * extend the tool surface.
+     */
+    dispatcher?: SandboxToolDispatcher;
+    /**
+     * Tool names to advertise to the bridge in the hello message.
+     * Defaults to `SANDBOX_TOOL_NAMES`. Override when supplying a
+     * custom dispatcher.
+     */
+    toolNames?: string[];
+    /** Initial reconnect delay in ms (default 500). */
+    initialReconnectDelayMs?: number;
+    /** Max reconnect delay in ms (default 30_000). */
+    maxReconnectDelayMs?: number;
+    /**
+     * Standby poll interval in ms (default 2_000). When the bridge closes this
+     * connection with the REPLACED code (another tab took the peer slot), the
+     * client polls the health endpoint at this cadence — plus per-poll jitter,
+     * so two standby tabs don't stampede a freshly vacant slot — and only
+     * reconnects when `sandboxConnected` is false.
+     */
+    standbyPollMs?: number;
+    /** Injectable fetch for the standby health poll (tests). Default: global. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Disable the auto-reconnect loop (useful in tests where the test
+     * harness explicitly controls connection lifecycle).
+     */
+    noReconnect?: boolean;
+    /** Called whenever the client transitions connection state. */
+    onStateChange?: (state: ConnectedBridgeState) => void;
+    /**
+     * Generic worker relay (remote sandbox, slice 1). When supplied, the
+     * client advertises the `worker-relay` capability in its hello and routes
+     * `worker-op` / `worker-sub` / `worker-unsub` frames through it — on the
+     * worker path this forwards them into the SharedWorker port
+     * (`relayWorkerOp` / `relayWorkerSub` in `serve/worker/client.ts`).
+     */
+    workerRelay?: WorkerRelay;
+}
+/** Host-supplied handlers that forward relay frames into the SharedWorker. */
+export interface WorkerRelay {
+    /** Dispatch one worker op; resolves with the worker's `res.value`. */
+    op(op: WorkerOpPayload): Promise<unknown>;
+    /**
+     * Register a worker subscription; `onValue` receives every snap value
+     * (including the `{ __error }` establishment-failure convention).
+     * Returns the unsubscribe function.
+     */
+    subscribe(sub: WorkerSubPayload, onValue: (value: unknown) => void): () => void;
+}
+export type ConnectedBridgeState = {
+    kind: 'connecting';
+} | {
+    kind: 'connected';
+    bridgeVersion: string;
+} | {
+    kind: 'disconnected';
+    reason: string;
+} | {
+    kind: 'reconnecting';
+    attempt: number;
+    delayMs: number;
+}
+/**
+ * Another tab holds the peer slot (this connection was closed with the
+ * REPLACED code). The client health-polls until the slot is vacant, then
+ * reconnects. Distinct from `reconnecting`: the bridge is healthy and
+ * deliberately serving a different tab.
+ */
+ | {
+    kind: 'standby';
+};
+export interface SandboxToolDispatcher {
+    /**
+     * Dispatch a tool call. Throws if the tool isn't recognised
+     * (the bridge advertises only what this dispatcher reports it
+     * can handle, so unknowns indicate wire-level drift).
+     */
+    (sandbox: LocalSandbox, name: string, args: Record<string, unknown>): Promise<{
+        ok: boolean;
+        summary: string;
+        data?: unknown;
+    }>;
+}
+export interface ConnectedBridge {
+    /** Close the bridge connection. Does NOT close the underlying sandbox. */
+    disconnect(): void;
+    /** Current connection state. */
+    state(): ConnectedBridgeState;
+}
+export declare function connectBridge(sandbox: LocalSandbox, opts?: ConnectBridgeOptions): ConnectedBridge;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge/client/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../../src/bridge/client/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAOV,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAWxB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,mDAAmD;IACnD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,kDAAkD;IAClD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACtD;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,EAAE,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACjF;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC5D;;;;;GAKG;GACD;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAC5E,EAAE,EAAE,OAAO,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,UAAU,IAAI,IAAI,CAAC;IACnB,gCAAgC;IAChC,KAAK,IAAI,oBAAoB,CAAC;CAC/B;AAaD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,YAAY,EACrB,IAAI,GAAE,oBAAyB,GAC9B,eAAe,CA8WjB"}