@attested-intelligence/aga-mcp-server 2.0.1 → 2.2.0

package/src/core/artifact.ts

@@ -0,0 +1,45 @@
+import { signStr, sigToB64, b64ToSig, pkToHex, hexToPk, verifyStr } from '../crypto/sign.js';
+import { sha256Str } from '../crypto/hash.js';
+import { canonicalize } from '../utils/canonical.js';
+import { utcNow } from '../utils/timestamp.js';
+import { SCHEMA_VERSION, PROTOCOL_VERSION } from '../utils/constants.js';
+import type { KeyPair, HashHex } from '../crypto/types.js';
+import type { PolicyArtifact, SubjectIdentifier, EnforcementParams, DisclosurePolicy, EvidenceCommitmentRecord } from './types.js';
+
+export interface ArtifactInput {
+  subject_identifier: SubjectIdentifier;
+  policy_reference: HashHex;
+  policy_version: number;
+  sealed_hash: HashHex;
+  seal_salt: string;
+  enforcement_parameters: EnforcementParams;
+  disclosure_policy: DisclosurePolicy;
+  evidence_commitments: EvidenceCommitmentRecord[];
+  issuer_keypair: KeyPair;
+  effective_timestamp?: string;
+  expiration_timestamp?: string | null;
+}
+
+export function generateArtifact(input: ArtifactInput): PolicyArtifact {
+  const now = utcNow();
+  const unsigned: Omit<PolicyArtifact, 'signature'> = {
+    schema_version: SCHEMA_VERSION, protocol_version: PROTOCOL_VERSION,
+    subject_identifier: input.subject_identifier, policy_reference: input.policy_reference,
+    policy_version: input.policy_version, sealed_hash: input.sealed_hash,
+    seal_salt: input.seal_salt, issued_timestamp: now,
+    effective_timestamp: input.effective_timestamp ?? now,
+    expiration_timestamp: input.expiration_timestamp ?? null,
+    issuer_identifier: pkToHex(input.issuer_keypair.publicKey),
+    enforcement_parameters: input.enforcement_parameters,
+    disclosure_policy: input.disclosure_policy,
+    evidence_commitments: input.evidence_commitments,
+  };
+  return { ...unsigned, signature: sigToB64(signStr(canonicalize(unsigned), input.issuer_keypair.secretKey)) };
+}
+
+export function hashArtifact(a: PolicyArtifact): HashHex { return sha256Str(canonicalize(a)); }
+
+export function verifyArtifactSignature(a: PolicyArtifact, issuerPkHex: string): boolean {
+  const { signature, ...unsigned } = a;
+  return verifyStr(b64ToSig(signature), canonicalize(unsigned), hexToPk(issuerPkHex));
+}

package/src/core/attestation.ts

@@ -0,0 +1,33 @@
+import { saltedCommitment, generateSalt } from '../crypto/salt.js';
+import { sha256HexCat } from '../crypto/hash.js';
+import type { SubjectIdentifier, EvidenceCommitmentRecord } from './types.js';
+import type { HashHex, SaltHex } from '../crypto/types.js';
+
+export interface AttestationInput {
+  subject_identifier: SubjectIdentifier;
+  policy_reference: HashHex;
+  evidence_items: Array<{ label: string; content: string }>;
+}
+
+export interface AttestationResult {
+  success: boolean;
+  sealed_hash: HashHex | null;
+  seal_salt: SaltHex | null;
+  evidence_commitments: EvidenceCommitmentRecord[];
+  rejection_reason: string | null;
+}
+
+export function performAttestation(input: AttestationInput): AttestationResult {
+  const evidence_commitments = input.evidence_items.map(item => {
+    const { commitment, salt } = saltedCommitment(item.content);
+    return { commitment, salt, label: item.label };
+  });
+  const seal_salt = generateSalt();
+  const sealed_hash = sha256HexCat(
+    input.subject_identifier.bytes_hash,
+    input.subject_identifier.metadata_hash,
+    input.policy_reference,
+    seal_salt
+  );
+  return { success: true, sealed_hash, seal_salt, evidence_commitments, rejection_reason: null };
+}

package/src/core/behavioral.ts

@@ -0,0 +1,132 @@
+/**
+ * Behavioral Drift Detection.
+ * NIST-2025-0035: "Governance mechanisms must measure behavioral outputs
+ * and decision patterns in addition to static artifacts."
+ *
+ * Tracks tool invocation patterns and compares against a behavioral
+ * baseline sealed in the policy artifact.
+ */
+import { sha256Str } from '../crypto/hash.js';
+import type { HashHex } from '../crypto/types.js';
+
+export interface ToolInvocation {
+  tool_name: string;
+  timestamp: string;
+  args_hash: HashHex;  // hash of args, not args themselves (privacy)
+}
+
+export interface BehavioralBaseline {
+  /** Allowed tools in this policy context */
+  permitted_tools: string[];
+  /** Maximum invocations per tool per measurement window */
+  rate_limits: Record<string, number>;
+  /** Forbidden tool sequences (e.g., read_secret then send_email) */
+  forbidden_sequences: string[][];
+  /** Measurement window in milliseconds */
+  window_ms: number;
+}
+
+export interface BehavioralMeasurement {
+  window_start: string;
+  window_end: string;
+  invocations: ToolInvocation[];
+  violations: BehavioralViolation[];
+  behavioral_hash: HashHex;  // hash of the behavioral pattern
+  drift_detected: boolean;
+}
+
+export type BehavioralViolation =
+  | { type: 'UNAUTHORIZED_TOOL'; tool: string }
+  | { type: 'RATE_EXCEEDED'; tool: string; count: number; limit: number }
+  | { type: 'FORBIDDEN_SEQUENCE'; sequence: string[] };
+
+export class BehavioralMonitor {
+  private invocations: ToolInvocation[] = [];
+  private baseline: BehavioralBaseline | null = null;
+
+  setBaseline(baseline: BehavioralBaseline): void {
+    this.baseline = baseline;
+  }
+
+  recordInvocation(toolName: string, argsHash: HashHex): void {
+    this.invocations.push({
+      tool_name: toolName,
+      timestamp: new Date().toISOString(),
+      args_hash: argsHash,
+    });
+  }
+
+  measure(): BehavioralMeasurement {
+    if (!this.baseline) {
+      return {
+        window_start: '', window_end: '', invocations: [],
+        violations: [], behavioral_hash: sha256Str('no-baseline'),
+        drift_detected: false,
+      };
+    }
+
+    const now = Date.now();
+    const windowStart = now - this.baseline.window_ms;
+    const windowInvocations = this.invocations.filter(
+      i => Date.parse(i.timestamp) >= windowStart
+    );
+
+    const violations: BehavioralViolation[] = [];
+
+    // Check unauthorized tools
+    for (const inv of windowInvocations) {
+      if (!this.baseline.permitted_tools.includes(inv.tool_name)) {
+        violations.push({ type: 'UNAUTHORIZED_TOOL', tool: inv.tool_name });
+      }
+    }
+
+    // Check rate limits
+    const counts: Record<string, number> = {};
+    for (const inv of windowInvocations) {
+      counts[inv.tool_name] = (counts[inv.tool_name] ?? 0) + 1;
+    }
+    for (const [tool, count] of Object.entries(counts)) {
+      const limit = this.baseline.rate_limits[tool];
+      if (limit !== undefined && count > limit) {
+        violations.push({ type: 'RATE_EXCEEDED', tool, count, limit });
+      }
+    }
+
+    // Check forbidden sequences
+    const toolSequence = windowInvocations.map(i => i.tool_name);
+    for (const forbidden of this.baseline.forbidden_sequences) {
+      if (containsSubsequence(toolSequence, forbidden)) {
+        violations.push({ type: 'FORBIDDEN_SEQUENCE', sequence: forbidden });
+      }
+    }
+
+    // Compute behavioral hash (pattern fingerprint)
+    const pattern = windowInvocations.map(i => i.tool_name).join('|');
+    const behavioral_hash = sha256Str(pattern);
+
+    return {
+      window_start: new Date(windowStart).toISOString(),
+      window_end: new Date(now).toISOString(),
+      invocations: windowInvocations,
+      violations,
+      behavioral_hash,
+      drift_detected: violations.length > 0,
+    };
+  }
+
+  reset(): void {
+    this.invocations = [];
+  }
+}
+
+function containsSubsequence(haystack: string[], needle: string[]): boolean {
+  if (needle.length === 0) return true;
+  let ni = 0;
+  for (const h of haystack) {
+    if (h === needle[ni]) {
+      ni++;
+      if (ni === needle.length) return true;
+    }
+  }
+  return false;
+}

package/src/core/bundle.ts

@@ -0,0 +1,45 @@
+import { signStr, sigToB64, b64ToSig, hexToPk, verifyStr, pkToHex } from '../crypto/sign.js';
+import { verifyProof } from '../crypto/merkle.js';
+import { canonicalize } from '../utils/canonical.js';
+import type { KeyPair, MerkleInclusionProof } from '../crypto/types.js';
+import type { EvidenceBundle, PolicyArtifact, SignedReceipt, CheckpointReference, VerificationTier } from './types.js';
+
+/**
+ * Generate an evidence bundle. Original signature preserved for backward compatibility.
+ * Tiered bundle generation (CAISI §3b):
+ *   BRONZE - artifact + receipts only (proofs omitted)
+ *   SILVER - artifact + receipts + Merkle proofs
+ *   GOLD   - artifact + receipts + Merkle proofs + anchor checkpoint reference
+ */
+export function generateBundle(artifact: PolicyArtifact, receipts: SignedReceipt[], proofs: MerkleInclusionProof[], checkpoint: CheckpointReference, kp: KeyPair, tier?: VerificationTier): EvidenceBundle {
+  const effectiveTier = tier ?? 'GOLD';
+  const bundleProofs = effectiveTier === 'BRONZE' ? [] : proofs;
+  const bundleCheckpoint: CheckpointReference = effectiveTier === 'GOLD' ? checkpoint : {
+    ...checkpoint,
+    transaction_id: effectiveTier === 'BRONZE' ? '' : checkpoint.transaction_id,
+    anchor_network: effectiveTier === 'BRONZE' ? '' : checkpoint.anchor_network,
+  };
+  const unsigned = { artifact, receipts, merkle_proofs: bundleProofs, checkpoint_reference: bundleCheckpoint, public_key: pkToHex(kp.publicKey), verification_tier: effectiveTier };
+  return { ...unsigned, bundle_signature: sigToB64(signStr(canonicalize(unsigned), kp.secretKey)) };
+}
+
+export interface VerificationResult {
+  step1_artifact_sig: boolean; step2_receipt_sigs: boolean;
+  step3_merkle_proofs: boolean; step4_anchor: 'SKIPPED_OFFLINE' | boolean;
+  overall: boolean; errors: string[];
+}
+
+export function verifyBundleOffline(bundle: EvidenceBundle, pinnedPkHex: string): VerificationResult {
+  const errors: string[] = [];
+  const { signature: aSig, ...aU } = bundle.artifact;
+  const s1 = verifyStr(b64ToSig(aSig), canonicalize(aU), hexToPk(pinnedPkHex));
+  if (!s1) errors.push('Artifact signature failed');
+  let s2 = true;
+  for (const r of bundle.receipts) {
+    const { portal_signature, ...rU } = r;
+    if (!verifyStr(b64ToSig(portal_signature), canonicalize(rU), hexToPk(bundle.public_key))) { s2 = false; errors.push(`Receipt ${r.receipt_id} sig failed`); }
+  }
+  let s3 = true;
+  for (const p of bundle.merkle_proofs) { if (!verifyProof(p)) { s3 = false; errors.push(`Merkle proof failed leaf ${p.leafIndex}`); } }
+  return { step1_artifact_sig: s1, step2_receipt_sigs: s2, step3_merkle_proofs: s3, step4_anchor: 'SKIPPED_OFFLINE', overall: s1 && s2 && s3, errors };
+}

package/src/core/chain.ts

@@ -0,0 +1,72 @@
+import { sha256Str } from '../crypto/hash.js';
+import { signStr, sigToB64, pkToHex } from '../crypto/sign.js';
+import { canonicalize } from '../utils/canonical.js';
+import { utcNow } from '../utils/timestamp.js';
+import { uuid } from '../utils/uuid.js';
+import { SCHEMA_VERSION, PROTOCOL_VERSION, TAXONOMY_VERSION } from '../utils/constants.js';
+import type { KeyPair, HashHex } from '../crypto/types.js';
+import type { ContinuityEvent, GenesisPayload, StructuralMetadata, EventType } from './types.js';
+
+/** Leaf hash from structural metadata ONLY. Payload EXCLUDED. Uses "||" delimiter. */
+export function computeLeafHash(m: StructuralMetadata): HashHex {
+  return sha256Str([
+    m.schema_version, m.protocol_version, m.event_type, m.event_id,
+    String(m.sequence_number), m.timestamp, m.previous_leaf_hash ?? 'NULL'
+  ].join('||'));
+}
+
+export function computePayloadHash(payload: unknown): HashHex {
+  return sha256Str(canonicalize(payload));
+}
+
+function buildEvent(type: EventType, payload: unknown, seq: number, prevLeaf: HashHex | null, kp: KeyPair): ContinuityEvent {
+  const id = uuid(), ts = utcNow();
+  const meta: StructuralMetadata = {
+    schema_version: SCHEMA_VERSION, protocol_version: PROTOCOL_VERSION,
+    event_type: type, event_id: id, sequence_number: seq,
+    timestamp: ts, previous_leaf_hash: prevLeaf,
+  };
+  const leafHash = computeLeafHash(meta);
+  const payloadHash = computePayloadHash(payload);
+  const sig = signStr(canonicalize({ ...meta, leaf_hash: leafHash, payload, payload_hash: payloadHash }), kp.secretKey);
+  return {
+    schema_version: SCHEMA_VERSION, protocol_version: PROTOCOL_VERSION,
+    event_type: type, event_id: id, sequence_number: seq,
+    timestamp: ts, previous_leaf_hash: prevLeaf,
+    leaf_hash: leafHash, payload, payload_hash: payloadHash,
+    event_signature: sigToB64(sig),
+  };
+}
+
+export function createGenesisEvent(kp: KeyPair, specHash: HashHex): ContinuityEvent {
+  const payload: GenesisPayload = {
+    protocol_version: PROTOCOL_VERSION, taxonomy_version: TAXONOMY_VERSION,
+    root_fingerprint: pkToHex(kp.publicKey), specification_hash: specHash, marker: 'GENESIS',
+  };
+  return buildEvent('GENESIS', payload, 0, null, kp);
+}
+
+export function appendEvent(type: EventType, payload: unknown, prev: ContinuityEvent, kp: KeyPair): ContinuityEvent {
+  return buildEvent(type, payload, prev.sequence_number + 1, prev.leaf_hash, kp);
+}
+
+export function verifyChainIntegrity(events: ContinuityEvent[]): {
+  valid: boolean; brokenAt: number | null; error: string | null;
+} {
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i];
+    const meta: StructuralMetadata = {
+      schema_version: e.schema_version, protocol_version: e.protocol_version,
+      event_type: e.event_type, event_id: e.event_id,
+      sequence_number: e.sequence_number, timestamp: e.timestamp,
+      previous_leaf_hash: e.previous_leaf_hash,
+    };
+    if (e.leaf_hash !== computeLeafHash(meta))
+      return { valid: false, brokenAt: e.sequence_number, error: `Leaf hash mismatch at seq ${e.sequence_number}` };
+    if (i > 0 && e.previous_leaf_hash !== events[i - 1].leaf_hash)
+      return { valid: false, brokenAt: e.sequence_number, error: `Chain linkage broken at seq ${e.sequence_number}` };
+    if (e.payload_hash !== computePayloadHash(e.payload))
+      return { valid: false, brokenAt: e.sequence_number, error: `Payload hash mismatch at seq ${e.sequence_number}` };
+  }
+  return { valid: true, brokenAt: null, error: null };
+}

package/src/core/checkpoint.ts

@@ -0,0 +1,22 @@
+import { buildMerkleTree, inclusionProof } from '../crypto/merkle.js';
+import { utcNow } from '../utils/timestamp.js';
+import { uuid } from '../utils/uuid.js';
+import type { ContinuityEvent, CheckpointReference, AnchorBatchPayload } from './types.js';
+import type { MerkleInclusionProof } from '../crypto/types.js';
+
+export function createCheckpoint(events: ContinuityEvent[], anchorNetwork = 'local'): { checkpoint: CheckpointReference; payload: AnchorBatchPayload } {
+  if (!events.length) throw new Error('No events to checkpoint');
+  const { root } = buildMerkleTree(events.map(e => e.leaf_hash));
+  const checkpoint: CheckpointReference = {
+    merkle_root: root, batch_start_sequence: events[0].sequence_number,
+    batch_end_sequence: events[events.length - 1].sequence_number,
+    anchor_network: anchorNetwork, transaction_id: `${anchorNetwork}:${uuid()}`, timestamp: utcNow(),
+  };
+  return { checkpoint, payload: { checkpoint_reference: checkpoint, leaf_count: events.length } };
+}
+
+export function eventInclusionProof(events: ContinuityEvent[], targetSeq: number): MerkleInclusionProof {
+  const idx = events.findIndex(e => e.sequence_number === targetSeq);
+  if (idx === -1) throw new Error(`Sequence ${targetSeq} not in batch`);
+  return inclusionProof(events.map(e => e.leaf_hash), idx);
+}

package/src/core/delegation.ts

@@ -0,0 +1,146 @@
+/**
+ * Constrained Sub-Agent Delegation.
+ * NCCoE filing: "Scope can only diminish through delegation, never expand."
+ *
+ * Primary agent's portal issues a derived artifact to secondary agent:
+ * - TTL <= parent's remaining TTL
+ * - Scope can only diminish, never expand
+ * - Secondary's genesis links to parent's chain
+ */
+import { generateArtifact, hashArtifact } from './artifact.js';
+import { isExpired } from '../utils/timestamp.js';
+import type { PolicyArtifact, EnforcementAction, MeasurementType } from './types.js';
+import type { KeyPair } from '../crypto/types.js';
+
+export interface DelegationRequest {
+  /** Subset of parent's enforcement triggers */
+  enforcement_triggers: EnforcementAction[];
+  /** Subset of parent's measurement types */
+  measurement_types: MeasurementType[];
+  /** Requested TTL in seconds (will be clamped to parent remaining) */
+  requested_ttl_seconds: number;
+  /** Description of the delegation purpose */
+  delegation_purpose: string;
+}
+
+export interface DelegationResult {
+  success: boolean;
+  child_artifact?: PolicyArtifact;
+  child_artifact_hash?: string;
+  parent_artifact_hash: string;
+  effective_ttl_seconds?: number;
+  scope_reduction?: {
+    triggers_removed: string[];
+    measurement_types_removed: string[];
+  };
+  error?: string;
+}
+
+/**
+ * Derive a constrained artifact from a parent artifact.
+ * Key rule: scope can only diminish, never expand.
+ */
+export function deriveArtifact(
+  parentArtifact: PolicyArtifact,
+  request: DelegationRequest,
+  issuerKP: KeyPair
+): DelegationResult {
+  const parentHash = hashArtifact(parentArtifact);
+
+  // Validate parent is not expired
+  if (isExpired(parentArtifact.issued_timestamp, parentArtifact.enforcement_parameters.ttl_seconds)) {
+    return { success: false, parent_artifact_hash: parentHash, error: 'Parent artifact TTL has expired' };
+  }
+
+  // Calculate parent remaining TTL
+  const parentIssuedMs = Date.parse(parentArtifact.issued_timestamp);
+  const parentExpiresMs = parentIssuedMs + (parentArtifact.enforcement_parameters.ttl_seconds * 1000);
+  const remainingMs = parentExpiresMs - Date.now();
+  const remainingSeconds = Math.max(0, Math.floor(remainingMs / 1000));
+
+  // Clamp child TTL to parent remaining
+  const effectiveTTL = Math.min(request.requested_ttl_seconds, remainingSeconds);
+  if (effectiveTTL <= 0) {
+    return { success: false, parent_artifact_hash: parentHash, error: 'No remaining TTL to delegate' };
+  }
+
+  // Validate triggers are subset of parent
+  const parentTriggers = new Set(parentArtifact.enforcement_parameters.enforcement_triggers);
+  const invalidTriggers = request.enforcement_triggers.filter(t => !parentTriggers.has(t));
+  if (invalidTriggers.length > 0) {
+    return { success: false, parent_artifact_hash: parentHash, error: `Cannot expand scope: triggers [${invalidTriggers.join(', ')}] not in parent` };
+  }
+
+  // Validate measurement types are subset of parent
+  const parentTypes = new Set<string>(parentArtifact.enforcement_parameters.measurement_types);
+  const invalidTypes = request.measurement_types.filter(t => !parentTypes.has(t));
+  if (invalidTypes.length > 0) {
+    return { success: false, parent_artifact_hash: parentHash, error: `Cannot expand scope: measurement types [${invalidTypes.join(', ')}] not in parent` };
+  }
+
+  // Build constrained child artifact
+  const childArtifact = generateArtifact({
+    subject_identifier: parentArtifact.subject_identifier,
+    policy_reference: parentArtifact.policy_reference,
+    policy_version: parentArtifact.policy_version,
+    sealed_hash: parentArtifact.sealed_hash,
+    seal_salt: parentArtifact.seal_salt,
+    enforcement_parameters: {
+      measurement_cadence_ms: parentArtifact.enforcement_parameters.measurement_cadence_ms,
+      ttl_seconds: effectiveTTL,
+      enforcement_triggers: request.enforcement_triggers,
+      re_attestation_required: parentArtifact.enforcement_parameters.re_attestation_required,
+      measurement_types: request.measurement_types,
+    },
+    disclosure_policy: parentArtifact.disclosure_policy,  // cannot expand
+    evidence_commitments: parentArtifact.evidence_commitments,
+    issuer_keypair: issuerKP,
+  });
+
+  // Track scope reduction
+  const triggersRemoved = [...parentTriggers].filter(t => !request.enforcement_triggers.includes(t as EnforcementAction));
+  const typesRemoved = [...parentTypes].filter(t => !request.measurement_types.includes(t as MeasurementType));
+
+  return {
+    success: true,
+    child_artifact: childArtifact,
+    child_artifact_hash: hashArtifact(childArtifact),
+    parent_artifact_hash: parentHash,
+    effective_ttl_seconds: effectiveTTL,
+    scope_reduction: {
+      triggers_removed: triggersRemoved,
+      measurement_types_removed: typesRemoved,
+    },
+  };
+}
+
+/**
+ * Validate that a child artifact is a valid delegation of a parent.
+ */
+export function validateDelegation(parent: PolicyArtifact, child: PolicyArtifact): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // TTL must be <= parent TTL
+  if (child.enforcement_parameters.ttl_seconds > parent.enforcement_parameters.ttl_seconds) {
+    errors.push(`Child TTL (${child.enforcement_parameters.ttl_seconds}s) exceeds parent (${parent.enforcement_parameters.ttl_seconds}s)`);
+  }
+
+  // Triggers must be subset
+  const pTriggers = new Set<string>(parent.enforcement_parameters.enforcement_triggers);
+  for (const t of child.enforcement_parameters.enforcement_triggers) {
+    if (!pTriggers.has(t)) errors.push(`Child trigger '${t}' not in parent scope`);
+  }
+
+  // Measurement types must be subset
+  const pTypes = new Set<string>(parent.enforcement_parameters.measurement_types);
+  for (const t of child.enforcement_parameters.measurement_types) {
+    if (!pTypes.has(t)) errors.push(`Child measurement type '${t}' not in parent scope`);
+  }
+
+  // Subject must match
+  if (child.subject_identifier.bytes_hash !== parent.subject_identifier.bytes_hash) {
+    errors.push('Child subject bytes_hash does not match parent');
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/core/disclosure.ts

@@ -0,0 +1,32 @@
+import { signStr, sigToB64 } from '../crypto/sign.js';
+import { canonicalize } from '../utils/canonical.js';
+import { utcNow } from '../utils/timestamp.js';
+import { uuid } from '../utils/uuid.js';
+import type { KeyPair } from '../crypto/types.js';
+import type { DisclosureRequest, DisclosurePolicy, SubstitutionReceipt, DisclosureMode } from './types.js';
+
+export interface DisclosureResult {
+  permitted: boolean; disclosed_claim_id: string | null; disclosed_value: unknown;
+  mode: DisclosureMode; was_substituted: boolean; substitution_receipt: SubstitutionReceipt | null;
+}
+
+export function processDisclosure(req: DisclosureRequest, policy: DisclosurePolicy, values: Record<string, unknown>, policyVersion: number, chainSeq: number, kp: KeyPair): DisclosureResult {
+  const claim = policy.claims_taxonomy.find(c => c.claim_id === req.requested_claim_id);
+  if (!claim) return { permitted: false, disclosed_claim_id: null, disclosed_value: null, mode: req.mode, was_substituted: false, substitution_receipt: null };
+  if (claim.permitted_modes.includes(req.mode))
+    return { permitted: true, disclosed_claim_id: claim.claim_id, disclosed_value: fv(values[claim.claim_id], req.mode), mode: req.mode, was_substituted: false, substitution_receipt: null };
+  for (const subId of claim.substitutes) {
+    const sub = policy.claims_taxonomy.find(c => c.claim_id === subId);
+    if (sub?.permitted_modes.includes(req.mode) && !sub.inference_risks.includes(req.requested_claim_id))
+      return { permitted: true, disclosed_claim_id: subId, disclosed_value: fv(values[subId], req.mode), mode: req.mode, was_substituted: true,
+        substitution_receipt: sr(req.requested_claim_id, subId, policyVersion, 'SENSITIVITY_DENIED', chainSeq, kp) };
+  }
+  return { permitted: false, disclosed_claim_id: null, disclosed_value: null, mode: req.mode, was_substituted: false,
+    substitution_receipt: sr(req.requested_claim_id, null, policyVersion, 'NO_PERMITTED_SUBSTITUTE', chainSeq, kp) };
+}
+
+function fv(v: unknown, m: DisclosureMode): unknown { return m === 'PROOF_ONLY' ? v != null : v; }
+function sr(orig: string, sub: string | null, pv: number, reason: string, seq: number, kp: KeyPair): SubstitutionReceipt {
+  const u = { receipt_id: uuid(), original_claim_id: orig, substitute_claim_id: sub, policy_version: pv, reason_code: reason, timestamp: utcNow(), chain_sequence_ref: seq };
+  return { ...u, signature: sigToB64(signStr(canonicalize(u), kp.secretKey)) };
+}

package/src/core/identity.ts

@@ -0,0 +1,62 @@
+/**
+ * Identity and Key Lifecycle.
+ *
+ * Non-biometric cryptographic identity: agent identity derived from
+ * cryptographic key pair bound to append-only attestation history in
+ * continuity chain. Authority from valid signature history, not biometric traits.
+ *
+ * Functions:
+ * - keyFingerprint: re-exported from crypto/sign.ts for convenience
+ * - isKeyValid: check key TTL expiry
+ * - rotateKeyPair: generate new key pair for rotation
+ * - recordKeyRotation: append KEY_ROTATION event to chain
+ */
+import { generateKeyPair, keyFingerprint, pkToHex } from '../crypto/sign.js';
+import { isExpired } from '../utils/timestamp.js';
+import { appendEvent } from './chain.js';
+import type { KeyPair } from '../crypto/types.js';
+import type { ContinuityEvent, KeyRotationRecord } from './types.js';
+
+// Re-export keyFingerprint for identity module consumers (NCCoE §2)
+export { keyFingerprint } from '../crypto/sign.js';
+
+/**
+ * Check whether a key is still valid given its issuance time and TTL.
+ * NCCoE §2: non-biometric identity validity check.
+ */
+export function isKeyValid(issuedAt: string, ttlSeconds: number): boolean {
+  return !isExpired(issuedAt, ttlSeconds);
+}
+
+/**
+ * Generate a new key pair for rotation, returning both old and new for
+ * a transition period defined by policy. NCCoE §3: key rotation.
+ */
+export function rotateKeyPair(currentKeyPair: KeyPair): { oldKeyPair: KeyPair; newKeyPair: KeyPair } {
+  const newKeyPair = generateKeyPair();
+  return { oldKeyPair: currentKeyPair, newKeyPair };
+}
+
+/**
+ * Record a key rotation event on the continuity chain.
+ * NCCoE §3: "Key rotation is handled by including both old and new public keys
+ * during a transition period defined by policy."
+ */
+export function recordKeyRotation(
+  prevEvent: ContinuityEvent,
+  keypairType: string,
+  oldPublicKeyHex: string,
+  newPublicKeyHex: string,
+  reason: string,
+  signingKeyPair: KeyPair,
+): ContinuityEvent {
+  const payload: KeyRotationRecord = {
+    keypair_type: keypairType,
+    old_public_key: oldPublicKeyHex,
+    new_public_key: newPublicKeyHex,
+    reason,
+    rotation_timestamp: new Date().toISOString(),
+    chain_sequence: prevEvent.sequence_number + 1,
+  };
+  return appendEvent('KEY_ROTATION', payload, prevEvent, signingKeyPair);
+}

package/src/core/index.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './subject.js';
+export * from './attestation.js';
+export * from './artifact.js';
+export * from './receipt.js';
+export * from './chain.js';
+export * from './portal.js';
+export * from './quarantine.js';
+export * from './checkpoint.js';
+export * from './bundle.js';
+export * from './disclosure.js';
+export * from './behavioral.js';
+export * from './delegation.js';
+export * from './identity.js';