ajp-protocol 0.2.1 → 0.3.0

package/src/client.js

@@ -6,7 +6,7 @@
  */
 
 import { sign, signWithKey, generateJobId, validateOffer } from './utils.js';
-import { Provenance } from 'provenance-protocol';
+import { declarationEndpointResolver } from './trust.js';
 
 export class AJPClient {
 
@@ -24,15 +24,25 @@ export class AJPClient {
    *                                           Required for agent/orchestrator senders. Allows any
    *                                           indexed agent to call any other without a shared secret.
    * @param {string} [opts.secret]           — HMAC secret. Required for human senders only.
-   * @param {string} [opts.provenanceApiUrl] — override Provenance API URL
+   * @param {function} [opts.resolveEndpoint] — async (provenanceId) => endpoint base URL.
+   *        Defaults to reading `ajp.endpoint` from the recipient's own signed
+   *        declaration, verified offline. No index is consulted unless you
+   *        pass indexEndpointResolver.
    * @param {number} [opts.defaultTimeoutMs] — default job timeout in ms (30s)
    */
-  constructor({ from, privateKey, secret, provenanceApiUrl, defaultTimeoutMs = 30000 }) {
+  constructor({ from, privateKey, secret, resolveEndpoint, defaultTimeoutMs = 30000, ...rest }) {
+    if ('provenanceApiUrl' in rest) {
+      // Ignoring it would silently change where jobs are routed.
+      throw new Error(
+        'provenanceApiUrl was removed in ajp-protocol 0.3: recipients are resolved from their own declarations. ' +
+        'To use an index, pass resolveEndpoint: indexEndpointResolver(new Provenance({ apiUrl })).'
+      );
+    }
     this.from = from;
     this.privateKey = privateKey || null;
     this.secret = secret || null;
     this.defaultTimeoutMs = defaultTimeoutMs;
-    this.provenance = new Provenance({ apiUrl: provenanceApiUrl });
+    this.resolveEndpoint = resolveEndpoint ?? declarationEndpointResolver();
 
     if (from.type === 'agent' || from.type === 'orchestrator') {
       if (!from.provenance_id) throw new Error('from.provenance_id required when type is agent or orchestrator');
@@ -56,11 +66,13 @@ export class AJPClient {
    * @param {object} [opts.context]      — { credentials?, memory?, constraints? }
    * @param {object} [opts.callback]     — { url, headers? } for async delivery
    * @param {number} [opts.pollIntervalMs] — how often to poll for result (2000)
+   * @param {string} [opts.endpoint]     — send here instead of resolving the recipient
    * @returns {Promise<JobResult>}
    */
   async send(toProvenanceId, task, budget = {}, opts = {}) {
-    // Resolve the agent's AJP endpoint from Provenance
-    const endpoint = await this._resolveEndpoint(toProvenanceId);
+    const endpoint = opts.endpoint
+      ? opts.endpoint.replace(/\/$/, '')
+      : await this.resolveEndpoint(toProvenanceId);
 
     // Build the job offer
     const jobId = generateJobId();
@@ -188,29 +200,5 @@ export class AJPClient {
     throw new Error(`Job timed out after ${timeoutMs}ms`);
   }
 
-  // ── Endpoint resolution ───────────────────────────────────────────────
-
-  async _resolveEndpoint(provenanceId) {
-    try {
-      const profile = await this.provenance.check(provenanceId);
-      if (!profile.found) throw new Error(`Agent not found in Provenance index: ${provenanceId}`);
-
-      // AJP endpoint is stored in the agent's PROVENANCE.yml
-      const endpoint = profile.provenance_yml?.ajp?.endpoint;
-      if (endpoint) return endpoint.replace(/\/$/, '');
-
-      // Fallback: derive from agent URL — unreliable, agent should declare ajp.endpoint in PROVENANCE.yml
-      if (profile.url) {
-        console.warn(`[AJP] No ajp.endpoint declared for ${provenanceId} — falling back to ${profile.url}/api/agent. Add ajp.endpoint to PROVENANCE.yml for reliability.`);
-        return `${profile.url.replace(/\/$/, '')}/api/agent`;
-      }
-
-      throw new Error(`No AJP endpoint found for ${provenanceId}`);
-    } catch (e) {
-      if (e.message.includes('No AJP endpoint')) throw e;
-      throw new Error(`Could not resolve endpoint for ${provenanceId}: ${e.message}`);
-    }
-  }
-
   _sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 }

package/src/index.js

@@ -2,7 +2,8 @@
  * ajp-protocol
  *
  * The Agent Job Protocol — standard interaction layer for the agent internet.
- * Part of the Provenance Protocol family.
+ * Builds on the Provenance Protocol: identities are provenance ids, and both
+ * sides find and verify each other from their own signed declarations.
  *
  * npm install ajp-protocol
  *
@@ -21,10 +22,13 @@
 
 export { AJPClient } from './client.js';
 export { AJPServer } from './server.js';
-export { sign, verify, generateJobId, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
+export { sign, verify, signWithKey, verifyWithKey, generateJobId, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
 export {
   declarationKeyResolver,
+  declarationEndpointResolver,
   indexKeyResolver,
+  indexEndpointResolver,
+  RecipientResolutionError,
   firstResolver,
   indexStandingCheck,
   SenderIdentityError,

package/src/server.js

@@ -6,8 +6,7 @@
  * Express, Next.js API routes, Fastify, or any Node HTTP framework.
  */
 
-import { verify, verifyWithKey, sign, signWithKey, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
-import { Provenance } from 'provenance-protocol';
+import { verify, verifyWithKey, isLegacySignature, sign, signWithKey, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
 import { declarationKeyResolver, SenderIdentityError } from './trust.js';
 
 export class AJPServer {
@@ -37,7 +36,6 @@ export class AJPServer {
    * @param {string[]} [opts.constraints]    — constraints this agent honors (from PROVENANCE.yml).
    *                                           Included as `constraints_asserted` in every signed JobResult,
    *                                           creating a cryptographic receipt tied to the registered identity.
-   * @param {string} [opts.provenanceApiUrl] — override Provenance API URL
    */
   constructor({
     provenanceId,
@@ -46,11 +44,17 @@ export class AJPServer {
     onJob,
     constraints = [],
     trustRequirements = {},
-    provenanceApiUrl,
     resolveSenderKey,
     checkStanding,
     onStandingUnavailable = 'deny',
+    ...rest
   }) {
+    if ('provenanceApiUrl' in rest) {
+      throw new Error(
+        'provenanceApiUrl was removed in ajp-protocol 0.3: sender keys come from their own declarations. ' +
+        'To use an index, pass resolveSenderKey / checkStanding built from new Provenance({ apiUrl }).'
+      );
+    }
     if (!privateKey) throw new Error('privateKey (PROVENANCE_PRIVATE_KEY) required — used to sign job results');
     this.provenanceId = provenanceId;
     this.privateKey = privateKey;
@@ -58,13 +62,24 @@ export class AJPServer {
     this.onJob = onJob;
     this.constraints = constraints;
     this.trustRequirements = trustRequirements;
-    this.provenance = new Provenance({ apiUrl: provenanceApiUrl });
     // Identity resolution never touches an index by default: a signature check
     // that depends on someone's web service being up is not a signature check.
     this.resolveSenderKey = resolveSenderKey ?? declarationKeyResolver();
     this.checkStanding = checkStanding ?? null;
     this.onStandingUnavailable = onStandingUnavailable;
 
+    // Requirements about standing (incidents, age) can only be answered by
+    // someone you ask. Accepting them with nobody to ask would ignore them
+    // while looking configured, so refuse at startup instead.
+    const needsStanding = ['requireClean', 'requireMinAge', 'requireMinConfidence', 'requireVerified']
+      .filter((k) => trustRequirements[k]);
+    if (needsStanding.length && !this.checkStanding) {
+      throw new Error(
+        `trustRequirements.${needsStanding.join(', ')} need a standing source: pass checkStanding ` +
+        '(e.g. indexStandingCheck(new Provenance({ apiUrl }))), or remove them.'
+      );
+    }
+
     // In-memory job store — replace with DB for production
     this.jobs = new Map();
   }
@@ -89,7 +104,7 @@ export class AJPServer {
             return this._json(res, 403, { error: 'This agent does not accept human callers' });
           }
           if (!verify(offer, this.secret)) {
-            return this._json(res, 401, { error: 'Invalid signature' });
+            return this._json(res, 401, this._badSignature(offer, { secret: this.secret }));
           }
         } else {
           // Agent/orchestrator callers: Ed25519. The key comes from whatever the
@@ -106,7 +121,28 @@ export class AJPServer {
             return this._json(res, 403, { error: 'Sender identity could not be established', reason: 'No public key resolved' });
           }
           if (!verifyWithKey(offer, sender.publicKey)) {
-            return this._json(res, 401, { error: 'Invalid signature' });
+            return this._json(res, 401, this._badSignature(offer, { publicKey: sender.publicKey }));
+          }
+
+          // Declared commitments are checked against the sender's own signed
+          // declaration when the resolver supplied one — no index needed. With
+          // no declaration and no standing source they cannot be checked at
+          // all, and are refused rather than skipped.
+          const { requireConstraints = [], requireCapabilities = [] } = this.trustRequirements;
+          if (requireConstraints.length || requireCapabilities.length) {
+            if (sender.declaration) {
+              const has = (list, v) => Array.isArray(list) && list.includes(v);
+              const missingC = requireConstraints.find((c) => !has(sender.declaration.constraints, c));
+              if (missingC) return this._json(res, 403, { error: 'Trust check failed', reason: `Sender has not committed to constraint: ${missingC}` });
+              const missingK = requireCapabilities.find((c) => !has(sender.declaration.capabilities, c));
+              if (missingK) return this._json(res, 403, { error: 'Trust check failed', reason: `Sender does not declare capability: ${missingK}` });
+            } else if (!this.checkStanding) {
+              return this._json(res, 403, {
+                error: 'Trust requirements could not be checked',
+                reason: 'No sender declaration was resolved and no standing source is configured',
+                code: 'REQUIREMENTS_UNCHECKABLE',
+              });
+            }
           }
         }
 
@@ -259,7 +295,7 @@ export class AJPServer {
       job.updated_at = job.completed_at;
       job.usage.duration_seconds = durationSeconds;
 
-      // Sign the result with Ed25519 — callers verify using this agent's public key from Provenance index.
+      // Sign the result with Ed25519 — callers verify it against the public key in this agent's declaration.
       // constraints_asserted is included in the signed payload — a cryptographic receipt of declared behavior.
       job.signature = signWithKey({
         job_id: job.job_id,
@@ -322,6 +358,17 @@ export class AJPServer {
     res.end(JSON.stringify(body));
   }
 
+  _badSignature(offer, keys) {
+    if (isLegacySignature(offer, keys)) {
+      return {
+        error: 'Invalid signature',
+        code: 'LEGACY_SIGNATURE',
+        reason: 'Signed by ajp-protocol < 0.3, whose signatures do not cover the job contents. The sender must upgrade.',
+      };
+    }
+    return { error: 'Invalid signature' };
+  }
+
   async _parseBody(req) {
     // Next.js App Router: req.json()
     if (typeof req.json === 'function') return req.json();

package/src/trust.js

@@ -19,7 +19,7 @@
  * them apart: identity never calls out to an index, and standing is opt-in.
  */
 
-import { verifyDeclaration, keyFingerprint } from 'provenance-protocol/verify';
+import { verifyDeclaration, keyFingerprint, locateDeclaration } from 'provenance-protocol/verify';
 
 /** Thrown when a sender's identity cannot be established. */
 export class SenderIdentityError extends Error {
@@ -36,7 +36,8 @@ 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`).
+ * The sender points at where its declaration lives (`from.declaration_url`),
+ * or — for domain and GitHub ids — the id itself names the standard location.
  * 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
@@ -51,7 +52,7 @@ const FETCH_TIMEOUT_MS = 8000;
  * @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}>}
+ * @returns {(provenanceId: string, from: object) => Promise<{publicKey: string, fingerprint: string, source: string, declaration: object}>}
  */
 export function declarationKeyResolver(options = {}) {
   const {
@@ -62,55 +63,17 @@ export function declarationKeyResolver(options = {}) {
   } = options;
 
   return async function resolve(provenanceId, from = {}) {
-    const url = from.declaration_url;
+    // The sender may say where its declaration is; otherwise its provenance id
+    // names the standard location.
+    const url = from.declaration_url || locateDeclaration(provenanceId);
     if (!url) {
       throw new SenderIdentityError(
-        'Sender did not provide from.declaration_url, so its key cannot be established offline',
+        'Sender gave no from.declaration_url and its provenance id has no standard location, 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'
-      );
-    }
+    const result = await fetchVerifiedDeclaration(url, provenanceId, { fetchText, parseDeclaration }, SenderIdentityError, 'Sender');
 
     if (knownKeys) {
       const seen = knownKeys.get(provenanceId);
@@ -123,7 +86,7 @@ export function declarationKeyResolver(options = {}) {
       if (!seen) knownKeys.set(provenanceId, result.fingerprint);
     }
 
-    return { publicKey: result.publicKey, fingerprint: result.fingerprint, source: url };
+    return { publicKey: result.publicKey, fingerprint: result.fingerprint, source: url, declaration: result.declaration };
   };
 }
 
@@ -134,7 +97,7 @@ export function declarationKeyResolver(options = {}) {
  * 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
+ * @param {object} provenanceClient  new Provenance({ apiUrl }) from provenance-protocol/index-client
  */
 export function indexKeyResolver(provenanceClient) {
   return async function resolve(provenanceId) {
@@ -178,7 +141,7 @@ export function firstResolver(...resolvers) {
  * 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} provenanceClient   new Provenance({ apiUrl }) from provenance-protocol/index-client
  * @param {object} [requirements]     Passed through to gate()
  */
 export function indexStandingCheck(provenanceClient, requirements = {}) {
@@ -188,6 +151,126 @@ export function indexStandingCheck(provenanceClient, requirements = {}) {
   };
 }
 
+/**
+ * Fetch a declaration, verify its signature, and confirm it was served from the
+ * location its own provenance id names and is for the agent expected.
+ * Throws `ErrorType` with a specific code for each way it can fail.
+ */
+async function fetchVerifiedDeclaration(url, provenanceId, { fetchText, parseDeclaration }, ErrorType, who) {
+  let text;
+  try {
+    text = await fetchText(url);
+  } catch (e) {
+    throw new ErrorType(`Could not fetch ${who.toLowerCase()} declaration: ${e.message}`, 'DECLARATION_UNREACHABLE');
+  }
+
+  let declaration;
+  try {
+    declaration = parseDeclaration ? parseDeclaration(text) : JSON.parse(text);
+  } catch {
+    throw new ErrorType(
+      parseDeclaration
+        ? `${who} declaration could not be parsed`
+        : `${who} 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 ErrorType(`${who} declaration did not verify: ${result.reason ?? 'unknown reason'}`, 'DECLARATION_INVALID');
+  }
+  if (result.location !== 'match') {
+    throw new ErrorType(`${who} declaration was not served from the location its provenance id names`, 'DECLARATION_LOCATION_MISMATCH');
+  }
+  if (result.provenanceId !== provenanceId) {
+    throw new ErrorType(`${who} declaration is for ${result.provenanceId}, not ${provenanceId}`, 'DECLARATION_ID_MISMATCH');
+  }
+  return { ...result, declaration };
+}
+
+/** Thrown when the agent a job is addressed to cannot be located. */
+export class RecipientResolutionError extends Error {
+  constructor(message, code = 'RECIPIENT_UNRESOLVED') {
+    super(message);
+    this.name = 'RecipientResolutionError';
+    this.code = code;
+  }
+}
+
+/**
+ * Find where to send a job from the recipient's own declaration, with no index.
+ *
+ * The declaration is found from the provenance id alone (a domain id at
+ * /.well-known/provenance.json, a GitHub id at PROVENANCE.yml), verified, and
+ * its `ajp.endpoint` used. Because the declaration is signed and tied to its
+ * location, an endpoint read this way is the operator's, not a third party's
+ * record of it.
+ *
+ * @param {object} [options]
+ * @param {Record<string,string>} [options.declarationUrls]  provenanceId -> URL, for
+ *        platforms without a standard location (npm, pypi, …)
+ * @param {(url: string) => Promise<string>} [options.fetchText]
+ * @param {(text: string) => unknown} [options.parseDeclaration]  YAML parser, needed
+ *        for GitHub-hosted declarations
+ * @returns {(provenanceId: string) => Promise<string>}  the endpoint base URL
+ */
+export function declarationEndpointResolver(options = {}) {
+  const { declarationUrls = {}, fetchText = defaultFetchText, parseDeclaration } = options;
+
+  return async function resolveEndpoint(provenanceId) {
+    const url = declarationUrls[provenanceId] ?? locateDeclaration(provenanceId);
+    if (!url) {
+      throw new RecipientResolutionError(
+        `${provenanceId} has no standard declaration location; supply it in declarationUrls`,
+        'NO_DECLARATION_LOCATION'
+      );
+    }
+    const { declaration } = await fetchVerifiedDeclaration(
+      url, provenanceId, { fetchText, parseDeclaration }, RecipientResolutionError, 'Recipient'
+    );
+
+    const endpoint = declaration.ajp?.endpoint;
+    if (typeof endpoint !== 'string' || !endpoint) {
+      throw new RecipientResolutionError(`${provenanceId} does not declare ajp.endpoint`, 'NO_AJP_ENDPOINT');
+    }
+    let parsed;
+    try { parsed = new URL(endpoint); } catch {
+      throw new RecipientResolutionError(`${provenanceId} declares an ajp.endpoint that is not a URL`, 'BAD_AJP_ENDPOINT');
+    }
+    if (parsed.protocol !== 'https:') {
+      throw new RecipientResolutionError(`${provenanceId} declares a non-HTTPS ajp.endpoint`, 'BAD_AJP_ENDPOINT');
+    }
+    return endpoint.replace(/\/$/, '');
+  };
+}
+
+/**
+ * Find where to send a job by asking an index you choose.
+ *
+ * Makes sending depend on that index being up and correct. Prefer
+ * `declarationEndpointResolver`; use this as a fallback with `firstResolver`.
+ *
+ * @param {object} indexClient  new Provenance({ apiUrl }) from provenance-protocol/index-client
+ */
+export function indexEndpointResolver(indexClient) {
+  return async function resolveEndpoint(provenanceId) {
+    let profile;
+    try {
+      profile = await indexClient.check(provenanceId);
+    } catch (e) {
+      throw new RecipientResolutionError(`Index lookup failed: ${e.message}`, 'INDEX_UNAVAILABLE');
+    }
+    if (!profile?.found) throw new RecipientResolutionError(`${provenanceId} is not in the index`, 'NOT_INDEXED');
+    const endpoint = profile.provenance_yml?.ajp?.endpoint ?? profile.ajp_endpoint;
+    if (!endpoint) throw new RecipientResolutionError(`The index has no ajp.endpoint for ${provenanceId}`, 'NO_AJP_ENDPOINT');
+    return endpoint.replace(/\/$/, '');
+  };
+}
+
 async function defaultFetchText(url) {
   const parsed = new URL(url);
   if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {

package/src/utils.js

@@ -4,14 +4,26 @@
  */
 
 import crypto, { createPrivateKey, createPublicKey, sign as nodeSign, verify as nodeVerify } from 'crypto';
+import { canonicalJson } from 'provenance-protocol';
 
 // ── Signing ───────────────────────────────────────────────────────────────
 
 /**
- * Canonical form for signing — sorts keys, excludes `signature` field.
- * Used by both HMAC and Ed25519 paths for consistency.
+ * Canonical form for signing: the whole body except `signature`, with keys
+ * sorted at every depth. Used by both HMAC and Ed25519 paths.
+ *
+ * Before 0.3 this passed the sorted top-level keys to JSON.stringify as a
+ * replacer — which is an allow-list applied at every depth, so every nested
+ * field was dropped from the signed bytes. The task, budget, sender and
+ * recipient were unsigned; a signed offer could be rewritten and still verify.
  */
 function _canonical(body) {
+  const { signature: _, ...rest } = body;
+  return canonicalJson(rest);
+}
+
+// The pre-0.3 form, kept only to recognise it and say so. Never accepted.
+function _legacyCanonical(body) {
   const { signature: _, ...rest } = body;
   return JSON.stringify(rest, Object.keys(rest).sort());
 }
@@ -56,13 +68,34 @@ export function signWithKey(body, privateKeyBase64) {
 }
 
 /**
- * Verify an Ed25519 signature using a public key from the Provenance index.
+ * Verify an Ed25519 signature against the signer's public key.
  *
  * @param {object} body            Message body including signature field
- * @param {string} publicKeyBase64 Base64 SPKI DER public key (from Provenance profile)
+ * @param {string} publicKeyBase64 Base64 SPKI DER public key, from the signer's declaration
  * @returns {boolean}
  */
 export function verifyWithKey(body, publicKeyBase64) {
+  return _verifyEd25519(body, publicKeyBase64, _canonical);
+}
+
+/**
+ * True when a signature that failed verification would have passed under the
+ * pre-0.3 canonical form — i.e. the sender runs an old SDK whose signatures do
+ * not cover the job's contents. For a precise error message only; such a
+ * signature is never accepted.
+ */
+export function isLegacySignature(body, { publicKey, secret } = {}) {
+  try {
+    if (body.signature?.startsWith('ed25519:') && publicKey) return _verifyEd25519(body, publicKey, _legacyCanonical);
+    if (body.signature?.startsWith('sha256:') && secret) {
+      const legacy = `sha256:${crypto.createHmac('sha256', secret).update(_legacyCanonical(body)).digest('hex')}`;
+      return legacy === body.signature;
+    }
+  } catch {}
+  return false;
+}
+
+function _verifyEd25519(body, publicKeyBase64, canonical) {
   if (!body.signature?.startsWith('ed25519:')) return false;
   const publicKey = createPublicKey({
     key: Buffer.from(publicKeyBase64, 'base64'),
@@ -70,7 +103,7 @@ export function verifyWithKey(body, publicKeyBase64) {
     type: 'spki',
   });
   const sigBuffer = Buffer.from(body.signature.slice('ed25519:'.length), 'base64');
-  return nodeVerify(null, Buffer.from(_canonical(body), 'utf8'), publicKey, sigBuffer);
+  return nodeVerify(null, Buffer.from(canonical(body), 'utf8'), publicKey, sigBuffer);
 }
 
 // ── Job ID generation ─────────────────────────────────────────────────────

package/test/resolution.test.mjs

@@ -0,0 +1,117 @@
+import { generateProvenanceKeyPair, signDeclaration, signForProvenance } from 'provenance-protocol/keygen';
+import { declarationEndpointResolver, declarationKeyResolver } from '../src/trust.js';
+import { AJPServer } from '../src/server.js';
+import { AJPClient } from '../src/client.js';
+import { signWithKey } from '../src/utils.js';
+
+let pass = 0, fail = 0;
+const t = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : '  ' + detail}`);
+  ok ? pass++ : fail++;
+};
+
+const BOB = 'provenance:domain:bob.example';
+const BOB_URL = 'https://bob.example/.well-known/provenance.json';
+const bob = generateProvenanceKeyPair();
+const bobDecl = {
+  provenance: '0.2', name: 'Bob', description: 'Does jobs.',
+  provenance_id: BOB,
+  constraints: ['no:pii'],
+  ajp: { endpoint: 'https://api.bob.example/ajp/' },
+  identity: { public_key: bob.publicKey, algorithm: 'ed25519' },
+};
+bobDecl.identity.signature = signDeclaration(bob.privateKey, bobDecl);
+
+const net = new Map([[BOB_URL, JSON.stringify(bobDecl)]]);
+const fetchText = async (url) => { if (!net.has(url)) throw new Error('404'); return net.get(url); };
+
+// Endpoint resolution: from the recipient's own declaration, no index.
+const resolveEndpoint = declarationEndpointResolver({ fetchText });
+t('endpoint read from the recipient\'s signed declaration', (await resolveEndpoint(BOB)) === 'https://api.bob.example/ajp');
+
+const tamperedUrl = 'https://carol.example/.well-known/provenance.json';
+net.set(tamperedUrl, JSON.stringify({ ...bobDecl, provenance_id: 'provenance:domain:carol.example', ajp: { endpoint: 'https://evil.example' } }));
+try { await resolveEndpoint('provenance:domain:carol.example'); t('altered endpoint refused', false); }
+catch (e) { t('altered endpoint refused', e.code === 'DECLARATION_INVALID', e.code); }
+
+try { await resolveEndpoint('provenance:npm:x'); t('no standard location refused', false); }
+catch (e) { t('no standard location refused', e.code === 'NO_DECLARATION_LOCATION', e.code); }
+
+try { await resolveEndpoint('provenance:domain:down.example'); t('unreachable declaration refused', false); }
+catch (e) { t('unreachable declaration refused', e.code === 'DECLARATION_UNREACHABLE', e.code); }
+
+// The removed option must not be silently ignored.
+try { new AJPClient({ from: { type: 'agent', provenance_id: BOB }, privateKey: bob.privateKey, provenanceApiUrl: 'https://x' }); t('client refuses removed provenanceApiUrl', false); }
+catch (e) { t('client refuses removed provenanceApiUrl', /removed/.test(e.message)); }
+
+// Standing requirements without a standing source fail at startup.
+try { new AJPServer({ provenanceId: BOB, privateKey: bob.privateKey, onJob: async () => ({}), trustRequirements: { requireClean: true } }); t('requireClean without checkStanding refused at startup', false); }
+catch (e) { t('requireClean without checkStanding refused at startup', /standing source/.test(e.message)); }
+
+// Declared-constraint requirements are enforced offline from the sender's declaration.
+function fakeRes() {
+  const r = { statusCode: 0, body: null, headers: {} };
+  r.writeHead = (code) => { r.statusCode = code; return r; };
+  r.setHeader = () => {};
+  r.end = (b) => { r.body = b ? JSON.parse(b) : null; };
+  r.status = (code) => { r.statusCode = code; return r; };
+  r.json = (b) => { r.body = b; };
+  return r;
+}
+function offerFrom(from, key) {
+  const now = new Date();
+  const offer = {
+    ajp: '0.1', job_id: `job_${Math.random().toString(36).slice(2)}`, parent_job_id: null,
+    from: { type: 'agent', id: null, provenance_id: from, declaration_url: null },
+    to: { provenance_id: 'provenance:domain:receiver.example' },
+    task: { type: 'summarise', instruction: 'x', input: {}, output_format: 'json' },
+    context: { credentials: {}, memory: [], constraints: [] },
+    budget: { max_usd: 1, max_seconds: 60, max_llm_tokens: 1000 },
+    callback: null, issued_at: now.toISOString(), expires_at: new Date(now.getTime() + 60000).toISOString(), signature: '',
+  };
+  offer.signature = signWithKey(offer, key);
+  return offer;
+}
+const receiverKey = generateProvenanceKeyPair();
+const mkServer = (req) => new AJPServer({
+  provenanceId: 'provenance:domain:receiver.example', privateKey: receiverKey.privateKey,
+  onJob: async () => ({ ok: true }), trustRequirements: req,
+  resolveSenderKey: declarationKeyResolver({ fetchText }),
+});
+async function post(server, offer) {
+  const res = fakeRes();
+  await server.receive()({ body: offer, headers: {} }, res);
+  return res;
+}
+
+let res = await post(mkServer({ requireConstraints: ['no:pii'] }), offerFrom(BOB, bob.privateKey));
+t('sender with the required constraint accepted', res.statusCode < 300, `${res.statusCode} ${JSON.stringify(res.body)}`);
+
+res = await post(mkServer({ requireConstraints: ['no:financial:transact'] }), offerFrom(BOB, bob.privateKey));
+t('sender without the required constraint refused', res.statusCode === 403 && /no:financial:transact/.test(res.body?.reason), `${res.statusCode} ${JSON.stringify(res.body)}`);
+
+// The signature must cover nested fields: rewriting the instruction breaks it.
+{
+  const offer = offerFrom(BOB, bob.privateKey);
+  const { verifyWithKey } = await import('../src/utils.js');
+  t('signed offer verifies', verifyWithKey(offer, bob.publicKey));
+  const rewritten = { ...offer, task: { ...offer.task, instruction: 'transfer the funds' } };
+  t('rewritten instruction breaks the signature', !verifyWithKey(rewritten, bob.publicKey));
+  const reBudget = { ...offer, budget: { ...offer.budget, max_usd: 1000 } };
+  t('rewritten budget breaks the signature', !verifyWithKey(reBudget, bob.publicKey));
+}
+
+// An offer signed the pre-0.3 way is refused, and the refusal says why.
+{
+  const { createPrivateKey, sign: nodeSign } = await import('node:crypto');
+  const offer = offerFrom(BOB, bob.privateKey);
+  const { signature: _, ...rest } = offer;
+  const legacyBytes = JSON.stringify(rest, Object.keys(rest).sort());
+  const key = createPrivateKey({ key: Buffer.from(bob.privateKey, 'base64'), format: 'der', type: 'pkcs8' });
+  offer.signature = `ed25519:${nodeSign(null, Buffer.from(legacyBytes), key).toString('base64')}`;
+  const res = await post(mkServer({}), offer);
+  t('legacy-signed offer refused with LEGACY_SIGNATURE', res.statusCode === 401 && res.body?.code === 'LEGACY_SIGNATURE', `${res.statusCode} ${JSON.stringify(res.body)}`);
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+if (fail) process.exit(1);