@fides-anima/fpp-protocol-core 1.0.2

package/src/identity.ts

@@ -0,0 +1,119 @@
+/**
+ * Key-bound agent identity primitives.
+ *
+ * V2 agent IDs are full key fingerprints: `fpp:ed25519:<sha256(pubkey)>`.
+ * Legacy truncated aliases (`fpp-<16 hex>`) remain parseable for display and
+ * migration but are never independent proof of identity.
+ */
+
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+ed.etc.sha512Sync = (...m) => sha512(ed.etc.concatBytes(...m));
+
+export const KEY_ALGORITHM = "ed25519" as const;
+
+export type ParsedAgentId =
+  | { kind: "v2"; algorithm: typeof KEY_ALGORITHM; fingerprint: string; raw: string }
+  | { kind: "legacy-alias"; fingerprintPrefix: string; raw: string }
+  | { kind: "unknown"; raw: string };
+
+function decodePublicKeyHex(publicKeyHex: string): Uint8Array {
+  if (!/^[0-9a-fA-F]+$/.test(publicKeyHex)) {
+    throw new Error("public key must be hex");
+  }
+  if (publicKeyHex.length !== 64) {
+    throw new Error("public key must be 32 bytes (64 hex chars)");
+  }
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = Number.parseInt(publicKeyHex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/** SHA-256 fingerprint of the raw public key bytes (64 hex chars). */
+export function fingerprintPublicKey(publicKeyHex: string): string {
+  const bytes = decodePublicKeyHex(publicKeyHex);
+  return bytesToHex(sha256(bytes));
+}
+
+/** V2 agent identifier bound to the full public-key fingerprint. */
+export function deriveAgentIdV2(publicKeyHex: string): string {
+  return `fpp:${KEY_ALGORITHM}:${fingerprintPublicKey(publicKeyHex)}`;
+}
+
+/**
+ * Historical truncated alias: `fpp-` + first 16 hex chars of SHA-256(pubkey).
+ * Labeled for migration/display only — not independent identity proof.
+ */
+export function deriveLegacyAlias(publicKeyHex: string): string {
+  return "fpp-" + fingerprintPublicKey(publicKeyHex).slice(0, 16);
+}
+
+export function isLegacyAgentAlias(agentId: string): boolean {
+  return /^fpp-[0-9a-f]{16}$/i.test(agentId);
+}
+
+export function parseAgentId(agentId: string): ParsedAgentId {
+  const v2 = /^fpp:(ed25519):([0-9a-f]{64})$/i.exec(agentId);
+  if (v2) {
+    return {
+      kind: "v2",
+      algorithm: KEY_ALGORITHM,
+      fingerprint: v2[2]!.toLowerCase(),
+      raw: agentId,
+    };
+  }
+  const legacy = /^fpp-([0-9a-f]{16})$/i.exec(agentId);
+  if (legacy) {
+    return {
+      kind: "legacy-alias",
+      fingerprintPrefix: legacy[1]!.toLowerCase(),
+      raw: agentId,
+    };
+  }
+  return { kind: "unknown", raw: agentId };
+}
+
+/**
+ * Recompute the expected identifier from the public key and compare.
+ * Legacy aliases match only when `allowLegacyAlias` is explicitly set.
+ */
+export function publicKeyMatchesAgentId(
+  agentId: string,
+  publicKeyHex: string,
+  options: { allowLegacyAlias?: boolean } = {},
+): boolean {
+  const expectedV2 = deriveAgentIdV2(publicKeyHex);
+  if (agentId === expectedV2) return true;
+  if (options.allowLegacyAlias === true) {
+    return agentId === deriveLegacyAlias(publicKeyHex);
+  }
+  return false;
+}
+
+export function verifySignature(
+  message: Uint8Array,
+  signature: Uint8Array,
+  publicKey: Uint8Array,
+): boolean {
+  try {
+    return ed.verify(signature, message, publicKey);
+  } catch {
+    return false;
+  }
+}
+
+export function signMessage(
+  message: Uint8Array,
+  privateKey: Uint8Array,
+): Uint8Array {
+  return ed.sign(message, privateKey);
+}
+
+export function publicKeyFromSeed(seed: Uint8Array): Uint8Array {
+  return ed.getPublicKey(seed);
+}

package/src/index.ts

@@ -0,0 +1,270 @@
+/**
+ * @fides-anima/fpp-protocol-core — shared schemas and cryptographic contracts
+ * for the Freedom Preserving Protocol.
+ *
+ * Package version and protocol schema version are independent:
+ * this package release carries schema version 2.
+ */
+
+export const PACKAGE_NAME = "@fides-anima/fpp-protocol-core" as const;
+export const PACKAGE_VERSION = "1.0.2" as const;
+/** Protocol schema version carried by this package release. */
+export const SCHEMA_VERSION = 2 as const;
+
+export {
+  canonicalize,
+  canonicalizeV1,
+  canonicalizeV2,
+} from "./canonical-json.js";
+
+export {
+  DIGEST_DOMAINS,
+  digest,
+  hashEntryV1,
+  type DigestDomain,
+  type DigestInput,
+} from "./digest.js";
+
+export {
+  computeMerkleRoot,
+  computeMerkleRootV1,
+  computeMerkleRootV2,
+  createMerkleProof,
+  createMerkleProofV1,
+  createMerkleProofV2,
+  hashPairV1,
+  hashPairV2,
+  verifyMerkleProof,
+  verifyMerkleProofV1,
+  verifyMerkleProofV2,
+  type MerkleProof,
+  type MerkleProofStep,
+} from "./merkle.js";
+
+export {
+  KEY_ALGORITHM,
+  deriveAgentIdV2,
+  deriveLegacyAlias,
+  fingerprintPublicKey,
+  isLegacyAgentAlias,
+  parseAgentId,
+  publicKeyFromSeed,
+  publicKeyMatchesAgentId,
+  signMessage,
+  verifySignature,
+  type ParsedAgentId,
+} from "./identity.js";
+
+export {
+  STEWARD_DIGEST_DOMAINS,
+  KeyRefSchema,
+  OperatorAuthorizationRevocationV1Schema,
+  OperatorAuthorizationV1Schema,
+  StewardBootstrapPolicyCapsV1Schema,
+  StewardBootstrapV1Schema,
+  StewardKeyAttestationV1Schema,
+  attestationSigningFields,
+  authorizationRevocationSigningFields,
+  authorizationSigningFields,
+  bootstrapSigningFields,
+  buildStewardEvidenceDigest,
+  buildStewardReplayDigest,
+  containsOpenPgpSecretKeyArmor,
+  isStewardIdV1,
+  mintStewardIdV1,
+  parseKeyRef,
+  parseOperatorAuthorization,
+  parseOperatorAuthorizationRevocation,
+  parseStewardBootstrap,
+  parseStewardIdV1,
+  parseStewardKeyAttestation,
+  validateOperatorAuthorizationBounds,
+  type BoundsResult,
+  type KeyRefParseResult,
+  type OperatorAuthorizationParseResult,
+  type OperatorAuthorizationRevocationParseResult,
+  type OperatorAuthorizationRevocationV1,
+  type OperatorAuthorizationV1,
+  type ParsedKeyRef,
+  type ParsedStewardIdV1,
+  type StewardBootstrapParseResult,
+  type StewardBootstrapPolicyCapsV1,
+  type StewardBootstrapV1,
+  type StewardIdParseResult,
+  type StewardIdV1,
+  type StewardKeyAttestationParseResult,
+  type StewardKeyAttestationV1,
+} from "./steward-authorization.js";
+
+export {
+  CLAIM_CLASSES,
+  ConstitutionalClaimV2Schema,
+  LegacyConstitutionalClaimV1Schema,
+  parseClaim,
+  type ClaimClass,
+  type ClaimParseResult,
+  type ConstitutionalClaimV2,
+  type LegacyConstitutionalClaimV1,
+} from "./claims.js";
+
+export {
+  FreshnessEnvelopeSchema,
+  buildReplayKey,
+  parseFreshnessEnvelope,
+  validateFreshness,
+  type FreshnessEnvelope,
+  type FreshnessParseResult,
+  type FreshnessPolicy,
+  type FreshnessValidation,
+} from "./freshness.js";
+
+export {
+  ConformanceReceiptV1Schema,
+  ReceiptInclusionEvidenceV1Schema,
+  parseConformanceReceipt,
+  parseReceiptInclusionEvidence,
+  type ConformanceReceiptV1,
+  type ReceiptInclusionEvidenceParseResult,
+  type ReceiptInclusionEvidenceV1,
+  type ReceiptParseResult,
+} from "./receipts.js";
+
+export {
+  GOVERNANCE_EVENT_KINDS,
+  GOVERNANCE_MODES,
+  GovernanceActorSchema,
+  GovernanceEpochSchema,
+  GovernanceEventSignatureSchema,
+  GovernanceEventV1Schema,
+  GovernanceModeSchema,
+  GovernanceStateV1Schema,
+  isGovernanceMode,
+  parseGovernanceEpoch,
+  parseGovernanceEvent,
+  parseGovernanceState,
+  type GovernanceEpochParseResult,
+  type GovernanceEventKind,
+  type GovernanceEventParseResult,
+  type GovernanceEventV1,
+  type GovernanceMode,
+  type GovernanceStateParseResult,
+  type GovernanceStateV1,
+} from "./governance.js";
+
+export {
+  MANDATE_ISSUER_CLASSES,
+  StandingMandateV1Schema,
+  mandateSigningFields,
+  parseStandingMandate,
+  validateMandateValidity,
+  verifyMandateSignature,
+  type MandateIssuerClass,
+  type MandateLedgerEntry,
+  type MandateParseResult,
+  type MandateStoreFile,
+  type MandateValidity,
+  type MandateValidityPolicy,
+  type StandingMandateV1,
+} from "./mandates.js";
+
+export {
+  SignedEmergencyOverrideV1Schema,
+  emergencyOverrideSigningFields,
+  parseSignedEmergencyOverride,
+  validateEmergencyOverrideValidity,
+  verifyEmergencyOverrideSignature,
+  type EmergencyOverrideLedgerEntry,
+  type EmergencyOverrideParseResult,
+  type EmergencyOverrideStoreFile,
+  type EmergencyOverrideValidity,
+  type EmergencyOverrideValidityPolicy,
+  type SignedEmergencyOverrideV1,
+} from "./emergency-override.js";
+
+export {
+  AUTHORIZATION_CLASSES,
+  AUTHZ,
+  DISPOSITION_DECISIONS,
+  isAuthorizationClass,
+  isDispositionDecision,
+  parseDispositionDecision,
+  type AuthorizationClass,
+  type DispositionDecision,
+  type DispositionParseResult,
+} from "./disposition.js";
+
+export {
+  CapsuleAdoptionDisclosureSummarySchema,
+  TrustStateCapsuleV2Schema,
+  parseTrustStateCapsule,
+  validateCapsuleAdoptionConsistency,
+  type CapsuleAdoptionConsistency,
+  type CapsuleAdoptionDisclosureSummary,
+  type CapsuleParseResult,
+  type TrustStateCapsuleV2,
+} from "./capsules.js";
+
+export {
+  ADOPTION_OVERLAY_FLAGS,
+  ADOPTION_STATES,
+  AdoptionStateRecordV1Schema,
+  AdoptionStateRecordV2Schema,
+  ENFORCEMENT_GRADES,
+  parseAdoptionStateRecord,
+  type AdoptionOverlayFlag,
+  type AdoptionParseResult,
+  type AdoptionState,
+  type AdoptionStateRecord,
+  type AdoptionStateRecordV1,
+  type AdoptionStateRecordV2,
+  type EnforcementGrade,
+} from "./adoption.js";
+
+export {
+  ADOPTION_ASSURANCE_CLASSES,
+  AdoptionDisclosureV1Schema,
+  maxJustifiedConclusion,
+  parseAdoptionDisclosure,
+  type AdoptionAssurance,
+  type AdoptionDisclosureParseResult,
+  type AdoptionDisclosureV1,
+} from "./adoption-disclosure.js";
+
+export {
+  EvidenceEnvelopeV1Schema,
+  parseEvidenceEnvelope,
+  type EvidenceEnvelopeV1,
+  type EvidenceParseResult,
+} from "./evidence.js";
+
+export {
+  QUORUM_CLASSES,
+  QUORUM_VOTES,
+  QuorumBallotV1Schema,
+  QuorumEvidencePackageV1Schema,
+  QuorumProposalV1Schema,
+  computeQuorumEvidenceDigest,
+  parseQuorumBallot,
+  parseQuorumEvidencePackage,
+  parseQuorumProposal,
+  validateBallotAgainstProposal,
+  type BallotMatchResult,
+  type QuorumBallotParseResult,
+  type QuorumBallotV1,
+  type QuorumClass,
+  type QuorumEvidencePackageV1,
+  type QuorumEvidenceParseResult,
+  type QuorumProposalParseResult,
+  type QuorumProposalV1,
+  type QuorumVote,
+} from "./quorum.js";
+
+export {
+  DEFAULT_WORKSPACE_PROFILE,
+  resolveWorkspaceRoot,
+  workspaceFile,
+  absolutizeWorkspacePath,
+  type ResolveWorkspaceOptions,
+  type AbsolutizeWorkspaceOptions,
+  type WorkspaceProfileId,
+} from "./workspace-profile.js";

package/src/mandates.ts

@@ -0,0 +1,201 @@
+/**
+ * Standing mandate schema — signed or allowlist-backed authorization
+ * consumed by the unattended disposition engine.
+ */
+
+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 MANDATE_ISSUER_CLASSES = [
+  "operator",
+  "peer-quorum",
+  "steward-quorum",
+  "standing-allowlist",
+] as const;
+
+export type MandateIssuerClass = (typeof MANDATE_ISSUER_CLASSES)[number];
+
+export const StandingMandateV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    mandateId: Type.String({ minLength: 1 }),
+    issuerClass: Type.Union(
+      MANDATE_ISSUER_CLASSES.map((c) => Type.Literal(c)) as [
+        ReturnType<typeof Type.Literal<(typeof MANDATE_ISSUER_CLASSES)[number]>>,
+        ...ReturnType<
+          typeof Type.Literal<(typeof MANDATE_ISSUER_CLASSES)[number]>
+        >[],
+      ],
+    ),
+    issuerId: 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 }),
+    revocable: Type.Boolean(),
+    revoked: Type.Optional(Type.Boolean()),
+    evidenceRef: Type.String({ minLength: 1 }),
+    quorumRef: Type.Optional(Type.String({ minLength: 1 })),
+    publicKey: Type.Optional(Type.String({ minLength: 1 })),
+    signature: Type.Optional(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+
+export type StandingMandateV1 = Static<typeof StandingMandateV1Schema>;
+
+/** Mutable runtime counters — never part of the signed grant payload. */
+export type MandateLedgerEntry = {
+  remainingActions?: number;
+  revoked?: boolean;
+};
+
+/**
+ * Shared on-disk mandate store shape (enforcement-core + trust-core).
+ * `ledgers` is additive; absent keys mean unlimited budget / not revoked.
+ */
+export type MandateStoreFile = {
+  schemaVersion: 1;
+  mandates: StandingMandateV1[];
+  ledgers?: Record<string, MandateLedgerEntry>;
+};
+
+export type MandateParseResult =
+  | { ok: true; mandate: StandingMandateV1 }
+  | { ok: false; error: string };
+
+export type MandateValidityPolicy = {
+  /** Verifier clock — not signer-controlled. */
+  nowMs: number;
+};
+
+export type MandateValidity = {
+  valid: boolean;
+  reason: string;
+};
+
+export function parseStandingMandate(input: unknown): MandateParseResult {
+  if (!Value.Check(StandingMandateV1Schema, input)) {
+    const errors = [...Value.Errors(StandingMandateV1Schema, input)];
+    return {
+      ok: false,
+      error:
+        errors[0] !== undefined
+          ? `${errors[0].path}: ${errors[0].message}`
+          : "invalid StandingMandateV1",
+    };
+  }
+  return { ok: true, mandate: input };
+}
+
+/**
+ * Temporal / revocation check for a schema-valid mandate.
+ * Budget debit and signature verification live in the plugin mandate store.
+ */
+export function validateMandateValidity(
+  mandate: StandingMandateV1,
+  policy: MandateValidityPolicy,
+): MandateValidity {
+  if (mandate.revoked === true) {
+    return { valid: false, reason: "mandate revoked" };
+  }
+  const from = Date.parse(mandate.validFrom);
+  const to = Date.parse(mandate.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: "mandate not yet valid (validFrom)" };
+  }
+  if (policy.nowMs > to) {
+    return { valid: false, reason: "mandate expired" };
+  }
+  return { valid: true, reason: "ok" };
+}
+
+/**
+ * Canonical unsigned payload for new mandate signatures.
+ * Excludes `signature`, `revoked`, and `budgets.remainingActions` so debit/revoke
+ * can mutate an unsigned ledger without invalidating the grant.
+ */
+export function mandateSigningFields(
+  mandate: StandingMandateV1,
+): Record<string, unknown> {
+  const {
+    signature: _signature,
+    revoked: _revoked,
+    budgets,
+    ...rest
+  } = mandate;
+  void _signature;
+  void _revoked;
+  const signingBudgets: Record<string, unknown> = {};
+  if (budgets.maxActions !== undefined) {
+    signingBudgets.maxActions = budgets.maxActions;
+  }
+  return {
+    ...rest,
+    budgets: signingBudgets,
+  };
+}
+
+function legacySigningFields(
+  mandate: StandingMandateV1,
+): Record<string, unknown> {
+  const { signature: _signature, ...unsigned } = mandate;
+  void _signature;
+  return unsigned as Record<string, unknown>;
+}
+
+function tryVerifyMandatePayload(
+  mandate: StandingMandateV1,
+  payload: Record<string, unknown>,
+): boolean {
+  if (!mandate.publicKey || !mandate.signature) {
+    return false;
+  }
+  const message = Buffer.from(canonicalizeV2(payload), "utf8");
+  const sigBytes = Buffer.from(mandate.signature, "hex");
+  const pubBytes = Buffer.from(mandate.publicKey, "hex");
+  if (sigBytes.length !== 64 || pubBytes.length !== 32) {
+    return false;
+  }
+  return verifySignature(message, sigBytes, pubBytes);
+}
+
+/**
+ * Dual-verify mandate signatures:
+ * 1. New payload (`mandateSigningFields`) — preferred for newly issued grants.
+ * 2. Legacy payload (full object minus `signature`) — undebited historical files.
+ *
+ * Standing-allowlist mandates are unsigned by design.
+ */
+export function verifyMandateSignature(mandate: StandingMandateV1): boolean {
+  if (mandate.issuerClass === "standing-allowlist") {
+    return true;
+  }
+  if (!mandate.publicKey || !mandate.signature) {
+    return false;
+  }
+  if (tryVerifyMandatePayload(mandate, mandateSigningFields(mandate))) {
+    return true;
+  }
+  return tryVerifyMandatePayload(mandate, legacySigningFields(mandate));
+}