@humanagencyp/hap-core 0.11.1 → 0.12.0

package/src/versions.ts

@@ -0,0 +1,47 @@
+/**
+ * Version negotiation — protocol.md → *Version negotiation (v0.7)*.
+ *
+ * "Gatekeepers and Authority Servers MUST reject unknown or untrusted
+ * versions" is a safety rule, not a transition plan; this module is the
+ * transition plan. A mandate request carries `supported_versions`; the AS
+ * issues at the highest version both sides support, or refuses with
+ * `VERSION_UNSUPPORTED` where there is none. A request without the field is
+ * read as `["0.6"]` (rule 1) — but this package issues and verifies `0.7`
+ * only (CLAUDE.md "Decided by the owner": no backward verify path), so that
+ * default exists to make the refusal message honest, not to accept the
+ * mandate.
+ */
+import { HapError } from './errors';
+
+/** The protocol version this package issues and verifies. */
+export const PROTOCOL_VERSION = '0.7';
+
+/** The protocol versions this package can verify and enforce. */
+export const SUPPORTED_VERSIONS: readonly string[] = ['0.7'];
+
+/**
+ * The highest version both the requester and this implementation support.
+ *
+ * @param requested `supported_versions` from the mandate request. Absent →
+ * read as `["0.6"]` (protocol.md rule 1) — which, against this package's
+ * `SUPPORTED_VERSIONS`, has no overlap and refuses honestly rather than
+ * silently assuming `0.7`.
+ * @throws HapError `VERSION_UNSUPPORTED` when no version is common to both.
+ */
+export function negotiateVersion(
+  requested: readonly string[] | undefined,
+  supported: readonly string[] = SUPPORTED_VERSIONS,
+): string {
+  const requestedVersions = requested ?? ['0.6'];
+  // Highest-first so a requester offering several supported versions gets the
+  // newest one both sides agree on, not merely the first common element.
+  const common = supported.filter((v) => requestedVersions.includes(v)).sort().reverse();
+  if (common.length === 0) {
+    throw new HapError(
+      'VERSION_UNSUPPORTED',
+      `no protocol version in [${requestedVersions.join(', ')}] is supported by this implementation ` +
+        `(supports [${supported.join(', ')}])`,
+    );
+  }
+  return common[0];
+}

package/src/attestation.ts

@@ -1,173 +0,0 @@
-/**
- * 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';
-import { canonicalize } from './canonicalize';
-
-/**
- * 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 {
-    // JCS-canonical bytes (RFC 8785) — must match the canonicalization the
-    // signer used. The AS signs the same canonical form (see keys.ts).
-    const payloadJson = canonicalize(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/receipt.ts

@@ -1,74 +0,0 @@
-/**
- * Execution receipts (HAP v0.5/v0.6) — the wire type and holder-side
- * verification. Until v0.6 this library had no receipt surface at all; every
- * verifier hand-assembled the strip→canonicalize→verify dance. This module is
- * that dance, once.
- *
- * Receipt payloads are camelCase on the wire (unlike the snake_case
- * attestation payload) — a shipped inconsistency v0.6 chose to document
- * rather than break (changelog.md → "Renames and terminology").
- */
-
-import * as ed from '@noble/ed25519';
-import type { ContentBinding, Subject } from './types';
-import { canonicalize } from './canonicalize';
-
-/** Signed execution receipt — protocol.md → "Receipt Payload Schema". */
-export interface ReceiptPayload {
-  id: string;
-  groupId?: string | null;
-  userId?: string;
-  boundsHash: string;
-  profileId: string;
-  /** Downstream tool name. Audit metadata only — never a dispatch key. */
-  action: string;
-  /** Semantic category — drives cumulative bucketing and bounds dispatch. */
-  actionType: string;
-  executionContext: Record<string, unknown>;
-  cumulativeState?: Record<string, unknown>;
-  limits?: Record<string, unknown>;
-  timestamp: number;
-  /** v0.6 — hash of the bound content, computed by the Gatekeeper, copied
-   * verbatim by the AS. The AS never sees the content. */
-  contentHash?: string;
-  /** v0.6 — the binding declaration echoed into the signed receipt, so a
-   * verifier knows exactly what `contentHash` covers. */
-  contentBinding?: Pick<ContentBinding, 'version' | 'kind' | 'fields' | 'required_fields' | 'appliesTo'>;
-  /** v0.6 — disclosed subset of the attestation's identity overlay. */
-  subjects?: Subject[];
-  /** v0.6 — review path: the proposal this receipt executed. */
-  proposalId?: string;
-  /** v0.6 — review path: the owner's HAP-approval signature (or its sha256)
-   * for the executed proposal. */
-  approvalSignature?: string;
-  /** Ed25519 over the JCS-canonical payload (this field excluded), base64url. */
-  signature: string;
-}
-
-/**
- * Verify a receipt's AS signature: strip `signature`, JCS-canonicalize the
- * rest, Ed25519-verify against the AS public key (hex). This is holder-side
- * verification — it needs the COMPLETE receipt; a redacted public view cannot
- * be re-verified this way (protocol.md → "Receipt Verification").
- *
- * Content is checked separately: where `contentHash` is present, recompute it
- * from the held artifact via the content-binding module and compare.
- *
- * @throws Error prefixed `INVALID_SIGNATURE:` when verification fails.
- */
-export async function verifyReceiptSignature(receipt: ReceiptPayload, publicKeyHex: string): Promise<void> {
-  const { signature, ...unsigned } = receipt;
-  if (!signature) {
-    throw new Error('INVALID_SIGNATURE: receipt carries no signature');
-  }
-  const bytes = new TextEncoder().encode(canonicalize(unsigned));
-  const base64 = signature.replace(/-/g, '+').replace(/_/g, '/');
-  const padding = base64.length % 4 === 0 ? '' : '='.repeat(4 - (base64.length % 4));
-  const sigBytes = new Uint8Array(Buffer.from(base64 + padding, 'base64'));
-  const publicKeyBytes = new Uint8Array(Buffer.from(publicKeyHex, 'hex'));
-
-  const ok = await ed.verifyAsync(sigBytes, bytes, publicKeyBytes).catch(() => false);
-  if (!ok) {
-    throw new Error('INVALID_SIGNATURE: receipt signature verification failed');
-  }
-}