@pyric/cli 0.1.0-alpha.9

package/dist/assurance/runner.js

@@ -0,0 +1,633 @@
+import { getAuth, sandbox as authSandbox } from "pyric/auth";
+import { endAt as endAtRtdb, endBefore as endBeforeRtdb, equalTo as equalToRtdb, getAdminDatabase, getDatabase, get as getRtdb, limitToFirst as limitToFirstRtdb, limitToLast as limitToLastRtdb, orderByChild as orderByChildRtdb, orderByKey as orderByKeyRtdb, orderByValue as orderByValueRtdb, query as queryRtdb, ref as rtdbRef, remove as removeRtdb, sandbox as rtdbSandbox, set as setRtdb, startAfter as startAfterRtdb, startAt as startAtRtdb, update as updateRtdb, } from "pyric/database";
+import { collection, deleteDoc, doc, getDoc, getDocs, getFirestore, limit, orderBy, query, setDoc, updateDoc, where, } from "pyric/firestore";
+import { seedDocuments, setRules, snapshotDocuments } from "pyric/sandbox/firestore";
+import { deleteObject, getBlob, getMetadata, getStorageSandbox, listAll, ref as storageRef, updateMetadata, uploadBytes, } from "pyric/storage";
+import { getAdminStorageSandbox } from "pyric/storage/internal";
+import { initializeSandbox, } from "pyric/sandbox";
+import { qualifyProbe } from "./capabilities.js";
+import { assertActor, assertInvariant, assertProbe, assertTarget, } from "./validation.js";
+import { ASSURANCE_CAMPAIGN_SCHEMA, ASSURANCE_REPORT_SCHEMA, AssuranceInputError, } from "./types.js";
+let storageRunSequence = 0;
+function assertCampaign(spec) {
+    if (spec.schema !== ASSURANCE_CAMPAIGN_SCHEMA) {
+        throw new AssuranceInputError(`campaign schema must be '${ASSURANCE_CAMPAIGN_SCHEMA}'.`);
+    }
+    if (!spec.id.trim())
+        throw new AssuranceInputError("campaign id is required.");
+    assertTarget(spec.target);
+    if (!Array.isArray(spec.actors)) {
+        throw new AssuranceInputError("campaign actors must be an array.");
+    }
+    if (!Array.isArray(spec.invariants)) {
+        throw new AssuranceInputError("campaign invariants must be an array.");
+    }
+    if (!Array.isArray(spec.probes)) {
+        throw new AssuranceInputError("campaign probes must be an array.");
+    }
+    for (const actor of spec.actors)
+        assertActor(actor);
+    for (const invariant of spec.invariants)
+        assertInvariant(invariant);
+    for (const probe of spec.probes)
+        assertProbe(probe);
+    uniqueIds(spec.actors, "actor");
+    uniqueIds(spec.invariants, "invariant");
+    uniqueIds(spec.probes, "probe");
+    for (const probe of spec.probes) {
+        const actor = spec.actors.find((item) => item.id === probe.actorId);
+        const invariant = spec.invariants.find((item) => item.id === probe.invariantId);
+        if (!actor)
+            throw new AssuranceInputError(`probe '${probe.id}' references unknown actor '${probe.actorId}'.`);
+        if (!invariant) {
+            throw new AssuranceInputError(`probe '${probe.id}' references unknown invariant '${probe.invariantId}'.`);
+        }
+        if (invariant.service !== "cross-service" &&
+            invariant.service !== probe.control.service) {
+            throw new AssuranceInputError(`probe '${probe.id}' service does not match invariant '${invariant.id}'.`);
+        }
+    }
+}
+function uniqueIds(items, label) {
+    const seen = new Set();
+    for (const item of items) {
+        if (!item.id.trim())
+            throw new AssuranceInputError(`${label} id is required.`);
+        if (seen.has(item.id))
+            throw new AssuranceInputError(`duplicate ${label} id '${item.id}'.`);
+        seen.add(item.id);
+    }
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
+}
+function targetHash(target) {
+    const input = stableStringify(target);
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index++) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `fnv1a32-${hash.toString(16).padStart(8, "0")}`;
+}
+function authUsers(target) {
+    return (target.state.auth?.users ?? []).map((user) => ({
+        uid: user.uid,
+        email: user.email ?? `${user.uid}@fixture.pyric.invalid`,
+        password: user.password ?? "__pyric_fixture_password__",
+        ...(user.customClaims ? { customClaims: user.customClaims } : {}),
+    }));
+}
+function seedAuth(sandbox, target) {
+    const auth = getAuth(sandbox);
+    authSandbox.seedUsers(auth, authUsers(target));
+    for (const user of target.state.auth?.users ?? []) {
+        if (user.disabled !== undefined || user.emailVerified !== undefined) {
+            authSandbox.updateUser(auth, user.uid, {
+                ...(user.disabled !== undefined ? { disabled: user.disabled } : {}),
+                ...(user.emailVerified !== undefined
+                    ? { emailVerified: user.emailVerified }
+                    : {}),
+            });
+        }
+    }
+    return auth;
+}
+function acquireActor(sandbox, target, actor) {
+    const auth = seedAuth(sandbox, target);
+    try {
+        switch (actor.acquisition.kind) {
+            case "anonymous-request":
+                return {
+                    auth: null,
+                    evidence: {
+                        actorId: actor.id,
+                        acquisition: actor.acquisition.kind,
+                        reachability: "reachable",
+                    },
+                };
+            case "anonymous-account": {
+                const session = authSandbox.mintSession(auth, { kind: "anonymous" });
+                return {
+                    auth: session.state,
+                    evidence: {
+                        actorId: actor.id,
+                        acquisition: actor.acquisition.kind,
+                        reachability: "reachable",
+                        uid: session.user.uid,
+                    },
+                };
+            }
+            case "password": {
+                const session = authSandbox.mintSession(auth, {
+                    kind: "password",
+                    email: actor.acquisition.email,
+                    password: actor.acquisition.password,
+                });
+                return {
+                    auth: session.state,
+                    evidence: {
+                        actorId: actor.id,
+                        acquisition: actor.acquisition.kind,
+                        reachability: "reachable",
+                        uid: session.user.uid,
+                    },
+                };
+            }
+            case "fixture-user": {
+                const session = authSandbox.mintSession(auth, {
+                    kind: "uid",
+                    uid: actor.acquisition.uid,
+                });
+                return {
+                    auth: session.state,
+                    evidence: {
+                        actorId: actor.id,
+                        acquisition: actor.acquisition.kind,
+                        reachability: "reachable",
+                        uid: session.user.uid,
+                    },
+                };
+            }
+            case "synthetic":
+                return {
+                    auth: {
+                        uid: actor.acquisition.uid,
+                        token: actor.acquisition.token ?? {},
+                    },
+                    evidence: {
+                        actorId: actor.id,
+                        acquisition: actor.acquisition.kind,
+                        reachability: "synthetic",
+                        uid: actor.acquisition.uid,
+                    },
+                };
+        }
+    }
+    catch (error) {
+        return {
+            auth: null,
+            evidence: {
+                actorId: actor.id,
+                acquisition: actor.acquisition.kind,
+                reachability: "unreachable",
+                error: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+async function createRuntime(campaignId, probeId, phase, target, actorRuntime, service) {
+    const sandbox = initializeSandbox();
+    seedAuth(sandbox, target);
+    const context = sandbox.withAuth(actorRuntime.auth);
+    const runtime = { sandbox, actor: actorRuntime };
+    if (service === "firestore") {
+        const firestore = getFirestore(context);
+        setRules(sandbox, target.rules.firestore);
+        seedDocuments(sandbox, target.state.firestore ?? {});
+        runtime.firestore = firestore;
+    }
+    else if (service === "rtdb") {
+        const rtdb = getDatabase(context);
+        const admin = getAdminDatabase(sandbox);
+        rtdbSandbox.setRules(rtdb, target.rules.rtdb);
+        rtdbSandbox.setData(admin, { "/": target.state.rtdb ?? {} });
+        runtime.rtdb = rtdb;
+        runtime.rtdbAdmin = admin;
+    }
+    else {
+        const dbName = [
+            "pyric-assurance",
+            campaignId,
+            probeId,
+            phase,
+            Date.now(),
+            storageRunSequence++,
+        ]
+            .join("-")
+            .replace(/[^a-zA-Z0-9_-]/g, "_");
+        const admin = getAdminStorageSandbox(sandbox, {
+            dbName,
+            rules: target.rules.storage,
+        });
+        for (const object of target.state.storage ?? []) {
+            await uploadBytes(storageRef(admin, object.path), decodeBase64(object.dataBase64), {
+                ...(object.contentType ? { contentType: object.contentType } : {}),
+                ...(object.customMetadata
+                    ? { customMetadata: object.customMetadata }
+                    : {}),
+            });
+        }
+        runtime.storageAdmin = admin;
+        runtime.storage = getStorageSandbox(context, { dbName });
+    }
+    return runtime;
+}
+function decodeBase64(value) {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+function eventEvidence(events) {
+    return events.map((event) => {
+        const raw = event;
+        return {
+            ...(typeof raw.id === "string" ? { id: raw.id } : {}),
+            ...(typeof raw.at === "number" ? { at: raw.at } : {}),
+            ...(typeof raw.kind === "string" ? { kind: raw.kind } : {}),
+            ...(typeof raw.service === "string" ? { service: raw.service } : {}),
+            ...(typeof raw.method === "string" ? { method: raw.method } : {}),
+            ...(typeof raw.op === "string" ? { op: raw.op } : {}),
+            ...(typeof raw.path === "string" ? { path: raw.path } : {}),
+            ...(typeof raw.result === "string" ? { result: raw.result } : {}),
+            ...(raw.auth !== undefined ? { auth: raw.auth } : {}),
+            ...(raw.actor !== undefined ? { actor: raw.actor } : {}),
+            ...(raw.authLens !== undefined ? { authLens: raw.authLens } : {}),
+            ...(Array.isArray(raw.reasons) &&
+                raw.reasons.every((item) => typeof item === "string")
+                ? { reasons: raw.reasons }
+                : {}),
+            ...(raw.origin !== undefined ? { origin: raw.origin } : {}),
+            ...(raw.request !== undefined ? { request: raw.request } : {}),
+            ...(raw.resourceBefore !== undefined
+                ? { resourceBefore: raw.resourceBefore }
+                : {}),
+            ...(raw.matchedRule !== undefined
+                ? { matchedRule: raw.matchedRule }
+                : {}),
+            ...(raw.evaluatedRule !== undefined
+                ? { evaluatedRule: raw.evaluatedRule }
+                : {}),
+            ...(raw.rules !== undefined ? { rules: raw.rules } : {}),
+        };
+    });
+}
+function errorDecision(error) {
+    const code = error?.code;
+    const message = error instanceof Error ? error.message : String(error);
+    const codeString = typeof code === "string" ? code : undefined;
+    const denied = /permission[-_ ]?denied|unauthorized/i.test(message) ||
+        (codeString
+            ? /permission[-_ ]?denied|unauthorized/i.test(codeString)
+            : false);
+    return {
+        decision: denied ? "DENY" : "ERROR",
+        error: { ...(codeString ? { code: codeString } : {}), message },
+    };
+}
+async function executeFirestore(operation, db) {
+    if (operation.service !== "firestore")
+        throw new Error("Expected a Firestore operation.");
+    switch (operation.method) {
+        case "get": {
+            const snapshot = await getDoc(doc(db, operation.path));
+            const exists = typeof snapshot.exists === "function"
+                ? snapshot.exists()
+                : snapshot.exists;
+            return exists ? snapshot.data() : null;
+        }
+        case "list": {
+            const constraints = [];
+            for (const item of operation.query?.where ?? []) {
+                constraints.push(where(item.field, item.op, item.value));
+            }
+            for (const item of operation.query?.orderBy ?? []) {
+                constraints.push(orderBy(item.field, item.direction));
+            }
+            if (operation.query?.limit !== undefined)
+                constraints.push(limit(operation.query.limit));
+            const source = constraints.length
+                ? query(collection(db, operation.path), ...constraints)
+                : collection(db, operation.path);
+            const snapshot = await getDocs(source);
+            return snapshot.docs.map((item) => ({
+                path: `${operation.path.replace(/\/$/, "")}/${item.id}`,
+                data: item.data(),
+            }));
+        }
+        case "create":
+        case "set":
+            await setDoc(doc(db, operation.path), operation.data ?? {});
+            return null;
+        case "merge":
+            await setDoc(doc(db, operation.path), operation.data ?? {}, {
+                merge: true,
+            });
+            return null;
+        case "update":
+            await updateDoc(doc(db, operation.path), operation.data ?? {});
+            return null;
+        case "delete":
+            await deleteDoc(doc(db, operation.path));
+            return null;
+    }
+}
+async function executeRtdb(operation, db) {
+    if (operation.service !== "rtdb")
+        throw new Error("Expected an RTDB operation.");
+    const target = rtdbRef(db, operation.path);
+    switch (operation.method) {
+        case "get": {
+            const constraints = [];
+            const querySpec = operation.query;
+            if (querySpec?.orderBy?.kind === "child") {
+                constraints.push(orderByChildRtdb(querySpec.orderBy.path));
+            }
+            else if (querySpec?.orderBy?.kind === "key") {
+                constraints.push(orderByKeyRtdb());
+            }
+            else if (querySpec?.orderBy?.kind === "value") {
+                constraints.push(orderByValueRtdb());
+            }
+            if (querySpec?.startAt) {
+                constraints.push(startAtRtdb(querySpec.startAt.value, querySpec.startAt.key));
+            }
+            if (querySpec?.startAfter) {
+                constraints.push(startAfterRtdb(querySpec.startAfter.value, querySpec.startAfter.key));
+            }
+            if (querySpec?.endAt) {
+                constraints.push(endAtRtdb(querySpec.endAt.value, querySpec.endAt.key));
+            }
+            if (querySpec?.endBefore) {
+                constraints.push(endBeforeRtdb(querySpec.endBefore.value, querySpec.endBefore.key));
+            }
+            if (querySpec?.equalTo) {
+                constraints.push(equalToRtdb(querySpec.equalTo.value, querySpec.equalTo.key));
+            }
+            if (querySpec?.limitToFirst !== undefined) {
+                constraints.push(limitToFirstRtdb(querySpec.limitToFirst));
+            }
+            if (querySpec?.limitToLast !== undefined) {
+                constraints.push(limitToLastRtdb(querySpec.limitToLast));
+            }
+            const source = constraints.length > 0 ? queryRtdb(target, ...constraints) : target;
+            return (await getRtdb(source)).val();
+        }
+        case "set":
+            await setRtdb(target, operation.data);
+            return null;
+        case "update":
+            if (!operation.data ||
+                typeof operation.data !== "object" ||
+                Array.isArray(operation.data)) {
+                throw new Error("RTDB update data must be an object.");
+            }
+            await updateRtdb(target, operation.data);
+            return null;
+        case "remove":
+            await removeRtdb(target);
+            return null;
+    }
+}
+async function executeStorage(operation, storage) {
+    const target = storageRef(storage, operation.path);
+    switch (operation.method) {
+        case "get": {
+            const [blob, metadata] = await Promise.all([
+                getBlob(target),
+                getMetadata(target),
+            ]);
+            return {
+                text: await blob.text(),
+                contentType: metadata.contentType,
+                customMetadata: metadata.customMetadata ?? {},
+            };
+        }
+        case "list": {
+            const result = await listAll(target);
+            return {
+                items: result.items.map((item) => item.fullPath),
+                prefixes: result.prefixes.map((item) => item.fullPath),
+            };
+        }
+        case "upload": {
+            if (!operation.dataBase64)
+                throw new Error("Storage upload requires dataBase64.");
+            const result = await uploadBytes(target, decodeBase64(operation.dataBase64), {
+                ...(operation.contentType
+                    ? { contentType: operation.contentType }
+                    : {}),
+                ...(operation.customMetadata
+                    ? { customMetadata: operation.customMetadata }
+                    : {}),
+            });
+            return result.metadata;
+        }
+        case "updateMetadata":
+            return updateMetadata(target, {
+                ...(operation.contentType
+                    ? { contentType: operation.contentType }
+                    : {}),
+                ...(operation.customMetadata
+                    ? { customMetadata: operation.customMetadata }
+                    : {}),
+            });
+        case "delete":
+            await deleteObject(target);
+            return null;
+    }
+}
+async function readState(operation, runtime) {
+    if (operation.service === "firestore") {
+        const state = snapshotDocuments(runtime.sandbox);
+        if (operation.method === "list") {
+            const prefix = `${operation.path.replace(/\/$/, "")}/`;
+            return Object.fromEntries(Object.entries(state).filter(([path]) => path.startsWith(prefix)));
+        }
+        return state[operation.path] ?? null;
+    }
+    if (operation.service === "rtdb") {
+        return (await getRtdb(rtdbRef(runtime.rtdbAdmin, operation.path))).val();
+    }
+    return readStorageState(operation, runtime.storageAdmin);
+}
+async function readStorageState(operation, storage) {
+    if (operation.method === "list") {
+        const result = await listAll(storageRef(storage, operation.path));
+        return {
+            items: result.items.map((item) => item.fullPath),
+            prefixes: result.prefixes.map((item) => item.fullPath),
+        };
+    }
+    const target = storageRef(storage, operation.path);
+    try {
+        const [blob, metadata] = await Promise.all([
+            getBlob(target),
+            getMetadata(target),
+        ]);
+        return {
+            text: await blob.text(),
+            contentType: metadata.contentType,
+            customMetadata: metadata.customMetadata ?? {},
+        };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "storage/object-not-found")
+            return null;
+        throw error;
+    }
+}
+async function executeOperation(campaignId, probeId, phase, target, actorRuntime, operation) {
+    const runtime = await createRuntime(campaignId, probeId, phase, target, actorRuntime, operation.service);
+    const before = await readState(operation, runtime);
+    const eventOffset = runtime.sandbox.history().length;
+    let decision = "ALLOW";
+    let output;
+    let failure;
+    try {
+        output =
+            operation.service === "firestore"
+                ? await executeFirestore(operation, runtime.firestore)
+                : operation.service === "rtdb"
+                    ? await executeRtdb(operation, runtime.rtdb)
+                    : await executeStorage(operation, runtime.storage);
+    }
+    catch (error) {
+        const result = errorDecision(error);
+        decision = result.decision;
+        failure = result.error;
+    }
+    const events = eventEvidence(runtime.sandbox.history().slice(eventOffset));
+    const after = await readState(operation, runtime);
+    return {
+        actorEvidence: runtime.actor.evidence,
+        evidence: {
+            operation,
+            decision,
+            ...(output !== undefined ? { output } : {}),
+            ...(failure ? { error: failure } : {}),
+            events,
+        },
+        stateDiff: {
+            changed: stableStringify(before) !== stableStringify(after),
+            before,
+            after,
+        },
+    };
+}
+function skippedEvidence(operation, decision) {
+    return { operation, decision, events: [] };
+}
+function classify(actor, invariant, control, mutation, stateDiff) {
+    if (actor.reachability === "unreachable")
+        return "invalid-probe";
+    if (control.decision !== "ALLOW")
+        return "invalid-probe";
+    if (mutation.decision === "ERROR" || mutation.decision === "UNSUPPORTED")
+        return "invalid-probe";
+    if (mutation.decision === invariant.expected)
+        return "no-counterexample";
+    if (invariant.expected === "DENY" && mutation.decision === "ALLOW") {
+        const hasImpact = stateDiff.changed ||
+            (mutation.output !== undefined && mutation.output !== null);
+        return actor.reachability === "reachable" &&
+            invariant.confidence !== "tentative" &&
+            hasImpact
+            ? "local-counterexample"
+            : "candidate-signal";
+    }
+    return "candidate-signal";
+}
+async function runProbe(spec, probe, hash) {
+    const actor = spec.actors.find((item) => item.id === probe.actorId);
+    const invariant = spec.invariants.find((item) => item.id === probe.invariantId);
+    const qualification = qualifyProbe(spec.target, probe);
+    if (!qualification.supported) {
+        return {
+            campaignId: spec.id,
+            probeId: probe.id,
+            targetHash: hash,
+            actorEvidence: {
+                actorId: actor.id,
+                acquisition: actor.acquisition.kind,
+                reachability: actor.acquisition.kind === "synthetic" ? "synthetic" : "unreachable",
+            },
+            invariant,
+            mutationSpec: probe.mutation,
+            control: skippedEvidence(probe.control, "UNSUPPORTED"),
+            mutation: skippedEvidence(probe.mutation.operation, "UNSUPPORTED"),
+            qualification,
+            classification: qualification.classification ?? "engine-gap",
+        };
+    }
+    const actorRuntime = acquireActor(initializeSandbox(), spec.target, actor);
+    if (actorRuntime.evidence.reachability === "unreachable") {
+        const error = {
+            message: actorRuntime.evidence.error ?? "Actor acquisition failed.",
+        };
+        return {
+            campaignId: spec.id,
+            probeId: probe.id,
+            targetHash: hash,
+            actorEvidence: actorRuntime.evidence,
+            invariant,
+            mutationSpec: probe.mutation,
+            control: { ...skippedEvidence(probe.control, "ERROR"), error },
+            mutation: {
+                ...skippedEvidence(probe.mutation.operation, "ERROR"),
+                error,
+            },
+            qualification,
+            classification: "invalid-probe",
+        };
+    }
+    const control = await executeOperation(spec.id, probe.id, "control", spec.target, actorRuntime, probe.control);
+    const mutation = await executeOperation(spec.id, probe.id, "mutation", spec.target, actorRuntime, probe.mutation.operation);
+    return {
+        campaignId: spec.id,
+        probeId: probe.id,
+        targetHash: hash,
+        actorEvidence: control.actorEvidence,
+        invariant,
+        mutationSpec: probe.mutation,
+        control: control.evidence,
+        mutation: mutation.evidence,
+        stateDiff: mutation.stateDiff,
+        qualification,
+        classification: classify(control.actorEvidence, invariant, control.evidence, mutation.evidence, mutation.stateDiff),
+    };
+}
+function summarize(results) {
+    return {
+        probes: results.length,
+        controlsPassed: results.filter((result) => result.control.decision === "ALLOW").length,
+        localCounterexamples: results.filter((result) => result.classification === "local-counterexample").length,
+        candidateSignals: results.filter((result) => result.classification === "candidate-signal").length,
+        noCounterexamples: results.filter((result) => result.classification === "no-counterexample").length,
+        engineGaps: results.filter((result) => result.classification === "engine-gap").length,
+        invalidProbes: results.filter((result) => result.classification === "invalid-probe").length,
+    };
+}
+export async function runAuthorizationCampaign(spec) {
+    assertCampaign(spec);
+    if (typeof globalThis.indexedDB === "undefined" &&
+        spec.probes.some((probe) => probe.control.service === "storage")) {
+        const fake = await import("fake-indexeddb");
+        Object.assign(globalThis, {
+            indexedDB: fake.indexedDB,
+            IDBKeyRange: fake.IDBKeyRange,
+        });
+    }
+    const hash = targetHash(spec.target);
+    const results = [];
+    for (const probe of spec.probes) {
+        results.push(await runProbe(spec, probe, hash));
+    }
+    return {
+        schema: ASSURANCE_REPORT_SCHEMA,
+        campaignId: spec.id,
+        targetHash: hash,
+        localOnly: { network: "forbid", engine: "pyric-local-sandboxes" },
+        results,
+        summary: summarize(results),
+    };
+}
+//# sourceMappingURL=runner.js.map