@humanagencyp/hap-core 0.4.0

package/src/attestation.ts

@@ -0,0 +1,170 @@
+/**
+ * Attestation Encoding, Decoding, and Verification
+ *
+ * Supports both v0.3 (frame_hash) and v0.4 (bounds_hash + context_hash).
+ */
+
+import { createHash } from 'crypto';
+import * as ed from '@noble/ed25519';
+import type { Attestation, AttestationPayload } from './types';
+
+/**
+ * Decodes a base64url-encoded attestation blob.
+ */
+export function decodeAttestationBlob(blob: string): Attestation {
+  try {
+    const base64 = blob.replace(/-/g, '+').replace(/_/g, '/');
+    const padding = base64.length % 4 === 0 ? '' : '='.repeat(4 - (base64.length % 4));
+    const json = Buffer.from(base64 + padding, 'base64').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    throw new Error('MALFORMED_ATTESTATION: Failed to decode attestation blob');
+  }
+}
+
+/**
+ * Encodes an attestation as a base64url blob (no padding).
+ */
+export function encodeAttestationBlob(attestation: Attestation): string {
+  const json = JSON.stringify(attestation);
+  const base64 = Buffer.from(json, 'utf8').toString('base64');
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Computes the attestation ID (hash of the blob).
+ */
+export function attestationId(blob: string): string {
+  const hash = createHash('sha256').update(blob, 'utf8').digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Verifies an attestation signature using the SP public key.
+ *
+ * @returns true if valid
+ * @throws Error with code prefix if invalid
+ */
+export async function verifyAttestationSignature(
+  attestation: Attestation,
+  publicKeyHex: string
+): Promise<void> {
+  try {
+    const payloadJson = JSON.stringify(attestation.payload);
+    const payloadBytes = new TextEncoder().encode(payloadJson);
+    const signatureBytes = Buffer.from(attestation.signature, 'base64');
+    const publicKeyBytes = Buffer.from(publicKeyHex, 'hex');
+
+    const isValid = await ed.verifyAsync(signatureBytes, payloadBytes, publicKeyBytes);
+
+    if (!isValid) {
+      throw new Error('INVALID_SIGNATURE: Attestation signature verification failed');
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('INVALID_SIGNATURE')) throw error;
+    throw new Error(`INVALID_SIGNATURE: Signature verification error: ${error}`);
+  }
+}
+
+/**
+ * Checks if an attestation has expired.
+ *
+ * @throws Error if expired
+ */
+export function checkAttestationExpiry(
+  payload: AttestationPayload,
+  now: number = Math.floor(Date.now() / 1000)
+): void {
+  if (payload.expires_at <= now) {
+    throw new Error(
+      `TTL_EXPIRED: Attestation expired at ${payload.expires_at}, current time is ${now}`
+    );
+  }
+}
+
+/**
+ * Verifies that the frame hash in the attestation matches the expected hash (v0.3).
+ *
+ * @throws Error if frame hash doesn't match
+ */
+export function verifyFrameHash(attestation: Attestation, expectedFrameHash: string): void {
+  if (attestation.payload.frame_hash !== expectedFrameHash) {
+    throw new Error('FRAME_MISMATCH: Frame hash mismatch');
+  }
+}
+
+/**
+ * Detects whether an attestation is v0.4 (has bounds_hash + context_hash)
+ * or v0.3 (has frame_hash).
+ *
+ * Migration rule: if attestation has frame_hash but not bounds_hash, it is v0.3.
+ */
+export function isV4Attestation(attestation: Attestation): boolean {
+  return attestation.payload.bounds_hash !== undefined;
+}
+
+/**
+ * Verifies that the bounds hash in the attestation matches the expected hash (v0.4).
+ *
+ * @throws Error if bounds hash doesn't match
+ */
+export function verifyBoundsHash(attestation: Attestation, expectedBoundsHash: string): void {
+  // Migration: if attestation has frame_hash but not bounds_hash, treat frame_hash as bounds_hash
+  const attestedHash = attestation.payload.bounds_hash ?? attestation.payload.frame_hash;
+  if (attestedHash !== expectedBoundsHash) {
+    throw new Error('BOUNDS_MISMATCH: Bounds hash mismatch');
+  }
+}
+
+/**
+ * Verifies that the context hash in the attestation matches the expected hash (v0.4).
+ *
+ * @throws Error if context hash doesn't match
+ */
+export function verifyContextHash(attestation: Attestation, expectedContextHash: string): void {
+  if (attestation.payload.context_hash !== expectedContextHash) {
+    throw new Error('CONTEXT_MISMATCH: Context hash mismatch');
+  }
+}
+
+/**
+ * Full attestation verification (signature + expiry + frame hash) — v0.3.
+ *
+ * @returns The decoded attestation payload
+ * @throws Error on any validation failure
+ */
+export async function verifyAttestation(
+  blob: string,
+  publicKeyHex: string,
+  expectedFrameHash: string
+): Promise<AttestationPayload> {
+  const attestation = decodeAttestationBlob(blob);
+
+  await verifyAttestationSignature(attestation, publicKeyHex);
+  checkAttestationExpiry(attestation.payload);
+  verifyFrameHash(attestation, expectedFrameHash);
+
+  return attestation.payload;
+}
+
+/**
+ * Full attestation verification for v0.4 (signature + expiry + bounds_hash + context_hash).
+ *
+ * @returns The decoded attestation payload
+ * @throws Error on any validation failure
+ */
+export async function verifyAttestationV4(
+  blob: string,
+  publicKeyHex: string,
+  expectedBoundsHash: string,
+  expectedContextHash: string
+): Promise<AttestationPayload> {
+  const attestation = decodeAttestationBlob(blob);
+
+  await verifyAttestationSignature(attestation, publicKeyHex);
+  checkAttestationExpiry(attestation.payload);
+  verifyBoundsHash(attestation, expectedBoundsHash);
+  verifyContextHash(attestation, expectedContextHash);
+
+  return attestation.payload;
+}

package/src/frame.ts

@@ -0,0 +1,245 @@
+/**
+ * Frame Canonicalization for Agent Profiles
+ *
+ * Agent profiles support mixed-type fields (strings and numbers).
+ * Canonical form: all values are converted to strings via String(value).
+ * Keys are ordered according to the profile's keyOrder.
+ *
+ * v0.3: frameSchema
+ * v0.4: boundsSchema + contextSchema (separate hashes)
+ */
+
+import { createHash } from 'crypto';
+import type { AgentFrameParams, AgentBoundsParams, AgentContextParams, AgentProfile } from './types';
+
+// ─── v0.3 Frame Functions ─────────────────────────────────────────────────────
+
+/**
+ * Validates frame parameters against the profile's frame schema.
+ */
+export function validateFrameParams(
+  params: AgentFrameParams,
+  profile: AgentProfile
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!profile.frameSchema) {
+    return { valid: false, errors: ['Profile does not have a frameSchema'] };
+  }
+
+  // Check all required fields are present
+  for (const [fieldName, fieldDef] of Object.entries(profile.frameSchema.fields)) {
+    if (fieldDef.required && !(fieldName in params)) {
+      errors.push(`Missing required field: ${fieldName}`);
+    }
+  }
+
+  // Validate each provided field
+  for (const [field, value] of Object.entries(params)) {
+    const fieldDef = profile.frameSchema.fields[field];
+    if (!fieldDef) {
+      errors.push(`Unknown field "${field}" not defined in profile ${profile.id}`);
+      continue;
+    }
+
+    // Type check
+    if (fieldDef.type === 'number' && typeof value !== 'number') {
+      errors.push(`Field "${field}" must be a number, got ${typeof value}`);
+    }
+    if (fieldDef.type === 'string' && typeof value !== 'string') {
+      errors.push(`Field "${field}" must be a string, got ${typeof value}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Builds the canonical frame string from parameters.
+ * All values are converted to strings. Keys are ordered per profile's keyOrder.
+ *
+ * @throws Error if any field fails validation
+ */
+export function canonicalFrame(params: AgentFrameParams, profile: AgentProfile): string {
+  const validation = validateFrameParams(params, profile);
+  if (!validation.valid) {
+    throw new Error(`Invalid frame parameters: ${validation.errors.join('; ')}`);
+  }
+
+  const lines = profile.frameSchema!.keyOrder.map(
+    (key) => `${key}=${String(params[key])}`
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Computes the frame hash from a canonical frame string.
+ *
+ * @returns Hash in format "sha256:<64 hex chars>"
+ */
+export function frameHash(canonicalFrameString: string): string {
+  const hash = createHash('sha256').update(canonicalFrameString, 'utf8').digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Convenience: builds canonical frame and computes hash in one step.
+ */
+export function computeFrameHash(params: AgentFrameParams, profile: AgentProfile): string {
+  return frameHash(canonicalFrame(params, profile));
+}
+
+// ─── v0.4 Bounds Functions ────────────────────────────────────────────────────
+
+/**
+ * Validates bounds parameters against the profile's boundsSchema (v0.4).
+ */
+export function validateBoundsParams(
+  params: AgentBoundsParams,
+  profile: AgentProfile
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!profile.boundsSchema) {
+    return { valid: false, errors: ['Profile does not have a boundsSchema'] };
+  }
+
+  // Check all required fields are present
+  for (const [fieldName, fieldDef] of Object.entries(profile.boundsSchema.fields)) {
+    if (fieldDef.required && !(fieldName in params)) {
+      errors.push(`Missing required field: ${fieldName}`);
+    }
+  }
+
+  // Validate each provided field
+  for (const [field, value] of Object.entries(params)) {
+    const fieldDef = profile.boundsSchema.fields[field];
+    if (!fieldDef) {
+      errors.push(`Unknown field "${field}" not defined in boundsSchema of profile ${profile.id}`);
+      continue;
+    }
+
+    // Type check
+    if (fieldDef.type === 'number' && typeof value !== 'number') {
+      errors.push(`Field "${field}" must be a number, got ${typeof value}`);
+    }
+    if (fieldDef.type === 'string' && typeof value !== 'string') {
+      errors.push(`Field "${field}" must be a string, got ${typeof value}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validates context parameters against the profile's contextSchema (v0.4).
+ */
+export function validateContextParams(
+  params: AgentContextParams,
+  profile: AgentProfile
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!profile.contextSchema) {
+    // No contextSchema is valid — empty context
+    if (Object.keys(params).length > 0) {
+      errors.push('Profile does not have a contextSchema but context params were provided');
+    }
+    return { valid: errors.length === 0, errors };
+  }
+
+  // Check all required fields are present
+  for (const [fieldName, fieldDef] of Object.entries(profile.contextSchema.fields)) {
+    if (fieldDef.required && !(fieldName in params)) {
+      errors.push(`Missing required field: ${fieldName}`);
+    }
+  }
+
+  // Validate each provided field
+  for (const [field, value] of Object.entries(params)) {
+    const fieldDef = profile.contextSchema.fields[field];
+    if (!fieldDef) {
+      errors.push(`Unknown field "${field}" not defined in contextSchema of profile ${profile.id}`);
+      continue;
+    }
+
+    // Type check
+    if (fieldDef.type === 'number' && typeof value !== 'number') {
+      errors.push(`Field "${field}" must be a number, got ${typeof value}`);
+    }
+    if (fieldDef.type === 'string' && typeof value !== 'string') {
+      errors.push(`Field "${field}" must be a string, got ${typeof value}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Builds the canonical bounds string from parameters.
+ * All values are converted to strings. Keys are ordered per profile's boundsSchema.keyOrder.
+ *
+ * @throws Error if any field fails validation
+ */
+export function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string {
+  const validation = validateBoundsParams(params, profile);
+  if (!validation.valid) {
+    throw new Error(`Invalid bounds parameters: ${validation.errors.join('; ')}`);
+  }
+
+  const lines = profile.boundsSchema!.keyOrder.map(
+    (key) => `${key}=${String(params[key])}`
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Builds the canonical context string from parameters.
+ * All values are converted to strings. Keys are ordered per profile's contextSchema.keyOrder.
+ * For empty context (no contextSchema or no fields), returns "".
+ *
+ * @throws Error if any field fails validation
+ */
+export function canonicalContext(params: AgentContextParams, profile: AgentProfile): string {
+  // No contextSchema or no fields → empty context
+  if (!profile.contextSchema || Object.keys(profile.contextSchema.fields).length === 0) {
+    return '';
+  }
+
+  const validation = validateContextParams(params, profile);
+  if (!validation.valid) {
+    throw new Error(`Invalid context parameters: ${validation.errors.join('; ')}`);
+  }
+
+  const lines = profile.contextSchema.keyOrder.map(
+    (key) => `${key}=${String(params[key])}`
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Computes the bounds hash from bounds parameters (v0.4).
+ *
+ * @returns Hash in format "sha256:<64 hex chars>"
+ */
+export function computeBoundsHash(params: AgentBoundsParams, profile: AgentProfile): string {
+  const canonical = canonicalBounds(params, profile);
+  const hash = createHash('sha256').update(canonical, 'utf8').digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Computes the context hash from context parameters (v0.4).
+ * For empty context {}, returns the sha256 of "":
+ *   "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ *
+ * @returns Hash in format "sha256:<64 hex chars>"
+ */
+export function computeContextHash(params: AgentContextParams, profile: AgentProfile): string {
+  const canonical = canonicalContext(params, profile);
+  const hash = createHash('sha256').update(canonical, 'utf8').digest('hex');
+  return `sha256:${hash}`;
+}