@fides-anima/fpp-protocol-core 1.0.2

package/src/merkle.ts

@@ -0,0 +1,138 @@
+/**
+ * Versioned Merkle tree primitives.
+ *
+ * V1 preserves the historical SHA-256(utf8(left+right)) pairing used by
+ * audit proofs. V2 domain-separates leaf and internal-node hashes.
+ */
+
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+import { DIGEST_DOMAINS } from "./digest.js";
+
+export type MerkleProofStep = {
+  hash: string;
+  position: "left" | "right";
+};
+
+export type MerkleProof = {
+  leaf: string;
+  index: number;
+  path: MerkleProofStep[];
+  root: string;
+};
+
+function sha256Hex(data: string): string {
+  return bytesToHex(sha256(utf8ToBytes(data)));
+}
+
+/** Legacy pair hash: SHA-256(utf8(a + b)) with no domain separator. */
+export function hashPairV1(a: string, b: string): string {
+  return sha256Hex(a + b);
+}
+
+/** V2 pair hash: domain-separated internal node. */
+export function hashPairV2(a: string, b: string): string {
+  return sha256Hex(DIGEST_DOMAINS.node + "\0" + a + "\0" + b);
+}
+
+function computeRoot(
+  leaves: string[],
+  hashPair: (a: string, b: string) => string,
+): string {
+  if (leaves.length === 0) return "0".repeat(64);
+  if (leaves.length === 1) return leaves[0]!;
+
+  const level: string[] = [];
+  for (let i = 0; i < leaves.length; i += 2) {
+    const left = leaves[i]!;
+    const right = leaves[i + 1] ?? left;
+    level.push(hashPair(left, right));
+  }
+  return computeRoot(level, hashPair);
+}
+
+function createProof(
+  leaves: string[],
+  index: number,
+  hashPair: (a: string, b: string) => string,
+): MerkleProof | null {
+  if (index < 0 || index >= leaves.length || leaves.length === 0) return null;
+
+  const path: MerkleProofStep[] = [];
+  let currentLevel = [...leaves];
+  let idx = index;
+
+  while (currentLevel.length > 1) {
+    if (currentLevel.length % 2 === 1) {
+      currentLevel.push(currentLevel[currentLevel.length - 1]!);
+    }
+    const siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1;
+    path.push({
+      hash: currentLevel[siblingIdx]!,
+      position: idx % 2 === 0 ? "right" : "left",
+    });
+
+    const nextLevel: string[] = [];
+    for (let i = 0; i < currentLevel.length; i += 2) {
+      nextLevel.push(hashPair(currentLevel[i]!, currentLevel[i + 1]!));
+    }
+    currentLevel = nextLevel;
+    idx = Math.floor(idx / 2);
+  }
+
+  return {
+    leaf: leaves[index]!,
+    index,
+    path,
+    root: currentLevel[0]!,
+  };
+}
+
+function verifyProof(
+  proof: MerkleProof,
+  hashPair: (a: string, b: string) => string,
+): boolean {
+  let current = proof.leaf;
+  for (const step of proof.path) {
+    current =
+      step.position === "left"
+        ? hashPair(step.hash, current)
+        : hashPair(current, step.hash);
+  }
+  return current === proof.root;
+}
+
+export function computeMerkleRootV1(leaves: string[]): string {
+  return computeRoot(leaves, hashPairV1);
+}
+
+export function createMerkleProofV1(
+  leaves: string[],
+  index: number,
+): MerkleProof | null {
+  return createProof(leaves, index, hashPairV1);
+}
+
+export function verifyMerkleProofV1(proof: MerkleProof): boolean {
+  return verifyProof(proof, hashPairV1);
+}
+
+export function computeMerkleRootV2(leaves: string[]): string {
+  return computeRoot(leaves, hashPairV2);
+}
+
+export function createMerkleProofV2(
+  leaves: string[],
+  index: number,
+): MerkleProof | null {
+  return createProof(leaves, index, hashPairV2);
+}
+
+export function verifyMerkleProofV2(proof: MerkleProof): boolean {
+  return verifyProof(proof, hashPairV2);
+}
+
+/** Compatibility aliases matching historical script/plugin names (v1). */
+export const computeMerkleRoot = computeMerkleRootV1;
+export const createMerkleProof = createMerkleProofV1;
+export const verifyMerkleProof = verifyMerkleProofV1;

package/src/quorum.ts

@@ -0,0 +1,193 @@
+/**
+ * Quorum proposal, ballot, and evidence-package schemas.
+ * Quorum finalization produces StandingMandateV1 with evidenceRef
+ * pointing at the evidence digest — not constitutional ratification.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { digest, DIGEST_DOMAINS } from "./digest.js";
+
+export const QUORUM_CLASSES = ["peer-quorum", "steward-quorum"] as const;
+export type QuorumClass = (typeof QUORUM_CLASSES)[number];
+
+export const QUORUM_VOTES = ["aye", "nay", "abstain"] as const;
+export type QuorumVote = (typeof QUORUM_VOTES)[number];
+
+const ScopeSchema = Type.Object(
+  {
+    classifications: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    capabilities: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+  },
+  { additionalProperties: false },
+);
+
+const BudgetsSchema = Type.Object(
+  {
+    maxActions: Type.Optional(Type.Integer({ minimum: 0 })),
+    remainingActions: Type.Optional(Type.Integer({ minimum: 0 })),
+  },
+  { additionalProperties: false },
+);
+
+export const QuorumProposalV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    proposalId: Type.String({ minLength: 1 }),
+    quorumClass: Type.Union([
+      Type.Literal("peer-quorum"),
+      Type.Literal("steward-quorum"),
+    ]),
+    proposerId: Type.String({ minLength: 1 }),
+    /** Digest of the intended unsigned mandate payload. */
+    mandateDigest: Type.String({ minLength: 1 }),
+    scope: ScopeSchema,
+    budgets: BudgetsSchema,
+    mandateValidFrom: Type.String({ minLength: 1 }),
+    mandateValidTo: Type.String({ minLength: 1 }),
+    proposedAt: Type.String({ minLength: 1 }),
+    expiresAt: Type.String({ minLength: 1 }),
+    publicKey: Type.String({ minLength: 1 }),
+    signature: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export type QuorumProposalV1 = Static<typeof QuorumProposalV1Schema>;
+
+export const QuorumBallotV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    ballotId: Type.String({ minLength: 1 }),
+    proposalId: Type.String({ minLength: 1 }),
+    voterId: Type.String({ minLength: 1 }),
+    vote: Type.Union([
+      Type.Literal("aye"),
+      Type.Literal("nay"),
+      Type.Literal("abstain"),
+    ]),
+    /** Must match the proposal's mandateDigest. */
+    mandateDigest: Type.String({ minLength: 1 }),
+    castAt: Type.String({ minLength: 1 }),
+    publicKey: Type.String({ minLength: 1 }),
+    signature: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export type QuorumBallotV1 = Static<typeof QuorumBallotV1Schema>;
+
+export const QuorumEvidencePackageV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    proposal: QuorumProposalV1Schema,
+    ballots: Type.Array(QuorumBallotV1Schema, { minItems: 1 }),
+    finalizedAt: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export type QuorumEvidencePackageV1 = Static<
+  typeof QuorumEvidencePackageV1Schema
+>;
+
+export type QuorumParseResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+export type QuorumProposalParseResult =
+  | { ok: true; proposal: QuorumProposalV1 }
+  | { ok: false; error: string };
+
+export type QuorumBallotParseResult =
+  | { ok: true; ballot: QuorumBallotV1 }
+  | { ok: false; error: string };
+
+export type QuorumEvidenceParseResult =
+  | { ok: true; package: QuorumEvidencePackageV1 }
+  | { ok: false; error: string };
+
+export type BallotMatchResult =
+  | { ok: true }
+  | { ok: false; error: string };
+
+function firstSchemaError(schema: unknown, input: unknown): string {
+  const errors = [...Value.Errors(schema as never, input)];
+  return errors[0] !== undefined
+    ? `${errors[0].path}: ${errors[0].message}`
+    : "invalid input";
+}
+
+export function parseQuorumProposal(input: unknown): QuorumProposalParseResult {
+  if (!Value.Check(QuorumProposalV1Schema, input)) {
+    return {
+      ok: false,
+      error: firstSchemaError(QuorumProposalV1Schema, input),
+    };
+  }
+  return { ok: true, proposal: input };
+}
+
+export function parseQuorumBallot(input: unknown): QuorumBallotParseResult {
+  if (!Value.Check(QuorumBallotV1Schema, input)) {
+    return {
+      ok: false,
+      error: firstSchemaError(QuorumBallotV1Schema, input),
+    };
+  }
+  return { ok: true, ballot: input };
+}
+
+export function parseQuorumEvidencePackage(
+  input: unknown,
+): QuorumEvidenceParseResult {
+  if (!Value.Check(QuorumEvidencePackageV1Schema, input)) {
+    return {
+      ok: false,
+      error: firstSchemaError(QuorumEvidencePackageV1Schema, input),
+    };
+  }
+  return { ok: true, package: input };
+}
+
+/**
+ * Ballot must reference the same proposal and mandateDigest.
+ * Signature cryptographic verification is left to the plugin layer.
+ */
+export function validateBallotAgainstProposal(
+  ballot: QuorumBallotV1,
+  proposal: QuorumProposalV1,
+): BallotMatchResult {
+  if (ballot.proposalId !== proposal.proposalId) {
+    return {
+      ok: false,
+      error: `proposalId mismatch: ballot=${ballot.proposalId} proposal=${proposal.proposalId}`,
+    };
+  }
+  if (ballot.mandateDigest !== proposal.mandateDigest) {
+    return {
+      ok: false,
+      error: "mandateDigest mismatch between ballot and proposal",
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Stable digest of a quorum evidence package for StandingMandateV1.evidenceRef.
+ * Domain-separated so it cannot be confused with claim/receipt digests.
+ */
+export function computeQuorumEvidenceDigest(
+  pkg: QuorumEvidencePackageV1,
+): string {
+  return digest({
+    version: 2,
+    domain: DIGEST_DOMAINS.quorum,
+    value: {
+      schemaVersion: pkg.schemaVersion,
+      proposal: pkg.proposal,
+      ballots: pkg.ballots,
+      finalizedAt: pkg.finalizedAt,
+    },
+  });
+}

package/src/receipts.ts

@@ -0,0 +1,150 @@
+/**
+ * Conformance receipt schema (emission deferred to later plans).
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import {
+  GovernanceEpochSchema,
+  GovernanceModeSchema,
+} from "./governance.js";
+
+const DigestHexSchema = Type.String({ pattern: "^[0-9a-f]{64}$" });
+
+export const ReceiptInclusionEvidenceV1Schema = Type.Object(
+  {
+    evidenceVersion: Type.Literal(1),
+    logKind: Type.Literal("conformance-receipt"),
+    entry: Type.Object(
+      {
+        previousHash: DigestHexSchema,
+        timestamp: Type.String({ minLength: 1 }),
+        kind: Type.Literal("conformance-receipt"),
+        receipt: Type.Unknown(),
+        hash: DigestHexSchema,
+      },
+      { additionalProperties: false },
+    ),
+    proof: Type.Object(
+      {
+        leaf: DigestHexSchema,
+        index: Type.Integer({ minimum: 0 }),
+        path: Type.Array(
+          Type.Object(
+            {
+              hash: DigestHexSchema,
+              position: Type.Union([
+                Type.Literal("left"),
+                Type.Literal("right"),
+              ]),
+            },
+            { additionalProperties: false },
+          ),
+        ),
+        root: DigestHexSchema,
+      },
+      { additionalProperties: false },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export type ReceiptInclusionEvidenceV1 = Static<
+  typeof ReceiptInclusionEvidenceV1Schema
+>;
+
+export type ReceiptInclusionEvidenceParseResult =
+  | { ok: true; evidence: ReceiptInclusionEvidenceV1 }
+  | { ok: false; error: string };
+
+export function parseReceiptInclusionEvidence(
+  input: unknown,
+): ReceiptInclusionEvidenceParseResult {
+  if (!Value.Check(ReceiptInclusionEvidenceV1Schema, input)) {
+    return { ok: false, error: "invalid ReceiptInclusionEvidenceV1" };
+  }
+  return { ok: true, evidence: input };
+}
+
+export const ConformanceReceiptV1Schema = Type.Union([
+  Type.Object(
+    {
+      schemaVersion: Type.Literal(1),
+      receiptClass: Type.Literal("conformance"),
+      actionDigest: DigestHexSchema,
+      policyId: Type.String({ minLength: 1 }),
+      policyVersion: Type.String({ minLength: 1 }),
+      implementationVersion: Type.String({ minLength: 1 }),
+      disposition: Type.Union([
+        Type.Literal("allow"),
+        Type.Literal("deny"),
+        Type.Literal("require_approval"),
+        Type.Literal("abstain"),
+        Type.Literal("allow_staged"),
+        Type.Literal("allow_minimal"),
+      ]),
+      authorization: Type.String({ minLength: 1 }),
+      outcome: Type.String({ minLength: 1 }),
+      issuedAt: Type.String({ minLength: 1 }),
+      constitutionHash: Type.Optional(DigestHexSchema),
+      classifierRulesetHash: Type.Optional(DigestHexSchema),
+      effectiveConfigHash: Type.Optional(DigestHexSchema),
+      // Forbidden when unpaired — both keys must be absent in this branch.
+      governanceEpoch: Type.Optional(Type.Never()),
+      governanceMode: Type.Optional(Type.Never()),
+    },
+    { additionalProperties: true },
+  ),
+  Type.Object(
+    {
+      schemaVersion: Type.Literal(1),
+      receiptClass: Type.Literal("conformance"),
+      actionDigest: DigestHexSchema,
+      policyId: Type.String({ minLength: 1 }),
+      policyVersion: Type.String({ minLength: 1 }),
+      implementationVersion: Type.String({ minLength: 1 }),
+      disposition: Type.Union([
+        Type.Literal("allow"),
+        Type.Literal("deny"),
+        Type.Literal("require_approval"),
+        Type.Literal("abstain"),
+        Type.Literal("allow_staged"),
+        Type.Literal("allow_minimal"),
+      ]),
+      authorization: Type.String({ minLength: 1 }),
+      outcome: Type.String({ minLength: 1 }),
+      issuedAt: Type.String({ minLength: 1 }),
+      constitutionHash: Type.Optional(DigestHexSchema),
+      classifierRulesetHash: Type.Optional(DigestHexSchema),
+      effectiveConfigHash: Type.Optional(DigestHexSchema),
+      /** Gateway governance binding — both fields required together. */
+      governanceEpoch: GovernanceEpochSchema,
+      governanceMode: GovernanceModeSchema,
+    },
+    { additionalProperties: true },
+  ),
+]);
+
+export type ConformanceReceiptV1 = Static<typeof ConformanceReceiptV1Schema>;
+
+export type ReceiptParseResult =
+  | { ok: true; receipt: ConformanceReceiptV1 }
+  | { ok: false; error: string };
+
+export function parseConformanceReceipt(input: unknown): ReceiptParseResult {
+  if (!Value.Check(ConformanceReceiptV1Schema, input)) {
+    return { ok: false, error: "invalid ConformanceReceiptV1" };
+  }
+  const issuedAt = (input as ConformanceReceiptV1).issuedAt;
+  const issuedAtMs = Date.parse(issuedAt);
+  if (
+    !Number.isFinite(issuedAtMs) ||
+    new Date(issuedAtMs).toISOString() !== issuedAt
+  ) {
+    return {
+      ok: false,
+      error: "invalid ConformanceReceiptV1: issuedAt must be canonical ISO-8601",
+    };
+  }
+  return { ok: true, receipt: input as ConformanceReceiptV1 };
+}