ajp-protocol 0.1.0 → 0.2.1

package/spec/SPEC.md

@@ -121,7 +121,8 @@ Confirm result received. Triggers payment settlement if applicable.
   "from": {
     "type": "human",
     "id": "user_abc123",
-    "provenance_id": null
+    "provenance_id": null,
+    "declaration_url": null
   },
 
   "to": {
@@ -159,6 +160,13 @@ Confirm result received. Triggers payment settlement if applicable.
 }
 ```
 
+`from.declaration_url` is where the sender's signed declaration is published.
+Agent and orchestrator senders SHOULD provide it: it is what lets a receiver
+establish the sender's key offline rather than trusting a third-party index.
+`null` for human senders, whose identity is carried by the platform's signature.
+
+---
+
 ### JobStatus
 
 ```json
@@ -195,6 +203,8 @@ Status values: `accepted` `running` `completed` `failed` `rejected` `expired`
     ]
   },
 
+  "constraints_asserted": ["no:pii", "no:persist:data"],
+
   "usage": {
     "llm_tokens": 4821,
     "duration_seconds": 18,
@@ -208,48 +218,103 @@ Status values: `accepted` `running` `completed` `failed` `rejected` `expired`
   },
 
   "completed_at": "2026-03-05T10:00:19Z",
-  "signature": "sha256:e5f6g7h8..."
+  "signature": "ed25519:base64..."
 }
 ```
 
+`constraints_asserted` lists the constraints the agent declares it honored during this job. The field is included in the signed payload — the signature ties the assertion to the agent's registered Provenance identity. Self-reported, but attributable: a false assertion is a cryptographic receipt of the lie, actionable via the Provenance incidents system.
+
 ---
 
 ## Trust verification
 
-When `from.type` is `agent`, the receiving agent MUST run a trust check before
-accepting the job. Using the `provenance-protocol` SDK:
+Establishing whether to accept a job from another agent splits into two
+questions, and only one of them needs a network service.
+
+### 1. Identity — MUST, and offline
+
+*Is this signature really from the party named in `from`?*
+
+The sender publishes its signed declaration and points at it with
+`from.declaration_url`. The receiver fetches that file and verifies it locally:
 
 ```js
-import { provenance } from 'provenance-protocol';
+import { verifyDeclaration } from 'provenance-protocol/verify';
 
-const result = await provenance.gate(offer.from.provenance_id, {
-  requireDeclared: true,
-  requireConstraints: [],        // add what your agent requires
-  requireClean: true,
-  requireMinAge: 7,              // don't accept jobs from brand-new agents
-});
+const result = await verifyDeclaration(declaration, { retrievedFrom: declarationUrl });
+// result.valid       — signature checks against the key inside the file
+// result.location    — the file was served from the location its id names
+// result.fingerprint — the key's fingerprint, for rotation detection
+```
 
-if (!result.allowed) {
-  return res.status(403).json({ error: 'Trust check failed', reason: result.reason });
-}
+A receiver MUST reject the offer unless the declaration verifies, the retrieval
+location matches the `provenance_id` it claims, and that id equals
+`from.provenance_id`. The sender's public key is then taken from the declaration
+and used to check the offer's signature.
+
+No index is consulted. Re-hosting a genuine declaration elsewhere fails the
+location check, and forging one requires the genuine private key.
+
+Receivers SHOULD remember the key fingerprint they saw for a `provenance_id`. A
+later offer signed by a different key is a key rotation and MUST be treated as
+a material change rather than a routine update.
+
+An earlier version of this specification obtained the sender's public key from a
+single index, which made signature verification depend on one service being
+reachable. That is no longer permitted for identity.
+
+### 2. Standing — SHOULD, online, and the receiver's choice
+
+*Is that party currently in good order?* Revoked, open incidents, stale
+evidence. This cannot be answered offline: the absence of news cannot be
+carried in a document, so somebody has to be asked.
+
+**Which attester to ask is the receiver's decision, not this protocol's.** One
+index, several, a private attester, or none. A conformant implementation MUST
+NOT hardcode a single provider.
+
+```js
+import { AJPServer, declarationKeyResolver, indexStandingCheck } from 'ajp-protocol';
+import { Provenance } from 'provenance-protocol';
+
+const server = new AJPServer({
+  provenanceId, onJob,
+  resolveSenderKey: declarationKeyResolver(),          // offline, the default
+  checkStanding: indexStandingCheck(new Provenance(), // opt-in, swappable
+    { requireConstraints: ['no:pii'], requireClean: true, requireMinAge: 7 }),
+  onStandingUnavailable: 'deny',
+});
 ```
 
-For `from.type === 'human'`, trust verification is handled by the platform
-(ClawMarket, SkillsMP, etc.) before the JobOffer is issued.
+A receiver that performs a standing check MUST distinguish *checked and failed*
+from *could not check*, and MUST state which way it fails when the check is
+unavailable. Reporting an unreachable attester as a failed trust check turns
+someone else's downtime into an accusation against the sender.
+
+For `from.type === 'human'`, identity is established by the platform issuing the
+offer, and the shared-secret signature covers it.
 
 ---
 
 ## Signature
 
 Every JobOffer and JobResult is signed by the sender. The signature covers the
-full message body excluding the `signature` field itself.
+full message body excluding the `signature` field itself, with keys sorted canonically.
+
+**Human senders** (no Provenance identity) — HMAC-SHA256 with a shared secret:
+```
+signature = "sha256:" + hex(HMAC-SHA256(canonical(body), sender_secret))
+```
 
+**Agent and orchestrator senders** — Ed25519 with the sender's registered Provenance private key:
 ```
-signature = "sha256:" + hex(HMAC-SHA256(JSON.stringify(body_without_signature), sender_secret))
+signature = "ed25519:" + base64(Ed25519Sign(canonical(body), provenance_private_key))
 ```
 
-Receiving agents verify signatures before processing. The `ajp-protocol` SDK
-handles signing and verification automatically.
+The receiving server verifies agent signatures by fetching the sender's public key from the
+Provenance index. This ties every message to a registered identity without a shared secret.
+
+The `ajp-protocol` SDK handles signing and verification automatically based on `from.type`.
 
 ---
 
@@ -262,7 +327,8 @@ import { AJPServer } from 'ajp-protocol';
 
 const server = new AJPServer({
   provenanceId: 'provenance:github:alice/research-assistant',
-  secret: process.env.AJP_SECRET,
+  privateKey: process.env.PROVENANCE_PRIVATE_KEY,
+  constraints: ['no:pii', 'no:persist:data'],  // asserted in every signed result
   onJob: async (job) => {
     // your agent logic here
     return { papers: [...] };
@@ -321,6 +387,19 @@ can discover an agent's AJP endpoint without out-of-band communication.
 
 ---
 
+## Implementing this specification
+
+This specification and its JSON Schema are published under the MIT Licence.
+You may implement them in any language, for any purpose, commercial or
+otherwise, without permission, notification or fee.
+
+AJP describes messages exchanged directly between agents. Nothing in it
+requires contacting any particular service. Trust verification is a separate
+concern, defined by the [Provenance Protocol](https://github.com/ilucky21c/provenance-protocol);
+an AJP implementation may use any verifier, or none.
+
+---
+
 ## Versioning
 
 The `ajp` field in every message declares the spec version. `0.1` is the current
@@ -329,5 +408,5 @@ version. Future versions add fields, never remove them.
 ---
 
 *AJP v0.1 — Provenance Protocol Family — MIT License*
-*https://provenance.dev/ajp*
-*https://github.com/provenance-protocol/ajp*
+*https://getprovenance.dev/ajp*
+*https://github.com/ilucky21c/ajp-protocol*

package/src/client.js

@@ -5,29 +5,41 @@
  * Consistent with provenance-protocol SDK class structure.
  */
 
-import { sign, generateJobId, validateOffer } from './utils.js';
+import { sign, signWithKey, generateJobId, validateOffer } from './utils.js';
 import { Provenance } from 'provenance-protocol';
 
 export class AJPClient {
 
   /**
    * @param {object} opts
-   * @param {object} opts.from          — sender identity
-   * @param {string} opts.from.type     — 'human' | 'agent' | 'orchestrator'
-   * @param {string} [opts.from.id]     — platform user ID (human only)
+   * @param {object} opts.from               — sender identity
+   * @param {string} opts.from.type          — 'human' | 'agent' | 'orchestrator'
+   * @param {string} [opts.from.id]          — platform user ID (human only)
    * @param {string} [opts.from.provenance_id] — required for agent/orchestrator
-   * @param {string} opts.secret        — HMAC signing secret
-   * @param {string} [opts.provenanceApiUrl]   — override Provenance API URL
-   * @param {number} [opts.defaultTimeoutMs]   — default job timeout in ms (30s)
+   * @param {string} [opts.from.declaration_url] — where this sender's signed
+   *        declaration is published. Lets receivers establish this sender's key
+   *        offline instead of looking it up in an index. Strongly recommended:
+   *        without it a receiver must fall back to trusting a third party.
+   * @param {string} [opts.privateKey]       — Base64 PKCS8 Ed25519 private key (PROVENANCE_PRIVATE_KEY).
+   *                                           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 {number} [opts.defaultTimeoutMs] — default job timeout in ms (30s)
    */
-  constructor({ from, secret, provenanceApiUrl, defaultTimeoutMs = 30000 }) {
+  constructor({ from, privateKey, secret, provenanceApiUrl, defaultTimeoutMs = 30000 }) {
     this.from = from;
-    this.secret = secret;
+    this.privateKey = privateKey || null;
+    this.secret = secret || null;
     this.defaultTimeoutMs = defaultTimeoutMs;
     this.provenance = new Provenance({ apiUrl: provenanceApiUrl });
 
-    if ((from.type === 'agent' || from.type === 'orchestrator') && !from.provenance_id) {
-      throw new Error('from.provenance_id required when type is agent or orchestrator');
+    if (from.type === 'agent' || from.type === 'orchestrator') {
+      if (!from.provenance_id) throw new Error('from.provenance_id required when type is agent or orchestrator');
+      if (!privateKey) throw new Error('privateKey (PROVENANCE_PRIVATE_KEY) required for agent/orchestrator senders');
+    }
+    if (from.type === 'human' && !secret) {
+      throw new Error('secret required for human senders');
     }
   }
 
@@ -64,6 +76,7 @@ export class AJPClient {
         type: this.from.type,
         id: this.from.id || null,
         provenance_id: this.from.provenance_id || null,
+        declaration_url: this.from.declaration_url || null,
       },
 
       to: { provenance_id: toProvenanceId },
@@ -93,8 +106,10 @@ export class AJPClient {
       signature: '',
     };
 
-    // Sign it
-    offer.signature = sign(offer, this.secret);
+    // Sign with Ed25519 (agents/orchestrators) or HMAC (humans)
+    offer.signature = (this.from.type === 'agent' || this.from.type === 'orchestrator')
+      ? signWithKey(offer, this.privateKey)
+      : sign(offer, this.secret);
 
     // Validate before sending
     const { valid, errors } = validateOffer(offer);
@@ -155,7 +170,9 @@ export class AJPClient {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ received: true }),
-        }).catch(() => {});
+        }).catch((e) => {
+          console.warn(`[AJP] Ack failed for ${jobId} — payment settlement may not trigger:`, e.message);
+        });
         return status;
       }
 
@@ -182,8 +199,11 @@ export class AJPClient {
       const endpoint = profile.provenance_yml?.ajp?.endpoint;
       if (endpoint) return endpoint.replace(/\/$/, '');
 
-      // Fallback: derive from agent URL
-      if (profile.url) return `${profile.url.replace(/\/$/, '')}/api/agent`;
+      // 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) {

package/src/index.js

@@ -22,3 +22,10 @@
 export { AJPClient } from './client.js';
 export { AJPServer } from './server.js';
 export { sign, verify, generateJobId, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
+export {
+  declarationKeyResolver,
+  indexKeyResolver,
+  firstResolver,
+  indexStandingCheck,
+  SenderIdentityError,
+} from './trust.js';

package/src/server.js

@@ -6,36 +6,64 @@
  * Express, Next.js API routes, Fastify, or any Node HTTP framework.
  */
 
-import { verify, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
+import { verify, verifyWithKey, sign, signWithKey, validateOffer, JOB_STATUS, FROM_TYPE } from './utils.js';
 import { Provenance } from 'provenance-protocol';
+import { declarationKeyResolver, SenderIdentityError } from './trust.js';
 
 export class AJPServer {
 
   /**
    * @param {object} opts
-   * @param {string} opts.provenanceId    — this agent's Provenance ID
-   * @param {string} opts.secret          — HMAC verification secret (must match client)
-   * @param {Function} opts.onJob         — async (job) => result — your agent logic
+   * @param {string} opts.provenanceId       — this agent's Provenance ID
+   * @param {string} opts.privateKey         — Base64 PKCS8 Ed25519 private key (PROVENANCE_PRIVATE_KEY).
+   *                                           Used to sign job results so callers can verify authenticity.
+   * @param {string} [opts.secret]           — HMAC secret for verifying human callers. Optional if you
+   *                                           only accept agent/orchestrator callers.
+   * @param {Function} opts.onJob            — async (job) => result — your agent logic
+   * @param {function} [opts.resolveSenderKey] — async (provenanceId, from) => { publicKey, fingerprint }
+   *        How the sender's key is established. Defaults to resolving it from the
+   *        sender's own signed declaration, offline, with no index involved.
+   * @param {function} [opts.checkStanding] — async (provenanceId) => { allowed, reason }
+   *        Optional current-standing check (revocation, incidents, freshness).
+   *        Off by default: standing is the receiver's policy, not a protocol rule.
+   * @param {'deny'|'allow'} [opts.onStandingUnavailable] — what to do when the
+   *        standing check itself fails to answer. Defaults to 'deny'.
    * @param {object} [opts.trustRequirements] — applied to all agent/orchestrator senders
    * @param {boolean} [opts.trustRequirements.requireDeclared]
    * @param {string[]} [opts.trustRequirements.requireConstraints]
+   * @param {string[]} [opts.trustRequirements.requireCapabilities] — e.g. ['delegate:agents'] to only accept jobs from declared orchestrators
    * @param {boolean} [opts.trustRequirements.requireClean]
    * @param {number} [opts.trustRequirements.requireMinAge]
-   * @param {number} [opts.trustRequirements.requireMinConfidence]
+   * @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,
+    privateKey,
     secret,
     onJob,
+    constraints = [],
     trustRequirements = {},
     provenanceApiUrl,
+    resolveSenderKey,
+    checkStanding,
+    onStandingUnavailable = 'deny',
   }) {
+    if (!privateKey) throw new Error('privateKey (PROVENANCE_PRIVATE_KEY) required — used to sign job results');
     this.provenanceId = provenanceId;
-    this.secret = secret;
+    this.privateKey = privateKey;
+    this.secret = secret || null;
     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;
 
     // In-memory job store — replace with DB for production
     this.jobs = new Map();
@@ -55,28 +83,59 @@ export class AJPServer {
         }
 
         // 2. Verify signature
-        if (!verify(offer, this.secret)) {
-          return this._json(res, 401, { error: 'Invalid signature' });
+        if (offer.from.type === FROM_TYPE.HUMAN) {
+          // Human callers: HMAC-SHA256 with shared secret
+          if (!this.secret) {
+            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' });
+          }
+        } else {
+          // Agent/orchestrator callers: Ed25519. The key comes from whatever the
+          // receiver configured — by default the sender's own signed declaration,
+          // verified offline. No index is consulted to check a signature.
+          let sender;
+          try {
+            sender = await this.resolveSenderKey(offer.from.provenance_id, offer.from);
+          } catch (e) {
+            const code = e instanceof SenderIdentityError ? e.code : 'SENDER_IDENTITY_FAILED';
+            return this._json(res, 403, { error: 'Sender identity could not be established', reason: e.message, code });
+          }
+          if (!sender?.publicKey) {
+            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' });
+          }
         }
 
-        // 3. Trust check — required for agent/orchestrator senders
-        if (offer.from.type === FROM_TYPE.AGENT || offer.from.type === FROM_TYPE.ORCHESTRATOR) {
-          const trustResult = await this.provenance.gate(
-            offer.from.provenance_id,
-            {
-              requireDeclared: this.trustRequirements.requireDeclared ?? false,
-              requireConstraints: this.trustRequirements.requireConstraints ?? [],
-              requireClean: this.trustRequirements.requireClean ?? true,
-              requireMinAge: this.trustRequirements.requireMinAge ?? 0,
-              requireMinConfidence: this.trustRequirements.requireMinConfidence ?? 0,
+        // 3. Standing check — optional, and the receiver's policy rather than a
+        //    protocol requirement. Identity is settled above without a network
+        //    service; standing is the part that genuinely needs asking someone,
+        //    so it is configured, degradable, and absent by default.
+        if (
+          this.checkStanding &&
+          (offer.from.type === FROM_TYPE.AGENT || offer.from.type === FROM_TYPE.ORCHESTRATOR)
+        ) {
+          let standing;
+          try {
+            standing = await this.checkStanding(offer.from.provenance_id, this.trustRequirements);
+          } catch (e) {
+            // "Could not check" must not be reported as "checked and failed".
+            if (this.onStandingUnavailable === 'allow') {
+              standing = { allowed: true, unavailable: true, reason: e.message };
+            } else {
+              return this._json(res, 403, {
+                error: 'Standing could not be checked',
+                reason: e.message,
+                code: 'STANDING_UNAVAILABLE',
+              });
             }
-          );
+          }
 
-          if (!trustResult.allowed) {
-            return this._json(res, 403, {
-              error: 'Trust check failed',
-              reason: trustResult.reason,
-            });
+          if (standing && standing.allowed === false) {
+            return this._json(res, 403, { error: 'Trust check failed', reason: standing.reason ?? null });
           }
         }
 
@@ -128,11 +187,11 @@ export class AJPServer {
 
         if (job.status === JOB_STATUS.COMPLETED) {
           response.output = job.output;
+          response.constraints_asserted = job.constraints_asserted;
           response.usage = job.usage;
-          response.agent = {
-            provenance_id: this.provenanceId,
-          };
+          response.agent = { provenance_id: this.provenanceId };
           response.completed_at = job.completed_at;
+          response.signature = job.signature;
         }
 
         if (job.status === JOB_STATUS.FAILED) {
@@ -184,14 +243,33 @@ export class AJPServer {
     this.jobs.set(jobId, job);
 
     try {
-      const output = await this.onJob(job);
+      const maxSeconds = job.budget?.max_seconds ?? 120;
+      const output = await Promise.race([
+        this.onJob(job),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error(`Job exceeded max_seconds (${maxSeconds}s)`)), maxSeconds * 1000)
+        ),
+      ]);
 
       const durationSeconds = (Date.now() - startTime) / 1000;
       job.status = JOB_STATUS.COMPLETED;
       job.output = output;
+      job.constraints_asserted = this.constraints;
       job.completed_at = new Date().toISOString();
       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.
+      // constraints_asserted is included in the signed payload — a cryptographic receipt of declared behavior.
+      job.signature = signWithKey({
+        job_id: job.job_id,
+        status: job.status,
+        output: job.output,
+        constraints_asserted: job.constraints_asserted,
+        completed_at: job.completed_at,
+        agent: { provenance_id: this.provenanceId },
+      }, this.privateKey);
+
       this.jobs.set(jobId, job);
 
       // Deliver result via callback if set
@@ -200,7 +278,7 @@ export class AJPServer {
       }
 
     } catch (e) {
-      job.status = JOB_STATUS.FAILED;
+      job.status = e.message.includes('max_seconds') ? JOB_STATUS.EXPIRED : JOB_STATUS.FAILED;
       job.error = e.message;
       job.updated_at = new Date().toISOString();
       this.jobs.set(jobId, job);
@@ -220,9 +298,11 @@ export class AJPServer {
           job_id: job.job_id,
           status: job.status,
           output: job.output,
+          constraints_asserted: job.constraints_asserted,
           usage: job.usage,
           agent: { provenance_id: this.provenanceId },
           completed_at: job.completed_at,
+          signature: job.signature,
         }),
       });
     } catch (e) {