@fides-anima/fpp-protocol-core 1.0.2

package/src/digest.ts

@@ -0,0 +1,63 @@
+/**
+ * Versioned digests with optional domain separation.
+ *
+ * V1 entry hashes omit domain prefixes so historical audit chains verify.
+ * V2 digests always include a domain label to prevent cross-type reuse.
+ */
+
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+import { canonicalizeV1, canonicalizeV2 } from "./canonical-json.js";
+
+/** Well-known digest domains for v2 payloads. */
+export const DIGEST_DOMAINS = {
+  entry: "fpp:v2:entry",
+  claim: "fpp:v2:claim",
+  leaf: "fpp:v2:merkle-leaf",
+  node: "fpp:v2:merkle-node",
+  receipt: "fpp:v2:receipt",
+  capsule: "fpp:v2:capsule",
+  evidence: "fpp:v2:evidence",
+  adoption: "fpp:v2:adoption",
+  quorum: "fpp:v2:quorum",
+  mandate: "fpp:v2:mandate",
+} as const;
+
+export type DigestDomain =
+  (typeof DIGEST_DOMAINS)[keyof typeof DIGEST_DOMAINS] | (string & {});
+
+function sha256Hex(data: string): string {
+  return bytesToHex(sha256(utf8ToBytes(data)));
+}
+
+/**
+ * Historical v1 entry digest: SHA-256 of canonicalizeV1(entry without hash).
+ */
+export function hashEntryV1(entry: Record<string, unknown>): string {
+  const { hash: _ignored, ...rest } = entry;
+  void _ignored;
+  return sha256Hex(canonicalizeV1(rest));
+}
+
+export type DigestInput =
+  | { version: 1; value: unknown; domain?: never }
+  | { version: 2; value: unknown; domain: DigestDomain };
+
+/**
+ * Compute a versioned digest. Version 2 requires a domain separator.
+ */
+export function digest(input: DigestInput): string {
+  if (input.version === 1) {
+    if (input.value !== null && typeof input.value === "object" && !Array.isArray(input.value)) {
+      return hashEntryV1(input.value as Record<string, unknown>);
+    }
+    return sha256Hex(canonicalizeV1(input.value));
+  }
+  if (input.version === 2) {
+    if (!input.domain || typeof input.domain !== "string") {
+      throw new Error("digest version 2 requires a domain separator");
+    }
+    return sha256Hex(input.domain + "\0" + canonicalizeV2(input.value));
+  }
+  throw new Error(`unsupported digest version: ${(input as { version: unknown }).version}`);
+}

package/src/disposition.ts

@@ -0,0 +1,74 @@
+/**
+ * Disposition decisions and authorization classes for unattended /
+ * operator-present policy resolution and receipt emission.
+ */
+
+export const DISPOSITION_DECISIONS = [
+  "allow",
+  "deny",
+  "require_approval",
+  "abstain",
+  "allow_staged",
+  "allow_minimal",
+] as const;
+
+export type DispositionDecision = (typeof DISPOSITION_DECISIONS)[number];
+
+export const AUTHORIZATION_CLASSES = [
+  "mandate",
+  "standing-allowlist",
+  "emergency",
+  "quorum-mandate",
+  "abstain",
+  "approved",
+  "policy-block",
+] as const;
+
+export type AuthorizationClass = (typeof AUTHORIZATION_CLASSES)[number];
+
+/**
+ * Named authorization-class constants for call sites.
+ * Prefer `AUTHZ.*` (or `const authorization = AUTHZ.…; { authorization }`)
+ * over `authorization: "<literal>"` so static scanners do not treat
+ * AuthorizationClass strings as exposed API-token secret literals.
+ */
+export const AUTHZ = {
+  mandate: "mandate",
+  standingAllowlist: "standing-allowlist",
+  emergency: "emergency",
+  quorumMandate: "quorum-mandate",
+  abstain: "abstain",
+  approved: "approved",
+  policyBlock: "policy-block",
+} as const satisfies Record<string, AuthorizationClass>;
+
+export type DispositionParseResult =
+  | { ok: true; disposition: DispositionDecision }
+  | { ok: false; error: string };
+
+export function isDispositionDecision(
+  value: unknown,
+): value is DispositionDecision {
+  return (
+    typeof value === "string" &&
+    (DISPOSITION_DECISIONS as readonly string[]).includes(value)
+  );
+}
+
+export function isAuthorizationClass(
+  value: unknown,
+): value is AuthorizationClass {
+  return (
+    typeof value === "string" &&
+    (AUTHORIZATION_CLASSES as readonly string[]).includes(value)
+  );
+}
+
+export function parseDispositionDecision(
+  input: unknown,
+): DispositionParseResult {
+  if (!isDispositionDecision(input)) {
+    return { ok: false, error: "invalid DispositionDecision" };
+  }
+  return { ok: true, disposition: input };
+}

package/src/emergency-override.ts

@@ -0,0 +1,168 @@
+/**
+ * Signed emergency override grant — mandate-shaped but mandate-separate.
+ *
+ * Stewards only for v1: agent-to-agent (peer) escalation without steward
+ * involvement is a materially larger trust decision; not an oversight.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { canonicalizeV2 } from "./canonical-json.js";
+import { verifySignature } from "./identity.js";
+
+export const SignedEmergencyOverrideV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    overrideId: Type.String({ minLength: 1 }),
+    issuerId: Type.String({ minLength: 1 }),
+    publicKey: Type.String({ minLength: 1 }),
+    signature: Type.String({ minLength: 1 }),
+    scope: Type.Object(
+      {
+        classifications: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        capabilities: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+      },
+      { additionalProperties: false },
+    ),
+    budgets: Type.Object(
+      {
+        maxActions: Type.Optional(Type.Integer({ minimum: 0 })),
+        remainingActions: Type.Optional(Type.Integer({ minimum: 0 })),
+      },
+      { additionalProperties: false },
+    ),
+    validFrom: Type.String({ minLength: 1 }),
+    validTo: Type.String({ minLength: 1 }),
+    evidenceRef: Type.String({ minLength: 1 }),
+    revoked: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+);
+
+export type SignedEmergencyOverrideV1 = Static<
+  typeof SignedEmergencyOverrideV1Schema
+>;
+
+/** Mutable runtime counters — never part of the signed grant payload. */
+export type EmergencyOverrideLedgerEntry = {
+  remainingActions?: number;
+  revoked?: boolean;
+};
+
+/**
+ * Shared on-disk emergency override store shape.
+ * `ledgers` is additive; absent keys mean unlimited budget / not revoked.
+ */
+export type EmergencyOverrideStoreFile = {
+  schemaVersion: 1;
+  overrides: SignedEmergencyOverrideV1[];
+  ledgers?: Record<string, EmergencyOverrideLedgerEntry>;
+};
+
+export type EmergencyOverrideParseResult =
+  | { ok: true; override: SignedEmergencyOverrideV1 }
+  | { ok: false; error: string };
+
+export type EmergencyOverrideValidityPolicy = {
+  /** Verifier clock — not signer-controlled. */
+  nowMs: number;
+};
+
+export type EmergencyOverrideValidity = {
+  valid: boolean;
+  reason: string;
+};
+
+export function parseSignedEmergencyOverride(
+  input: unknown,
+): EmergencyOverrideParseResult {
+  if (!Value.Check(SignedEmergencyOverrideV1Schema, input)) {
+    const errors = [...Value.Errors(SignedEmergencyOverrideV1Schema, input)];
+    return {
+      ok: false,
+      error:
+        errors[0] !== undefined
+          ? `${errors[0].path}: ${errors[0].message}`
+          : "invalid SignedEmergencyOverrideV1",
+    };
+  }
+  return { ok: true, override: input };
+}
+
+/**
+ * Temporal / revocation check for a schema-valid emergency override.
+ * Budget debit and signature verification live in the enforcement store.
+ */
+export function validateEmergencyOverrideValidity(
+  override: SignedEmergencyOverrideV1,
+  policy: EmergencyOverrideValidityPolicy,
+): EmergencyOverrideValidity {
+  if (override.revoked === true) {
+    return { valid: false, reason: "emergency override revoked" };
+  }
+  const from = Date.parse(override.validFrom);
+  const to = Date.parse(override.validTo);
+  if (Number.isNaN(from) || Number.isNaN(to)) {
+    return { valid: false, reason: "validFrom/validTo must be ISO-8601" };
+  }
+  if (to <= from) {
+    return { valid: false, reason: "validTo must be after validFrom" };
+  }
+  if (policy.nowMs < from) {
+    return {
+      valid: false,
+      reason: "emergency override not yet valid (validFrom)",
+    };
+  }
+  if (policy.nowMs > to) {
+    return { valid: false, reason: "emergency override expired" };
+  }
+  return { valid: true, reason: "ok" };
+}
+
+/**
+ * Canonical unsigned payload for emergency override signatures.
+ * Excludes `signature`, `revoked`, and `budgets.remainingActions` so debit/revoke
+ * can mutate an unsigned ledger without invalidating the grant.
+ */
+export function emergencyOverrideSigningFields(
+  override: SignedEmergencyOverrideV1,
+): Record<string, unknown> {
+  const {
+    signature: _signature,
+    revoked: _revoked,
+    budgets,
+    ...rest
+  } = override;
+  void _signature;
+  void _revoked;
+  const signingBudgets: Record<string, unknown> = {};
+  if (budgets.maxActions !== undefined) {
+    signingBudgets.maxActions = budgets.maxActions;
+  }
+  return {
+    ...rest,
+    budgets: signingBudgets,
+  };
+}
+
+/**
+ * Verify an emergency override signature over `emergencyOverrideSigningFields`.
+ */
+export function verifyEmergencyOverrideSignature(
+  override: SignedEmergencyOverrideV1,
+): boolean {
+  if (!override.publicKey || !override.signature) {
+    return false;
+  }
+  const message = Buffer.from(
+    canonicalizeV2(emergencyOverrideSigningFields(override)),
+    "utf8",
+  );
+  const sigBytes = Buffer.from(override.signature, "hex");
+  const pubBytes = Buffer.from(override.publicKey, "hex");
+  if (sigBytes.length !== 64 || pubBytes.length !== 32) {
+    return false;
+  }
+  return verifySignature(message, sigBytes, pubBytes);
+}

package/src/evidence.ts

@@ -0,0 +1,48 @@
+/**
+ * Append-only evidence envelopes with optional correction references.
+ * Global trust scores are intentionally excluded.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { CLAIM_CLASSES } from "./claims.js";
+
+export const EvidenceEnvelopeV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    evidenceId: Type.String({ minLength: 1 }),
+    evidenceClass: Type.Union([
+      Type.Literal("claim"),
+      Type.Literal("receipt"),
+      Type.Literal("capsule"),
+      Type.Literal("adoption"),
+      Type.Literal("annotation"),
+    ]),
+    claimClass: Type.Optional(
+      Type.Union(
+        CLAIM_CLASSES.map((c) => Type.Literal(c)) as [
+          ReturnType<typeof Type.Literal<(typeof CLAIM_CLASSES)[number]>>,
+          ...ReturnType<typeof Type.Literal<(typeof CLAIM_CLASSES)[number]>>[],
+        ],
+      ),
+    ),
+    payloadDigest: Type.String({ minLength: 1 }),
+    recordedAt: Type.String({ minLength: 1 }),
+    corrects: Type.Optional(Type.String({ minLength: 1 })),
+    annotation: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
+export type EvidenceEnvelopeV1 = Static<typeof EvidenceEnvelopeV1Schema>;
+
+export type EvidenceParseResult =
+  | { ok: true; envelope: EvidenceEnvelopeV1 }
+  | { ok: false; error: string };
+
+export function parseEvidenceEnvelope(input: unknown): EvidenceParseResult {
+  if (!Value.Check(EvidenceEnvelopeV1Schema, input)) {
+    return { ok: false, error: "invalid EvidenceEnvelopeV1" };
+  }
+  return { ok: true, envelope: input };
+}

package/src/freshness.ts

@@ -0,0 +1,103 @@
+/**
+ * Freshness and replay-key contracts for signed envelopes.
+ *
+ * Policy limits (max lifetime, clock skew) are verifier-controlled inputs.
+ * This module does not implement replay-cache persistence (Plan 4).
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+import { canonicalizeV2 } from "./canonical-json.js";
+
+export const FreshnessEnvelopeSchema = Type.Object(
+  {
+    audience: Type.String({ minLength: 1 }),
+    challenge: Type.String({ minLength: 1 }),
+    issuedAt: Type.String({ minLength: 1 }),
+    expiresAt: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export type FreshnessEnvelope = Static<typeof FreshnessEnvelopeSchema>;
+
+export type FreshnessPolicy = {
+  /** Maximum allowed (expiresAt - issuedAt) in milliseconds. */
+  maxLifetimeMs: number;
+  /** Allowed clock skew when comparing issuedAt/expiresAt to now. */
+  allowedClockSkewMs: number;
+  /** Verifier clock — not signer-controlled. */
+  nowMs: number;
+};
+
+export type FreshnessValidation = {
+  valid: boolean;
+  reason: string;
+};
+
+export type FreshnessParseResult =
+  | { ok: true; envelope: FreshnessEnvelope }
+  | { ok: false; error: string };
+
+export function parseFreshnessEnvelope(input: unknown): FreshnessParseResult {
+  if (!Value.Check(FreshnessEnvelopeSchema, input)) {
+    const errors = [...Value.Errors(FreshnessEnvelopeSchema, input)];
+    return {
+      ok: false,
+      error:
+        errors[0] !== undefined
+          ? `${errors[0].path}: ${errors[0].message}`
+          : "invalid freshness envelope",
+    };
+  }
+  return { ok: true, envelope: input };
+}
+
+export function validateFreshness(
+  envelope: FreshnessEnvelope,
+  policy: FreshnessPolicy,
+): FreshnessValidation {
+  const issued = Date.parse(envelope.issuedAt);
+  const expires = Date.parse(envelope.expiresAt);
+  if (Number.isNaN(issued) || Number.isNaN(expires)) {
+    return { valid: false, reason: "issuedAt/expiresAt must be ISO-8601" };
+  }
+  if (expires <= issued) {
+    return { valid: false, reason: "expiresAt must be after issuedAt" };
+  }
+  const lifetime = expires - issued;
+  if (lifetime > policy.maxLifetimeMs) {
+    return {
+      valid: false,
+      reason: "lifetime exceeds verifier policy maxLifetimeMs",
+    };
+  }
+  if (issued > policy.nowMs + policy.allowedClockSkewMs) {
+    return { valid: false, reason: "issuedAt is in the future beyond skew" };
+  }
+  if (expires < policy.nowMs - policy.allowedClockSkewMs) {
+    return { valid: false, reason: "envelope expired" };
+  }
+  return { valid: true, reason: "fresh" };
+}
+
+/**
+ * Deterministic replay key over audience + challenge + issuedAt.
+ * Persistence/dedup is deferred to Plan 4.
+ */
+export function buildReplayKey(envelope: FreshnessEnvelope): string {
+  return bytesToHex(
+    sha256(
+      utf8ToBytes(
+        "fpp:v2:replay\0" +
+          canonicalizeV2({
+            audience: envelope.audience,
+            challenge: envelope.challenge,
+            issuedAt: envelope.issuedAt,
+          }),
+      ),
+    ),
+  );
+}

package/src/governance.ts

@@ -0,0 +1,152 @@
+/**
+ * Gateway governance transition contracts: modes, epochs, and audited events.
+ *
+ * These schemas define the voluntary constitutional-layer state machine
+ * (enabled → draining → disabled) without implying gateway enforcement is shipped.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+export const GOVERNANCE_MODES = ["enabled", "draining", "disabled"] as const;
+
+export type GovernanceMode = (typeof GOVERNANCE_MODES)[number];
+
+export const GOVERNANCE_EVENT_KINDS = [
+  "governance-enabled",
+  "governance-disabled",
+] as const;
+
+export type GovernanceEventKind = (typeof GOVERNANCE_EVENT_KINDS)[number];
+
+/** SHA-256 hex digest (64 lowercase or uppercase hex chars). */
+const HexDigest64 = Type.String({ pattern: "^[0-9a-fA-F]{64}$" });
+
+export const GovernanceEpochSchema = Type.Integer({ minimum: 0 });
+
+export const GovernanceModeSchema = Type.Union(
+  GOVERNANCE_MODES.map((m) => Type.Literal(m)) as [
+    ReturnType<typeof Type.Literal<(typeof GOVERNANCE_MODES)[number]>>,
+    ...ReturnType<typeof Type.Literal<(typeof GOVERNANCE_MODES)[number]>>[],
+  ],
+);
+
+export const GovernanceStateV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    mode: GovernanceModeSchema,
+    epoch: GovernanceEpochSchema,
+  },
+  { additionalProperties: false },
+);
+
+export type GovernanceStateV1 = Static<typeof GovernanceStateV1Schema>;
+
+export const GovernanceActorSchema = Type.Object(
+  {
+    role: Type.String({ minLength: 1 }),
+    id: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export const GovernanceEventSignatureSchema = Type.Object(
+  {
+    alg: Type.String({ minLength: 1 }),
+    keyId: Type.String({ minLength: 1 }),
+    sig: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Tamper-evident governance enable/disable event.
+ * `epoch` is the published epoch after the transition; `previousMode` is the
+ * mode immediately before durable publication of this event.
+ */
+export const GovernanceEventV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    kind: Type.Union([
+      Type.Literal("governance-enabled"),
+      Type.Literal("governance-disabled"),
+    ]),
+    eventId: Type.String({ minLength: 1 }),
+    ts: Type.String({ minLength: 1 }),
+    epoch: GovernanceEpochSchema,
+    previousMode: GovernanceModeSchema,
+    mode: GovernanceModeSchema,
+    actor: GovernanceActorSchema,
+    constitutionHash: HexDigest64,
+    policyEngineVersion: Type.String({ minLength: 1 }),
+    prevHash: HexDigest64,
+    entryHash: HexDigest64,
+    reason: Type.Optional(Type.String({ minLength: 1 })),
+    signature: GovernanceEventSignatureSchema,
+  },
+  { additionalProperties: false },
+);
+
+export type GovernanceEventV1 = Static<typeof GovernanceEventV1Schema>;
+
+export type GovernanceEpochParseResult =
+  | { ok: true; epoch: number }
+  | { ok: false; error: string };
+
+export type GovernanceStateParseResult =
+  | { ok: true; state: GovernanceStateV1 }
+  | { ok: false; error: string };
+
+export type GovernanceEventParseResult =
+  | { ok: true; event: GovernanceEventV1 }
+  | { ok: false; error: string };
+
+export function isGovernanceMode(value: unknown): value is GovernanceMode {
+  return (
+    typeof value === "string" &&
+    (GOVERNANCE_MODES as readonly string[]).includes(value)
+  );
+}
+
+export function parseGovernanceEpoch(
+  input: unknown,
+): GovernanceEpochParseResult {
+  if (!Value.Check(GovernanceEpochSchema, input)) {
+    return { ok: false, error: "invalid GovernanceEpoch" };
+  }
+  return { ok: true, epoch: input };
+}
+
+export function parseGovernanceState(
+  input: unknown,
+): GovernanceStateParseResult {
+  if (!Value.Check(GovernanceStateV1Schema, input)) {
+    return { ok: false, error: "invalid GovernanceStateV1" };
+  }
+  return { ok: true, state: input };
+}
+
+/**
+ * Parse a governance event and enforce kind ↔ terminal mode consistency:
+ * disabled events publish mode "disabled"; enabled events publish "enabled".
+ */
+export function parseGovernanceEvent(
+  input: unknown,
+): GovernanceEventParseResult {
+  if (!Value.Check(GovernanceEventV1Schema, input)) {
+    return { ok: false, error: "invalid GovernanceEventV1" };
+  }
+  if (input.kind === "governance-disabled" && input.mode !== "disabled") {
+    return {
+      ok: false,
+      error: "governance-disabled event must publish mode disabled",
+    };
+  }
+  if (input.kind === "governance-enabled" && input.mode !== "enabled") {
+    return {
+      ok: false,
+      error: "governance-enabled event must publish mode enabled",
+    };
+  }
+  return { ok: true, event: input };
+}