@spacefast/common 0.0.26 → 0.2.2

package/dist/contracts/content-contract-verification.js

@@ -0,0 +1,320 @@
+import { z } from "zod";
+import { canonicalJson } from "../utils/canonical-json.js";
+import { applicationJournalDeliveryClaimV1Schema, applicationJournalDeliveryReceiptV1Schema, applicationJournalEntryV1Schema, } from "./application-journal.js";
+import { compiledContentProgramV1Schema, contentExecutableSetV1Schema, contentProgramJsonValueSchema, contentProgramReleaseV1Schema, contentProgramSha256Schema, contentRouteContributionSetV1Schema, contentSdkDescriptorSetV1Schema, } from "./content-program.js";
+import { contentMarkdownConflictProblemSchema, syncReconciliationExchangeV1Schema, syncSourceAcknowledgementV1Schema, syncLedgerV1Schema, } from "./content-sync.js";
+import { frameGrantDecisionV1Schema, frameLaunchTicketClaimsV1Schema, frameSessionClaimsV1Schema, } from "./frame-session.js";
+import { principalAssertionV1Schema } from "./principal-assertion.js";
+import { routeInventoryV1Schema, spaceRouteSnapshotV1Schema, } from "./route-inventory.js";
+import { programRequirementsV1Schema, runtimeComponentInventoryV1Schema, runtimeComponentPlacementReceiptV1Schema, runtimeComponentPlacementTargetV1Schema, } from "./runtime-components.js";
+const encoder = new TextEncoder();
+async function sha256Text(value) {
+    const encoded = encoder.encode(value);
+    const bytes = new ArrayBuffer(encoded.byteLength);
+    new Uint8Array(bytes).set(encoded);
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return contentProgramSha256Schema.parse(`sha256:${hex}`);
+}
+export function contentContractSha256(value) {
+    return sha256Text(canonicalJson(value));
+}
+export function contentContractTextSha256(value) {
+    return sha256Text(value);
+}
+async function requireDigest(actual, meaning, subject) {
+    const expected = await contentContractSha256(meaning);
+    if (actual !== expected) {
+        throw new TypeError(`${subject} digest mismatch: expected ${expected}, received ${actual}`);
+    }
+}
+async function requireTextDigest(actual, value, subject) {
+    const expected = await contentContractTextSha256(value);
+    if (actual !== expected) {
+        throw new TypeError(`${subject} digest mismatch: expected ${expected}, received ${actual}`);
+    }
+}
+function requireSameValue(actual, expected, subject) {
+    if (canonicalJson(actual) !== canonicalJson(expected)) {
+        throw new TypeError(`${subject} mismatch`);
+    }
+}
+function frameGrantDecisionMeaning(claims) {
+    return frameGrantDecisionV1Schema.parse({
+        format: "spacefast.frame-grant-decision",
+        version: 1,
+        audience: claims.audience,
+        link: claims.link,
+        principal: claims.principal,
+        target: claims.target,
+        surface: claims.surface,
+        parentOrigin: claims.parentOrigin,
+        capabilities: claims.capabilities,
+        accessGeneration: claims.accessGeneration,
+        sessionVersion: claims.sessionVersion,
+    });
+}
+export async function verifyContentProgramReleaseV1(value) {
+    const program = contentProgramReleaseV1Schema.parse(value);
+    await Promise.all(program.schemas.map((definition) => requireDigest(definition.sha256, definition.schema, `schema ${definition.id}`)));
+    const { revision, ...meaning } = program;
+    await requireDigest(revision, meaning, "content program revision");
+    return program;
+}
+export const compiledContentProgramBundleV1Schema = z
+    .object({
+    capsule: contentProgramJsonValueSchema,
+    artifacts: z
+        .object({
+        program: contentProgramReleaseV1Schema,
+        executables: contentExecutableSetV1Schema,
+        sdk: contentSdkDescriptorSetV1Schema,
+        routes: contentRouteContributionSetV1Schema,
+        requirements: programRequirementsV1Schema,
+    })
+        .strict(),
+    compiled: compiledContentProgramV1Schema,
+})
+    .strict();
+export async function verifyCompiledContentProgramBundleV1(value) {
+    const bundle = compiledContentProgramBundleV1Schema.parse(value);
+    const capsuleDigest = await contentContractSha256(bundle.capsule);
+    const program = await verifyContentProgramReleaseV1(bundle.artifacts.program);
+    await Promise.all([
+        verifyContentArtifactV1(bundle.compiled.program, bundle.artifacts.program, capsuleDigest, false),
+        verifyContentArtifactV1(bundle.compiled.executables, bundle.artifacts.executables, program.revision),
+        verifyContentArtifactV1(bundle.compiled.sdk, bundle.artifacts.sdk, program.revision),
+        verifyContentArtifactV1(bundle.compiled.routes, bundle.artifacts.routes, program.revision),
+        verifyContentArtifactV1(bundle.compiled.requirements, bundle.artifacts.requirements, program.revision),
+    ]);
+    requireSameValue(bundle.artifacts.executables.executables.map((executable) => executable.id), [...program.abilities.map((ability) => ability.id), ...program.hooks.map((hook) => hook.id)], "content executable identities");
+    requireSameValue(bundle.artifacts.sdk.operations.map(({ invalidates: _invalidates, ...operation }) => operation), program.abilities.map((ability) => ({
+        id: ability.id,
+        kind: ability.kind,
+        mode: ability.mode,
+        input: ability.input,
+        output: ability.output,
+        cache: ability.cache,
+    })), "content SDK operation descriptors");
+    const abilityIds = new Set(program.abilities.map((ability) => ability.id));
+    for (const operation of bundle.artifacts.sdk.operations) {
+        for (const invalidatedAbility of operation.invalidates) {
+            if (!abilityIds.has(invalidatedAbility)) {
+                throw new TypeError(`content SDK operation ${operation.id} invalidates unknown ability ${invalidatedAbility}`);
+            }
+        }
+    }
+    requireSameValue(bundle.artifacts.sdk.sync, program.syncBindings.map((binding) => ({
+        id: binding.id,
+        resourceId: binding.resourceId,
+        source: binding.source,
+    })), "content SDK sync descriptors");
+    requireSameValue(bundle.artifacts.routes.routes, program.abilities.flatMap((ability) => ability.exposure.kind === "routed"
+        ? [{ abilityId: ability.id, route: ability.exposure.route }]
+        : []), "content route contributions");
+    return bundle;
+}
+export async function verifySyncLedgerV1(value) {
+    const ledger = syncLedgerV1Schema.parse(value);
+    const { revision, ...meaning } = ledger;
+    await requireDigest(revision, meaning, "sync ledger revision");
+    await requireTextDigest(ledger.markdownDigest, ledger.baseMarkdown, "sync ledger Markdown");
+    return ledger;
+}
+export async function verifySyncReconciliationExchangeV1(value, acknowledgement) {
+    const exchange = syncReconciliationExchangeV1Schema.parse(value);
+    await verifySyncLedgerV1(exchange.receipt.ledger);
+    if (exchange.receipt.status !== "pulled" &&
+        exchange.receipt.ledger.baseMarkdown !== exchange.request.markdown) {
+        throw new TypeError(`sync ${exchange.receipt.status} receipt must commit the requested Markdown`);
+    }
+    if (acknowledgement === undefined)
+        return { exchange };
+    const parsedAcknowledgement = syncSourceAcknowledgementV1Schema.parse(acknowledgement);
+    if (exchange.receipt.status !== "pulled") {
+        throw new TypeError("only a prepared source pull accepts a source acknowledgement");
+    }
+    if (parsedAcknowledgement.bindingId !== exchange.request.bindingId) {
+        throw new TypeError("sync acknowledgement binding mismatch");
+    }
+    if (parsedAcknowledgement.operationId !== exchange.request.operationId) {
+        throw new TypeError("sync acknowledgement operation mismatch");
+    }
+    if (parsedAcknowledgement.baseRevision !== exchange.receipt.ledger.revision) {
+        throw new TypeError("sync acknowledgement base revision mismatch");
+    }
+    return { exchange, acknowledgement: parsedAcknowledgement };
+}
+export async function verifyContentMarkdownConflictProblem(value) {
+    const problem = contentMarkdownConflictProblemSchema.parse(value);
+    await Promise.all(["base", "source", "wordpress"].map((side) => requireTextDigest(problem.details[side].digest, problem.details[side].markdown, `sync conflict ${side}`)));
+    return problem;
+}
+export async function verifyFrameLaunchTicketClaimsV1(value) {
+    const ticket = frameLaunchTicketClaimsV1Schema.parse(value);
+    await requireDigest(ticket.grantDecisionDigest, frameGrantDecisionMeaning(ticket), "Frame launch Grant decision");
+    return ticket;
+}
+export async function verifyFrameSessionClaimsV1(value) {
+    const session = frameSessionClaimsV1Schema.parse(value);
+    await requireDigest(session.grantDecisionDigest, frameGrantDecisionMeaning(session), "Frame session Grant decision");
+    return session;
+}
+export async function verifyFrameProtocolV1(input) {
+    const principalAssertion = principalAssertionV1Schema.parse(input.principalAssertion);
+    const [launchTicket, session] = await Promise.all([
+        verifyFrameLaunchTicketClaimsV1(input.launchTicket),
+        verifyFrameSessionClaimsV1(input.session),
+    ]);
+    if (principalAssertion.actor.kind !== "user") {
+        throw new TypeError("Frame sessions require a user principal assertion");
+    }
+    requireSameValue(launchTicket.audience, principalAssertion.audience, "Frame ticket audience");
+    requireSameValue(session.audience, principalAssertion.audience, "Frame session audience");
+    const assertedPrincipal = {
+        kind: "user",
+        id: principalAssertion.actor.id,
+        assertionNonce: principalAssertion.nonce,
+    };
+    requireSameValue(launchTicket.principal, assertedPrincipal, "Frame ticket principal");
+    requireSameValue(session.principal, assertedPrincipal, "Frame session principal");
+    if (launchTicket.accessGeneration !== principalAssertion.accessGeneration ||
+        session.accessGeneration !== principalAssertion.accessGeneration) {
+        throw new TypeError("Frame access generation mismatch");
+    }
+    if (launchTicket.sessionVersion !== principalAssertion.sessionVersion ||
+        session.sessionVersion !== principalAssertion.sessionVersion) {
+        throw new TypeError("Frame session version mismatch");
+    }
+    requireSameValue(frameGrantDecisionMeaning(session), frameGrantDecisionMeaning(launchTicket), "Frame ticket and session Grant decision");
+    if (session.launchTicketId !== launchTicket.ticketId) {
+        throw new TypeError("Frame session launch ticket mismatch");
+    }
+    if (launchTicket.issuedAt < principalAssertion.issuedAt ||
+        launchTicket.expiresAt > principalAssertion.expiresAt) {
+        throw new TypeError("Frame launch ticket exceeds its principal assertion lifetime");
+    }
+    if (session.issuedAt < launchTicket.issuedAt || session.issuedAt >= launchTicket.expiresAt) {
+        throw new TypeError("Frame session was not issued while its launch ticket was valid");
+    }
+    if (session.expiresAt > principalAssertion.expiresAt) {
+        throw new TypeError("Frame session exceeds its principal assertion lifetime");
+    }
+    return { principalAssertion, launchTicket, session };
+}
+export async function verifyApplicationJournalEntryV1(value) {
+    const entry = applicationJournalEntryV1Schema.parse(value);
+    await requireDigest(entry.payloadDigest, entry.payload, "application journal payload");
+    return entry;
+}
+export async function verifyApplicationJournalDeliveryV1(entryValue, claimValue, receiptValue) {
+    const entry = await verifyApplicationJournalEntryV1(entryValue);
+    const claim = applicationJournalDeliveryClaimV1Schema.parse(claimValue);
+    const receipt = applicationJournalDeliveryReceiptV1Schema.parse(receiptValue);
+    await verifyApplicationJournalEntryV1(claim.entry);
+    requireSameValue(claim.entry, entry, "application journal claim entry");
+    requireSameValue(receipt.fence, claim.fence, "application journal delivery fence");
+    if (receipt.idempotencyKey !== claim.idempotencyKey) {
+        throw new TypeError("application journal delivery idempotency key mismatch");
+    }
+    return { entry, claim, receipt };
+}
+export async function verifyRuntimeComponentInventoryV1(value) {
+    const inventory = runtimeComponentInventoryV1Schema.parse(value);
+    const { digest, ...meaning } = inventory;
+    await requireDigest(digest, meaning, "runtime component inventory");
+    return inventory;
+}
+export async function verifyProgramRuntimeCompatibilityV1(requirementsValue, inventoryValue) {
+    const requirements = programRequirementsV1Schema.parse(requirementsValue);
+    const inventory = await verifyRuntimeComponentInventoryV1(inventoryValue);
+    const provided = new Set(inventory.components.flatMap((component) => component.provides));
+    const missing = requirements.capabilities.filter((capability) => !provided.has(capability));
+    if (missing.length > 0) {
+        throw new TypeError(`runtime components do not provide ${missing.join(", ")}`);
+    }
+    return { requirements, inventory };
+}
+export async function verifyRuntimePlacementReadinessV1(input) {
+    const receipt = runtimeComponentPlacementReceiptV1Schema.parse(input.receipt);
+    if (receipt.status !== "ready") {
+        throw new TypeError("runtime placement is not ready");
+    }
+    const expectedTarget = runtimeComponentPlacementTargetV1Schema.parse(input.expectedTarget);
+    const [inventory, routeInventory, routeSnapshot] = await Promise.all([
+        verifyRuntimeComponentInventoryV1(input.inventory),
+        verifyRouteInventoryV1(input.routeInventory),
+        verifySpaceRouteSnapshotV1(input.routeSnapshot),
+    ]);
+    requireSameValue(receipt.target, expectedTarget, "runtime placement target");
+    if (receipt.platformRelease !== inventory.platformRelease) {
+        throw new TypeError("runtime placement platform release mismatch");
+    }
+    if (receipt.expectedInventoryDigest !== inventory.digest ||
+        receipt.observedInventoryDigest !== inventory.digest) {
+        throw new TypeError("runtime placement component inventory mismatch");
+    }
+    if (receipt.substrate.routing.snapshotRevision !== routeSnapshot.revision) {
+        throw new TypeError("runtime placement route snapshot mismatch");
+    }
+    const routeInventoryDigest = await contentContractSha256(routeInventory);
+    if (receipt.substrate.routing.inventoryDigest !== routeInventoryDigest) {
+        throw new TypeError("runtime placement route inventory mismatch");
+    }
+    if (routeSnapshot.spaceId !== expectedTarget.spaceId) {
+        throw new TypeError("runtime placement route snapshot target mismatch");
+    }
+    return { receipt, expectedTarget, inventory, routeInventory, routeSnapshot };
+}
+export async function verifySpaceRouteSnapshotV1(value) {
+    const snapshot = spaceRouteSnapshotV1Schema.parse(value);
+    const { revision, ...meaning } = snapshot;
+    await requireDigest(revision, meaning, "Space route snapshot revision");
+    return snapshot;
+}
+function routeInventoryRecordIdMeaning(route) {
+    return {
+        kind: route.kind,
+        source: route.source,
+        runtime: route.runtime,
+        host: route.host,
+        path: route.path,
+        methods: route.methods,
+        auth: route.auth,
+        cache: "cache" in route ? (route.cache ?? null) : null,
+        destination: "destination" in route ? route.destination : null,
+        status: "status" in route ? route.status : null,
+    };
+}
+export async function verifyRouteInventoryV1(value) {
+    const inventory = routeInventoryV1Schema.parse(value);
+    const semanticIds = await Promise.all(inventory.routes.map((route) => contentContractSha256(routeInventoryRecordIdMeaning(route))));
+    const occurrences = new Map();
+    const expectedIds = await Promise.all(semanticIds.map((semanticId) => {
+        const occurrence = occurrences.get(semanticId) ?? 0;
+        occurrences.set(semanticId, occurrence + 1);
+        return occurrence === 0
+            ? semanticId
+            : contentContractSha256({ route: semanticId, occurrence });
+    }));
+    for (const [index, route] of inventory.routes.entries()) {
+        const expected = expectedIds[index];
+        if (route.id !== expected) {
+            throw new TypeError(`route ${route.source} digest mismatch: expected ${expected}, received ${route.id}`);
+        }
+    }
+    return inventory;
+}
+export async function verifyContentArtifactV1(ref, artifact, expectedInputDigest, payloadCarriesInputDigest = true) {
+    if (ref.inputDigest !== expectedInputDigest) {
+        throw new TypeError(`content artifact input digest mismatch: expected ${expectedInputDigest}, received ${ref.inputDigest}`);
+    }
+    if (payloadCarriesInputDigest && artifact.inputDigest !== expectedInputDigest) {
+        throw new TypeError(`content artifact payload input digest mismatch: expected ${expectedInputDigest}, received ${String(artifact.inputDigest)}`);
+    }
+    await requireDigest(ref.sha256, artifact, "content artifact");
+    const bytes = encoder.encode(canonicalJson(artifact)).byteLength;
+    if (ref.bytes !== bytes) {
+        throw new TypeError(`content artifact byte length mismatch: expected ${bytes}, received ${ref.bytes}`);
+    }
+}