ajp-protocol 0.1.0 → 0.2.2

package/src/trust.js

@@ -0,0 +1,205 @@
+/**
+ * AJP — sender trust resolution
+ *
+ * Establishing who sent a job splits into two questions, and only one of them
+ * needs a network service:
+ *
+ *   1. IDENTITY — is this signature really from the party named in `from`?
+ *      Answerable offline. The sender's declaration carries its public key and
+ *      is itself signed; verifying it against the location it claims binds the
+ *      key to the identity with no third party involved.
+ *
+ *   2. STANDING — is that party currently in good order? Revoked, open
+ *      incidents, stale evidence. NOT answerable offline: absence of news
+ *      cannot be carried in a document. This requires asking someone, and who
+ *      to ask is the receiver's choice.
+ *
+ * Earlier versions collapsed both into one call to a single index, which made
+ * even the cryptography depend on one company's uptime. These resolvers keep
+ * them apart: identity never calls out to an index, and standing is opt-in.
+ */
+
+import { verifyDeclaration, keyFingerprint } from 'provenance-protocol/verify';
+
+/** Thrown when a sender's identity cannot be established. */
+export class SenderIdentityError extends Error {
+  constructor(message, code = 'SENDER_IDENTITY_FAILED') {
+    super(message);
+    this.name = 'SenderIdentityError';
+    this.code = code;
+  }
+}
+
+const MAX_DECLARATION_BYTES = 64 * 1024;
+const FETCH_TIMEOUT_MS = 8000;
+
+/**
+ * Resolve a sender's public key from its own declaration, with no index.
+ *
+ * The sender points at where its declaration lives (`from.declaration_url`).
+ * Hosting a copy elsewhere does not help an impostor: the declaration names
+ * its own provenance id, and a declaration served from a location that does
+ * not match that id is rejected. Forging one is not possible without the
+ * genuine private key.
+ *
+ * @param {object} [options]
+ * @param {(url: string) => Promise<string>} [options.fetchText]  Override for tests.
+ * @param {Map<string,string>} [options.knownKeys]  provenanceId -> key fingerprint
+ *   seen before. A different key later is a rotation, and by default a
+ *   rotation is refused rather than silently accepted.
+ * @param {boolean} [options.allowKeyRotation]  Accept a changed key (default false).
+ * @param {(declaration: string) => unknown} [options.parseDeclaration]  YAML parser.
+ *   Declarations are YAML; AJP has no YAML dependency, so supply one to accept
+ *   YAML declarations. Without it, only JSON declarations are read.
+ * @returns {(provenanceId: string, from: object) => Promise<{publicKey: string, fingerprint: string, source: string}>}
+ */
+export function declarationKeyResolver(options = {}) {
+  const {
+    fetchText = defaultFetchText,
+    knownKeys,
+    allowKeyRotation = false,
+    parseDeclaration,
+  } = options;
+
+  return async function resolve(provenanceId, from = {}) {
+    const url = from.declaration_url;
+    if (!url) {
+      throw new SenderIdentityError(
+        'Sender did not provide from.declaration_url, so its key cannot be established offline',
+        'NO_DECLARATION_URL'
+      );
+    }
+
+    let text;
+    try {
+      text = await fetchText(url);
+    } catch (e) {
+      throw new SenderIdentityError(`Could not fetch sender declaration: ${e.message}`, 'DECLARATION_UNREACHABLE');
+    }
+
+    let declaration;
+    try {
+      declaration = parseDeclaration ? parseDeclaration(text) : JSON.parse(text);
+    } catch {
+      throw new SenderIdentityError(
+        parseDeclaration
+          ? 'Sender declaration could not be parsed'
+          : 'Sender declaration is not JSON; pass parseDeclaration to accept YAML',
+        'DECLARATION_UNPARSEABLE'
+      );
+    }
+
+    // Verifies the signature against the key inside the file AND that the file
+    // was served from the location its own provenance id names.
+    const result = await verifyDeclaration(declaration, { retrievedFrom: url });
+
+    if (!result.valid) {
+      throw new SenderIdentityError(
+        `Sender declaration did not verify: ${result.reason ?? 'unknown reason'}`,
+        'DECLARATION_INVALID'
+      );
+    }
+    if (result.location !== 'match') {
+      throw new SenderIdentityError(
+        'Sender declaration was not served from the location its provenance id names',
+        'DECLARATION_LOCATION_MISMATCH'
+      );
+    }
+    if (result.provenanceId !== provenanceId) {
+      throw new SenderIdentityError(
+        `Sender declaration is for ${result.provenanceId}, not ${provenanceId}`,
+        'DECLARATION_ID_MISMATCH'
+      );
+    }
+
+    if (knownKeys) {
+      const seen = knownKeys.get(provenanceId);
+      if (seen && seen !== result.fingerprint && !allowKeyRotation) {
+        throw new SenderIdentityError(
+          'Sender is signing with a different key than previously seen — treat as key rotation, not as a routine update',
+          'KEY_ROTATED'
+        );
+      }
+      if (!seen) knownKeys.set(provenanceId, result.fingerprint);
+    }
+
+    return { publicKey: result.publicKey, fingerprint: result.fingerprint, source: url };
+  };
+}
+
+/**
+ * Resolve a sender's key from a Provenance index instead of its declaration.
+ *
+ * Kept for receivers that already trust an index and prefer one lookup to a
+ * fetch — but note this makes identity verification depend on that service
+ * being reachable, which `declarationKeyResolver` does not.
+ *
+ * @param {object} provenanceClient  An instance of Provenance from provenance-protocol
+ */
+export function indexKeyResolver(provenanceClient) {
+  return async function resolve(provenanceId) {
+    const profile = await provenanceClient.check(provenanceId).catch(() => null);
+    if (!profile?.found) {
+      throw new SenderIdentityError('Sender not found in the index', 'SENDER_NOT_INDEXED');
+    }
+    if (!profile.public_key) {
+      throw new SenderIdentityError('Sender has no public key in the index', 'NO_PUBLIC_KEY');
+    }
+    const fingerprint = await keyFingerprint(profile.public_key).catch(() => null);
+    return { publicKey: profile.public_key, fingerprint, source: 'index' };
+  };
+}
+
+/**
+ * Try resolvers in order and use the first that succeeds.
+ *
+ * The useful arrangement is offline first, index second: identity is
+ * established without a network service whenever the sender supports it, and
+ * the index is a fallback rather than a requirement.
+ */
+export function firstResolver(...resolvers) {
+  const usable = resolvers.filter(Boolean);
+  return async function resolve(provenanceId, from) {
+    let last;
+    for (const resolver of usable) {
+      try {
+        return await resolver(provenanceId, from);
+      } catch (e) {
+        last = e;
+      }
+    }
+    throw last ?? new SenderIdentityError('No key resolver was configured', 'NO_RESOLVER');
+  };
+}
+
+/**
+ * Check a sender's current standing against a Provenance index.
+ *
+ * Opt-in on purpose. A receiver may use this, another attester, several, or
+ * none — standing is a policy question, not a protocol requirement.
+ *
+ * @param {object} provenanceClient   An instance of Provenance
+ * @param {object} [requirements]     Passed through to gate()
+ */
+export function indexStandingCheck(provenanceClient, requirements = {}) {
+  return async function check(provenanceId) {
+    const result = await provenanceClient.gate(provenanceId, requirements);
+    return { allowed: result.allowed, reason: result.reason ?? null, fallback: result.fallback ?? false };
+  };
+}
+
+async function defaultFetchText(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`Unsupported protocol: ${parsed.protocol}`);
+  }
+  const res = await fetch(url, {
+    redirect: 'error',
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    headers: { Accept: 'application/json, application/yaml, text/yaml, text/plain' },
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const text = await res.text();
+  if (text.length > MAX_DECLARATION_BYTES) throw new Error('declaration too large');
+  return text;
+}

package/src/utils.js

@@ -3,26 +3,33 @@
  * Consistent with provenance-protocol SDK conventions.
  */
 
-import crypto from 'crypto';
+import crypto, { createPrivateKey, createPublicKey, sign as nodeSign, verify as nodeVerify } from 'crypto';
 
 // ── Signing ───────────────────────────────────────────────────────────────
 
+/**
+ * Canonical form for signing — sorts keys, excludes `signature` field.
+ * Used by both HMAC and Ed25519 paths for consistency.
+ */
+function _canonical(body) {
+  const { signature: _, ...rest } = body;
+  return JSON.stringify(rest, Object.keys(rest).sort());
+}
+
 /**
  * Sign a message body with HMAC-SHA256.
- * Excludes the `signature` field from the hash input.
+ * Used for human callers (no Provenance identity).
  */
 export function sign(body, secret) {
-  const { signature: _, ...rest } = body;
-  const canonical = JSON.stringify(rest, Object.keys(rest).sort());
-  const hash = crypto.createHmac('sha256', secret).update(canonical).digest('hex');
+  const hash = crypto.createHmac('sha256', secret).update(_canonical(body)).digest('hex');
   return `sha256:${hash}`;
 }
 
 /**
- * Verify a signed message. Returns true if valid.
+ * Verify an HMAC-SHA256 signature. Returns true if valid.
  */
 export function verify(body, secret) {
-  if (!body.signature) return false;
+  if (!body.signature?.startsWith('sha256:')) return false;
   const expected = sign(body, secret);
   return crypto.timingSafeEqual(
     Buffer.from(body.signature),
@@ -30,16 +37,52 @@ export function verify(body, secret) {
   );
 }
 
+/**
+ * Sign a message body with Ed25519.
+ * Used by agents and orchestrators — consistent with provenance-protocol/keygen.js.
+ *
+ * @param {object} body             Message body (signature field excluded automatically)
+ * @param {string} privateKeyBase64 Base64 PKCS8 DER private key (PROVENANCE_PRIVATE_KEY)
+ * @returns {string}                Signature string: "ed25519:<base64>"
+ */
+export function signWithKey(body, privateKeyBase64) {
+  const privateKey = createPrivateKey({
+    key: Buffer.from(privateKeyBase64, 'base64'),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  const sig = nodeSign(null, Buffer.from(_canonical(body), 'utf8'), privateKey);
+  return `ed25519:${sig.toString('base64')}`;
+}
+
+/**
+ * Verify an Ed25519 signature using a public key from the Provenance index.
+ *
+ * @param {object} body            Message body including signature field
+ * @param {string} publicKeyBase64 Base64 SPKI DER public key (from Provenance profile)
+ * @returns {boolean}
+ */
+export function verifyWithKey(body, publicKeyBase64) {
+  if (!body.signature?.startsWith('ed25519:')) return false;
+  const publicKey = createPublicKey({
+    key: Buffer.from(publicKeyBase64, 'base64'),
+    format: 'der',
+    type: 'spki',
+  });
+  const sigBuffer = Buffer.from(body.signature.slice('ed25519:'.length), 'base64');
+  return nodeVerify(null, Buffer.from(_canonical(body), 'utf8'), publicKey, sigBuffer);
+}
+
 // ── Job ID generation ─────────────────────────────────────────────────────
 
 /**
  * Generate a unique job ID.
- * Format: job_ + timestamp_ms (base36) + random (base36)
+ * Format: job_ + timestamp_ms (base36) + cryptographically random suffix (base36)
  * Sortable, URL-safe, no external deps.
  */
 export function generateJobId() {
   const ts = Date.now().toString(36);
-  const rand = Math.random().toString(36).slice(2, 10);
+  const rand = crypto.randomBytes(6).toString('hex');
   return `job_${ts}${rand}`;
 }
 
@@ -51,10 +94,12 @@ export function generateJobId() {
  */
 export function validateOffer(offer) {
   const errors = [];
+  const warnings = [];
 
   if (!offer.ajp)          errors.push('missing: ajp');
   if (!offer.job_id)       errors.push('missing: job_id');
   if (!offer.from?.type)   errors.push('missing: from.type');
+  else if (!['human', 'agent', 'orchestrator'].includes(offer.from.type)) errors.push('from.type must be human, agent, or orchestrator');
   if (!offer.to?.provenance_id) errors.push('missing: to.provenance_id');
   if (!offer.task?.type)   errors.push('missing: task.type');
   if (!offer.task?.instruction) errors.push('missing: task.instruction');
@@ -65,6 +110,13 @@ export function validateOffer(offer) {
 
   if (offer.from?.type === 'agent' || offer.from?.type === 'orchestrator') {
     if (!offer.from.provenance_id) errors.push('from.provenance_id required when type is agent/orchestrator');
+    // declaration_url is optional on purpose — a receiver configured with an
+    // index resolver does not need it. But without it, that receiver cannot
+    // establish this sender's key without consulting a third party, so the
+    // offer may be refused. Surfaced as a warning, never a validation failure.
+    if (!offer.from.declaration_url) {
+      warnings.push('from.declaration_url absent — receivers cannot verify this sender offline and may refuse the offer');
+    }
   }
 
   // Check expiry
@@ -72,7 +124,7 @@ export function validateOffer(offer) {
     errors.push('offer has expired');
   }
 
-  return { valid: errors.length === 0, errors };
+  return { valid: errors.length === 0, errors, warnings };
 }
 
 // ── Status helpers ────────────────────────────────────────────────────────

package/test/trust.test.mjs

@@ -0,0 +1,88 @@
+import { generateProvenanceKeyPair, signForProvenance } from 'provenance-protocol/keygen';
+import { declarationKeyResolver, SenderIdentityError } from '../src/trust.js';
+
+let pass = 0, fail = 0;
+const t = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : '  ' + detail}`);
+  ok ? pass++ : fail++;
+};
+
+// Alice publishes a signed declaration in her own repo.
+const ALICE = 'provenance:github:alice/research-agent';
+const alice = generateProvenanceKeyPair();
+const aliceDecl = {
+  provenance: '0.1', name: 'Research Agent', description: 'Searches and summarises.',
+  provenance_id: ALICE,
+  identity: {
+    public_key: alice.publicKey,
+    signature: signForProvenance(alice.privateKey, ALICE, alice.publicKey),
+    algorithm: 'ed25519',
+  },
+};
+const ALICE_URL = 'https://raw.githubusercontent.com/alice/research-agent/main/PROVENANCE.json';
+
+// A fake network: url -> body
+const net = new Map([[ALICE_URL, JSON.stringify(aliceDecl)]]);
+const fetchText = async (url) => {
+  if (!net.has(url)) throw new Error('404');
+  return net.get(url);
+};
+
+const resolve = declarationKeyResolver({ fetchText });
+
+// 1. Honest sender resolves offline, no index anywhere.
+const ok1 = await resolve(ALICE, { declaration_url: ALICE_URL });
+t('honest sender resolves offline', ok1.publicKey === alice.publicKey && !!ok1.fingerprint);
+
+// 2. No declaration_url -> refused with a specific code.
+try { await resolve(ALICE, {}); t('missing declaration_url refused', false); }
+catch (e) { t('missing declaration_url refused', e.code === 'NO_DECLARATION_URL', e.code); }
+
+// 3. Impostor re-hosts Alice's genuine declaration on their own server.
+const EVIL_URL = 'https://evil.example/copied/PROVENANCE.json';
+net.set(EVIL_URL, JSON.stringify(aliceDecl));
+try { await resolve(ALICE, { declaration_url: EVIL_URL }); t('re-hosted declaration refused', false); }
+catch (e) { t('re-hosted declaration refused', e.code === 'DECLARATION_LOCATION_MISMATCH', e.code); }
+
+// 4. Impostor forges their own key under Alice's id.
+const evil = generateProvenanceKeyPair();
+const forged = { ...aliceDecl, identity: {
+  public_key: evil.publicKey,
+  signature: signForProvenance(evil.privateKey, ALICE, evil.publicKey),
+  algorithm: 'ed25519' } };
+const FORGED_URL = 'https://raw.githubusercontent.com/evil/fork/main/PROVENANCE.json';
+net.set(FORGED_URL, JSON.stringify(forged));
+try { await resolve(ALICE, { declaration_url: FORGED_URL }); t('forged key at wrong location refused', false); }
+catch (e) { t('forged key at wrong location refused', e.code === 'DECLARATION_LOCATION_MISMATCH', e.code); }
+
+// 5. Tampered declaration (constraints added after signing) fails verification.
+const tampered = { ...aliceDecl, provenance_id: 'provenance:github:alice/research-agent' , identity: { ...aliceDecl.identity, public_key: evil.publicKey } };
+net.set('https://raw.githubusercontent.com/alice/research-agent/main/TAMPERED.json', JSON.stringify(tampered));
+try {
+  await resolve(ALICE, { declaration_url: 'https://raw.githubusercontent.com/alice/research-agent/main/TAMPERED.json' });
+  t('tampered declaration refused', false);
+} catch (e) { t('tampered declaration refused', e.code === 'DECLARATION_INVALID', e.code); }
+
+// 6. Key rotation is flagged, not silently accepted.
+const known = new Map();
+const pinning = declarationKeyResolver({ fetchText, knownKeys: known });
+await pinning(ALICE, { declaration_url: ALICE_URL });
+const rotated = generateProvenanceKeyPair();
+net.set(ALICE_URL, JSON.stringify({ ...aliceDecl, identity: {
+  public_key: rotated.publicKey,
+  signature: signForProvenance(rotated.privateKey, ALICE, rotated.publicKey),
+  algorithm: 'ed25519' } }));
+try { await pinning(ALICE, { declaration_url: ALICE_URL }); t('key rotation refused by default', false); }
+catch (e) { t('key rotation refused by default', e.code === 'KEY_ROTATED', e.code); }
+
+// 7. Rotation accepted when explicitly allowed.
+const allowing = declarationKeyResolver({ fetchText, knownKeys: new Map([[ALICE, 'old']]), allowKeyRotation: true });
+const ok7 = await allowing(ALICE, { declaration_url: ALICE_URL });
+t('rotation accepted when allowed', ok7.publicKey === rotated.publicKey);
+
+// 8. Unreachable declaration is its own error, distinct from invalid.
+try { await resolve(ALICE, { declaration_url: 'https://nowhere.example/x.json' }); t('unreachable is distinct from invalid', false); }
+catch (e) { t('unreachable is distinct from invalid', e.code === 'DECLARATION_UNREACHABLE', e.code); }
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);