@agexhq/core 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agexhq/core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "AGEX protocol primitives — crypto, schemas, policy engine",
   "type": "module",
   "main": "src/index.js",

package/src/crypto/ecdh.js

@@ -4,7 +4,7 @@
  * Pure JavaScript — works on Termux without native compilation
  */
 
-import { x25519, edwardsToMontgomeryPub } from '@noble/curves/ed25519'
+import { x25519 } from '@noble/curves/ed25519'
 import { hkdf } from '@noble/hashes/hkdf'
 import { sha256 } from '@noble/hashes/sha256'
 import { randomBytes } from '@noble/hashes/utils'
@@ -105,6 +105,8 @@ export function ed25519PrivateToX25519 (ed25519PrivateBase64url) {
  * Uses the birational map from Ed25519 to X25519 (Montgomery form).
  */
 export function ed25519PublicToX25519 (publicKeyJWK) {
+  // @noble/curves provides this conversion
+  const { edwardsToMontgomeryPub } = await import('@noble/curves/ed25519')
   const edPub = base64url.decode(publicKeyJWK.x)
   return edwardsToMontgomeryPub(edPub)
 }

package/src/crypto/index.js

@@ -0,0 +1,14 @@
+export {
+  generateKeypair, publicKeyToJWK, jwkToPublicKeyBytes,
+  sign, verify,
+  canonicalJson,
+  sha3Hash, sha256Hash,
+  computeEventHash,
+  generateId, generateNonce,
+  base64url, randomBytes
+} from './keys.js'
+
+export {
+  encryptEnvelope, decryptEnvelope,
+  ed25519PrivateToX25519
+} from './ecdh.js'

package/src/crypto/keys.js

@@ -0,0 +1,119 @@
+/**
+ * @agexhq/core — Cryptographic primitives
+ * Ed25519 key generation, signing, verification
+ * All pure JavaScript via @noble — zero native deps
+ */
+
+import * as ed from '@noble/ed25519'
+import { sha256 } from '@noble/hashes/sha256'
+import { sha3_256 } from '@noble/hashes/sha3'
+import { randomBytes } from '@noble/hashes/utils'
+import { base64url } from 'jose'
+import { v4 as uuidv4 } from 'uuid'
+
+// ── Key Generation ────────────────────────────────────────────────────────
+
+export function generateKeypair () {
+  const privateKey = ed.utils.randomPrivateKey()
+  const publicKey = ed.getPublicKeySync(privateKey)
+  return {
+    privateKey: base64url.encode(privateKey),
+    publicKey: base64url.encode(publicKey),
+    jwk: publicKeyToJWK(publicKey)
+  }
+}
+
+export function publicKeyToJWK (publicKeyBytes) {
+  return { kty: 'OKP', crv: 'Ed25519', x: base64url.encode(publicKeyBytes) }
+}
+
+export function jwkToPublicKeyBytes (jwk) {
+  return base64url.decode(jwk.x)
+}
+
+// ── Signing ───────────────────────────────────────────────────────────────
+
+export async function sign (message, privateKeyBase64url) {
+  const privBytes = base64url.decode(privateKeyBase64url)
+  const msgBytes = typeof message === 'string'
+    ? new TextEncoder().encode(message)
+    : message
+  const sig = await ed.signAsync(msgBytes, privBytes)
+  return base64url.encode(sig)
+}
+
+export async function verify (message, signatureBase64url, publicKeyJWK) {
+  try {
+    const pubBytes = jwkToPublicKeyBytes(publicKeyJWK)
+    const sigBytes = base64url.decode(signatureBase64url)
+    const msgBytes = typeof message === 'string'
+      ? new TextEncoder().encode(message)
+      : message
+    return await ed.verifyAsync(sigBytes, msgBytes, pubBytes)
+  } catch {
+    return false
+  }
+}
+
+// ── Canonical JSON (RFC 8785 — fixed edge cases from audit 3.3) ──────────
+
+export function canonicalJson (obj) {
+  if (obj === null) return 'null'
+  if (obj === undefined) return undefined
+  if (typeof obj === 'boolean') return String(obj)
+  if (typeof obj === 'number') {
+    if (!Number.isFinite(obj)) return 'null'
+    return Object.is(obj, -0) ? '0' : String(obj)
+  }
+  if (typeof obj === 'string') return JSON.stringify(obj)
+  if (obj instanceof Date) return JSON.stringify(obj.toISOString())
+  if (Array.isArray(obj)) {
+    return '[' + obj.map(v => {
+      const s = canonicalJson(v)
+      return s === undefined ? 'null' : s
+    }).join(',') + ']'
+  }
+  if (typeof obj === 'object') {
+    const pairs = Object.keys(obj)
+      .sort()
+      .map(k => {
+        const v = canonicalJson(obj[k])
+        if (v === undefined) return undefined
+        return JSON.stringify(k) + ':' + v
+      })
+      .filter(p => p !== undefined)
+    return '{' + pairs.join(',') + '}'
+  }
+  return 'null'
+}
+
+// ── Hashing ───────────────────────────────────────────────────────────────
+
+export function sha3Hash (data) {
+  const bytes = typeof data === 'string'
+    ? new TextEncoder().encode(data) : data
+  return Buffer.from(sha3_256(bytes)).toString('hex')
+}
+
+export function sha256Hash (data) {
+  const bytes = typeof data === 'string'
+    ? new TextEncoder().encode(data) : data
+  return Buffer.from(sha256(bytes)).toString('hex')
+}
+
+// ── Audit Hash Chain ──────────────────────────────────────────────────────
+
+export function computeEventHash (event, prevHash) {
+  const payload = canonicalJson({ ...event, prev_hash: prevHash })
+  return sha3Hash(payload)
+}
+
+// ── ID Generation ─────────────────────────────────────────────────────────
+
+export function generateId () { return uuidv4() }
+
+export function generateNonce () {
+  return base64url.encode(randomBytes(16))
+}
+
+export { base64url, randomBytes }

package/src/index.js

@@ -0,0 +1,40 @@
+/**
+ * @agexhq/core — AGEX Protocol Primitives
+ * The foundation package for the entire AGEX ecosystem.
+ * Pure JavaScript — zero native dependencies — works everywhere including Termux.
+ */
+
+// ── Crypto ────────────────────────────────────────────────────────────────
+export {
+  generateKeypair, publicKeyToJWK, jwkToPublicKeyBytes,
+  sign, verify,
+  canonicalJson,
+  sha3Hash, sha256Hash,
+  computeEventHash,
+  generateId, generateNonce,
+  base64url, randomBytes
+} from './crypto/keys.js'
+
+export {
+  encryptEnvelope, decryptEnvelope,
+  ed25519PrivateToX25519
+} from './crypto/ecdh.js'
+
+// ── Schemas ───────────────────────────────────────────────────────────────
+export {
+  AIDSchema, ManifestSchema, CLCSchema,
+  ServiceProviderSchema,
+  PolicyDocSchema, PolicyRuleSchema, PolicyConditionSchema
+} from './schemas/index.js'
+
+// ── Protocol ──────────────────────────────────────────────────────────────
+export {
+  verifyAIDSignature, selfSignAID,
+  signManifest, verifyManifest,
+  buildAgexHeaders, signRequest, verifyRequest,
+  AgexError,
+  AGEX_VERSION, AUDIT_EVENTS
+} from './protocol/index.js'
+
+// ── Policy Engine ─────────────────────────────────────────────────────────
+export { evaluatePolicy, evaluateCondition } from './policy/index.js'

package/src/policy/index.js

@@ -0,0 +1,133 @@
+/**
+ * @agexhq/core — AGEX Policy Language (APL) Evaluation Engine
+ * Deterministic, stateless policy evaluation
+ */
+
+export function evaluatePolicy (policy, aid, manifest) {
+  const rules = [...(policy.rules || [])].sort((a, b) => (a.priority || 99) - (b.priority || 99))
+
+  for (const rule of rules) {
+    const matched = evaluateCondition(rule.condition, aid, manifest)
+    if (matched) {
+      return {
+        action: rule.action,
+        rule_id: rule.rule_id,
+        reason: rule.description || `Matched rule: ${rule.rule_id}`
+      }
+    }
+  }
+
+  return {
+    action: policy.default_action || 'reject',
+    reason: 'No rules matched; applying default_action'
+  }
+}
+
+export function evaluateCondition (condition, aid, manifest) {
+  if (!condition) return true
+
+  switch (condition.type) {
+
+    case 'trust_tier': {
+      const tier = typeof aid.trust_tier === 'number' ? aid.trust_tier : parseInt(aid.trust_tier)
+      switch (condition.operator) {
+        case 'gte': return tier >= condition.value
+        case 'lte': return tier <= condition.value
+        case 'eq': return tier === condition.value
+        case 'gt': return tier > condition.value
+        case 'lt': return tier < condition.value
+        default: return false
+      }
+    }
+
+    case 'scope': {
+      const requested = manifest.target?.requested_scopes || []
+      if (condition.operator === 'contains_any') {
+        return condition.values.some(s => requested.includes(s))
+      }
+      if (condition.operator === 'contains_all') {
+        return condition.values.every(s => requested.includes(s))
+      }
+      if (condition.operator === 'subset_of') {
+        return requested.every(s => condition.values.includes(s))
+      }
+      return false
+    }
+
+    case 'intent_type': {
+      const taskType = manifest.intent?.task_type
+      if (condition.operator === 'eq') return taskType === condition.value
+      if (condition.operator === 'in') return (condition.values || []).includes(taskType)
+      return false
+    }
+
+    case 'data_classification': {
+      const dc = manifest.intent?.data_classification
+      const levels = ['public', 'internal', 'confidential', 'restricted']
+      const reqLevel = levels.indexOf(dc)
+      const condLevel = levels.indexOf(condition.value)
+      if (condition.operator === 'lte') return reqLevel <= condLevel
+      if (condition.operator === 'gte') return reqLevel >= condLevel
+      if (condition.operator === 'eq') return reqLevel === condLevel
+      return false
+    }
+
+    case 'pii_processing':
+      return manifest.data_handling?.pii_processing === condition.value
+
+    case 'environment': {
+      const env = manifest.target?.environment
+      if (condition.operator === 'eq') return env === condition.value
+      if (condition.operator === 'in') return (condition.values || []).includes(env)
+      return false
+    }
+
+    case 'time_window': {
+      const now = new Date()
+      const hour = now.getUTCHours()
+      const day = now.getUTCDay()
+      const inHours = hour >= (condition.start_hour || 0) && hour < (condition.end_hour || 24)
+      const inDays = !condition.days_of_week ||
+        condition.days_of_week.includes(['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'][day])
+      return inHours && inDays
+    }
+
+    // FIX: audit 2.6 — clarified geography semantics
+    case 'geography': {
+      const agentJurisdiction = aid.agent?.principal?.jurisdiction ||
+        (typeof aid.restrictions === 'string' ? JSON.parse(aid.restrictions) : aid.restrictions)?.geo_restrictions?.[0]
+      const allowedRegions = (typeof aid.restrictions === 'string' ? JSON.parse(aid.restrictions) : aid.restrictions)?.geo_restrictions || []
+
+      if (condition.operator === 'agent_in') {
+        return condition.values.includes(agentJurisdiction)
+      }
+      if (condition.operator === 'agent_not_in') {
+        return !condition.values.includes(agentJurisdiction)
+      }
+      if (condition.operator === 'restricted_to') {
+        return condition.values.every(v => allowedRegions.includes(v))
+      }
+      // Backwards compat with old in/not_in operators
+      if (condition.operator === 'in') {
+        return condition.values.some(v => allowedRegions.includes(v))
+      }
+      if (condition.operator === 'not_in') {
+        return !condition.values.some(v => allowedRegions.includes(v))
+      }
+      return false
+    }
+
+    case 'and':
+      return (condition.conditions || []).every(c => evaluateCondition(c, aid, manifest))
+
+    case 'or':
+      return (condition.conditions || []).some(c => evaluateCondition(c, aid, manifest))
+
+    case 'not':
+      return !evaluateCondition(condition.condition, aid, manifest)
+
+    default:
+      console.warn(`[APL] Unknown condition type: ${condition.type}`)
+      return false
+  }
+}

package/src/protocol/index.js

@@ -0,0 +1,107 @@
+/**
+ * @agexhq/core — Protocol operations
+ * AID verification, manifest signing, AGEX header construction
+ */
+
+import { sign, verify, canonicalJson, generateId } from '../crypto/keys.js'
+
+// ── AID Signature Verification (FIX: audit 1.1) ──────────────────────────
+// ALWAYS verifies — never silently bypasses
+
+export async function verifyAIDSignature (aid, iaPublicKeyJWK) {
+  if (!iaPublicKeyJWK) {
+    throw new AgexError('IA_KEY_REQUIRED', 'IA public key required for AID verification', 400)
+  }
+  const { ia_signature, ...aidBody } = aid
+  const canonical = canonicalJson(aidBody)
+  const valid = await verify(canonical, ia_signature, iaPublicKeyJWK)
+  if (!valid) {
+    throw new AgexError('IA_SIGNATURE_INVALID', 'AID ia_signature failed verification', 401)
+  }
+  return true
+}
+
+/**
+ * Self-sign an AID using the Hub's own key (dev/self-signed IA mode).
+ * The AID is still cryptographically signed — just by the hub instead of an external IA.
+ */
+export async function selfSignAID (aidBody, hubPrivateKey) {
+  const { ia_signature, ...body } = aidBody
+  const canonical = canonicalJson(body)
+  const signature = await sign(canonical, hubPrivateKey)
+  return { ...body, ia_signature: signature }
+}
+
+// ── Manifest Signing (FIX: audit 1.3) ─────────────────────────────────────
+// Real Ed25519 signatures instead of placeholder strings
+
+export async function signManifest (manifest, privateKey) {
+  const { agent_signature, ...body } = manifest
+  const canonical = canonicalJson(body)
+  return await sign(canonical, privateKey)
+}
+
+export async function verifyManifest (manifest, publicKeyJWK) {
+  const { agent_signature, ...body } = manifest
+  if (!agent_signature || agent_signature === 'sdk-placeholder') return false
+  const canonical = canonicalJson(body)
+  return await verify(canonical, agent_signature, publicKeyJWK)
+}
+
+// ── AGEX Request Headers ──────────────────────────────────────────────────
+
+export function buildAgexHeaders (aidId, version = '1.0') {
+  return {
+    'X-AGEX-Version': version,
+    'X-AGEX-Request-ID': generateId(),
+    'X-AGEX-Timestamp': new Date().toISOString(),
+    'X-AGEX-AID': aidId
+  }
+}
+
+export async function signRequest (body, timestamp, requestId, privateKey) {
+  const bodyStr = body ? canonicalJson(body) : ''
+  const sigInput = `${bodyStr}|${timestamp}|${requestId}`
+  return await sign(sigInput, privateKey)
+}
+
+export async function verifyRequest (body, timestamp, requestId, signature, publicKeyJWK) {
+  const bodyStr = body ? canonicalJson(body) : ''
+  const sigInput = `${bodyStr}|${timestamp}|${requestId}`
+  return await verify(sigInput, signature, publicKeyJWK)
+}
+
+// ── Error class ───────────────────────────────────────────────────────────
+
+export class AgexError extends Error {
+  constructor (code, message, statusCode = 400) {
+    super(message)
+    this.name = 'AgexError'
+    this.code = code
+    this.statusCode = statusCode
+  }
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────
+
+export const AGEX_VERSION = '1.0'
+
+export const AUDIT_EVENTS = {
+  AID_REGISTERED: 'aid.registered',
+  AID_REVOKED: 'aid.revoked',
+  CREDENTIAL_REQUESTED: 'credential.requested',
+  CREDENTIAL_ISSUED: 'credential.issued',
+  CREDENTIAL_REJECTED: 'credential.rejected',
+  CREDENTIAL_PENDING: 'credential.pending_approval',
+  ROTATION_INITIATED: 'rotation.initiated',
+  ROTATION_COMPLETED: 'rotation.completed',
+  ROTATION_FAILED: 'rotation.failed',
+  DELEGATION_CREATED: 'delegation.created',
+  ERS_INITIATED: 'ers.initiated',
+  ERS_COMPLETED: 'ers.completed',
+  CLC_REVOKED: 'clc.revoked',
+  CLC_SUSPENDED: 'clc.suspended',
+  CLC_RESUMED: 'clc.resumed',
+  APPROVAL_GRANTED: 'approval.granted',
+  APPROVAL_REJECTED: 'approval.rejected'
+}

package/src/schemas/index.js

@@ -0,0 +1,153 @@
+/**
+ * @agexhq/core — Zod schemas for all AGEX protocol objects
+ * Single source of truth — used by hub, SDK, and CLI
+ */
+
+import { z } from 'zod'
+
+// ── AID Schema (Agent Identity Document) ──────────────────────────────────
+
+export const AIDSchema = z.object({
+  aid_version: z.literal('1.0'),
+  aid_id: z.string().uuid(),
+  issuer: z.object({
+    ia_id: z.string(),
+    ia_name: z.string(),
+    ia_cert_id: z.string()
+  }),
+  issued_at: z.string().datetime(),
+  expires_at: z.string().datetime(),
+  agent: z.object({
+    name: z.string().optional(),
+    type: z.enum(['orchestrator', 'worker', 'specialist', 'gateway']),
+    capabilities: z.array(z.string()).default([]),
+    principal: z.object({
+      organisation: z.string(),
+      org_id: z.string(),
+      contact: z.string().email(),
+      jurisdiction: z.string()
+    })
+  }),
+  trust_tier: z.number().int().min(0).max(3),
+  public_key: z.object({ kty: z.string(), crv: z.string(), x: z.string() }),
+  restrictions: z.object({
+    allowed_services: z.array(z.string()).optional(),
+    max_clc_duration_seconds: z.number().int().optional(),
+    max_delegation_depth: z.number().int().min(0).max(5).optional(),
+    geo_restrictions: z.array(z.string()).optional()
+  }).default({}),
+  ia_signature: z.string()
+})
+
+// ── Intent Manifest Schema ────────────────────────────────────────────────
+
+export const ManifestSchema = z.object({
+  manifest_version: z.literal('1.0'),
+  manifest_id: z.string().uuid(),
+  requesting_aid: z.string().uuid(),
+  target: z.object({
+    service_id: z.string(),
+    requested_scopes: z.array(z.string()).min(1),
+    minimum_scopes: z.array(z.string()).optional(),
+    environment: z.enum(['production', 'staging', 'development']).default('production')
+  }),
+  intent: z.object({
+    summary: z.string().max(500),
+    task_type: z.enum(['read', 'write', 'read_write', 'admin', 'transact', 'notify']),
+    data_classification: z.enum(['public', 'internal', 'confidential', 'restricted']).default('internal'),
+    automated: z.boolean().default(true),
+    reversible: z.boolean().default(true),
+    human_visible: z.boolean().default(false)
+  }),
+  duration: z.object({
+    max_duration_seconds: z.number().int().min(60).max(604800),
+    idle_timeout_seconds: z.number().int().min(60).default(3600)
+  }),
+  data_handling: z.object({
+    pii_processing: z.boolean().default(false),
+    cross_border_transfer: z.boolean().default(false),
+    deletion_on_completion: z.boolean().default(false)
+  }).default({}),
+  agent_signature: z.string()
+})
+
+// ── CLC Schema (Credential Lifecycle Contract) ────────────────────────────
+
+export const CLCSchema = z.object({
+  clc_version: z.literal('1.0'),
+  clc_id: z.string().uuid(),
+  beneficiary_aid: z.string().uuid(),
+  manifest_id: z.string().uuid(),
+  manifest_hash: z.string(),
+  credential_envelope: z.object({
+    algorithm: z.string(),
+    epk: z.object({ kty: z.string(), crv: z.string(), x: z.string() }),
+    ciphertext: z.string(),
+    nonce: z.string(),
+    tag: z.string()
+  }),
+  granted_scopes: z.array(z.string()),
+  scope_ceiling: z.array(z.string()),
+  validity: z.object({
+    not_before: z.string().datetime(),
+    not_after: z.string().datetime(),
+    idle_timeout_seconds: z.number().int().default(3600)
+  }),
+  rotation_policy: z.object({
+    rotation_interval_seconds: z.number().int(),
+    rotation_overlap_seconds: z.number().int(),
+    key_derivation_function: z.string().default('HKDF-SHA256')
+  }),
+  delegation_policy: z.object({
+    delegation_permitted: z.boolean(),
+    max_delegation_depth: z.number().int().min(0).max(5),
+    max_further_delegation: z.number().int().min(0).default(0)
+  }),
+  chain_provenance: z.array(z.string()).default([]),
+  provider_signature: z.string(),
+  hub_binding: z.object({
+    hub_id: z.string(),
+    hub_signature: z.string()
+  })
+})
+
+// ── Service Provider Schema (NEW — fixes audit 3.1) ──────────────────────
+
+export const ServiceProviderSchema = z.object({
+  sp_id: z.string().min(1).max(128).regex(/^[a-z0-9][a-z0-9._-]*$/, 'sp_id must be lowercase alphanumeric with dots/hyphens/underscores'),
+  sp_name: z.string().min(1).max(256),
+  service_url: z.string().url(),
+  credential_endpoint: z.string().url(),
+  policy_endpoint: z.string().url().optional(),
+  public_key_jwk: z.object({ kty: z.string(), crv: z.string(), x: z.string() }),
+  supported_scopes: z.array(z.string()).default([])
+})
+
+// ── APL Policy Schema ─────────────────────────────────────────────────────
+
+export const PolicyConditionSchema = z.lazy(() => z.discriminatedUnion('type', [
+  z.object({ type: z.literal('trust_tier'), operator: z.enum(['eq', 'gt', 'gte', 'lt', 'lte']), value: z.number() }),
+  z.object({ type: z.literal('scope'), operator: z.enum(['contains_any', 'contains_all', 'subset_of']), values: z.array(z.string()) }),
+  z.object({ type: z.literal('intent_type'), operator: z.enum(['eq', 'in']), value: z.string().optional(), values: z.array(z.string()).optional() }),
+  z.object({ type: z.literal('data_classification'), operator: z.enum(['eq', 'gte', 'lte']), value: z.string() }),
+  z.object({ type: z.literal('pii_processing'), value: z.boolean() }),
+  z.object({ type: z.literal('environment'), operator: z.enum(['eq', 'in']), value: z.string().optional(), values: z.array(z.string()).optional() }),
+  z.object({ type: z.literal('time_window'), start_hour: z.number().optional(), end_hour: z.number().optional(), days_of_week: z.array(z.string()).optional() }),
+  z.object({ type: z.literal('geography'), operator: z.enum(['agent_in', 'agent_not_in', 'restricted_to']), values: z.array(z.string()) }),
+  z.object({ type: z.literal('and'), conditions: z.array(PolicyConditionSchema) }),
+  z.object({ type: z.literal('or'), conditions: z.array(PolicyConditionSchema) }),
+  z.object({ type: z.literal('not'), condition: PolicyConditionSchema }),
+]))
+
+export const PolicyRuleSchema = z.object({
+  rule_id: z.string(),
+  priority: z.number().int().default(99),
+  condition: PolicyConditionSchema.optional(),
+  action: z.enum(['approve', 'reject', 'review']),
+  description: z.string().optional()
+})
+
+export const PolicyDocSchema = z.object({
+  rules: z.array(PolicyRuleSchema),
+  default_action: z.enum(['approve', 'reject', 'review']).default('reject')
+})