@humanagencyp/hap-core 0.4.0

package/README.md

@@ -0,0 +1,71 @@
+# @humanagencyprotocol/hap-core
+
+Core types, cryptographic primitives, and verification logic for the [Human Agency Protocol](https://humanagencyprotocol.com).
+
+## Install
+
+```bash
+npm install @humanagencyprotocol/hap-core
+```
+
+## What's included
+
+- **Types** — `AgentProfile`, `AgentBoundsParams`, `AgentContextParams`, execution context schemas, gate questions
+- **Frame** — Canonical hashing of bounds and context (`computeBoundsHash`, `computeContextHash`)
+- **Attestation** — Ed25519 signing and verification of attestation blobs
+- **Gatekeeper** — Execution verification against bounds, context constraints, and cumulative tracking
+- **Profiles** — Runtime profile registry (`registerProfile`, `getProfile`, `getAllProfiles`, `clearProfiles`)
+
+## Usage
+
+```typescript
+import {
+  type AgentProfile,
+  computeBoundsHash,
+  computeContextHash,
+  verify,
+  registerProfile,
+  getProfile,
+} from '@humanagencyprotocol/hap-core';
+
+// Register a profile
+registerProfile(profile.id, profile);
+
+// Compute deterministic hashes for bounds and context
+const boundsHash = computeBoundsHash(bounds, profile);
+const contextHash = computeContextHash(context, profile);
+
+// Verify an execution against bounds and attestations
+const result = await verify(
+  { frame, attestations, execution, context },
+  publicKeyHex,
+);
+
+if (result.approved) {
+  // Execution is within bounds
+}
+```
+
+## Constraint types
+
+The gatekeeper enforces three types of constraints from the profile's bounds and context schemas:
+
+| Type | Description | Example |
+|---|---|---|
+| `max` | Numeric upper bound | `amount_max: 1000` |
+| `enum` | Value must be in allowed set | `currency: ["USD", "EUR"]` |
+| `subset` | Every item must appear in bound | `allowed_domains: "acme.com,partner.org"` |
+
+## Cumulative tracking
+
+Bounds fields ending in `_daily_max` or `_monthly_max` are checked against cumulative execution logs. The gatekeeper resolves running totals from an `ExecutionLog` interface:
+
+```typescript
+interface ExecutionLog {
+  sumByWindow(profileId: string, path: string, field: string, window: 'daily' | 'monthly'): Promise<number>;
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,499 @@
+/**
+ * HAP Core Types — Agent Demo
+ *
+ * Types for agent-oriented profiles with bounded execution.
+ */
+interface AttestationHeader {
+    typ: 'HAP-attestation';
+    alg: 'EdDSA';
+    kid?: string;
+}
+interface ResolvedDomain {
+    domain: string;
+    did: string;
+}
+interface AttestationPayload {
+    attestation_id: string;
+    version: '0.3' | '0.4';
+    profile_id: string;
+    /** v0.3 (deprecated) — hash of the authorization frame */
+    frame_hash?: string;
+    /** v0.4 — hash of the bounds parameters */
+    bounds_hash?: string;
+    /** v0.4 — hash of the context parameters */
+    context_hash?: string;
+    execution_context_hash: string;
+    resolved_domains: ResolvedDomain[];
+    gate_content_hashes: Record<string, string>;
+    issued_at: number;
+    expires_at: number;
+}
+interface Attestation {
+    header: AttestationHeader;
+    payload: AttestationPayload;
+    signature: string;
+}
+/**
+ * Field constraint type — what kind of bound a field supports.
+ * - max: numeric upper bound (actual <= bound)
+ * - enum: value must be in the allowed set
+ * - subset: every item in actual must appear in bound (comma-separated, case-insensitive)
+ */
+interface FieldConstraint {
+    type: 'number' | 'string';
+    enforceable: Array<'max' | 'enum' | 'subset'>;
+}
+/**
+ * Frame field definition within a profile.
+ */
+interface ProfileFrameField {
+    type: 'string' | 'number';
+    required: boolean;
+    description?: string;
+    constraint?: FieldConstraint;
+    enum?: string[];
+}
+/**
+ * Bounds field definition within a v0.4 profile.
+ */
+interface ProfileBoundsField {
+    type: 'string' | 'number';
+    required: boolean;
+    description?: string;
+    displayName?: string;
+    format?: 'email' | 'domain' | 'url' | 'currency';
+    constraint?: FieldConstraint;
+    enum?: string[];
+}
+/**
+ * Context field definition within a v0.4 profile.
+ */
+interface ProfileContextField {
+    type: 'string' | 'number';
+    required: boolean;
+    description?: string;
+    displayName?: string;
+    format?: 'email' | 'domain' | 'url' | 'currency';
+    constraint?: FieldConstraint;
+    enum?: string[];
+}
+/**
+ * Execution context field definition — declared source (value comes from the agent's tool call).
+ */
+interface DeclaredFieldDef {
+    source: 'declared';
+    description: string;
+    required: boolean;
+    constraint?: FieldConstraint;
+}
+/**
+ * Cumulative window types for stateful limit tracking.
+ */
+type CumulativeWindow = 'daily' | 'weekly' | 'monthly';
+/**
+ * Execution context field definition — cumulative source (resolved from execution log).
+ *
+ * The gatekeeper resolves these by querying the execution log:
+ * - `cumulativeField`: which declared field to sum (use "_count" for plain counting)
+ * - `window`: time window for aggregation (daily, weekly, monthly)
+ *
+ * The resolved value = running total within window + current call value.
+ */
+interface CumulativeFieldDef {
+    source: 'cumulative';
+    cumulativeField: string;
+    window: CumulativeWindow;
+    description: string;
+    required: boolean;
+    constraint?: FieldConstraint;
+}
+/**
+ * Execution context field definition — either declared or cumulative.
+ */
+type ExecutionContextFieldDef = DeclaredFieldDef | CumulativeFieldDef;
+/**
+ * Gate question definition.
+ */
+interface GateQuestion {
+    question: string;
+    required: boolean;
+}
+/**
+ * Execution path definition within a profile.
+ */
+interface ExecutionPath {
+    description: string;
+    requiredDomains?: string[];
+    ttl?: {
+        default: number;
+        max: number;
+    };
+}
+/**
+ * Agent Profile — defines constraint types, execution paths, gate questions,
+ * and the frame/bounds/context schemas for bounded execution.
+ *
+ * Supports both v0.3 (frameSchema) and v0.4 (boundsSchema + contextSchema).
+ */
+interface AgentProfile {
+    id: string;
+    name?: string;
+    version: string;
+    description: string;
+    /**
+     * v0.3 frame schema (deprecated, kept for backward compat).
+     * Used when boundsSchema is not present.
+     */
+    frameSchema?: {
+        keyOrder: string[];
+        fields: Record<string, ProfileFrameField>;
+    };
+    /**
+     * v0.4 bounds schema — defines the authorization bounds parameters.
+     */
+    boundsSchema?: {
+        keyOrder: string[];
+        fields: Record<string, ProfileBoundsField>;
+    };
+    /**
+     * v0.4 context schema — defines the execution context parameters (e.g., currency, action_type).
+     * May be absent or empty for profiles with no static context.
+     */
+    contextSchema?: {
+        keyOrder: string[];
+        fields: Record<string, ProfileContextField>;
+    };
+    executionContextSchema: {
+        fields: Record<string, ExecutionContextFieldDef>;
+    };
+    executionPaths: Record<string, ExecutionPath>;
+    requiredGates: string[];
+    gateQuestions: {
+        problem: GateQuestion;
+        objective: GateQuestion;
+        tradeoffs: GateQuestion;
+    };
+    ttl: {
+        default: number;
+        max: number;
+    };
+    retention_minimum: number;
+    /**
+     * Tool gating configuration — how MCP tools map to execution context.
+     * @deprecated Tool gating now lives in integration manifests (content/integrations/*.json).
+     * Kept for backward compatibility with profiles that still include it.
+     */
+    toolGating?: ProfileToolGating;
+}
+/**
+ * Available transforms for array-aware execution mappings.
+ * - length: array length → number
+ * - join: array items joined by comma → string
+ * - join_domains: extract email domains, deduplicate, sort, join → string
+ */
+type ExecutionMappingTransform = 'join' | 'join_domains' | 'length';
+/**
+ * Execution mapping value — how a tool argument maps to execution context field(s).
+ * - string: direct copy (argName → fieldName)
+ * - { field, divisor }: numeric division (e.g., cents ÷ 100 → EUR)
+ * - { field, transform }: array transform (e.g., join_domains)
+ * - Array form: one argument maps to multiple execution fields
+ */
+type ExecutionMappingValue = string | {
+    field: string;
+    divisor: number;
+} | {
+    field: string;
+    transform: ExecutionMappingTransform;
+} | Array<{
+    field: string;
+    divisor?: number;
+    transform?: ExecutionMappingTransform;
+}>;
+/**
+ * Tool gating entry — how a tool's calls map to execution context fields.
+ * Read-only tools use { category: "read" } — they require authorization
+ * but skip execution context verification.
+ */
+interface ProfileToolGatingEntry {
+    executionMapping: Record<string, ExecutionMappingValue>;
+    staticExecution?: Record<string, string | number>;
+    /** Read-only tools: require authorization but no execution context checks */
+    category?: 'read';
+}
+/**
+ * Profile-level tool gating configuration.
+ * - default: applied to all tools not listed in overrides
+ * - overrides: per-tool configs keyed by original MCP tool name
+ *   Use { category: "read" } for read-only tools (null is deprecated)
+ */
+interface ProfileToolGating {
+    default: ProfileToolGatingEntry;
+    overrides?: Record<string, ProfileToolGatingEntry | null>;
+}
+/**
+ * A recorded execution — stored after gatekeeper approval for cumulative tracking.
+ */
+interface ExecutionLogEntry {
+    profileId: string;
+    path: string;
+    execution: Record<string, string | number>;
+    timestamp: number;
+}
+/**
+ * Interface for querying cumulative execution data.
+ * Implementations live in the MCP server layer (not hap-core).
+ */
+interface ExecutionLogQuery {
+    /**
+     * Sum a field's values within a time window for a given profile.
+     * Use field="_count" to count executions instead of summing a field.
+     */
+    sumByWindow(profileId: string, path: string, field: string, window: CumulativeWindow, now?: number): number;
+}
+/**
+ * Agent frame parameters — mixed types (strings and numbers).
+ * Keys and values come from the profile's frameSchema.
+ */
+type AgentFrameParams = Record<string, string | number>;
+/**
+ * Agent bounds parameters — mixed types (strings and numbers).
+ * Keys and values come from the profile's boundsSchema (v0.4).
+ */
+type AgentBoundsParams = Record<string, string | number>;
+/**
+ * Agent context parameters — mixed types (strings and numbers).
+ * Keys and values come from the profile's contextSchema (v0.4).
+ */
+type AgentContextParams = Record<string, string | number>;
+/**
+ * Request to the Gatekeeper for bounded execution verification.
+ */
+interface GatekeeperRequest {
+    /** The authorization frame (what was attested to) — v0.3 */
+    frame: AgentFrameParams;
+    /** Attestation blobs (base64url) for each domain */
+    attestations: string[];
+    /** The agent's execution values for this specific action */
+    execution: Record<string, string | number>;
+    /** v0.4: context parameters (currency, action_type, etc.) */
+    context?: AgentContextParams;
+}
+/**
+ * Structured error from Gatekeeper verification.
+ */
+interface GatekeeperError {
+    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION';
+    field?: string;
+    message: string;
+    bound?: string | number;
+    actual?: string | number;
+}
+/**
+ * Gatekeeper verification result.
+ */
+type GatekeeperResult = {
+    approved: true;
+} | {
+    approved: false;
+    errors: GatekeeperError[];
+};
+
+/**
+ * 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)
+ */
+
+/**
+ * Validates frame parameters against the profile's frame schema.
+ */
+declare function validateFrameParams(params: AgentFrameParams, profile: AgentProfile): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 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
+ */
+declare function canonicalFrame(params: AgentFrameParams, profile: AgentProfile): string;
+/**
+ * Computes the frame hash from a canonical frame string.
+ *
+ * @returns Hash in format "sha256:<64 hex chars>"
+ */
+declare function frameHash(canonicalFrameString: string): string;
+/**
+ * Convenience: builds canonical frame and computes hash in one step.
+ */
+declare function computeFrameHash(params: AgentFrameParams, profile: AgentProfile): string;
+/**
+ * Validates bounds parameters against the profile's boundsSchema (v0.4).
+ */
+declare function validateBoundsParams(params: AgentBoundsParams, profile: AgentProfile): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validates context parameters against the profile's contextSchema (v0.4).
+ */
+declare function validateContextParams(params: AgentContextParams, profile: AgentProfile): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 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
+ */
+declare function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string;
+/**
+ * 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
+ */
+declare function canonicalContext(params: AgentContextParams, profile: AgentProfile): string;
+/**
+ * Computes the bounds hash from bounds parameters (v0.4).
+ *
+ * @returns Hash in format "sha256:<64 hex chars>"
+ */
+declare function computeBoundsHash(params: AgentBoundsParams, profile: AgentProfile): string;
+/**
+ * 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>"
+ */
+declare function computeContextHash(params: AgentContextParams, profile: AgentProfile): string;
+
+/**
+ * Attestation Encoding, Decoding, and Verification
+ *
+ * Supports both v0.3 (frame_hash) and v0.4 (bounds_hash + context_hash).
+ */
+
+/**
+ * Decodes a base64url-encoded attestation blob.
+ */
+declare function decodeAttestationBlob(blob: string): Attestation;
+/**
+ * Encodes an attestation as a base64url blob (no padding).
+ */
+declare function encodeAttestationBlob(attestation: Attestation): string;
+/**
+ * Computes the attestation ID (hash of the blob).
+ */
+declare function attestationId(blob: string): string;
+/**
+ * Verifies an attestation signature using the SP public key.
+ *
+ * @returns true if valid
+ * @throws Error with code prefix if invalid
+ */
+declare function verifyAttestationSignature(attestation: Attestation, publicKeyHex: string): Promise<void>;
+/**
+ * Checks if an attestation has expired.
+ *
+ * @throws Error if expired
+ */
+declare function checkAttestationExpiry(payload: AttestationPayload, now?: number): void;
+/**
+ * Verifies that the frame hash in the attestation matches the expected hash (v0.3).
+ *
+ * @throws Error if frame hash doesn't match
+ */
+declare function verifyFrameHash(attestation: Attestation, expectedFrameHash: string): void;
+/**
+ * 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.
+ */
+declare function isV4Attestation(attestation: Attestation): boolean;
+/**
+ * Verifies that the bounds hash in the attestation matches the expected hash (v0.4).
+ *
+ * @throws Error if bounds hash doesn't match
+ */
+declare function verifyBoundsHash(attestation: Attestation, expectedBoundsHash: string): void;
+/**
+ * Verifies that the context hash in the attestation matches the expected hash (v0.4).
+ *
+ * @throws Error if context hash doesn't match
+ */
+declare function verifyContextHash(attestation: Attestation, expectedContextHash: string): void;
+/**
+ * Full attestation verification (signature + expiry + frame hash) — v0.3.
+ *
+ * @returns The decoded attestation payload
+ * @throws Error on any validation failure
+ */
+declare function verifyAttestation(blob: string, publicKeyHex: string, expectedFrameHash: string): Promise<AttestationPayload>;
+/**
+ * Full attestation verification for v0.4 (signature + expiry + bounds_hash + context_hash).
+ *
+ * @returns The decoded attestation payload
+ * @throws Error on any validation failure
+ */
+declare function verifyAttestationV4(blob: string, publicKeyHex: string, expectedBoundsHash: string, expectedContextHash: string): Promise<AttestationPayload>;
+
+/**
+ * Gatekeeper — Stateless Verification for Bounded Execution
+ *
+ * Supports both v0.3 (frameSchema / frame_hash) and v0.4 (boundsSchema + contextSchema /
+ * bounds_hash + context_hash).
+ *
+ * v0.3 flow (§8.6):
+ *   1. Resolve profile from frame
+ *   2. Recompute frame_hash
+ *   3. For each required domain: find attestation, verify signature, verify frame_hash, verify TTL
+ *   4. Check bounds: max → actual <= bound, enum → actual in allowed
+ *   5. Return { approved } or { approved: false, errors: [...] }
+ *
+ * v0.4 flow:
+ *   1. Resolve profile from bounds.profile
+ *   2. Recompute bounds_hash and context_hash
+ *   3. For each required domain: find attestation, verify signature, verify bounds_hash + context_hash, verify TTL
+ *   4. Check bounds (from boundsSchema), check context constraints (from contextSchema)
+ *   5. Resolve cumulative fields, check cumulative limits
+ *   6. Return { approved } or { approved: false, errors: [...] }
+ */
+
+/**
+ * Verify an execution request against attested authorization.
+ *
+ * For v0.4 profiles (have boundsSchema), the `frame` param is interpreted as `bounds`,
+ * and the optional `context` param is used for the context hash check.
+ *
+ * For v0.3 profiles (have frameSchema only), existing logic is used unchanged.
+ *
+ * @param request - The frame/bounds, attestations, execution values, and optional context
+ * @param publicKeyHex - The SP's public key in hex (cached locally by MCP server)
+ * @param now - Current timestamp in seconds (for testing)
+ * @param executionLog - Optional execution log for resolving cumulative fields
+ */
+declare function verify(request: GatekeeperRequest, publicKeyHex: string, now?: number, executionLog?: ExecutionLogQuery): Promise<GatekeeperResult>;
+
+/**
+ * Profile Registry — dynamically populated from git-hosted profile sources.
+ */
+
+declare function registerProfile(profileId: string, profile: AgentProfile): void;
+declare function getProfile(profileId: string): AgentProfile | undefined;
+declare function listProfiles(): string[];
+declare function getAllProfiles(): AgentProfile[];
+declare function clearProfiles(): void;
+
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ResolvedDomain, attestationId, canonicalBounds, canonicalContext, canonicalFrame, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContextHash, computeFrameHash, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };